GET /trace
Since 0.6
The body is the frozen Vec<FrameDelta>.
What the delta budget left out is reported in x-argus-trace-truncated, and the page's span in x-argus-trace-range, so a client can page backwards with ?before= without the body shape changing.
Request
Query parameters
| Parameter | Shape | Meaning |
|---|---|---|
frames | integer | how many frames to return, newest last. Default 60, maximum 300. |
before | integer | only frames strictly older than this, for paging backwards |
Response
Response: array of FrameDelta
What changed on one frame.
| Field | Type | Present | Description |
|---|---|---|---|
frame | integer | always | The frame this delta describes. |
keyframe | boolean | always | True when transforms lists every non-static entity rather than only the dirty ones. True exactly when frame % 60 == 0. |
transforms | TransformDelta[] | always | Entities whose transform changed this frame (every entity on a keyframe). |
events | EventRecord[] | always | Events that fired on this frame, in order. |
Response: EventRecord
One frame-stamped thing that happened.
| Field | Type | Present | Description |
|---|---|---|---|
seq | integer | always | Monotonic per-process sequence number. Strictly increasing, no gaps. |
frame | integer | always | The frame the event fired on. |
time | number | always | Simulated seconds since the scene loaded. |
kind | EventKind | always | What happened. |
Response: EventKind
The payload of an EventRecord, tagged by type on the wire.
| Value | Meaning |
|---|---|
collision | Two colliders started or stopped touching. Mirrors argus_host::GameEvent::Collision. |
trigger | A sensor volume was entered or left. Mirrors argus_host::GameEvent::Trigger. |
custom | ctx.events.emit(name, data) from a behavior, or ctx.events.emitTo(to, name, data). |
script_error | A behavior threw, ran away or blew its per-tick budget and was disabled — or, with disabled false, keeps running: it threw a stale handle (entity-despawned) from a per-tick hook, or its update stayed over its wall-clock budget (phase budget) under the host's default OverrunPolicy::Warn. |
script_warning | A behavior did something the engine let pass but its author almost certainly did not mean. The behavior keeps running; nothing is disabled. |
ui | The game UI's stack, focus or an activation changed. |
log | ctx.log(...) from a behavior. |
Response: TransformDelta
One entity's transform at one frame.
| Field | Type | Present | Description |
|---|---|---|---|
id | string | always | The entity's stable scene id. |
position | number[3] | always | World-space position, [x, y, z]. |
rotation | number[4] | sometimes | World-space rotation as a quaternion, [x, y, z, w]. Present when it changed since this entity's last delta, and on every keyframe. |
scale | number[3] | sometimes | Local scale, present only on the frames it changed, and on every keyframe. |
Example
curl "http://127.0.0.1:7700/trace"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.