POST /snapshot
Since 0.6
Put the world back into a previously captured state.
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 (lane rule 35).
| 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. |
Response: RestoreResponse
POST /snapshot response.
| Field | Type | Present | Description |
|---|---|---|---|
restored | boolean | always | Always true. A failed restore is a 4xx. |
frame | integer | always | The frame the world is at now, which is the frame the submitted state carried. |
skipped | integer | sometimes | Entities in the submitted state that the loaded scene no longer has, so a restore against a scene that has been edited since is visibly partial rather than silently so. Absent when every entity was applied. |
Example
curl -X POST "http://127.0.0.1:7700/snapshot" --json @body.jsonStart a server with argus run --serve; the port is --port (7700 by default). The request and response fields are in the query API guide.