Gessa Docs
Recipes

Recipe

Spawn points checkpoints and respawn flow

Players need a place to start, checkpoints to save progress mid-level, and a way back after death or a fall. The player's start and respawn are NOT a script: a spawn location is a SpawnPointComponent entity and the character policy spawns and respawns the body. Checkpoints and the death-return are the script pattern, authored as durable state plus a handler.
engine v1.0.234since script-semantic-patch-ops.v1, action-catalog.v1.0.232, persistence.v1, prefabs.v1Copy for LLM

Use this for

placing where players start; save-point checkpoints; sending a dead or fallen player back to the last checkpoint; spawning entities from a prefab or template

Not for

matchmaking room placement (see multiplayer-replication-and-rooms); health and death rules (see combat-damage-and-respawn)

Pairs with: Combat damage health and respawn scripting, Saves persistence player progress and data stores, Physics colliders rigid bodies triggers and joints

The recipe

  1. Player spawns: place Spawn Point entities, the spawn_point preset (a TransformComponent for the location and facing plus a SpawnPointComponent). Set the component's teamKey for a per-team spawn and its priority and spread radius so simultaneous spawns do not overlap. The game's character policy spawns a body for every seat that joins, its spawn selector chooses among the eligible points, and its respawn rule brings an eliminated player back. You do not script the initial player spawn (see player-characters-and-spawns and teams-and-team-play).
  2. Seed the checkpoint position as durable state: writeTypedStateValue { "storeKey":"progress", "recordKey":"player", "field":"checkpoint", "valueType":"vector3", "value": <start position> }.
  3. Place checkpoint entities with a trigger ColliderComponent (collision:"trigger"). On cross, react with addTriggerHandler { "handlerKey":"onCheckpoint" } and inside it writeTypedStateValue the new checkpoint position (read the checkpoint entity's transform in a GessaScript body via ctx.entity.readComponent if you need exact coordinates).
  4. Return on death: from the death handler (see combat-damage-and-respawn), readTypedStateValue the checkpoint into a binding, then teleport the player from a GessaScript body with ctx.world.teleportPlayer. To place a fresh non-player entity instead, spawnEntityFromTemplate { "scope":{...}, "prefabKey": <prefab key>, "config": { ...inline overrides } }.

Pitfalls

  • A player's spawn point is a SpawnPointComponent entity, not a tagged capsule you spawn from in a script; the character policy reads it. Keep the player spawn (component plus policy) and the checkpoint save (durable state plus a handler) as two separate concerns.
  • spawnEntityFromTemplate requires EITHER templateKey OR prefabKey, and its config values must be validated inline literals, not arbitrary JSON.
  • Spawn and teleport ops carry requiresAuthority; they run on the server authority, not the client.
  • Storing the checkpoint as vector3 state (not on a component) is what makes it survive death and reload; a position written only on the entity is lost when the entity despawns.
  • ctx.world.teleportPlayer is gated by worlds.teleport_authority; use it for the player, spawnEntityFromTemplate for fresh entities.

Verify

  • simulation_run to prove crossing a checkpoint updates the stored position and death returns the player there.
  • project_get_graph_snapshot to confirm the Spawn Point entities and the checkpoint triggers exist.
Was this helpful?Report an issueContact support

On this page