GET /entities
Since 0.6
Still a bare array however it is narrowed; how many matched and where the next page starts are the x-argus-total and x-argus-next-cursor headers.
Request
Query parameters
| Parameter | Shape | Meaning |
|---|---|---|
id | a,b,coin#* | the entity's id is one of these; an item with * or ? is a pattern |
name | pattern | the entity's name matches (* any run of characters, ? exactly one) |
tag | string | the entity carries this tag exactly |
component | string | the entity carries a component of this type |
near | x,y,z,radius | the entity's position is within radius metres of the point |
inside | minx,miny,minz,maxx,maxy,maxz | the entity's position is inside this box, bounds included |
fields | transform,anim | keep only these top-level fields of each entity; id is always kept |
limit | integer | return at most this many |
cursor | the last page's x-argus-next-cursor | start the page there |
Response
Response: array of 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: AnimLayerStateView
One animator layer in a snapshot (AnimStateView::layers).
| Field | Type | Present | Description |
|---|---|---|---|
name | string | always | The layer's name, as the scene declares it. |
state | string | sometimes | The state playing on it. Absent when it is empty. |
once | string | sometimes | The one-shot playing on it. Absent when none is. |
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: 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: TilemapLayerView
One tilemap layer's size and fill.
| Field | Type | Present | Description |
|---|---|---|---|
name | string | always | Its name (ctx.tilemap calls it this). |
width | integer | always | Cells across. |
height | integer | always | Cells down. |
tiles | integer | always | Cells that hold a tile. |
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: VehicleActions
VehicleView::actions: the input action a vehicle reads for each role, where the scene binds it.
| Field | Type | Present | Description |
|---|---|---|---|
throttle | VehicleAction | sometimes | Drives it forward, 0..1 (a button reads 1). |
brake | VehicleAction | sometimes | Slows it; held at a standstill, reverses. |
steer | VehicleAction | sometimes | One axis, -1..1, +1 turning right. |
handbrake | VehicleAction | sometimes | Locks the wheels whose handbrake is set. |
Response: VehicleDriftView
VehicleView::drift: what a tester or a game reads of an arcade drift.
| Field | Type | Present | Description |
|---|---|---|---|
active | boolean | always | A drift is held now. |
angle | number | always | The angle between where it points and where it travels, radians, positive right like steerAngle; 0 when not drifting. |
charge | number | always | Seconds of boost-earning slide in this drift. |
tier | integer | always | The boost tier the charge has reached: 0 none. |
boostTime | number | always | Seconds of drift boost left; 0 when none. |
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]. |
Example
curl "http://127.0.0.1:7700/entities"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.