Skip to content

The Launcher

Emanuele Manzione edited this page May 18, 2023 · 24 revisions

The Launcher (or Updater, both the terms can be used interchangeably) is what your user will run to update the game. It requires an initial configuration in order to work.

Initialization

I will refer to the Launcher scene in MHLab/Patch/Launcher/Scenes, but the configuration is similar for other clients (WPF, WinForms, etc).

To configure it, just find the LauncherData game object: it contains a LauncherData component. It should look like this:

Launcher data

Here you must set some information:

  • Remote URL: the HTTP address where you uploaded files previously
  • Launcher Executable Name: the name of your Launcher executable, with the extension. In the screenshot you can see an example related to Windows's exe.
  • Game Executable Name: the name of your game executable, with the extension.

Other settings you see in the screenshot are just for UI management.

Hint

If you need to deeper customize settings, take a look at the LauncherBase.cs script, in CreateSettings method. The LauncherSettings instance exposes multiple customizable settings you can tune to fit your needs. Launcher.cs and LauncherUpdater.cs scripts also expose a method to configure settings: OverrideSettings. You can customize settings only for Launcher or PreGame in this method.

Initialization on WPF

The WPF integration of PATCH can be found at Assets\MHLab\Patch\Launcher as MHLab.Patch.Launcher.Wpf.7z archive (for Basic) and at Assets\MHLab\Patch as MHLab.Patch.7z (for Plus). Extract the project somewhere and open it with your IDE. You are now read to customize it.

Basic version additional step

If you own the Basic version, you will need to add the two DLLs (MHLab.Patch.Core.Client.dll and MHLab.Patch.Core.dll, contained in the archive) as dependencies of your project. To add them as dependencies, just right click on Dependencies and select Add dependency, then browse for those DLLs. Also, you will need to remove these two project dependencies from the project:

image

To customize the options of your WPF Launcher, you can set Remote URL and other settings in MainWindow.xaml.cs in CreateSettings method.

Customization

Launcher and other scenes are just samples: you're encouraged to customize them. Also the Launcher.cs script is just a minimal sample of what you can do with the PATCH's API: feel free to edit it.

The UI can be trivially customized with the Unity UI system (or with Visual Studio if you're using the WPF version).

First launcher update

When you are satisfied of your Launcher, it's time to build it as I explained here. Place built files in Updater folder in your PATCH's workspace then go to Admin Tool > Launcher.

Here just insert the Launcher archive name and the Compression level and hit Build Launcher update.

Commandline equivalent

Run the command .\MHLab.Patch.Admin.exe launcherUpdate

When the process completes you will notice a new file in Updater folder: updater_index.json. It contains metadata for the Launcher update. PATCH also generated a compressed archive (it is in the root folder of PATCH workspace) that contains your Launcher, ready to be distributed to the clients.

Uploading the first update

Just upload the whole Updater folder to your web server. That's it! :)

Hint

Assuming your remote root is http://localhost/patch/, after the uploading we should be able to see the Updater folder at http://localhost/patch/Updater and with the browser we should be able to navigate to http://localhost/patch/Updater/updater_index.json.

Testing the Launcher

If you want to test the Launcher, just create a new folder and extract inside it the content of the Launcher compressed archive. Don't run your Launcher inside the Updater folder! The same is valid for game builds while they are in the Builds folder: don't run them directly!

Run the extracted executable and check that everything is acting like you expect!

After the first run, your Launcher downloaded your game in the Game subfolder. From now on you can run directly your game: the PreGame scene will check if any update is available and - if so - it will run the Launcher for updates.

Settings Overriding

Some settings can be changed for an already compiled Launcher just by creating a settings.json file near to your Launcher executable and declaring options you want to override. The content of the settings.json file should look like this:

{
   "DebugMode": true,
   "PatcherUpdaterSafeMode": true
}

This is the list of the available options you can regulate:

  • DebugMode: enables the Debug Mode. You can find more information about it here.
  • PatcherUpdaterSafeMode: enables the Launcher's Safe Mode. It's a way to force the Launcher to replace itself with an arbitrary package that you can define on your server. The replacing will happen without any further questioning or check from the Launcher. This has the purpose of offering a way to fix Launchers that cannot self-update because of fatal errors/bugs in the previous self-update. Find more here.

Having a settings.json file is optional. If the Launcher does not find it, default settings will be used. You can also customize and expand settings, just read how to do it here.