S9SourceNine Labs / CMAPI Docs 1.0
CMAPI / Guides

Player placement

Perform bounded, same-planet, host-safe teleportation.

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

Local-player placement API

CMAPI 1.0.0 exposes the same proven, same-planet placement path used by the teleport console command without requiring mods to reference Unity or Assembly-CSharp:

CSHARP
PlayerPlacementResult result = await helper.PlayerPlacement.TeleportAsync(
    new WorldPosition(559f, 2f, 600f)
);

if (!result.Succeeded)
    Monitor.Warning($"Teleport: {result.Status} — {result.Message}");

TeleportAsync always targets the local player, always requires the current world host, accepts only finite coordinates from -1,000,000 through 1,000,000, and never changes planets. CMAPI schedules the game call on Unity's main thread and uses PlayerMainController.SetPlayerPlacement(..., teleport: true) so the game runs its native teleport placement path.

Return points

Every loaded mod gets an independent in-memory return point:

CSHARP
if (helper.PlayerPlacement.HasReturnPoint)
{
    PlayerPlacementResult back =
        await helper.PlayerPlacement.ReturnAsync();
}

A successful teleport records the origin. A successful return records the place the player just left, so repeated returns toggle between the two positions. ClearReturnPoint() discards it explicitly. CMAPI also removes the point when the owning mod fails/unloads; ReturnAsync rejects and clears a point when the local controller or planet no longer matches.

The console's teleport back point and each mod's API point are intentionally separate. One mod cannot overwrite another mod's recovery state.

Structured outcomes

PlayerPlacementResult provides Status, Message, Origin, Destination, and the convenience Succeeded property. Treat these as normal outcomes:

Status Meaning
Success The native placement call completed.
InvalidCoordinates A component was NaN, infinite, or outside the safe bound.
WorldNotReady No usable local player/current planet exists yet.
HostRequired A joining client attempted placement.
NoReturnPoint This mod has not recorded an origin.
PlayerChanged The recorded point belongs to an earlier player session.
PlanetChanged The recorded point belongs to a different planet.
OwnerInactive The requesting mod is no longer active.
GameRejected Planet Crafter threw while applying otherwise valid placement.
TimedOut CMAPI could not reach the game main thread within ten seconds.
Failed An unexpected compatibility/runtime error occurred.

Origin and Destination are nullable because a rejected request may fail before CMAPI can safely read one or both positions.

Safety rules

  • Use known-safe coordinates and give players a recovery action.
  • Do not treat placement as vehicle movement or planet travel.
  • Do not teleport remote players; CMAPI does not expose that authority surface.
  • Await the task and handle every status instead of assuming the next frame contains the player at the destination.
  • Test host, joining-client, world-exit, player replacement, and planet-change paths on a disposable backed-up save.