Install CMAPI 1.0.0

CMAPI 1.0.0 targets the complete Windows x64 Steam version of The Planet Crafter.

CMAPI is standalone. Players do not separately install BepInEx, a generic Unity loader, or a .NET runtime.

Requirements

• The complete game, launched normally at least once.
• The complete CMAPI Windows package, including CMAPI-Installer.exe.
• Planet Crafter and every CMAPI process closed during maintenance.

Install, update, or repair

1. Extract the CMAPI package to a temporary folder.
2. Run CMAPI-Installer.exe. Setup first verifies CMAPI-package.json and the SHA-256 of every extracted file. A missing, changed, duplicate, unsafe, or unlisted file stops setup.
3. Confirm the automatically detected game directory or browse to it.
4. Review the action offered by CMAPI Setup:
   • Install for a clean game directory;
   • Update for an older healthy receipt-owned standalone installation;
   • Repair when the installed version already matches the package, or when a receipt-owned file is missing or damaged;
   • Uninstall to remove only safely identified CMAPI-owned files.
5. Complete setup and launch through CMAPI.exe.
6. Run version and health_check in the CMAPI console.

The common Steam directory is:

C:\Program Files (x86)\Steam\steamapps\common\The Planet Crafter

Additional Steam libraries are detected. The installer refuses to overwrite an unowned root winhttp.dll or bootstrap configuration; it reports the conflict instead of guessing ownership.

Install, Update, and Repair are transactional. Setup stages and verifies the complete owned runtime, backs up the previous bytes, applies atomic replacements, and commits the new receipt last. A normal failure restores the prior install. If rollback itself is deliberately blocked, Setup preserves the exact recovery journal under CMAPI\Install\Transactions and prints its path.

Installed layout

<GameRoot>\
    Planet Crafter.exe
    CMAPI.exe
    winhttp.dll
    doorstop_config.ini
    CMAPI\
        Bootstrap\
            CMAPI.Bootstrap.dll
            Mono.Cecil.dll
        Runtime\
            CMAPI.Runtime.dll
            CMAPI.API.dll
            CMAPI.API.xml
            CMAPI.Shared.dll
            Newtonsoft.Json.dll
        Mods\
        UserData\Mods\
        Backups\
        Logs\
        CrashReports\
        config.json

UnityDoorstop is an internal CMAPI bootstrap component included in the package; players do not configure it separately.

Steam launch option

Run:

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

Paste the copied value into Steam Library → The Planet Crafter → Properties → General → Launch Options. Keep %command%; Steam replaces it with the game executable. Closing the game closes the console. Closing the console closes the game by default, so prefer the game's normal Quit action when possible.

If automatic discovery cannot find the game, pass its directory explicitly:

.\CMAPI.exe "D:\SteamLibrary\steamapps\common\The Planet Crafter"

Update from the CMAPI console launcher

After the official GitHub Pages feed is published, close Planet Crafter and run:

.\CMAPI.exe --update

CMAPI validates the feed, official release URL, package name, byte count, SHA-256, safe ZIP layout, and installed game MVID. It then opens the same Setup wizard with Update selected. No live file changes occur until you approve the wizard. If the feed is unavailable or the game build is not listed, CMAPI stops the update safely and shows the manual release path.

Choose the channel in CMAPI\config.json:

{
  "CmapiUpdateChannel": "stable"
}

Accepted values are stable and beta; the default is stable.

Install a mod

Every mod gets its own directory:

<GameRoot>\CMAPI\Mods\ExampleMod\
    manifest.json
    ExampleMod.dll
    OtherDependency.dll

Start CMAPI and use mods, modinfo <UniqueID>, and updates to inspect the installation. Mod configuration and persistent data live separately under CMAPI\UserData\Mods\<UniqueID> so replacing a mod folder does not erase them.

Preserved data and uninstall

Update, repair, and uninstall preserve:

• CMAPI\Mods;
• CMAPI\config.json;
• CMAPI\UserData;
• save backups, logs, and crash reports;
• every file not listed in CMAPI's ownership receipt.

Uninstall also refuses to delete a receipt-owned file whose contents were modified after installation. CMAPI never removes or restores unrelated loader, plugin, or user files.

Troubleshooting

Development deployments are covered by ../architecture/STANDALONE-VALIDATION.md.