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.
How the game starts depends on who keeps it up to date.
| Your own installer | Store build | |
|---|---|---|
| Installs the game | Your installer | The store client |
| Updates the game | updater.exe | The store client |
| Shortcuts start | updater.exe | core.exe |
Ship updater.exe | Yes | No |
| Crash reports and statistics | Optional | Optional |
The updater and the crash reporter need .NET Framework 4.8. The host doesn't.
Matchstick doesn't install games. Bring your own installer, such as NSIS, and have it do these steps in order:
game folder, except game/game.json.dependencies\vc2022_redist.x64.exe /install /quiet /norestart.updater.exe.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 code | Meaning |
|---|---|
0 | Installed. |
3010, 1641 | Installed, and Windows needs a restart. |
| Anything else | Failed. |
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.
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.
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.
The updater stays out of the way. If the check fails or times out, the game starts without a message.
| If | The updater |
|---|---|
| The player picks Later or cancels the download | Starts the current version. |
| The download fails or the hash doesn't match | Says so, then starts the current version. |
| The player refuses the elevation prompt | Starts the current version. |
| The installer fails | Doesn'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.
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:
| File | Contents |
|---|---|
log.txt | The game log, the crash details, and the game, Matchstick and Windows versions. |
minidump.dmp | A 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.
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.
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);| Argument | What it does |
|---|---|
-metricsport | Serves metrics to Prometheus on this port. |
-logendpoint | Streams 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.