Migrate a CMAPI 0.8.x mod to 0.9.0

CMAPI 0.9.0 keeps the complete 0.8.x public API. Existing player, event, command, notification, item, and Terra Token code does not need to change.

Manifest

Set the minimum version to 0.9.0 only if the mod uses a new environment type:

"MinimumApiVersion": "0.9.0"

A mod which uses only 0.8 APIs should retain its older minimum so compatible players are not forced to update CMAPI unnecessarily.

New helper properties

IModHelper adds five services:

helper.Weather
helper.WorldState
helper.Environment
helper.Planets
helper.PlayerPlacement

These are additive interface members. Rebuild a 0.8 mod against CMAPI.API.dll 0.9 before accessing them. Mods compiled against the 0.8 API continue to load because their existing member references are unchanged.

PlayerPlacement exposes host-only TeleportAsync and ReturnAsync with PlayerPlacementResult. It never performs planet travel and keeps a separate in-memory return point for each mod. See PLAYER-PLACEMENT-API.md.

Structured environment results

Weather starts and daylight resets return Task<EnvironmentActionResult>. They do not use GameplayActionResult, since quantities, partial item grants, and inventory-specific statuses do not apply.

EnvironmentActionResult result =
    await helper.Weather.StartAsync("ExactWeatherAssetId");

if (!result.Succeeded)
    Log($"{result.Status}: {result.Message}");

Public mutations are always host-only, even when a player disables the console setting RequireHostForCheatCommands.

Handle EnvironmentActionStatus.UnsupportedGameBuild as a normal feature- disable result. On a game update missing required hooks, CMAPI keeps loading mods but returns unavailable/empty environment snapshots and refuses mutations without calling incompatible game code.

Snapshot behavior

Weather, world-state, planet, and environment data is returned as immutable snapshots. A snapshot does not update itself. Read the property or call GetSnapshot() again when current state matters.

At the title screen or during travel:

• helper.Weather.Events can be empty;
• helper.Weather.Status.IsAvailable can be false;
• helper.WorldState.GetSnapshot().IsAvailable can be false;
• helper.Environment.GetSnapshot().IsAvailable can be false;
• helper.Planets.CurrentPlanet can be null.

These are normal lifecycle states, not exceptions.

Command discovery change

commands <search> now checks a command provider's Unique ID in addition to its name. A search like commands SourceNine therefore finds commands owned by SourceNineLabs.* even when the displayed mod name does not contain that text.

The console now colors structured command output for readability. Command text sent through the API remains plain and redirected output remains plain, so mods must not emit ANSI escape sequences.

Recommended testing

Follow TESTING.md, especially the active-weather overlap, terraformation-boundary, host/client, planet-travel, and world-exit cases. See ENVIRONMENT-API.md for the full contracts and examples.