# GET /snapshot

> Talos 0.7 · Since 0.6

## Response

#### Response: `WorldStateView`

Everything needed to restore the world to this frame.

| Field | Type | Present | Description |
|---|---|---|---|
| `frame` | `integer` | always | The frame this state was captured at. |
| `time` | `number` | always | Simulated seconds since the scene loaded. `frame` multiplied by the fixed timestep; carried so a snapshot lines up with the `time` on an event without the client doing arithmetic. |
| `rng_seed` | `integer` | always | The deterministic RNG seed in effect. |
| `entities` | `EntityStateView[]` | always | Every entity's restorable state. |
| `hud` | `Props` | always | HUD fields the scene's `hud` components are showing. Values are strings or numbers; a field with no value is omitted rather than set to null. |
| `goals` | `GoalStateView[]` | always | Goal progress, in declaration order. |
| `opaque` | `OpaqueState` | sometimes | Solver state the physics backend cannot rebuild from transforms and velocities alone — contact islands, sleeping flags, warm-start impulses. |
| `session_paused` | `boolean` | sometimes | Whether `ctx.session.pause()` was holding the world. Absent when it was not. A held world counts frames without advancing `time`, so a capture taken after a pause has `time` behind `frame` × the timestep, and a restore keeps that `time` rather than recomputing it. |
| `instances` | `InstancesStateView[]` | sometimes | What the run changed in each instanced mesh since load: instances a behaviour added, moved or removed, by stable id. Absent when nothing was changed, so a world without instanced meshes, or one whose instances stood still, snapshots exactly as before they existed. |
| `nav_live` | `NavLiveStateView` | sometimes | A `meta.nav.live` navmesh rebuild that was waiting for its install tick, so a restore installs the same navmeshes on the same ticks as the run it was taken from (multiplayer resync, a lockstep rewind). |
| `spawned` | `SpawnedDefView[]` | sometimes | The definition of every entity a behaviour spawned at run time and that is alive, ascending by id. Absent when nothing was spawned, so a world that never spawned snapshots exactly as before this existed. |
| `spawn_counts` | `{ string: integer }` | sometimes | Per source id, how many ids `ctx.world.spawn({ like })` has derived from it (`like#N`), so a copy spawned after a restore, in this world or a fresh one (a late joiner), gets the id it got in the run that never restored. Present whenever anything was spawned or counted. |
| `npc` | `NpcWorldStateView` | sometimes | The NPC types' simulations: per type an opaque runtime that resumes it exactly and what each NPC is doing, plus what scripts asked of the NPCs that their next tick applies. Absent in a world without NPC types; a snapshot without it restores its NPCs as a fresh load starts them. |
| `crowd` | `CrowdWorldStateView` | sometimes | The world's crowd: what each navagent is doing and, for the Rust crowd, an opaque runtime that resumes it exactly. Absent without navagents; a snapshot without it puts each agent back where its entity stands and plans its target again. |
| `road_progress` | `RoadTrackView[]` | sometimes | Every entity `ctx.world.road(id).progress(entity)` is tracking: road by road in id order, each road's in the order its tracking started. Absent when nothing is tracked; a snapshot without it restores with nothing tracked, and tracking starts again at the next `progress`. |

#### Response: `CrowdWorldStateView`

A world's crowd (`WorldStateView::crowd`).

| Field | Type | Present | Description |
|---|---|---|---|
| `agents` | `CrowdAgentView[]` | sometimes | Each navagent, by its scene id, ascending. |
| `runtime` | `OpaqueState` | sometimes | `argus-nav`'s runtime of the Rust crowd; missing or of another version, the agents are put back from their summaries. |

#### Response: `CrowdAgentView`

One navagent as a reader sees it.

