GET /feel
Since 0.6
What an agent that cannot look or listen needs to judge how the game feels: animator state and pose, whether the camera's near plane is inside a collider, whether the player is in view, sounds started and animator names that resolved to nothing.
?section= keeps some of the top-level sections; ?id=, ?name= and ?tag= keep the animators (and animator misses) of those entities; ?fields= keeps some of each animator's fields; ?limit= and ?cursor= page the animators.
Request
Query parameters
| Parameter | Shape | Meaning |
|---|---|---|
section | camera,animators | keep only these top-level sections: player, camera, animators, audio, particles, haptics, animator_misses, and clips (below); frame is always kept |
id (or entity) | hero,crab* | only the animators, animator misses, emitters and the burst and rumble records of these entities (a record with no entity goes with an unfiltered answer only); patterns as on /entities |
name | pattern | of entities whose name matches |
tag | string | of entities carrying this tag |
fields | states,clips | keep only these fields of each animator: position, states, joints, bind_deviation, pose, feet, foot_joints, feet_from, feet_method, feet_confidence, feet_reason, feet_unknown, rig_joints, clips, loop_seams, loop_ranges, pops, or the groups gait (feet, foot_joints, feet_from, feet_unknown) and rig (joints, rig_joints, pose, bind_deviation); entity is always kept |
limit, cursor | integer, the last page's x-argus-next-cursor | page the animators; x-argus-total counts them |
Response
Response: FeelView
GET /feel — the game-feel numbers for the tick this answers on.
| Field | Type | Present | Description |
|---|---|---|---|
frame | integer | always | The frame these numbers describe. |
player | FeelPlayer | sometimes | The entity player input drives: the scene's spawn { for: "player" }, else the first character controller. Absent when there is neither. |
camera | FeelCamera | sometimes | The view the frame is drawn from. Absent when the scene has no camera at all. |
animators | FeelAnimator[] | always | Every entity with a live animator, in entity order. |
audio | FeelAudio | always | Sounds started since load. |
particles | FeelParticles | sometimes | Particle emissions since load. |
haptics | FeelHaptics | sometimes | Rumble calls since load. |
animator_misses | AnimatorMiss[] | always | Names ctx.animator.set / ctx.animator.play asked for that the animator does not have, since load. set used to drop them without a word. |
Response: AnimatorMiss
A state or clip name the animator did not have.
| Field | Type | Present | Description |
|---|---|---|---|
entity | string | always | The entity whose animator was asked. |
call | string | always | "set" or "play". |
name | string | always | The name asked for. |
count | integer | always | How many times, since load. |
states | string[] | always | The states the animator does have, sorted. |
Response: FeelAnimator
One animator, this tick.
| Field | Type | Present | Description |
|---|---|---|---|
entity | string | always | The entity the animator is on. |
position | number[3] | always | The entity's world position. |
states | string[] | always | Every state the animator declares, sorted. Which one is playing, the clip, the playhead and the parameters are the entity's own anim on GET /entities, not repeated here. |
joints | integer | always | Joints in the rig. |
bind_deviation | number | always | How far the pose carries any joint, or a point 10 cm from one, from where the bind pose puts it, metres. Near zero is the bind (T-)pose: nothing is being applied to the skeleton. |
pose | number[3][] | always | Up to 32 points in the rig's own frame, metres: each rides one joint, 10 cm from its origin off every axis, so it moves when the joint turns as well as when it travels. Sampled evenly through the skeleton, the same joints on every read of the same animator: diff two reads to see how much the pose moved. |
feet | number[3][] | always | The feet, world space, in the same order on every read, at most four: the joints the animator's feet names, or else the ones the engine found (feet_method): joints named foot, toe or ankle; else the leaf joints a looping clip plants on the ground and lifts in turn; else the lowest end of each limb near the ground at bind (toe ends on a humanoid, paws on a quadruped). |
foot_joints | string[] | always | Their joint names, in the same order. |
feet_from | string | always | "animator" when the feet are the ones animator.feet names, "auto" when the engine found them (feet_method says how). |
feet_method | string | sometimes | How the feet were found: animator (named in animator.feet), names (joints named foot, toe or ankle), motion (planted in turn by a looping clip), bind (lowest at bind, nothing better to go on) or none. |
feet_confidence | number | sometimes | 0..1, how sure the engine is these are the feet: 1 for animator, 0.95 for names a clip also plants, 0.4 for the bind pose alone. Under a half, name them in animator.feet. |
feet_reason | string | sometimes | One sentence naming the evidence: the names, the clip that plants them, the bind heights. |
feet_unknown | string[] | always | Names in animator.feet the rig does not have. With fewer than two found, the feet are chosen by height instead. |
rig_joints | string[] | sometimes | Every joint of the rig, by name, in joint order: the names animator.feet, an IK chain, a look-at and a retarget map are written with. |
clips | FeelClip[] | sometimes | Every clip the animator can play, as measured when it was built: length, whether it loops cleanly, and the ground speed it was authored at. |
loop_seams | FeelLoopSeam[] | sometimes | Looping states whose clips do not meet end to start: each one jumps at the wrap (animator-loop-seam). For a state that plays clips, also each hand-over from one to the next that jumps. |
loop_ranges | FeelLoopRange[] | sometimes | Every clip a state or blend point loops over part of (loopStart/loopEnd), measured over that part. |
strides | FeelStride[] | sometimes | Every point of a stride-matched blend tree: the ground speed it plays against, measured or authored (refSpeed), and the rate that gives it on its own coordinate. |
pops | FeelPops | sometimes | Pose discontinuities since the animator was built: ticks on which a joint turned far more than on the ticks either side. Absent when there have been none. |
Response: FeelClip
One clip, measured when its animator was built.
| Field | Type | Present | Description |
|---|---|---|---|
name | string | always | The clip's name, as a state's clip names it. |
duration | number | always | Seconds. |
loopable | boolean | always | False when its last frame is far from its first: looped, it jumps at the wrap. |
seam_deg | number | always | The largest joint turn from the last frame to the first, degrees. |
seam_joint | string | sometimes | The joint that turn is on; absent when the clip turns no joint. |
max_step_deg | number | always | The largest joint turn between two neighbouring frames, degrees. |
ground_speed | number | always | The ground speed it was authored at, m/s at playback rate 1, in the world at the entity's scale: the speed its planted foot slides back under the body, or its root's travel. What a blend point's at should be, and what stride matching plays against. 0 in place. |
speed_from | string | always | feet, root or none: where ground_speed was read. |
in_place | boolean | sometimes | True when the clip walks or runs in place: its feet cycle (speed_from is feet) while its root does not travel. Its ground_speed is its stance foot's pace under the body. |
root_travel | number | always | Metres the root travels over one cycle: what rootMotion moves the character per loop. |
Response: FeelLoopRange
A clip looped over part of itself, measured over that part.
| Field | Type | Present | Description |
|---|---|---|---|
state | string | always | The state that plays it. |
point | integer | sometimes | The blend point's index in the state's blend.points; absent for the state's own clip. |
clip | string | always | The clip looped. |
loop_start | number | always | Where the loop begins, a fraction of the clip in 0..1: it plays from 0 once, then loops between loop_start and loop_end. |
loop_end | number | always | Where the loop ends and wraps back to loop_start, a fraction of the clip in 0..1. |
loopable | boolean | always | False when the range's end is far from its start: it jumps at every wrap. |
seam_deg | number | always | The largest joint turn from the range's end to its start, degrees. |
seam_joint | string | sometimes | The joint that turn is on; absent when the clip turns no joint. |
max_step_deg | number | always | The largest joint turn between two neighbouring frames inside the range, degrees. |
ground_speed | number | always | The ground speed one cycle of the range covers, m/s at rate 1: what stride matching plays a ranged blend point against. |
Response: FeelLoopSeam
A looping state whose clip jumps where it comes round.
| Field | Type | Present | Description |
|---|---|---|---|
state | string | always | The looping state. |
clip | string | always | The clip that ends. |
next | string | always | The clip that follows it: the same clip for a loop, the next of a state's clips. |
seam_deg | number | always | How far the pose jumps there, degrees, at its worst joint. |
joint | string | always | That joint. |
loop_range | number[2] | sometimes | [loopStart, loopEnd] when the state loops part of the clip: the seam is from the range's end to its start. Absent for a whole clip. |
Response: FeelPops
Pose discontinuities an animator has shown.
| Field | Type | Present | Description |
|---|---|---|---|
count | integer | always | How many since the animator was built. |
worst | FeelPop | always | The largest. |
recent | FeelPop[] | always | The latest, oldest first, at most eight. |
Response: FeelStride
One point of a stride-matched blend tree, as the tree plays it.
| Field | Type | Present | Description |
|---|---|---|---|
state | string | always | The state whose tree it is. |
clip | string | always | The point's clip. |
at | number | always | The point's coordinate, m/s. |
measured | number | always | The clip's ground speed as measured, m/s at rate 1 (over its loop range, when it has one). |
ref_speed | number | sometimes | The point's refSpeed, which the tree plays against instead of measured; absent when the scene gives none. |
rate | number | always | The playback rate at at: at over the ground speed used, 1 for a point in place. Far from 1 (over 3 or under a third) is animator-stride-rate. |
Response: FeelAudio
Sounds, counted since load.
| Field | Type | Present | Description |
|---|---|---|---|
started | integer | always | Voices started: ctx.audio.play cues and audio components that play at load. |
music | integer | always | Music layers that started. |
unplayable | integer | always | ctx.audio.play calls naming an asset with no sound behind it: the game tried to make a noise and nothing played. |
recent | string[] | always | The last few assets started, oldest first, at most 16. |
output | string | sometimes | Where the mix goes: device (a real output), silent (this world never asked for one: headless, a worker, a preview, --no-audio, ARGUS_NO_AUDIO) or unavailable (asked for, and the platform refused; output_note says why). The numbers below are the same either way. |
output_note | string | sometimes | The device's name, or why there is none. Absent for silent. |
playing | integer | sometimes | Voices sounding now. |
peak_voices | integer | sometimes | The most voices that ever sounded at once. |
voices | FeelVoice[] | sometimes | Every voice sounding now, loudest first. |
sounds | FeelSound[] | sometimes | Every sound that has played since load, by asset. |
stacked | FeelStack[] | sometimes | Identical non-spatial loops of one asset sounding at once, three or more: stacked in the centre they add up to one louder copy that masks the rest of the mix. Now, by asset. |
level | FeelLevel | sometimes | The mix's loudness, estimated from each voice's gain and its sound's own level. |
buses | FeelBus[] | sometimes | Every bus the mixer has, in declaration order (master, music, sfx and any the project declares in meta.audio). Absent when there is no mixer to ask or no buses. |
Response: FeelBus
One mixer bus, as it is now.
| Field | Type | Present | Description |
|---|---|---|---|
name | string | always | The bus's name, as meta.audio and ctx.audio.bus(name) call it. |
volume | number | always | This bus's own linear volume, 0..1, ramps included. Its parents' volumes are not in it, so a voice's gain is this times every ancestor's. |
muted | boolean | always | True when the bus is muted: it is silent whatever its volume says. |
Response: FeelLevel
The mix's loudness, estimated: the mixer computes gains and never renders samples.
| Field | Type | Present | Description |
|---|---|---|---|
rms | number | always | Now: every voice's gain times its sound's RMS, added as unrelated signals (power adds). |
peak | number | always | Now: the voices' peaks added as if they lined up, the worst case. Over 1 can clip. |
max_rms | number | always | The loudest rms since load. |
max_peak | number | always | The loudest peak since load. |
Response: FeelSound
What one asset did since load.
| Field | Type | Present | Description |
|---|---|---|---|
asset | string | always | The asset, as the scene names it. |
plays | integer | always | Voices of it started. |
peak_gain | number | always | The loudest it was mixed at (a final gain, as voices[].gain). |
max_overlap | integer | always | The most voices of it sounding at once. |
max_stacked_loops | integer | always | The most non-spatial loops of it sounding at once. |
rms | number | sometimes | The asset's own RMS level (0..1), measured when it was registered. Absent for a streamed sound, which is decoded only as it plays. |
Response: FeelStack
Identical loops stacked now.
| Field | Type | Present | Description |
|---|---|---|---|
asset | string | always | The asset looping. |
voices | integer | always | Non-spatial loops of it sounding. |
gain | number | always | Their gains added: what one copy would have to be mixed at to be as loud, in phase. |
Response: FeelVoice
One voice sounding now, as the mixer computed it.
| Field | Type | Present | Description |
|---|---|---|---|
voice | integer | always | The voice's handle, as ctx.audio.play returned it. |
asset | string | always | The asset it plays. |
bus | string | always | The meta.audio bus it is mixed on. |
gain | number | always | The final linear gain: its own volume, every bus, the rolloff and any fade. |
looped | boolean | always | Plays until stopped. |
spatial | boolean | always | Placed in the world (at), attenuated by distance and panned. |
distance | number | always | Metres from the listener; 0 for a non-spatial voice. |
pitch | number | always | Playback rate, 1 as authored. |
seconds | number | always | Seconds it has played. |
Response: FeelCamera
The view the frame is drawn from.
| Field | Type | Present | Description |
|---|---|---|---|
kind | string | always | "scene" (the scene's camera entity), "fixed", "third-person", "orbit", "first-person" (a rig a script drives), or "override" (the editor's view). |
source | string | always | Who places the view: "rig" (the engine's camera rig, which a behaviour configured with ctx.camera.set / follow — the game's own script or a built-in such as player), "entity" (the scene's primary camera entity, wherever its transform puts it: a camera component's kind, target and distance do not move it), or "editor" (the editor's view override). |
entity | string | sometimes | The scene camera entity's id, when source is "entity". |
position | number[3] | always | The eye, world space. |
forward | number[3] | always | Unit view direction, world space. |
yaw | number | always | Heading of forward about +Y, radians: 0 looks down −Z, +π/2 looks down −X. The same yaw ctx.camera.set takes. |
fov_y | number | always | Vertical field of view, degrees. |
near | number | always | Near clip distance, metres. |
near_radius | number | always | Radius of the sphere around the eye that contains the whole near plane at the widest aspect the engine draws: the probe near_clear is measured with. |
near_clear | boolean | always | False when that sphere overlaps a solid collider: part of the near plane is inside it and the frame shows the inside of a wall. |
near_hit | string | sometimes | The entity the near plane is inside, when it is. |
clearance | number | always | Metres from the eye to the nearest solid collider, measured up to 1 m (1 means nothing within a metre). Under 0.3 m most of the frame is a surface a hand's width away. |
pitch | number | sometimes | Vertical angle of forward, radians: 0 level, positive looks up, −π/2 straight down. The same pitch ctx.camera.set takes. |
look_at | number[3] | sometimes | The world point a fixed script rig looks at (ctx.camera.set("fixed", { target })). Absent for every other rig and view. |
target | string | sometimes | The entity the rig is locked or focused on, when it has one (a lock-on rig). Absent otherwise: no rig sets it yet, so a reader treats absent as "no target". |
follow | string | sometimes | The entity a script rig follows, when it follows one. |
to_player | number | sometimes | Metres from the eye to the player's chest. Absent with no player. |
player_visible | boolean | sometimes | Whether a ray from the eye reaches the player's chest before anything solid. Absent with no player. |
occluder | string | sometimes | What the ray hit first, when the player is hidden. |
arm | CameraArmView | sometimes | The follow rig's spring arm — its length, whether geometry shortened or collapsed it, the character fade — as POST /capture frames report it. Absent unless a third-person or orbit arm is the view. |
shake | number | sometimes | Eye offset of the running ctx.camera.shake, metres; absent at rest. |
Response: CameraArmView
What a follow camera's spring arm was doing: ctx.camera.arm, on the wire.
| Field | Type | Present | Description |
|---|---|---|---|
desired | number | always | The length the rig asked for, metres. |
length | number | always | The length it had, pivot to eye, after collision and the recovery ease. |
collapsed | boolean | always | Shorter than the arm's minimum (0.5 m): the eye was in or against the character. |
blocked | boolean | always | Geometry was shortening the arm. |
blocker | string | sometimes | The entity shortening it, by id. |
fade | number | always | 0..1, how far the followed character was faded away. Faded pixels are dropped by a dither, so they are missing from the frame's depth and id buffers as well. |
probeRadius | number | always | Radius of the sphere the boom swept, widened to hold the near plane. |
Response: FeelHaptics
GET /feel's haptics: ctx.input.rumble, measurable with no pad attached.
| Field | Type | Present | Description |
|---|---|---|---|
total | integer | always | ctx.input.rumble calls since load; the newest record's seq. |
played | integer | always | Of those, the calls a connected pad that can rumble took. 0 on any headless run. |
recent | FeelRumble[] | always | The last 64 calls, oldest first. |
Response: FeelRumble
One ctx.input.rumble call, after clamping.
| Field | Type | Present | Description |
|---|---|---|---|
seq | integer | always | 1 for the first call since load, counting up. |
frame | integer | always | The simulation frame it was called on. |
source | string | sometimes | The entity whose behavior called it. Absent when that entity is gone. |
strength | number | always | The heavy (low-frequency) motor, 0..1. |
high | number | always | The light (high-frequency) motor, 0..1. |
seconds | number | always | How long, 0..10 s. |
Response: FeelParticles
GET /feel's particles: what was emitted, readable by a probe that polls every tick or every few.
| Field | Type | Present | Description |
|---|---|---|---|
bursts | integer | always | ctx.particles.emit calls since load that named a preset. |
burst_particles | integer | always | Particles those bursts emitted (each is capped at its preset's pool). |
recent | FeelEmit[] | always | The last 64 bursts, oldest first. |
emitters | FeelEmitter[] | always | Every live particles component's emitter, in entity slot order. |
Response: FeelEmit
One ctx.particles.emit burst.
| Field | Type | Present | Description |
|---|---|---|---|
seq | integer | always | 1 for the first burst since load, counting up. |
frame | integer | always | The simulation frame it was emitted on. |
entity | string | sometimes | The entity whose behavior emitted it. Absent when that entity is gone, or the engine emitted it. |
preset | string | always | The preset's name. |
count | integer | always | Particles emitted. |
position | number[3] | always | World position it was emitted at. |
Response: FeelEmitter
One particles component's emitter.
| Field | Type | Present | Description |
|---|---|---|---|
entity | string | always | The entity the component is on. |
preset | string | always | The preset it runs. |
emitted | integer | always | Particles it has emitted since it was made. |
live | integer | always | Particles alive now. |
Response: FeelPlayer
The player's body, as the character controller has it.
| Field | Type | Present | Description |
|---|---|---|---|
id | string | always | The entity's scene id. |
position | number[3] | always | Feet, world space. |
velocity | number[3] | always | m/s, world space. Zero for a player with no controller. |
grounded | boolean | always | True when the controller stands on something. True for a player with no controller. |
controller | boolean | always | Whether the entity has a character controller. |
blocked | boolean | always | True when the controller's last move was stopped by something in its way. |
Example
curl "http://127.0.0.1:7700/feel"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.