# POST /step

> Talos next · 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. |
| `pointer` | Where the mouse points: pixel `(x, y)` of view `view`'s cell, the space `ctx.camera.pick` takes and `ctx.input.pointer` reports. A level like a key: it holds until another `pointer` moves it or one with `off: true` takes it away, and a replay records it. |
| `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, 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: `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

```sh
curl -X POST "http://127.0.0.1:7700/step" --json @body.json
```

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.