Launchers

Launchers Overview

A launcher is a desktop application that manages the installation, updating, and maintenance of the game or application. It also handles authentication and collects usage data.

PatchKit Launchers

PatchKit offers two types of launchers: Unity-based and Electron-based. The following table highlights the differences between the two:

Acquiring the Launcher

A Unity-based launcher is built automatically for each application that has at least one published version. You can download it by navigating to your application page and then by clicking on the Get Launcher button.

The electron-based launcher on the other hand needs to be built and uploaded manually. Currently, this is done by PatchKit team on request.

Unity Launcher

Customization

For the Unity launcher, you can freely customize it by downloading the source code from GitHub repository and by opening in the Unity editor. It’s required to use version Unity 2018.4.x of the Unity editor. You can easily download it from Unity Hub.

You do all the customization in the Patcher scene. Make sure to copy it and perform all the modifications on that new copy. Otherwise, you may have hard time upgrading your launcher to the latest release from the source code.

To build it, choose Tools / Build / PLATFORM from the main menu where PLATFORM is your platform of choice.

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.

Troubleshooting

If it comes to troubleshooting the Unity-based launcher, there are two main steps you can take:

• Try to troubleshoot it yourself by following the steps described on the Troubleshooting page.
• Contact our support team by creating a support ticket.

In both cases it’s important to provide the logs and the version of the launcher. Below you can find the instructions on how to get them.

Getting the Logs

Getting the logs is the first step in troubleshooting issues with the Unity-based launcher. The logs can be found in the following locations depending on the operating system:

The logs can be accessed in two ways:

• By pressing CTRL+SHIFT+D in the launcher window, then choosing the Open Launcher log file location option.
• By navigating to the following locations:

Windows

• C:\Users\USERNAME\AppData\LocalLow\UpSoft\PatchKit Patcher\output_log.txt

GNU/Linux

• ~/.config/unity3d/UpSoft/PatchKit Patcher/Player.log

Mac OSX

• ~/Library/Logs/Unity/Player.log

Note that if you’ve changed the Company Name and Product Name in the launcher settings, the log file location may be different. For more information, please refer to Unity’s documentation.

Finding the Installed Version

To find the version of the installed Unity-based launcher, you can follow these steps:

1. Search for the launcher log file (output_log.txt or Player.log)
2. Open the log file
3. Look for the version number in the first lines of the log file, it should look similar to this:

2022-03-16 11:12:01.154 +01:00 [ DEBUG ] <Patcher::Awake> patchkit-patcher-unity: v3.17.11.0

Electron Launcher

Customization

Customization Services

At PatchKit, we specialize in tailoring services to meet your specific needs, including custom launcher design and development. Our team is skilled at accurately assessing your requirements to estimate the volume of work, ensuring we build the perfect launcher that aligns with your vision. Operating on an hourly basis, we dedicate our time and resources effectively to bring your ideas to life. If you’re intrigued by the possibility of creating your own unique launcher theme, we invite you to get in touch with us so we can delve into your specifications and start crafting your custom solution.

Manual Customization

The Electron-based launcher can be customized using the Electron Launcher SDK. The SDK is a tool that enables the development of a PatchKit Electron-based launcher theme in a lightweight development environment consisting of a web browser window and a code editor of your choice.

The SDK allows you to test how custom code would look and behave by mimicking different states of the launcher. The launcher is built on the Chromium web engine, so we recommend using a Chromium-based web browser.

Please note that the launcher theme code is not only responsible for the appearance but also the behavior, such as the user flow. For example, you can trigger the authentication logic before the user can install the game.

Requirements

• NodeJS version 16.x or older
• An operating system that is supported by NodeJS

Installation

To install the Electron Launcher SDK from scratch:

1. Download the latest version (version 5) from https://public.3.basecamp.com/p/3PkjG7FYyhpzFEqtXSSrJ7Y8
2. Open a terminal window in the main folder
3. Run the yarn command to install all dependencies

Updating

To update the Electron Launcher SDK to the latest release:

1. Overwrite the .local_deps directory with the new version
2. Delete the node_modules directory
3. Run the yarn command again to reinstall the modules

Running the Development Environment

To run the development environment:

1. Open the command line in the root directory of the SDK (the directory with the package.json file).
2. Use the command yarn run-theme-dev to start the development server.
3. Open the URL http://localhost:9060/dev in your web browser.

