Distributing a game

Matchstick can keep an installed game up to date, report its crashes, and send you gameplay statistics. Each feature is optional, and each talks to a service you run.

You will learn

  • Which programs to ship for a store build and for your own installer
  • What your installer has to do
  • How to publish an update
  • How to collect crash reports
  • How to record statistics and metrics

Choose how you ship

How the game starts depends on who keeps it up to date.

Your own installer Shortcut updater.exe checks for an update Store Store client core.exe runs the game crash crashreporter.exe offers to send a report
Your own installerStore build
Installs the gameYour installerThe store client
Updates the gameupdater.exeThe store client
Shortcuts startupdater.execore.exe
Ship updater.exeYesNo
Crash reports and statisticsOptionalOptional

The updater and the crash reporter need .NET Framework 4.8. The host doesn't.

Write an installer

Matchstick doesn't install games. Bring your own installer, such as NSIS, and have it do these steps in order:

  1. Copy the runtime and the game folder, except game/game.json.
  2. Run dependencies\vc2022_redist.x64.exe /install /quiet /norestart.
  3. Install .NET Framework 4.8 if it is missing.
  4. Create shortcuts that start updater.exe.
  5. Register the uninstaller.
  6. Write game/game.json.

PitfallWrite game.json last. The updater reads its version to decide whether an install finished. If any step fails, exit with a non-zero code and leave the old file alone.

The updater runs your installer and reads its exit code:

Exit codeMeaning
0Installed.
3010, 1641Installed, and Windows needs a restart.
Anything elseFailed.

The updater starts the installer without elevation. If the installer needs administrator rights, it has to ask for them itself. In NSIS that is RequestExecutionLevel admin. Don't run updater.exe itself as administrator. It refuses to start the game.

A complete NSIS script

Put the runtime zip's contents in runtime, your game in game, and the .NET Framework 4.8 web installer (ndp48-web.exe) beside the script. Build it with makensis /DGAME_VERSION=1.2.3 installer.nsi.

!include "MUI2.nsh"
!include "FileFunc.nsh"
!include "LogicLib.nsh"

!ifndef GAME_VERSION
  !error "GAME_VERSION is required"
!endif
!define UNINSTALL_KEY "Software\Microsoft\Windows\CurrentVersion\Uninstall\NewGame"

Name "New Game"
OutFile "NewGameSetup.exe"
InstallDir "$PROGRAMFILES64\NewGame"
InstallDirRegKey HKLM "${UNINSTALL_KEY}" "InstallLocation"
RequestExecutionLevel admin

!insertmacro MUI_PAGE_DIRECTORY
!insertmacro MUI_PAGE_INSTFILES
!insertmacro MUI_UNPAGE_CONFIRM
!insertmacro MUI_UNPAGE_INSTFILES
!insertmacro MUI_LANGUAGE "English"

; Stop with exit code 4 if the last step failed.
!macro CheckInstallStep
  IfErrors 0 +3
    SetErrorLevel 4
    Quit
!macroend

Function .onInit
  SetRegView 64
  SetShellVarContext all
  InitPluginsDir
FunctionEnd

Section "Install New Game"
  ; The updater and the crash reporter need .NET Framework 4.8.
  ReadRegDWORD $0 HKLM "SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full" "Release"
  ${If} $0 < 528040
    SetOutPath "$PLUGINSDIR"
    File "ndp48-web.exe"
    ExecWait '"$PLUGINSDIR\ndp48-web.exe" /q /norestart' $0
    ${If} $0 == 3010
    ${OrIf} $0 == 1641
      SetRebootFlag true
    ${ElseIf} $0 != 0
      IfSilent +2
        MessageBox MB_OK|MB_ICONSTOP "Cannot install .NET Framework 4.8. Setup will stop."
      SetErrorLevel 2
      Quit
    ${EndIf}
  ${EndIf}

  ClearErrors
  SetOutPath "$INSTDIR"
  File /r "runtime\*"
  !insertmacro CheckInstallStep
  ExecWait '"$INSTDIR\dependencies\vc2022_redist.x64.exe" /install /quiet /norestart' $0
  !insertmacro CheckInstallStep
  ${If} $0 == 3010
    SetRebootFlag true
  ${ElseIf} $0 != 0
  ${AndIf} $0 != 1638
    IfSilent +2
      MessageBox MB_OK|MB_ICONSTOP "Cannot install the Visual C++ runtime. Setup will stop."
    SetErrorLevel 3
    Quit
  ${EndIf}

  SetOutPath "$INSTDIR\game"
  File /r /x game.json "game\*"
  !insertmacro CheckInstallStep

  SetOutPath "$INSTDIR"
  WriteUninstaller "$INSTDIR\Uninstall.exe"
  CreateDirectory "$SMPROGRAMS\New Game"
  CreateShortcut "$SMPROGRAMS\New Game\New Game.lnk" "$INSTDIR\updater.exe"
  CreateShortcut "$DESKTOP\New Game.lnk" "$INSTDIR\updater.exe"
  CreateShortcut "$SMPROGRAMS\New Game\Uninstall.lnk" "$INSTDIR\Uninstall.exe"
  WriteRegStr HKLM "${UNINSTALL_KEY}" "DisplayName" "New Game"
  WriteRegStr HKLM "${UNINSTALL_KEY}" "DisplayVersion" "${GAME_VERSION}"
  WriteRegStr HKLM "${UNINSTALL_KEY}" "InstallLocation" "$INSTDIR"
  WriteRegStr HKLM "${UNINSTALL_KEY}" "UninstallString" '$\"$INSTDIR\Uninstall.exe$\"'
  WriteRegStr HKLM "${UNINSTALL_KEY}" "QuietUninstallString" '$\"$INSTDIR\Uninstall.exe$\" /S'
  WriteRegDWORD HKLM "${UNINSTALL_KEY}" "NoModify" 1
  WriteRegDWORD HKLM "${UNINSTALL_KEY}" "NoRepair" 1
  !insertmacro CheckInstallStep
  ${GetSize} "$INSTDIR" "/S=0K" $0 $1 $2
  WriteRegDWORD HKLM "${UNINSTALL_KEY}" "EstimatedSize" $0
  !insertmacro CheckInstallStep

  ; game.json marks a complete install. Write it last.
  SetOutPath "$INSTDIR\game"
  File "game\game.json"
  !insertmacro CheckInstallStep
