POST /step
Since 0.6
: inputs, ticks and an entity read in one call.
Request
Request body: StepRequest
POST /step request: inputs, then whole ticks, then a read, as one atomic call.
| Field | Type | Required | Description |
|---|---|---|---|
input | InputEvent[] | no | Inputs to place before the ticks, applied in order. May be empty (just step and read). |
step | integer | no | Whole fixed ticks to run, at most 3600. One by default. |
entities | string[] | no | Entity ids to read after the ticks, answered as GET /entity/{id} would. |
Request body: InputEvent
One synthetic input, tagged by type.
| Value | Meaning |
|---|---|
action | A named action, as ctx.input.pressed("jump") reads it. |
axis | A two-axis input, as ctx.input.axis("move") reads it. |
steer | World-frame steering for a harness walking a route. |
mouse | Mouse motion, as a person's mouse gives it: delta pixels every tick, for frames ticks. |
key | One key going down or up, as the window's keyboard sends it. |
Response
Response: StepResponse
POST /step response: what POST /time says, what POST /input said, and the entities read.
| Field | Type | Present | Description |
|---|---|---|---|
frame | integer | always | The frame counter after the ticks ran. |
paused | boolean | always | Whether the sim is paused. |
stepped | integer | always | How many ticks ran. |
input | InputResponse | sometimes | POST /input's answer for the inputs placed; absent when there were none. |
entities | EntitySnapshot[] | sometimes | The entities asked for, as of frame, in the order asked. |
Response: EntitySnapshot
Everything the agent can see about one entity at one frame.
| Field | Type | Present | Description |
|---|---|---|---|
id | string | always | Stable scene id, unique within the scene. The key for GET /entity/:id. |
name | string | always | Human-readable label from the scene file. Not unique. |
tags | Tags | always | Scene tags, in declaration order. The ?tag= filter matches one of these exactly. |
position | number[3] | always | World-space position, [x, y, z], metres. |
rotation | number[4] | always | World-space rotation as a quaternion, [x, y, z, w]. |
scale | number[3] | always | Local scale, [x, y, z]. |
parent | string | sometimes | Parent entity id, absent at the root. |
static | boolean | always | True when the entity is marked static (never moves; excluded from trace deltas). |
velocity | Velocity | sometimes | Linear and angular velocity. Absent for entities with no rigid body. |
components | Components | always | Scene components on this entity, in declaration order. |
overrides | { string: Props } | sometimes | What a behavior has written over this entity's components with entity.set, by component type — and only what it has written, so an entity nothing has touched has none. |
script | ScriptStateView | sometimes | The behavior's ctx.state, if it has a script component. |
anim | AnimStateView | sometimes | Animator state, if it has an animator component. |
vehicle | VehicleView | sometimes | What its vehicle is doing, if it is a running vehicle. Everything a tester driving it through its input actions needs to steer by; ?fields=vehicle keeps just this. |
sprite | SpriteView | sometimes | What its sprite shows, if it has one: the animation, the frame, the view the last frame drew and the picture's world bounds. ?fields=sprite keeps just this. |
tilemap | TilemapView | sometimes | Its tilemap, if it has one: each layer's size and filled cells, the chunks the last frame drew, the collision rectangles and the world bounds. ?fields=tilemap keeps just this. |
frame | integer | always | The frame this snapshot was taken at. Correlates with /capture, /events and /trace. |
Response: AnimStateView
One animator's restorable playhead.
| Field | Type | Present | Description |
|---|---|---|---|
state | string | always | Current state machine state. |
time | number | always | Playhead in seconds. |
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: SpriteView
A sprite component as it plays and was last drawn.
| Field | Type | Present | Description |
|---|---|---|---|
animation | string | sometimes | The animation playing (or stopped on); absent while a still frame shows. |
frame | string | always | The frame showing. |
frameIndex | integer | always | Its entry in the animation's frame list, 0 up. |
playing | boolean | always | False once stopped or a non-looping animation reached its end. |
speed | number | always | Playback multiplier (ctx.sprite.speed). |
view | integer | always | The view the last drawn frame showed: 0 the front, counting counter-clockwise seen from above. |
views | integer | always | How many views the frame has (1: the same from every side). |
visible | boolean | always | Whether it is drawn (ctx.sprite.visible). |
opacity | number | always | 0..1; below 1 it is drawn see-through. |
bounds | number[3][2] | always | World-space box of the picture showing, [min, max]: for a sprite that turns to the camera, the box it sweeps as it turns, so it does not depend on where the camera is. |
Response: TilemapView
A tilemap component as it stands and was last drawn.
| Field | Type | Present | Description |
|---|---|---|---|
layers | TilemapLayerView[] | always | Every layer, in the component's order. |
chunksDrawn | integer | always | Chunks (16 × 16 cells, one draw each) the last frame drew. |
collisionRects | integer | always | Boxes in the collision body (merged rectangles of solid cells); 0 with none. |
bounds | number[3][2] | always | World-space box of every layer, [min, max]. |
Response: VehicleView
A running vehicle, as GET /entities reports it: how it is driven, and where it is going.
| Field | Type | Present | Description |
|---|---|---|---|
input | string | always | Who owns its movement. "auto": the engine, from the actions, every tick; a behaviour's ctx.vehicle.drive is ignored. "script": a behaviour, through ctx.vehicle.drive; holds on the actions move nothing. |
actions | VehicleActions | always | The actions it reads, by role, each with its kind — only those the scene's gameplay context binds (an unbound role reads 0 and is left out). |
speed | number | always | m/s along its forward; negative while reversing. |
forward | number[3] | always | Its nose: the entity's -Z in world axes, unit length. |
steerAngle | number | always | The front wheels' angle now, radians, positive right — the sign the steer action has. |
maxSteer | number | always | The wheels' angle at full lock, radians, at a standstill (it shrinks with speed). |
wheelbase | number | always | Front axle to rear axle, metres. |
minTurnRadius | number | always | The tightest circle it can turn at its speed now, metres: wheelbase / tan(lock), with the lock the steering's speed reduction leaves. |
brakeDecel | number | always | The deceleration full brake gives on the level, m/s²: what stopping at a mark takes. |
topSpeed | number | always | The fastest it goes flat out on the level, m/s (before drag). |
throttle | number | always | The throttle and brake in force this tick, 0..1, after the reverse rule. |
brake | number | always | See throttle. |
gear | integer | always | 1 forward, -1 reverse. |
wheelsOnGround | integer | always | How many of its wheels touch the ground. |
drift | VehicleDriftView | sometimes | The drift, only on a vehicle that has a drift block. |
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: InputResponse
POST /input response.
| Field | Type | Present | Description |
|---|---|---|---|
accepted | integer | always | How many of the submitted inputs were applied. |
frame | integer | always | The frame they take effect on: the next tick the sim runs. |
unbound | string[] | sometimes | Names that no entity in the scene consumes, so the caller learns about a typo instead of watching nothing happen. |
Example
curl -X POST "http://127.0.0.1:7700/step" --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.