Steam launching, shutdown, and save backups

CMAPI 1.0.0 can be the normal Steam launch path for The Planet Crafter. It also keeps rolling snapshots of the game's save files before and after a session.

Make Steam launch through CMAPI

Run this once from PowerShell in the game folder:

.\CMAPI.exe --steam-launch-option

CMAPI prints the exact option and copies it to the Windows clipboard. In Steam, open Library → The Planet Crafter → Properties → General → Launch Options and paste it. The result normally looks like:

"C:\Program Files (x86)\Steam\steamapps\common\The Planet Crafter\CMAPI.exe" %command%

%command% is required. Steam replaces it with the game executable and any Steam arguments. CMAPI forwards those arguments unchanged.

Source developers can instead run:

.\scripts\Configure-SteamLaunch.ps1 `
  -GamePath "C:\Program Files (x86)\Steam\steamapps\common\The Planet Crafter"

Coupled lifetime

The default behavior is:

closing the game closes CMAPI after the post-exit backup;
pressing Ctrl+C in CMAPI asks the game to close normally, waits up to 15 seconds, then ends the process only if it did not respond;
closing the CMAPI window directly also closes the game through a Windows Job Object.

Closing the console window is an emergency-style hard shutdown: Windows may terminate the game before its current unsaved progress is written. CMAPI's pre-launch backup protects the previous saved state, but it cannot preserve progress that the game has never saved. Prefer closing from the game menu.

These settings are available in <GameRoot>\CMAPI\config.json:

{
  "CloseConsoleWithGame": true,
  "CloseGameWithConsole": true
}

Set either value to false to decouple that direction.

Automatic backups

By default, CMAPI snapshots every top-level .json and .sav file from the game's LocalLow save directory:

immediately before launching the game;
after the game process exits;
after the game finishes a save requested by backup create.

Archives are stored under:

<GameRoot>\CMAPI\Backups

Each ZIP includes the save files plus cmapi-backup.json, which records the backup phase, UTC time, CMAPI/game versions, loaded mods when available, and file list. The newest 20 archives are retained by default.

Configuration:

{
  "CreatePreLaunchBackup": true,
  "CreatePostExitBackup": true,
  "BackupRetentionCount": 20
}

Retention accepts 1–100. Backup failure is reported as a warning and never prevents the game from starting or closing.

List and create backups

While the game is running:

backups
backup
backup create

backup create first asks the game to save normally. CMAPI waits for the game's OnSaved callback and snapshots only after it fires, so the archive is not captured halfway through a game save.

While the game is closed:

.\CMAPI.exe --list-backups

Restore a backup

Close the game, then pass a filename shown by --list-backups:

.\CMAPI.exe --restore-backup "cmapi-20260821T120000000Z-manual.zip"

CMAPI refuses to restore while Planet Crafter is running. Before overwriting any matching save files, it takes a pre-restore snapshot of the current save directory. Restore accepts only CMAPI backup ZIPs inside CMAPI\Backups, only extracts flat .json/.sav save entries, rejects path traversal and duplicate entries, and leaves unrelated save files untouched.

Backups are protection against accidental corruption, not a replacement for copying important saves somewhere outside the game directory before major mod testing.

Steam and save backups