• The differences between launchers
• Unity-based single-launcher
  • Before you start
  • Getting hands on the project
  • Making changes
    • Basic look & feel
    • Changing the window size
  • Building
  • Uploading
  • Updating
  • Community resources
  • Troubleshooting
    • The launcher crashes right away
• Electron-based launcher
  • SDK 1.0
  • SDK 2.0
  • Requirements
  • Quick start with an example project
  • Basic concepts
  • Launcher component
    • Presets
    • patchkit-generic-launcher2-dev-tools
    • patchkit-generic-launcher2-base-presets
  • Theme component
    • Possible routing issues
  • Building and deployment
    • Building the Launcher component
    • Deploying the Launcher component
    • Building the Theme component
    • Deploying the Theme component
  • Sharing your launcher
  • FAQ
    • Do I need to update the launcher component each time I update the theme?
    • When should I update the launcher component?
  • Getting help

The differences between launchers

There are significant differences between launchers. To learn more about them, please visit Launcher Overview page.

Unity-based single-launcher

Before you start

Before you start customizing your launcher, you first have to create your account and set up your game. You may find out how to do that in Getting Started page. As soon as you did that, please proceed further.

Getting hands on the project

Unity-based single-launcher is a Unity project. It means that you are required to have at least fundamental Unity and Unity UI knowledge.

You can get the project source files from GitHub project page.

The project has been created and tested with Unity 2018.4.x. We highly recommend using the same version while working with the project; otherwise, you may encounter unexpected issues. You can get it through Unity Archive. If you already have a Unity version installed via Unity Hub, simply use it to download 2018.4. If you’re not using Unity Hub, please follow these instructions.

Making changes

Basic look & feel

Before starting the customization of your launcher, make sure to make a copy of the Patcher scene and do all the modifications on that new scene. If you modify the supplied scene, any asset upgrade overwrites your changes!

The launcher layout is done entirely in Unity UI. Feel free to change it however you want, but make sure to keep all the attached scripts in place.

Changing the window size

If you’d like to change the window size, you should update it in Player Settings, Resolution and Presentation, Default Screen Width/Height.

Building

1. Choose Tools / Build / PLATFORM_NAME from the main menu, where PLATFORM_NAME is your target platform for which you’re building your launcher.
2. Select an empty directory and name your build. We recommend naming it Launcher.
3. Remember where the launcher has been built. You will need those files in a moment.

Building the launcher using Unity’s Build Settings window or File / Build And Run option may result in a corrupted build. As a result, your launcher may not work at all.

Do not be surprised that launcher is not working when you run it from the desktop. It needs to be uploaded to the PatchKit’s panel first.

Uploading

Now when you have your new launcher build, you have to upload it to your PatchKit account.

1. Navigate to publisher panel applications page.
2. Click the New Application button and then choose New Launcher from the popup.
3. In the new application form, name your launcher (e.g.,My Launcher Windows 64) and click the Create button. Shortly after, you should be able to see your new application.
4. Now click the New Version button.
5. Edit the new version Label to, let’s say, 1.0.
6. Click the Upload Content button.
7. Compress the directory of your launcher into the zip file. Make sure that the patcher.manifest file can be found next to the launcher executable.
8. Choose that newly created zip file as your application content.
9. Wait for the upload and version processing to finish.
10. If there are no errors, click the Publish button.
11. After the version is published, navigate to your game’s page.
12. Inside Configuration panel look for Custom Launcher field. Click on the Edit button right next to it.
13. From the drop-down, select your new launcher.
14. Click on the Save button.

From now on, your new application is using your custom launcher instead of the default one.

Updating

Unity-based single-launcher will be getting updates from time to time introducing new features and bug fixes. If you’re using a custom launcher, make sure to either:

• Follow our Blog
• Follow our GitHub repository for new releases

Some releases may include migration guidelines since new changes can break yours.

Updating custom launcher is the same process as updating every application - you need to upload a new version to your launcher application and publish it. Old launcher versions are replaced by the new version on the next start of the runner application.

Community resources

• PatchKit Tutorial: Making a Launcher on MacOSX

Troubleshooting

The launcher crashes right away

First, look into the logs. A significant error message should be at the end of it. Usually, there may be two reasons:

1. You’re trying to start launcher directly - this is not allowed. You can only test it inside Unity editor. When it’s built, you have to upload it to PatchKit for further testing.
2. You did change application secret in inspector - For security reasons you have to reset application secret to default value which currently is ac20fc855b75a7ea5f3e936dfd38ccd8.

Electron-based launcher

The electron-based launcher can be customized using PatchKit Electron Launcher SDK. Currently, the electron launcher can be installed on your account by request. If you’d like to use it, please contact us.

SDK 1.0

The SDK version 1.0 is now deprecated. If you’re looking for the documentation of the previous version, please click here.

SDK 2.0

Release date: 2023-07-23

The Electron Launcher SDK is a tool that enables the development of PatchKit electron-based launcher themes in a lightweight development environment, consisting of a web browser window and a code editor of your choice. The SDK allows mimicking different states of the launcher to test how custom code would look and behave. The launcher is built on the Chromium web engine; therefore, we recommend using a Chromium-based web browser.

Please note that the launcher theme code is responsible for both the appearance and behavior, such as user flow. For instance, you can trigger the authentication logic before the user can install the game.

Requirements

To start working with the SDK, you need a few things installed on your development machine:

• NodeJS (we recommend nvs and NodeJS v16.16.0)
• A package manager of your choice (we recommend yarn, although both npm and pnpm should work as well)
• An App Catalog on PatchKit Panel (you can create it here)

Quick start with an example project

To assist you in bootstrapping your launcher, we recommend downloading the example project. Simply download the patchkit-example-launcher.zip archive and unpack the contents into a directory where you will be working on your launcher.

Now, you need to run theme and the launcher components in that order (preferably in development mode).

cd theme
yarn
yarn start

Once your theme is running, start the launcher.

cd runtime
yarn

# Windows
yarn run-dev -p windows-preset.js -t http://localhost:3000

# macOS
yarn run-dev -p macos-preset.js -t http://localhost:3000

# Linux
yarn run-dev -p linux-preset.js -t http://localhost:3000

As you do that, you will see a launcher window appear. The library on games in it, is a library of games of PatchKit demo launcher, which you can easily switch to yours later on. The example project has hot-reloading enabled, so any changes you make in the theme will be instantly reflected in the launcher.

Basic concepts

The PatchKit Launcher SDK structures the project into two separate components:

• Launcher - an application built on top of the Electron framework that supplies core functionality like installing and updating the apps, as well as window management, shortcut creation, and deep links.
• Theme - a user interface built with frontend technologies, allowing you to completely customize your launcher. You can think of it as a front-end application with additional API exposed from the launcher.

These two components are deployed individually to allow quick updates of the theme without the need to rebuild the launcher. The deployment instructions are detailed in this section.

Launcher component

The launcher component consists of:

• A package.json file that depends on two SDK packages: patchkit-generic-launcher2-dev-tools and patchkit-generic-launcher2-base-presets.
• Presets

Presets

The concept of presets allows you to have different variants of your launcher. Common use cases for having multiple presets are:

• To target multiple platforms (Windows, macOS, or Linux)
• To separate development/internal and production versions of the launcher

Each preset is a JavaScript file placed in the src directory that exports the configuration object. This setup enables you to store shared configurations in separate JavaScript files and compose them with libraries like deepmerge. Please refer to the example project for details.

Configurable preset fields include:

• id - Example: patchkit-demo-launcher. Required. Please note that it cannot be changed once the launcher is deployed.
• name - Example: PatchKit Demo Launcher. Required. This is used in areas visible to the user.
• description - Example: PatchKit Demo Launcher. Required. It usually matches the name, but you can use it to describe the specifics of your launcher.
• companyId - Example: upsoft. Required. Please note that it cannot be changed once the launcher is deployed.
• companyName - Example: Upsoft. Required. This is used in areas visible to the user.
• iconFilePath - Example: require.resolve("./icons/windows.ico").
• secret - Example: aabbccddeeffgghhiijjkkll11223344. Required.
• appsCatalogId - Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee. Required. You can find this in the list of your App Catalogs on PatchKit Panel.
• isAppsBranchesNotDefaultRootDirAllowed - Default: false. This determines whether to allow installing apps in any directory (not just the default ones).
• window
  • defaultSize - Default: { width: 1024, height: 768 }.
  • defaultMinSize - Default: { width: 1024, height: 768 }.
  • defaultMaxSize - Default: { width: 1024, height: 768 }.
  • defaultIsResizable - Default: false.
  • isBorderless - Default: false.
  • isTransparent - Default: false.
  • areCornersRounded - Default: true.