Interface Overview

1. The top bar contains a set of buttons that allow you to simulate specific actions in the launcher.
2. The preview of your theme is in the center.
3. The bottom section is an editor for the state data loaded into the theme. Modifying the data affects the content.

Modifying the Theme

You can freely modify the theme by editing the files in the src directory using your preferred code editor.

The example theme included is based on React, and all React rules apply.

In the React example, we use camel-case notation for styling, and non-numeric values must be enclosed in quotation marks (``, ‘’, “”).

For example:

style={{
    height: `100%`,
    flexBasis: `60px`,
    flexGrow: 0,
    flexShrink: 0,
    paddingLeft: `10px`,

    overflow: `auto`,
}}

For more complex styling, the emotion package can be imported:

import emotion = require('emotion');

This allows us to use standard CSS styling with the className attribute:

className={emotion.css`
  &::-webkit-scrollbar {
    width: 5px;
  }

  &::-webkit-scrollbar-thumb {
    border-radius: 50px;
    background-color: #dedede;
  }
`}

Modifying the Window

The main theme file is called window_widget.tsx and can be found in the src directory. This is the place to change the overall background color or round the corners, for example.

Reusable Components

There are universal components that can be used in different situations, such as:

• button_widget.tsx
• hoverable_html_div_widget.tsx
• label_button_widget.tsx
• label_widget.tsx
• popup_widget.tsx

These components are used in several places with slight modifications.

Please be cautious when making changes to these components, as it may result in unexpected behavior for other components that rely on them.

Backend-related Components

All components with app_branch in their name are backend-related components. Modify these components only if you are confident that it will not affect the functionality of the launcher.

More Examples

Changing the Background Color of the Launcher

To change the background color of the launcher, you need to first change the main background color in the window_widget.tsx file:

backgroundColor: `lightblue`,

The top bar still retains its original color. To change it, you need to modify the window_title_bar_widget.tsx file:

backgroundColor: `lightblue`,

Changing the popup background color

popup_widget.tsx

backgroundColor: `lightblue`,

Centering the INSTALL/PLAY button

To center the INSTALL/PLAY button, you need to add a centering style to the parent div of the AppBranchStateWidget component in the app_branch_widget.tsx file:

display: `flex`,
justifyContent: `center`,

This will result in the following code:

<div
  style={{
    width: `100%`,
    flexBasis: 0,
    flexGrow: 1,
    flexShrink: 0,
    display: `flex`,
    justifyContent: `center`,
  }}
>
  <AppBranchStateWidget
    appId={appId}
    appBranchId={appBranchId}
    appPresentation={appPresentation}
  />
</div>

Removing the “Check for updates” button

To remove the “Check for Updates” button, simply change the isVisible flag to false.

In the start_app_branch_widget.tsx file:

checkForUpdatesButtonWidget={{
  isVisible: false,
}}

Adding the application name next to its icon

In the window_widget.tsx file on line 126, there is a component responsible for displaying the application icons in the left menu. The children iteratively return the icon of each application. The icon code is:

<div
    style={{
      width: `40px`,
      height: `40px`,
      marginTop: `10px`,

      cursor: `pointer`,

      backgroundImage: `url(${appState.iconImageUrl})`,
      backgroundSize: `contain`,
      backgroundRepeat: `no-repeat`,
    }}
    onClick={() => {
      setCurrentAppId({ currentAppId: appId });
    }}
    >{[
    currentAppId === appId
      ? undefined
      : <div
        style={{
          width: `100%`,
          height: `100%`,
          backgroundColor: `#00000055`,
        }}
      />,
    ]}
</div>

For simplification, I will use the icon code as <AppIcon /> in future examples.

To display the application name, you can use the appState object. Replace the code:

<AppIcon />

with the following code:

<div>
    <AppIcon />
    <div>{appState.name}</div>
</div>

This will look like this:

The text might be too wide and might not fit inside the bar. To fix this issue, you can increase the flexBasis value on line 140.

The icon styling can be updated to the following:

<div
    style={{
        display: `flex`,
        alignItems: `center`,
        cursor: `pointer`,
    }}
>
    <AppIcon />
    <div
        style={{
            width: `100%`,
            paddingLeft: `10px`,
        }}
    >{appState.name}</div>
