Recipes
Animation clips walk run attack idle and poses
A character should walk, idle, swing, or hold a seated pose. Clip playback is the
AnimationStateComponent driving one clip from a rigged model. It selects and plays clips; it does NOT author or blend them.engine v1.0.234since component-field-contract ecs.component-field-contract.v1, rendering.v1, mutation.v1, script-semantic-patch-ops.v1Copy for LLM
Use this for
playing a walk, run, idle, or attack clip on a character; looping an idle or ping-pong pose; switching clips by state; holding a seated or emote pose; setting playback speed
Not for
authoring the animation itself or an animation blend graph (no atomic, see capability-ceiling); moving-object transforms with no skeleton (see moving-platforms-and-elevators); particle effects (see particles-and-visual-effects)
Pairs with: Imported and uploaded 3D models in the world, Third-person follow camera and platformer jump movement, Combat damage health and respawn scripting, Capability ceiling what the agent cannot author and the in-envelope fallback
The recipe
Attach values with project_add_component, and switch clips at runtime with ctx.entity.patchComponent in a script.
- Rig requirement: the animated entity needs a
RenderableComponentshape:"mesh"pointing at a rigged model asset (see imported-and-uploaded-models); clips are keys inside that asset. - Attach
AnimationStateComponent{ "type":"AnimationStateComponent", "clipKey":"idle", "playMode":"loop", "speed": 1, "startTime": 0 }.clipKeyis an intra-asset clip key;playModeisloop,once, orping-pong. - Loop vs one-shot:
loopfor idle, walk, run;oncefor a swing or a jump that plays through and stops;ping-pongfor a breathing or hover bob. - Switch by state: in a GessaScript body (
replaceScriptFromGessaScript), read movement or combat state andctx.entity.patchComponenttheAnimationStateComponentclipKey(idle to run when speed rises, to an attack clip on a fire action, back to idle when it finishes). - Speed and hold: raise
speedfor a faster cycle; set a static pose by playing a single-frame cliponce, or a held emote by looping a pose clip.
Pitfalls
clipKeymust name a clip that exists in the bound model asset; a missing key plays nothing. Confirm the asset's clip names first.- There is NO animation-graph, blend-tree, or state-machine authoring surface; cross-fades and blends are not AI-expressible (see capability-ceiling). Switch clips discretely instead.
AnimationStateComponentanimates a skeleton; a rigid mover with no skeleton uses a Transform patch (see moving-platforms-and-elevators), not this.- Drive clip changes from a throttled handler on real state, not every tick, or the animation thrashes between clips.
Verify
engine_get_component_schemaonAnimationStateComponentfor theplayModeenum and field bounds.qa_capture_renderer_viewportto see the clip play, andsimulation_runto confirm the clip switches on the intended state change.