| Field | Type | Present | Description |
|---|---|---|---|
| `id` | `string` | always | The agent's scene id. |
| `position` | `number[3]` | always | Where it stands. |
| `velocity` | `number[3]` | always | How it is moving, m/s. |
| `target` | `number[3]` | sometimes | Where `ctx.nav.goTo` last sent it, on the navmesh. |
| `arrived` | `boolean` | sometimes | It reached its target. |
| `stuck` | `boolean` | sometimes | It has not closed on its target for three seconds, or cannot reach it. |

#### Response: `OpaqueState`

Backend state a snapshot carries but nothing outside the backend interprets.

| Field | Type | Present | Description |
|---|---|---|---|
| `backend` | `string` | always | Which backend wrote this, e.g. `rapier3d`. A snapshot is only restorable into the same one. |
| `version` | `integer` | always | The backend's format version. A mismatch means the blob cannot be restored. |
| `data` | `string` | always | The blob, base64. |

#### Response: `EntityStateView`

One entity's restorable state.

| Field | Type | Present | Description |
|---|---|---|---|
| `id` | `string` | always | The entity's stable scene id. |
| `name` | `string` | always | Human-readable label, so a snapshot reads without a second call to `/entities`. |
| `tags` | `Tags` | sometimes | Scene tags. Omitted when the entity has none. |
| `position` | `number[3]` | always | World-space position. |
| `rotation` | `number[4]` | always | World-space rotation, `[x, y, z, w]`. |
| `scale` | `number[3]` | always | Local scale. |
| `velocity` | `Velocity` | sometimes | Linear and angular velocity. Absent for an entity with no rigid body, which is not the same thing as a rigid body at rest. |
| `script` | `ScriptStateView` | sometimes | The behavior's `ctx.state`, if it has one. |
| `anim` | `AnimStateView` | sometimes | Animator playhead, if it has one. |
| `overrides` | `{ string: Props }` | sometimes | What a behavior has written over this entity's components with `entity.set`, by component type. Omitted for an entity nothing has written to, which is almost all of them. |
| `reparent` | `ReparentView` | sometimes | Where a behaviour moved this entity with `entity.setParent`, when that is not the parent the scene gave it. Omitted for every entity still where the scene put it; a restore that omits it puts the entity back under the scene's parent. |
| `controller` | `ControllerStateView` | sometimes | The character controller's state between ticks, for an entity with a `controller`. A restore that omits it (a snapshot from an older build) puts a character that was resting back on its floor and leaves one rising or falling in the air. |

#### Response: `AnimStateView`

One animator's restorable playhead, what gates gameplay, and its exact runtime .

