Animation

​

Load a clip — and meet two gates

curl -s -X POST http://localhost:3917/animation/load -H 'Content-Type: application/json' \
  -d '{"path":"assets/characters/hero.glb"}'
# {"ok":false,"error":"Failed to load glTF 'assets/characters/hero.glb': No such file or directory (os error 2)"}

curl -s -X POST http://localhost:3917/animation/load -H 'Content-Type: application/json' -d '{}'
# {"ok":false,"error":"Missing 'path' to glTF file"}

curl -s http://localhost:3917/animation/list
# {"clips":[],"count":0}

​

Play, blend, and overlay on an entity

curl -s -X POST http://localhost:3917/spawn -H 'Content-Type: application/json' -d '{"health":100}'
# {"entity_id":2,"entity_generation":0}

curl -s -X POST http://localhost:3917/animation/play -H 'Content-Type: application/json' \
  -d '{"entity_id":2,"clip":0,"speed":1.0,"loop":true}'
# {"ok":true,"message":"Playing animation clip 0 on entity 2"}

curl -s -X POST http://localhost:3917/animation/state-machine -H 'Content-Type: application/json' \
  -d '{"entity_id":2,"initial_state":0,"states":[{"name":"idle","clip":0},{"name":"run","clip":1,"speed":1.5}]}'
# {"ok":true,"message":"State machine set on entity 2"}

curl -s -X POST http://localhost:3917/animation/montage -H 'Content-Type: application/json' \
  -d '{"entity_id":2,"clip":2,"clip_duration":0.8,"blend_in":0.1,"blend_out":0.2}'
# {"ok":true,"message":"Montage (clip 2) triggered on entity 2"}

curl -s -X POST http://localhost:3917/animation/stop -H 'Content-Type: application/json' \
  -d '{"entity_id":2}'
# {"ok":true,"message":"Stopped animation on entity 2"}

​

Behavior and gotchas

• Loading has two distinct failure modes. A missing/bad path fails at the glTF read (No such file or directory); a valid file with no AnimationLibrary registered fails at the store (AnimationLibrary resource not initialized). The clip list is empty in both cases — they are not the same gate.
• clip is a numeric index, not a clip name. /animation/play, the state-machine states, and the montage all reference clips by their integer position in the library, not by string. Index 0 is the default for play.
• Attaching an animator needs only an entity, not the library. play, state-machine, montage, and stop all succeed on the bare server (they insert components on an entity) — the clip they point at simply doesn’t resolve to pose data until a real library is loaded and a render host skins it.
• No /step to attach. The component is inserted on the call; the per-tick animation_evaluate pipeline (state machine → sample → crossfade → montage → root motion) runs when the host steps and renders.
• montage is idempotent on re-trigger. A second montage on an entity that already has a MontagePlayer re-plays into the existing player rather than stacking a new one.

​

Endpoints

​

Status

• Shipped & headless — the animator, state-machine, and montage component model (all verified on the bare server), plus crossfade blending, blend spaces, two-bone and FABRIK IK, look-at constraints, root motion, and animation events.
• Host-dependent — clip loading needs both a real glTF file and a registered AnimationLibrary; the minimal example server has neither, so /animation/load fails and /animation/list is empty. Producing the on-screen skinned mesh from the evaluated BoneTransforms is the render host’s job.
• Render caveat — skinned characters currently receive shadows but do not cast them: the shadow depth pass draws only the static cascade batches, so a posed skinned mesh isn’t written into the shadow map. Proper skinned shadow casting needs GPU compute skinning and is not yet wired.