GET /perf
Since 0.6
Response
Response: PerfSample
One frame's cost, as the agent sees it.
| Field | Type | Present | Description |
|---|---|---|---|
presentation | PresentationSample | sometimes | |
frame | integer | always | The frame these numbers describe. |
frame_ms | number | always | Legacy host frame cost; the app reports simulation-step cost here, not presentation cadence. |
physics_ms | number | always | Time inside the physics step. |
script_ms | number | always | Time inside behavior update and event dispatch. |
render_ms | number | always | Time inside render submission. |
p95_frame_ms | number | always | 95th percentile of frame_ms over the last 120 frames. |
draw_calls | integer | always | Draw calls submitted for the last frame, every pass counted. |
instances | integer | always | Instances submitted in the opaque pass. |
triangles | integer | always | Triangles submitted in the opaque pass. |
heap_mb | number | always | Resident heap in mebibytes, or 0 when the host does not measure it. |
entities | integer | always | Live entities. |
bodies | integer | always | Rigid bodies in the physics world. |
agents | integer | always | Crowd agents on the navmesh. |
time_scale | number | always | Simulation time scale in effect (0 while paused). |
paused | boolean | always | Whether the simulation is paused. |
nonfinite_scrubbed | integer | always | Non-finite floats scrubbed on the way out since process start. Non-zero means some subsystem produced a NaN or an infinity; see crates/query/src/finite.rs. |
unwired | UnwiredCalls | always | Behavior calls the engine recorded but could not act on, cumulative since load. See UnwiredCalls; all-zero is healthy and is what an empty scene reports. |
ui_ms | number | sometimes | Wall time of the game UI's tick and draw-list mapping, in milliseconds. 0 with no UI. GET /ui/stats breaks it down by screen. |
ui_draw_calls | integer | sometimes | Draw calls the UI pass issued last frame (quad rounds plus text rounds). Part of draw_calls; 0 headless. |
terrain_load | TerrainLoadTimes | sometimes | The scene load's terrain time by stage; all-zero with no terrain. |
Response: PresentationSample
| Field | Type | Present | Description |
|---|---|---|---|
presented_frames | integer | always | |
skipped_frames | integer | always | |
samples | integer | always | |
fps | number | always | |
mean_interval_ms | number | always | |
p95_interval_ms | number | always | |
cpu_work_ms | number | always | |
present_wait_ms | number | always | |
physics_ms | number | always | |
script_ms | number | always | |
render_submit_ms | number | always | |
render_width | integer | always | |
render_height | integer | always | |
window_width | integer | always | |
window_height | integer | always | |
vsync | boolean | always |
Response: TerrainLoadTimes
Where the scene load's terrain time went, by stage, in wall-clock milliseconds.
| Field | Type | Present | Description |
|---|---|---|---|
prewarm_ms | number | sometimes | Starting the renderer's terrain pipeline early (a read of the layers' material files). |
decode_ms | number | sometimes | Reading and parsing the terrain file, and (drawn) decoding the layers' textures. |
cache_read_ms | number | sometimes | Reading and decompressing the project's terrain cache, hits and misses alike. |
evaluate_ms | number | sometimes | The evaluation apart from its cache reads (the stack's images and sculpt tiles, and the cells the cache did not have), plus bringing the ground to the roads, the water data and the collision query. |
mesh_ms | number | sometimes | Building the cells' render meshes on the CPU (every level). |
upload_ms | number | sometimes | Handing the layers, the cells' maps and the meshes to the renderer (GPU uploads). |
collider_ms | number | sometimes | The cell entities, their colliders and the ground's material lookup. |
total_ms | number | sometimes | The whole terrain attach, start to end. |
disk_hits | integer | sometimes | Cell results read back from the cache on disk: 0 on a cold load. |
cells_evaluated | integer | sometimes | Cell results computed during the load: 0 on a warm one. |
Response: UnwiredCalls
Calls a behavior made that the engine recorded but could not act on.
| Field | Type | Present | Description |
|---|---|---|---|
audio_play | integer | always | ctx.audio.play for an asset with no registered sound. |
particles_emit | integer | always | ctx.particles.emit with a preset name outside the eight the contract defines. |
hud_set | integer | always | ctx.hud.set for a field nothing draws. |
nav_speed_override | integer | always | ctx.nav.goTo(target, speed) with a speed: the crowd has no per-agent speed setter. |
audio_bus | integer | always | ctx.audio.play({ bus }) or ctx.audio.bus(name) naming a bus meta.audio does not declare. The cue still plays, on the default bus. |
audio_snapshot | integer | always | ctx.audio.snapshot(name) with no such snapshot in meta.audio.snapshots. |
audio_music | integer | always | ctx.audio.music.play(layer) with no such layer in meta.audio.music.layers. |
body_push | integer | sometimes | A ctx.body force, torque or impulse on a body that is not dynamic (kinematic or static), or through a handle whose body has gone. Nothing moved. |
joint_ignored | integer | sometimes | A ctx.joint setMotor, stopMotor or setLimits on a fixed joint, or through a handle whose joint has gone. Nothing changed. |
vehicle_ignored | integer | sometimes | A ctx.vehicle.drive on a vehicle the engine drives from the input actions (input: "auto"), or a ctx.vehicle call through a handle whose vehicle has gone. Nothing changed. |
Example
curl "http://127.0.0.1:7700/perf"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.