S9SourceNine Labs / CMAPI Docs 1.0
CMAPI / Migrations

Migrate from 0.6

Update a CMAPI 0.6 mod for the 0.7 API.

View source ↗
CMAPI 1.0.0Standalone runtimeWindows x64Tested with Planet Crafter 2.008

Migrate a CMAPI 0.6.x mod to 0.7.0

CMAPI 0.7.0 keeps the complete 0.6.x read-only API and adds opt-in methods. A 0.6.x mod normally continues working without source changes.

Raise MinimumApiVersion only when the mod uses the new surface:

JSON
{
  "MinimumApiVersion": "0.7.0"
}

Host-safe gameplay mutation

Item and Terra Token services now expose asynchronous mutations:

CSHARP
GameplayActionResult itemResult = await helper.Items
    .AddToLocalBackpackAsync("Iron", 2);

GameplayActionResult tokenResult = await helper.TerraTokens.AddAsync(500);

Both methods may be called from any thread. CMAPI dispatches the game work to the main thread and returns a GameplayActionResult instead of throwing for normal validation or game-state failures.

Check Succeeded for the simple path. For detailed handling, inspect Status, RequestedAmount, AppliedAmount, and Message. Stable statuses cover invalid arguments, world readiness, host authority, item lookup, capacity, overflow, game rejection, timeout, and unexpected failure.

These mutations are always host-only. The console setting which can relax its own cheat-command guard does not weaken the public mod API.

Native HUD notifications

Use helper.Notifications for general, item, or Terra Token feedback:

CSHARP
helper.Notifications.Show("Research sample catalogued.");
helper.Notifications.ShowItemAdded("Iron", 2);
helper.Notifications.ShowTerraTokensAdded(500);

Successful CMAPI mutation calls already show the matching native notification when ShowGameplayNotifications is enabled. See NOTIFICATIONS.md for queue and lifetime behavior.