CMAPI — Crafter Modding API

CMAPI is an unofficial, beginner-friendly modding platform for The Planet Crafter. It is developed by SourceNine Labs and is not affiliated with or endorsed by Miju Games.

1.0 release: CMAPI 1.0.0 is the first standalone public-release line. Publish the stable asset and update-feed entry only after the exact final ZIP passes the Windows clean-install, launch, uninstall, and reinstall proof.

Runtime architecture

UnityDoorstop 4 (internal bootstrap component)
    → CMAPI.Bootstrap
        → CMAPI.Runtime
            → CMAPI mod loader
                → CMAPI/Mods

CMAPI owns the Planet Crafter runtime, lifecycle, paths, logging, console IPC, compatibility checks, services, and mod lifecycle. BepInEx is not a build, runtime, packaging, installer, or user dependency. CMAPI does not install, modify, restore, or remove unrelated BepInEx files.

The verified full-game target is Planet Crafter 2.008 with Assembly-CSharp MVID:

520dcd8f-2c13-4a99-b871-44c7ad40bcc1

Unknown builds receive member-level compatibility checks. Missing hooks disable the affected API surface with a clear diagnostic instead of silently continuing an unsafe operation.

Current platform surface

• First-party Windows launcher, live console, Steam launch option, and game/console lifetime coupling.
• Small, Planet Crafter-specific bootstrap with early validation, startup logs, and catastrophic-failure reports.
• One-folder-per-mod discovery under <GameRoot>\CMAPI\Mods, strict manifests, dependency ordering, private assembly resolution, and failed-mod cleanup.
• Versioned, Unity-free CMAPI.API.dll with XML documentation.
• Per-mod typed configuration, persistent JSON data, and disposable cache paths.
• Owner-scoped main-thread scheduling plus update and one-second game-loop events.
• Player, local inventory, recipes, unlocks, world/save/weather lifecycle, placement, notifications, item, Terra Token, environment, and planet APIs.
• Searchable command catalog and validated host-safe gameplay commands.
• Rolling pre-launch, post-exit, and manual save backups.
• Verified stable/beta framework update discovery plus informational mod update checks; both fail open when offline.
• First-party setup wizard for install, update, repair, and receipt-based uninstall while preserving mods, configuration, data, logs, and backups.
• Optional CMAPI Mod Menu 0.2.2 experimental beta, versioned separately from the runtime and excluded from the standalone-core release gate.

Player requirements

• Windows x64.
• The complete Steam version of The Planet Crafter.
• No separate .NET runtime, BepInEx installation, or generic mod loader.

Install or update CMAPI

1. Close Planet Crafter and CMAPI.
2. Extract the complete CMAPI package to a temporary folder.
3. Run CMAPI-Installer.exe.
4. Confirm the detected Planet Crafter folder.
5. Choose the action offered by the wizard. A clean game offers Install; an existing CMAPI installation offers Update, Repair, and Uninstall.
6. Launch through CMAPI.exe and run health_check in the console.

The installer verifies the complete package manifest before touching the game, refuses to overwrite an unowned root bootstrap, and rolls a failed operation back as one transaction. Uninstall removes only receipt-owned files whose hashes still match and preserves user content.

When the official Pages feed is published, close the game and run CMAPI.exe --update to download and verify a compatible release, then approve the normal Update action in Setup. CMAPI never silently updates itself.

CMAPI binaries intentionally remain beside this specific game. Moving executable DLLs into Documents would make OneDrive, redirection, and execution-policy failures part of startup. A future external layout requires a separately validated bootstrap locator; it will not be silently introduced during release hardening.

Expected installed layout:

The Planet Crafter\
├── 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\
    └── config.json

Install a mod

Put each mod in its own folder:

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

Start CMAPI and use mods and modinfo <UniqueID> to verify it.

Example manifest:

{
  "Name": "Hello Crafter",
  "Author": "Your Name",
  "Description": "Adds a friendly greeting command.",
  "Version": "1.0.0",
  "MinimumApiVersion": "1.0.0",
  "UniqueID": "YourName.HelloCrafter",
  "EntryDll": "HelloCrafter.dll",
  "UpdateKeys": [
    "GitHub:YourGitHubName/HelloCrafter"
  ]
}

UpdateKeys is optional. CMAPI reports available stable releases but does not silently replace installed mods.

Create a mod

Ordinary mods reference only CMAPI.API.dll and derive one public entry class from CMAPI.Mod:

using CMAPI;

namespace YourName.HelloCrafter
{
    public sealed class HelloCrafterMod : Mod
    {
        public override void Entry(IModHelper helper)
        {
            HelloConfig config = helper.Storage.ReadConfig<HelloConfig>();

            helper.Events.GameLoop.OneSecondTicked += tick =>
                Monitor.Debug($"CMAPI has run for {tick.RuntimeElapsed.TotalSeconds:0}s.");

            helper.ConsoleCommands.Add(
                "hello_crafter",
                "Prints a friendly greeting.",
                "hello_crafter",
                context => context.WriteLine(config.Message)
            );

            helper.Scheduler.RunOnMainThread(() =>
                Monitor.Info("Hello Crafter is ready.")
            );
        }
    }

    public sealed class HelloConfig
    {
        public string Message { get; set; } = "Hello, crafter!";
    }
}

CMAPI keeps mod configuration and data under CMAPI\UserData\Mods\<UniqueID> so mod updates do not erase them. Scheduled actions and event handlers are attributed to their owner and cleaned up if mod startup fails.

Essential diagnostics

Run commands in the live console for the complete gameplay and developer command catalog.

Build and deploy from source

Source builds need Visual Studio or a compatible current .NET SDK and a local full-game installation. Game and Unity assemblies are intentionally not committed.

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\scripts\Deploy-Dev.ps1 `
  -GamePath "C:\Program Files (x86)\Steam\steamapps\common\The Planet Crafter" `
  -Configuration Debug

Deploy-Dev.ps1 synchronizes the exact game references, builds the solution, publishes the launcher, and installs the developer runtime and Test Mod. Use -SkipBuild -SkipReferenceSync only after a successful current build.

For the official release artifact:

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

Release packaging requires a pinned UnityDoorstop 4 x64 binary, its complete LGPL-2.1 license, and exact version provenance under vendor\UnityDoorstop. The build creates a deterministic per-file package manifest, self-contained Windows archive, SHA-256 sidecar, and validated GitHub Pages update-feed fragment. It runs positive, deliberately damaged-package, and full installer-transaction gates before producing the release.

Repository layout

Release status

CMAPI and its public mod API are versioned 1.0.0. The standalone runtime, transactional setup, update feed, package integrity gates, and tested Planet Crafter 2.008 compatibility form the supported core. The optional Mod Menu keeps its separate 0.2.2 experimental-beta status and is not required for core runtime support.

The repository and final ZIP still must pass the official release checklist; compiling alone is never sufficient. The GitHub Pages documentation can be finalized against this frozen 1.0 product/API contract.

Licensing

CMAPI is licensed under the MIT License. Distributed third-party components and obligations are listed in THIRD-PARTY-NOTICES.md.