SectionEnd

Function un.onInit
  SetRegView 64
  SetShellVarContext all
FunctionEnd

Section "Uninstall"
  Delete "$DESKTOP\New Game.lnk"
  RMDir /r "$SMPROGRAMS\New Game"
  DeleteRegKey HKLM "${UNINSTALL_KEY}"
  RMDir /r "$INSTDIR"
SectionEnd

The Visual C++ installer returns 1638 when a newer runtime is already there. The script treats that as success.

Publish updates

Add updateService to game.json. Every time the game starts, the updater sends a GET request to that URL and expects a description of the newest version:

{
  "version": "1.2.3",
  "installerUrl": "https://www.example.com/NewGameSetup_1.2.3.exe",
  "sha256": "<64 hexadecimal digits>",
  "installerArguments": ["/S", "/D={installDir}"]
}

The updater passes installerArguments to your installer and replaces {installDir} with the install folder.

A static JSON file on a web server is enough. To release an update, upload the new installer and edit the file.

Check GET updateService Ask Update now / Later Download verify SHA-256 Install run your installer Start new version nothing newer Later download failed Start current version

The updater stays out of the way. If the check fails or times out, the game starts without a message.

IfThe updater
The player picks Later or cancels the downloadStarts the current version.
The download fails or the hash doesn't matchSays so, then starts the current version.
The player refuses the elevation promptStarts the current version.
The installer failsDoesn't start the game. On the next run it offers to repair the install.

NoteBoth URLs must use HTTPS. The updater checks the installer's SHA-256 hash, not its signature. For testing, plain HTTP to 127.0.0.1 is allowed.

See the update service reference for the fields, limits and timeouts.

Collect crash reports

Add crashReportService to game.json and ship crashreporter.exe beside core.exe. Add privacyPolicy and the dialog links to it.

{
    "crashReportService": "https://www.example.com/api/crashes",
    "privacyPolicy": "https://www.example.com/privacy"
}

When the game crashes, the player sees a dialog with the error and two buttons: Send report and Don't send. Nothing leaves the machine unless they choose to send.

A report is a zip file with two entries:

FileContents
log.txtThe game log, the crash details, and the game, Matchstick and Windows versions.
minidump.dmpA minidump of core.exe, when one is available.

Three things count as a crash: an unhandled exception, a call to FatalError, and core.exe exiting with an exception status code. A normal exit never shows the dialog.

For automated tests, start the host with -hideerrors. It suppresses the dialog and keeps the minidump in the user data folder instead.

See the crash report service reference for the requests your service has to answer.

Record statistics

Statistics are events from a play session, such as a level starting or a boss going down. Add statisticsService to game.json, then push values from the sim thread.

MGDF::ComObject<IMGDFStatisticsManager> statistics;
host->GetStatistics(statistics.Assign());
// Does nothing unless game.json names a statistics service.
// The last argument takes optional tags.
statistics->PushString("level_started", "caves", nullptr);

The host batches the values and posts them as JSON. Each one carries a timestamp and the session's id. See the statistics service reference for the format.

PitfallMatchstick doesn't ask the player for consent. That is your job. Ask, remember the answer, and push nothing until the player agrees.

Watch performance

Metrics are numbers you sample while the game runs, such as frame time or entity count. Create one, record to it, and the host exposes it to Prometheus.

// Create the metric once and keep it
host->CreateGaugeMetric("entities", "Live entity count", _entities.Assign());

// Record a value whenever it changes
_entities->Record(static_cast<double>(_world.Count()), nullptr);
ArgumentWhat it does
-metricsportServes metrics to Prometheus on this port.
-logendpointStreams the log to a Loki server.

Counters and histograms work the same way. You can also time code with CreateCPUCounter, and time GPU work with a GPU counter.

Next steps