| Field | Type | Present | Description |
|---|---|---|---|
| `state` | `string` | always | Current state machine state. |
| `time` | `number` | always | Playhead in seconds. |
| `once` | `string` | sometimes | The one-shot playing (`ctx.animator.play`). Absent when none is. |
| `layers` | `AnimLayerStateView[]` | sometimes | Each declared layer: its name, state and one-shot. Absent with no layers. |
| `speed` | `number` | sometimes | The animator-wide playback rate when it is not 1 (0 is a hit-stop). |
| `windows` | `string[]` | sometimes | The animation event windows open now (an attack's hit window). |
| `runtime` | `OpaqueState` | sometimes | The animator's exact runtime (backend `argus-animator`); hand it back as it is. Missing or of another version, a restore uses `state` and `time` only. |

#### Response: `ControllerStateView`

A character controller's state between ticks, past its position and heading: what lets a restored character step exactly as the one saved. Entities are named by scene id.

| Field | Type | Present | Description |
|---|---|---|---|
| `velocity` | `number[3]` | always | The character's own velocity, without the speed it carries from ground it left. |
| `carry` | `number[3]` | always | Horizontal speed kept from moving ground the character jumped or walked off. |
| `pitch` | `number` | always | Look pitch, radians. |
| `grounded` | `boolean` | always | Standing on walkable ground. |
| `crouching` | `boolean` | always | Crouched (the shorter capsule). |
| `groundNormal` | `number[3]` | always | The ground's normal under the character. |
| `ground` | `string` | sometimes | The entity the character stands on. |
| `underFoot` | `number[3]` | sometimes | Where the ground check met the ground. |
| `touching` | `string` | sometimes | The entity the character last touched sideways. |
| `moving` | `boolean` | always | Moving faster than the idle speed. |
| `jumpHeld` | `boolean` | always | The jump input on the last tick: a press is its rising edge. |
| `leaveGround` | `boolean` | always | An upward velocity write waiting to lift the character off the ground on the next tick. |
| `nextJumpHeight` | `number` | sometimes | A jump height asked for the next jump only. |
| `anchor` | `ControllerAnchorView` | sometimes | The ground the character rides and where on it. |
| `teleported` | `string` | sometimes | Ground reported teleported, not to carry the character across. |
| `groundVelocity` | `number[3]` | always | How fast the ground carried the character on the last tick. |
| `groundTurn` | `number` | always | How far moving ground turned the character on the last tick, radians. |
| `walkSpeed` | `number` | always | The walking speed a script or a steer last set, m/s. |
| `gravityScale` | `number` | always | `ctx.controller.gravityScale`. |
| `moveWithGround` | `boolean` | always | `ctx.controller.moveWithGround`. |
| `crouchInput` | `boolean` | always | The crouch `ctx.controller.crouch(on)` latched, held until the script says otherwise. |
| `pending` | `PendingInputView` | sometimes | Input a behaviour gave an engine-driven character after its pass this tick, which its pass on the next tick takes. Absent when there is none. |
| `yaw` | `number` | sometimes | The controller's heading, radians about +Y, which `look` turns. Always written; a state without it (from an older engine) restores the heading from the entity's rotation, as before. |
| `squeezedBy` | `string` | sometimes | The moving body that was closing on the character on this tick, by scene id: the next tick's `character-squeezed` event is an edge against it. Absent when there was none. |

#### Response: `ReparentView`

A behaviour's reparent, as a snapshot carries it: the new parent's scene id, or `null` for the top of the scene.

| Field | Type | Present | Description |
|---|---|---|---|
| `parent` | `string` | sometimes | The parent's scene id; `null` when the entity was moved to the top of the scene. |

#### Response: `ScriptStateView`

One behavior's restorable `ctx.state`.

| Field | Type | Present | Description |
|---|---|---|---|
| `module` | `string` | always | The module specifier. |
| `state` | `Props` | always | `ctx.state`. Always an object. |

#### Response: `Velocity`

Linear and angular velocity in world space.

| Field | Type | Present | Description |
|---|---|---|---|
| `linear` | `number[3]` | always | Metres per second, `[x, y, z]`. |
| `angular` | `number[3]` | always | Radians per second about each world axis, `[x, y, z]`. |

#### Response: `GoalStateView`

One goal's progress.

| Field | Type | Present | Description |
|---|---|---|---|
| `id` | `string` | always | The goal's authored id, from its `goal` component. |
| `labelKey` | `string` | always | The string-table key for the goal's display text. |
| `order` | `integer` | sometimes | Declaration order, when the goal component gives one. |
| `reached` | `boolean` | always | Whether the goal has been reached. |
| `at_frame` | `integer` | sometimes | The frame it was reached on. Absent while it has not been. |

#### Response: `InstancesStateView`

One instanced mesh's run-time changes (`WorldStateView::instances`).

| Field | Type | Present | Description |
|---|---|---|---|
| `id` | `string` | always | The instanced mesh entity's stable scene id. |
| `next_id` | `integer` | always | The id the next added instance would get. |
| `changes` | `InstanceChangeView[]` | always | Ascending by instance id. |

#### Response: `InstanceChangeView`

One instance a behaviour added or moved (with its value), or removed (no value).

| Field | Type | Present | Description |
|---|---|---|---|
| `id` | `integer` | always | The instance's stable id. |
| `value` | `InstanceValueView` | sometimes | Where it is now, in its instanced mesh's frame; absent when it was removed. |

#### Response: `NavLiveStateView`

A pending `meta.nav.live` rebuild (`WorldStateView::nav_live`).

| Field | Type | Present | Description |
|---|---|---|---|
| `install_at` | `integer` | always | The tick the pending navmesh goes in on. |
| `gathered_at` | `integer` | always | The tick its geometry was gathered on. |
| `again` | `boolean` | sometimes | Another static changed while it waited: the next rebuild starts on `install_at`. |
| `included` | `integer` | sometimes | How many leading entries of `since` the pending rebuild was gathered with. |
| `since` | `NavChangeView[]` | sometimes | Every static collider change since the navmesh in force was gathered, in tick order. |

#### Response: `NavChangeView`

One static collider change: exactly one of `moved`, `spawned`, `despawned`, by the entity's stable id, with its local pose (relative to its parent) before the change.

| Field | Type | Present | Description |
|---|---|---|---|
| `id` | `string` | always | The entity's stable scene id (or the id a behaviour spawned it with). |
| `at` | `integer` | always | The tick of the change. |
| `moved` | `NavPoseView` | sometimes | It moved; its local pose before the move. |
| `spawned` | `boolean` | sometimes | It was spawned (it is not in the geometry gathered before). |
| `despawned` | `NavPoseView` | sometimes | It was despawned; its local pose before it went. |

#### Response: `NpcWorldStateView`

The NPC types of a world (`WorldStateView::npc`).

| Field | Type | Present | Description |
|---|---|---|---|
| `types` | `NpcTypeStateView[]` | sometimes | Each NPC type, in module order. |
| `commands` | `any[]` | sometimes | Script commands raised since the NPCs' last tick, in order (as `GET /npc/pending` lists them). |
| `stimuli` | `any[]` | sometimes | Script stimuli raised since the NPCs' last tick, in order. |
| `clock` | `[number, integer]` | sometimes | The world clock a script last set: hour of the day, day length in ticks. |

#### Response: `NpcTypeStateView`

One NPC type's simulation.

| Field | Type | Present | Description |
|---|---|---|---|
| `module` | `string` | always | The type's script module. |
| `tick` | `integer` | always | Its tick count. |
| `npcs` | `NpcSummaryView[]` | sometimes | What each of its NPCs is doing. |
| `runtime` | `OpaqueState` | sometimes | `argus-npc`'s runtime of the type; missing or of another version, the type starts over. |

#### Response: `RoadTrackView`

One entity's progress along one road (`WorldStateView::road_progress`): the engine's whole track, so a restore counts the lap and orders the standings exactly as the world it came from.

| Field | Type | Present | Description |
|---|---|---|---|
| `road` | `string` | always | The road entity's scene id. |
| `entity` | `string` | always | The tracked entity's scene id. |
| `position` | `number[3]` | always | Where it was at its last step, in the road's own frame. |
| `s` | `number` | always | Its distance along the centre line there. |
| `offset` | `number` | always | How far right of the centre line it was (negative is left). |
| `from_line` | `number` | always | How far from the centre line it was. |
| `along` | `number` | always | Its distance past the start line, laps unwrapped (`s` on an open road). |
| `checkpoint` | `integer` | always | The last checkpoint it crossed in order, counted across laps (-1 on the grid behind the line). |
| `backward` | `number` | always | Metres gone backward, net of forward since. |
| `reached` | `integer` | always | The tick its race distance last reached a new best (a tie in the standings goes to the earlier). |
| `best` | `number` | always | That best race distance. |

#### Response: `SpawnedDefView`

A runtime-spawned entity as a scene file would hold it (`WorldStateView::spawned`).

| Field | Type | Present | Description |
|---|---|---|---|
| `id` | `string` | always | The entity's id, the same as the matching entry of `entities`. |
| `def` | `Props` | always | The scene-contract entity object, exactly as a scene file's `entities` array holds one. |

## Example

```sh
curl "http://127.0.0.1:7700/snapshot"
```

Start a server with `argus run --serve`; the port is `--port` (7700 by default). The request and response fields are in the query API guide.