---
title: "Animation clips walk run attack idle and poses"
description: "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."
engineVersion: v1.0.234
date: 2026-09-28
license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/."
canonical: https://gessa.ai/docs/knowledge/playbooks/animation-clips-and-poses/
---

# Animation clips walk run attack idle and poses

## When to use

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.

## The recipe

Attach values with `project_add_component`, and switch clips at runtime with
`ctx.entity.patchComponent` in a script.

1. Rig requirement: the animated entity needs a `RenderableComponent`
   `shape:"mesh"` pointing at a rigged model asset (see
   imported-and-uploaded-models); clips are keys inside that asset.
2. Attach `AnimationStateComponent`
   `{ "type":"AnimationStateComponent", "clipKey":"idle", "playMode":"loop",
   "speed": 1, "startTime": 0 }`. `clipKey` is an intra-asset clip key;
   `playMode` is `loop`, `once`, or `ping-pong`.
3. Loop vs one-shot: `loop` for idle, walk, run; `once` for a swing or a jump
   that plays through and stops; `ping-pong` for a breathing or hover bob.
4. Switch by state: in a GessaScript body (`replaceScriptFromGessaScript`), read
   movement or combat state and `ctx.entity.patchComponent` the
   `AnimationStateComponent` `clipKey` (idle to run when speed rises, to an attack
   clip on a fire action, back to idle when it finishes).
5. Speed and hold: raise `speed` for a faster cycle; set a static pose by playing
   a single-frame clip `once`, or a held emote by looping a pose clip.

## Pitfalls

- `clipKey` must 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.
- `AnimationStateComponent` animates 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_schema` on `AnimationStateComponent` for the `playMode`
  enum and field bounds.
- `qa_capture_renderer_viewport` to see the clip play, and `simulation_run` to
  confirm the clip switches on the intended state change.