Full-game environment API research

This audit targets the tested full-game Assembly-CSharp module with MVID 520dcd8f-2c13-4a99-b871-44c7ad40bcc1. The goal is a Unity-free CMAPI public contract backed by real game lifecycle and network paths.

Recommended surfaces

Weather and meteor events

PlanetData supplies decorative meteoEvents and resource-bearing meteoEventsWithAsteroids. MeteoEventData includes duration, rain emission, wetness, rain color, audio, environment volume, sky prefab, terraforming-stage bounds, and optional AsteroidEventData.

MeteoHandler synchronizes the selected event index, start time, random seed, reference position, and reference client through Netcode variables. It applies environment/audio/rain state on every peer and adds/removes the associated asteroid event.

Important constraint: selecting a new non-negative event while another is active does not run the cleanup branch used when the index becomes -1. CMAPI must refuse overlap or implement and test an orderly stop before exposing replacement. Although the game's start RPC permits every client, CMAPI should require world-host authority.

Terraforming and world units

WorldUnitsHandler exposes per-planet Oxygen, Energy, Heat, Pressure, Terraformation, Biomass, Plants, Insects, Animals, and Purification units plus system Terraformation. WorldUnit exposes total value, increase/decrease/net rates, formatted values, and unit type. These values are Netcode state and are excellent read-only public data.

TerraformStagesHandler exposes current stage, next stage, and percentage completion. TerraformStage exposes stable ID, threshold, unit type, and icon. CMAPI should wrap the stable data without leaking Unity sprites.

The game also exposes direct setters and resets. Those are progression/save mutations and should not be part of the first API version.

Day/night and visual environment

EnvironmentDayNightCycle synchronizes a 0–100 day/night lerp value from the server and has ResetToFullDay. A public snapshot and phase-change event are straightforward. Reset must be host-only and tested across clients.

EnvironmentUpdater and EnvironmentVolumeVariables can override main light, fog, skybox, clouds, ambient lighting, reflection intensity, planet color, and post-process hue. The volume stack removes entries only after their lerp reaches zero, and raw definitions contain Unity materials and colors. Arbitrary public mutation would be client-local, conflict-prone, and easy to leave behind after a mod failure or planet switch. Defer it until CMAPI has owner-scoped override handles with guaranteed restoration.

Weather additionally controls terrain wetness, rain particles, sound, and sky prefabs, which is why weather should use the game's event path instead of raw visual overrides.

Planets and travel

PlanetLoader exposes current planet, load state, and a planetIsLoaded callback. PlanetNetworkLoader exposes available planets and synchronized planet switching. PlanetUnlocker exposes unlock state and OnPlanetUnlocked.

Read-only planet definitions and load/unlock events are safe candidates. Forced travel is not: the game's operation moves players, transfers pod inventory, creates/destroys world objects, chooses landing positions, and changes Netcode state. CMAPI should not expose it until it has explicit host authority, readiness checks, a structured result, and multiplayer/travel regression tests.

Toxic areas and water

ToxicAreaHandler.GetCurrentPlanetToxicProgress already uses a server request and targeted client response. Per-area progress and completion callbacks also exist. CMAPI can wrap counts and percentages without exposing game objects or cleanup mutations.

WaterHandler.IsUnderWater(Vector3) answers whether a position is inside an active water volume after water has begun rising. A CMAPI position query is safe; the game does not expose a similarly clean general water-level setter.

Story events

StoryEventsHandler exposes event lookup by stable ID/hash and triggered-event history. Story events can deliver messages, enqueue weather, unlock groups, and notify registered game objects. Forcing an event therefore changes progression and can have one-time effects. Begin with definitions, history, and observation; do not expose activation as a casual console command.

Local-player placement

Planet Crafter's teleporter UI, portals, unstuck action, and planet loader all call PlayerMainController.SetPlayerPlacement. With teleport: true, it uses the player's NetworkTransform, synchronizes physics, resets the last grounded position used for fall damage, re-evaluates breathable/environment colliders, and forces world performer checks.

CMAPI 0.8.0 introduced that path for a guarded same-planet console command. CMAPI 0.9.0 exposes the same guarantees through IPlayerPlacementManager, with structured outcomes and one owner-scoped return point per mod. Rotation is preserved, coordinates must be finite, and planet transitions remain excluded. Cross-planet travel belongs to IPlanetManager and must not be disguised as coordinate teleporting.

Release discipline

For every new manager:

1. publish immutable, Unity-free definitions and snapshots;
2. define unavailable/no-world behavior explicitly;
3. update on the main thread and clean owner subscriptions on failed mod load;
4. add structured mutation results instead of throwing for normal game state;
5. require host authority even where a game RPC accepts any client;
6. test world exit, planet travel, save switching, host/client synchronization, and an unrecognized but structurally compatible game build;
7. ship matching XML summaries, beginner examples, commands, and release gates.

Implemented in 0.9.0

CMAPI 0.9.0 implements the safe first wave from this audit:

• IWeatherManager catalog/status and guarded host starts;
• IWorldStateManager totals, rates, and terraformation stages;
• IEnvironmentManager day/night, underwater queries, and host day reset;
• IPlanetManager current and installed/purchased planet definitions.

It deliberately retains the audit's deferrals for forced weather stopping, raw visual/material overrides, terraformation setters, forced planet travel, toxicity cleanup mutation, and story-event activation.