1. Index
  2. Customizing Launcher

Customizing Launcher

This feature requires Custom Launcher to be enabled on your account. Please check your account page if it already is. If not, change your plan or send us a message.

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:

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

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

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

Installation

If you are starting from scratch:

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

Updating

To update, bump the patchkit_* entries in the package.json file to their latest version.

Running the Development Environment

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

Interface Overview

  1. The top bar contains a set of buttons that allow you to simulate the call of specific actions in the launcher.
  2. Below it (in the center), you can find the preview of your theme.
  3. At the bottom, there’s an editor for the state data loaded into the theme. Modifying them affects the content.

:::warning Simulated actions do not terminate automatically. When you trigger an action in the launcher, such as clicking the INSTALL button, you may think it has crashed. You have to terminate it manually using buttons (e.g., finishAppBranchOngoingInstallTaskStep). :::

Modifying the Theme

:::warning By default, the theme is set to the not initialized state. This is the state where the launcher theme is being displayed to the user, but the launcher still needs some time to load all the required data. Feel free to customize this view and switch to the initialized state by setting State > isInitialized to true in the data editor. :::

You can modify the theme by editing files in the src directory using your favorite code editor. The included example theme is based on React, and all React rules apply here.

:::info You can build launcher themes on any technology, not just React. :::

:::info In the example, all components are styled inline, and there are no external stylesheets. However, you can use external stylesheets freely if you prefer! You might need to update the scripts/core/_get_app_webpack_config.ts file. :::

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

Example:


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

  overflow: `auto`,
{{
  height: `100%`,
  flexBasis: `60px`,
  flexGrow: 0,
  flexShrink: 0,
  paddingLeft: `10px`,

  overflow: `auto`,
{% end %}
}}

For more complex styling, you can import the emotion package:

import emotion = require('emotion');

This allows you 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. For example, if you want to change the overall background color or round the corners, this is the right place to do it.

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 various places with slightly modified variations. Be cautious when making changes to these components, as it can lead to unpredictable behavior of other components that rely on them.

All components containing app_branch in their name are backend-related components. Modify those only if you are sure that it will not break the launcher functionality.

:::info We recommend using version control systems (VCS) like Git and committing your code frequently. This way, you can track any breaking changes more easily. :::

Examples

Changing the Background Color of the Launcher

To change the main background color, modify the window_widget.tsx file:

88. backgroundColor: `lightblue`,

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

43. backgroundColor: `lightblue`,

Changing the popup background color

To change the popup background color, modify the popup_widget.tsx file:

48. backgroundColor: `lightblue`,

Centering the INSTALL/PLAY Button

In the app_branch_widget.tsx file, add centering style to the parent div of the AppBranchStateWidget component:

91. display: `flex`,
92. justifyContent: `center`,

The code should look like this:

{% raw %}
<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

Change the isVisible flag to false in the start_app_branch_widget.tsx file:


68. checkForUpdatesButtonWidget={{
69.   isVisible: false,
70. }}

Adding the Application Name Next to Its Icon

In the window_widget.tsx file, around the line 126, there is a component responsible for displaying application icons in the left menu. Its children iteratively return the icon of each application. To add the application name next to its icon, you can use the appState object.


<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 get information about the application name, we can use the appState object.

You should change: (pseudocode)

<AppIcon />

into:

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

The text is too wide and cannot fit inside the bar. To fix this issue, apply some styling:

  1. Around the line 140, increase the flexBasis value to widen the entire bar.
  2. Modify the icon styling:

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

The text will not respond to clicks because the onClick action is only attached to the icon. To include the text, move the onClick action up a level:


<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 deployment process is currently in beta and some of its elements may be different than described. If you encounter any issues, please contact us.

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. You can learn how to do this by navigating to the Launcher Themes page.

Frequently Asked Questions (FAQ)

Q1: Can I use a different front-end framework or library other than React for my custom launcher theme?

Yes, you can use any front-end framework or library, or even build your launcher theme from scratch. The example provided uses React, but you’re not limited to using React.

Q2: How can I integrate custom logic or user authentication before allowing a user to install or update a game?

You can add custom logic by modifying the relevant components in the SDK, such as the app_branch_widget.tsx file. Implement the desired logic within the component and make sure the launcher functionality isn’t affected.

Q3: Can I use CSS modules or external stylesheets instead of inline styling?

Yes, you can use external stylesheets or CSS modules. To include them, you might need to update the scripts/core/_get_app_webpack_config.ts file to properly load and apply the styles.

Q4: Can I use a different JavaScript/TypeScript bundler instead of Webpack?

Yes, you can use a different bundler if you prefer. However, you will need to configure it correctly to work with the Electron Launcher SDK and ensure compatibility with all dependencies.

Q5: What should I do if I encounter an issue or bug with the Electron Launcher SDK?

If you encounter an issue or bug, first ensure that you have the latest version of the SDK. If the issue persists, consult the documentation and relevant online resources. If you still cannot resolve the issue, consider contacting the SDK support team for assistance.

Q6: How can I test my custom launcher theme on different operating systems and devices?

Since the launcher is built on the Chromium web engine, it should work consistently across different operating systems and devices that support Chromium. However, to ensure compatibility and optimal user experience, it’s recommended to test your custom theme on various devices and operating systems.

Q7: How do I deploy my custom launcher theme?

To deploy your custom launcher theme, you need to build the launcher theme and upload it to your dashboard. Please refer to the Deploying section for more information.

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!

Did this page help you? If you have any questions, don't hesitate and contact us.

Copyright © 2015 - 2022 Upsoft
All Rights Reserved.