• protocol - Default: undefined. Example: { "id": "patchkit-demo-launcher" }. This allows you to configure the deep link functionality for your launcher so it can be opened from web links like patchkit-demo-launcher://action.

patchkit-generic-launcher2-dev-tools

This package provides the scripts required to start the launcher in development mode as well as to build it:

• run-patchkit-generic-dev-launcher2:
  • required -p or --presetFileName
  • required -t or --overrideThemeUrl
• build-patchkit-generic-prod-launcher2:
  • required -p or --presetFileName
  • required -v or --version
  • optional --appleId
  • optional --appleIdPassword

You can use these scripts:

• Directly with yarn, for example yarn run-patchkit-generic-dev-launcher2
• Directly with npx, for example npx run-patchkit-generic-dev-launcher2
• By aliasing them in the scripts field of package.json (please refer to the example project)

patchkit-generic-launcher2-base-presets

This package provides presets with default values that are commonly used across launchers built with the SDK.

Theme component

The theme is simply a user interface application built with web technologies, similar to a front-end. Please refer to the example project to learn how to utilize the API exposed from the launcher runtime to create the launcher user interface.

Possible routing issues

To ensure your launcher theme is compatible with the deployment option on the PatchKit Panel, you need to adjust the routing method in your application. Since the theme is going to be deployed in a subdirectory, you can’t assume the absolute path to your application at build time. Therefore, we recommend using solutions like HashRouter from react-router to avoid any issues after deployment.

Building and deployment

When you’re done working on your launcher, you need to build it.

Building the Launcher component

To build the launcher, run:

cd runtime

# Windows
yarn build-prod -p windows-preset.js -v 1.0.0

# macOS
yarn build-prod -p macos-preset.js -v 1.0.0 --appleId yourappleid --appleIdPassword yourappleidpassword

# Linux
yarn build-prod -p linux-preset.js -v 1.0.0

This should create a dist directory in the runtime directory that contains the launcher distribution zip file as of format: Launcher-1.0.0-windows.zip.

Deploying the Launcher component

To deploy the launcher, follow these steps:

1. Compress the dist directory into a zip file.
2. Open the PatchKit Panel.
3. If you already do have an Electron Launcher application, skip to step 7.
4. Navigate to the Applications page.
5. Click the New Application button and then choose New Custom Launcher from the popup.
6. On the next form, choose the Electron Launcher option and click the Create button.
7. Click on the Draft Version button.
8. If you don’t see the box with the “Drag and drop Your ZIP File Here” message, click on the Import Content button, then Upload a ZIP File.
9. Select or drag and drop your zip file from the dist directory.
10. Wait for the upload and version processing to finish.
11. If there are no errors, click the Publish button.

Building the Theme component

To build the theme, run:

cd theme
yarn build

This should create a build directory in the theme directory that contains the built theme.

Deploying the Theme component

Steps on how to set up and upload a new theme version are described in the Launcher Themes Managament page.

Sharing your launcher

Once both the runtime and theme have been uploaded, you can distribute your launcher to the end-users. You can do so by navigating to your launcher application page on the PatchKit Panel (the Overview tab) and finding the Download Link in the Details frame on the right side of the page.

FAQ

Do I need to update the launcher component each time I update the theme?

No, you don’t. The launcher component is responsible for fetching the latest version of the theme from the PatchKit servers. Therefore, you can update the theme without the need to update the launcher component.

When should I update the launcher component?

You should update the launcher component when you want to introduce new features or bug fixes to the launcher itself. For example, if you want to add a new feature to the launcher, you need to update the launcher component to expose the new API to the theme.

For the list of changes to the launcher component… TODO

Getting help

If you’d require any help with the custom launcher, please don’t hesitate to contact us. We will assist you the best as we can!