</div>

This will look like this:

Note that the text will not respond to clicks, as the onClick action is only attached to the icon. To make the text clickable, move the onClick action up a level so that it also includes the text:

<div
    style={{
        display: `flex`,
        alignItems: `center`,
        cursor: `pointer`,
    }}
    onClick={() => {
      setCurrentAppId({ currentAppId: appId });
    }}
>
    <AppIcon />
    <div
        style={{
            width: `100%`,
            paddingLeft: `10px`,
        }}
    >{appState.name}</div>
</div>

Deploying

The deploying process encompasses the personalization of your launcher’s appearance, uploading your custom theme to the PatchKit servers, and finally, implementing it for your users.

Please note that this feature requires the themes capability to be enabled on your launcher. If you’re working with a launcher deployed before 2023-03-20, it might not have this feature enabled. To enable it, please contact us.

Building the Custom Theme

To deploy your custom launcher theme, you need to build the launcher theme and upload it to your dashboard. You can build your theme by executing the following command:

yarn build-theme-prod

This will create a theme_prod folder in the root directory of your project. You should zip the contents of this folder and upload it to your dashboard.

Uploading the Custom Theme

After customizing your theme, here’s how you can upload it:

1. Go to the PatchKit Dashboard and sign in.
2. In the left sidebar, click on the Launcher Themes link.
3. Press the New Launcher Theme button.
4. Click the New Version button.
5. Choose your theme file (.zip format) and click the Upload button. The Launcher Version field can be left blank for now.

The Launcher Version field, if specified, should reflect the launcher version compatible with your theme. By default, it assumes the highest defined version or 0.0.0 if left empty, suggesting compatibility with all versions. However, if you specify a launcher version, the theme will only work with that version and newer ones having the same major version number.

Implementing the Custom Theme

Once uploaded, your theme isn’t directly available to your users. To make it accessible, associate it with a specific launcher app. This can be done from the Launcher Themes page on the PatchKit Dashboard or directly through your launcher app settings.

Associating a Theme from the Launcher Themes Page

1. Go to the PatchKit Dashboard and sign in.
2. Click the Launcher Themes link in the left sidebar.
3. Press the Edit button next to the theme you want to assign.
4. Click the Assign to Launcher button.
5. Select the launcher app to link with your theme and press the Assign button.

Associating a Theme from Launcher App Settings

1. Visit the PatchKit Dashboard and sign in.
2. Click the Applications link in the left sidebar.
3. Select the launcher app you want to associate with your theme.
4. From the Launcher Theme list, choose your theme and click the Save button.

After associating your theme, your users can access it, although the launcher might need to be restarted to reflect the changes.

Deployment FAQ

How can I remove a theme?

To delete a theme, you need to disassociate it from all launcher apps. You can achieve this either from the Launcher Themes page in the PatchKit Dashboard or from your launcher app settings by selecting the (default) launcher theme.

How can I revert to a previous version of a theme?

If you wish to revert to a previous version of a theme, you’ll have to remove all newer versions. You can do this from the Launcher Themes page in the PatchKit Dashboard.

How can I completely remove a theme?

To completely delete a theme, navigate to the Launcher Themes page in the PatchKit Dashboard, click the Edit button next to the theme you wish to remove, and then select Delete from the cogs dropdown.

Troubleshooting

If you encounter any issues with the Electron-based launcher, there are two main steps you can take:

1. Try troubleshooting it yourself by following the steps described on the Troubleshooting page.
2. Contact our support team by creating a support ticket.

In both cases, it is important to provide the logs and the version of the launcher. Below, you will find instructions on how to get them.

Getting the Logs

Launcher logs are usually the first thing you should be looking into when reporting issues with the electron-based launcher.

The logs can be accessed in two ways:

• By pressing CTRL+SHIFT+D in the launcher window, it will compress all the required logs and present you with a zip file to be delivered to the developer. (Recommended)
• By navigating to the following locations:

Note: Logs will be overwritten each time the launcher is started, so be sure to copy them before starting the launcher again if you need to send them to support@patchkit.net.

Finding the Installed Version

1. If the launcher has a shortcut (e.g. on Desktop), right-click on it and select Open File Location.
2. In next window, right-click on the launcher executable and select Properties.
3. In next window, select Details tab.
4. Search for File Version and find the version number.