@waica/engine 0.26.0 → 0.27.0

package/README.md

@@ -25,6 +25,15 @@ A `Game` draws through three's `WebGPURenderer` (ADR 0025): WebGPU when the brow
 - **Tests under happy-dom.** happy-dom has no GPU: a project test that builds a `Game` replaces `WebGPURenderer` from `three/webgpu` with a fake (it previously replaced `WebGLRenderer` from `three`), whose `init()` resolves.
 - **Run Sessions.** A Run Session waits for the Render Backend before it reports ready, steps or screenshots, and its snapshots carry `backend`. A renderer that cannot initialize ends `start_project` with a runtime error that names the failure.
 
+## Migrating to 0.27.0: 3D animation
+
+A glTF's clips play (issue #166, ADR 0029): a `Model` keeps its `handle`, an `Animator` beside it plays the clips, a `StateMachine` drives either kind of Clip Target through one seam, and a 3D character turns to face its walk. Every 2D scene file loads as it did; the seam is additive, one type changes (`TriggerEnv.clipFinished`) and two behaviours change (`play` restarts a finished clip, a `CharacterMotor` turns by default):
+
+- **The state machine plays through the Clip Target.** `StateMachine` no longer names `AnimatedSprite`: it plays each state's clip through the first sibling that satisfies `isClipTarget` (`{ current, clipNames, clipFinished, clipsPending?, play(name), setFlipX? }`), which is the `AnimatedSprite` in a 2D scene and the `Animator` in a 3D one. A project component that plays clips can be that target by exposing the same members. A target whose clips are pending (`clipsPending`: an Animator whose glb is still loading) is asked anyway and remembers the request; a sprite with no clips is not pending and still warns about its states. A mirrored directional clip on a target without `setFlipX` plays unmirrored and warns once per state.
+- **`TriggerEnv.clipFinished`.** Code that builds a `TriggerEnv` for `evaluateTrigger` or `nextTransition` (tests of role graphs, mostly) adds `clipFinished: false`; the new `clip:end` trigger reads it.
+- **`play(current)` restarts a finished clip.** `AnimatedSprite.play(name)` is still a no-op for the clip that is running, but once a `loop: false` clip has ended, playing it again restarts it from frame 0 (and clears `clipFinished`). A project that re-entered a state to keep holding a one-shot's last frame now sees the clip replay; keep the entity in its state instead.
+- **A `CharacterMotor` turns by default.** `turnSpeed` (degrees per second, default 540) turns the entity's yaw toward where it walks; set `turnSpeed: 0` to snap, and keep the yaw out of your own code's hands or they will fight. The kinematic body is unaffected.
+
 ## Migrating to 0.26.0: 3D scenes
 
 A scene can declare a 3D space (issue #154, ADR 0027). Nothing about a 2D scene changes — every existing scene file loads as it did — but a few types and one build setting do:
@@ -247,19 +256,32 @@ A scene declares its space (ADR 0027): `render.space: '2d'` (the default) or `'3
 ```
 
 - **Camera.** `{ kind: 'perspective', position, target, fov, near, far }`, defaults `[0, 5, 10]`, `[0, 0, 0]`, 60, 0.1, 1000; `follow` and the 2D fields are not accepted. A 3D scene without a camera block gets the defaults. The camera is fixed by the scene; game code may move `game.camera`. `resize()` keeps the letterbox and sets the camera's aspect from the letterboxed size. Camera Fade and Flash work in 3D; Shake does nothing.
-- **Model.** Draws a glTF/glb from `src` (a `waica:` uri or a project path under `src/art/`, loaded once through `game.assets.model(uri)`) or a primitive `shape` (`'box'`, `'sphere'`, `'plane'` — the plane lies on the ground) of a `color` (`0xrrggbb`) and a uniform `size`, with a standard (lit) material. With both `src` and `shape`, `src` wins. The entity's `position`, `rotation` and `scale` place it; `color` and `size` follow the inspector live, a new `src` or `shape` rebuilds it. glTF animations load with the file (`ModelHandle.animations`) and are not played yet.
+- **Model.** Draws a glTF/glb from `src` (a `waica:` uri or a project path under `src/art/`, loaded once through `game.assets.model(uri)`) or a primitive `shape` (`'box'`, `'sphere'`, `'plane'` — the plane lies on the ground) of a `color` (`0xrrggbb`) and a uniform `size`, with a standard (lit) material. With both `src` and `shape`, `src` wins. The entity's `position`, `rotation` and `scale` place it; `color` and `size` follow the inspector live, a new `src` or `shape` rebuilds it. `handle` is the `ModelHandle` of the file it draws (null for a primitive): its clips play through an `Animator` beside it.
+- **Animator.** Plays the glTF clips of the `Model` beside it (ADR 0029): one `AnimationMixer` over the entity's own clone, advanced by the Simulation Step, nothing per render frame. It is the 3D Clip Target, so a `StateMachine` plays each state's clip through it and `clip:end` fires when a `loop: false` clip finishes. Params: `initialClip` (plays when the file settles, if nothing asked for a clip before it loaded — a `play` before the model loads is remembered and applied then; `clipsPending` is true meanwhile, so a `StateMachine` asks for its state's clip anyway) and `fade` (seconds of crossfade, default 0.15; `0` cuts). The `clips` prop, authored in JSON like `AnimatedSprite.clips`, holds per-clip overrides keyed by the glTF clip name: `{ loop: false }` plays once and holds the last pose, `{ speed: 2 }` doubles the rate; they are read when the actions are built, as the file settles. A Model rebuild (a new `src` or `shape`) is noticed on the next step: the Animator drops the mixer over the old clone, attaches to the new one and asks for the clip it was playing. Clip names match the file exactly (a state's `clip` override maps `idle` to a pack's `Idle`); an unknown name warns once. `inspect_runtime` shows `{ loaded, current, time, playing, poseHash }`. In a 2D scene it creates nothing and `play` is a no-op; without a `Model` file beside it it warns once at runtime and `validate_project` reports `animator-without-model` per scene entity (an instance may complete its prefab with a `Model.src` override), while `missing-clip` checks its states, `initialClip` and override keys against the glb's clips, on the prefab and again only on an instance that changes them.
 - **Lights.** The Ambient Light of a 3D scene drives one `THREE.AmbientLight` the Game owns (`render.lighting.ambient` and `game.lighting.ambient`, full white by default). `Sun` is a directional light: `direction` `[x, y, z]` in world space (default `[-1, -2, -1]`), `color`, `intensity`. `PointLight` shines from its entity plus `offsetX/Y/Z`: `color`, `intensity`, `distance` (0 = unlimited), `decay` (default 2). Both create nothing in a 2D scene, follow their props live and leave with their entity. No shadows. three's lights are physically based: a point light of intensity 1 is dim, so a scene tunes intensities (the smoke example uses 3 for the Sun and 14 for the lamp).
 - **`game.worldToScreen(point)`.** `{ x, y, z? }` in logical coordinates to canvas CSS pixels inside the letterbox, or `null` when a perspective camera cannot see the point (behind its near plane). Anchored Pieces and spatial audio go through the same projection: in 3D a piece behind the camera is hidden, sounds attenuate by the 3D distance from the camera and pan by where they land on screen.
 - **Picking.** A click in a 3D scene casts a ray through the letterboxed point against every live `Model` (a glTF still loading is skipped) and resolves `PointerPick` with the nearest hit's entity and its world-space point (`point.z`). With no hit the entity is `null` and the point is where the ray meets the ground plane y = 0; a ray at the sky yields no pick.
 - **Assets.** `game.assets.model(uri)` returns a `ModelHandle` at once: `root` is empty until the file settles, then holds your own clone of the cached glTF (skinned meshes cloned with `SkeletonUtils.clone`), `animations` its clips, `settled` resolves `'loaded'` or `'failed'`. One backend load per URL for the Game's life; `status` counts models with textures, `preload` routes `.glb`/`.gltf` to them, `GameOptions.models` replaces the real `GLTFLoader` backend (`ModelBackend { load(url) }`) for a project's own tests. Only a `.glb`, or a `.gltf` with every buffer and image embedded as a `data:` uri, works in the editor (which serves each file from a `blob:` url) and in a built project (which hashes every art file's name): a `.gltf` that points at an external `.bin` or textures loads empty there, and `validate_project` warns (`gltf-external-resource`).
 - **Simulation.** A 3D scene gets one Rapier world (ADR 0028, `@dimforge/rapier3d-deterministic-compat` 0.21.0), stepped once per Simulation Step after every component's `onUpdate`. `simulation: { gravity: [x, y, z] }` in the scene sets its gravity (default `[0, -9.81, 0]`; a `simulation` block in a 2D scene is an error, `invalid-scene-simulation`). Rapier is imported dynamically by the first 3D scene that loads, counts as a pending asset (`game.assets.ready()` and `game.ready()` of a Game with a live 3D scene wait for it, and `game.ready()` rejects naming the package if it fails), and a 2D project never loads it. Steps taken while it loads run every component update and skip only the physics. `GameOptions.physics` replaces the import for a project's own tests.
 - **Collider.** `shape` (`'box'`, `'sphere'`, `'capsule'`), `size` (a box's full extents), `radius`, `height` (a capsule's end-to-end height), `offset` (in the entity's local frame), `sensor`, `layer`, `collidesWith`, `friction`, `restitution`. Alone on an entity it is a fixed wall or floor, created at the entity's position and rotation and scaled by its `scale` (box size and capsule height per axis, a sphere's radius by the largest axis, a capsule's by the larger of x and z); moving the entity later does not move it. A capsule's `height` is at least twice its radius (a shorter one would be a taller sphere). `validate_project` reports `invalid-collider-param` for an unknown shape, a non-positive dimension, a radius or height under 0.01, a capsule shorter than twice its radius, an `offset` that is not three finite numbers, a bad layer or mask and a friction or restitution outside 0 to 1; at runtime such a Collider creates no body and warns once.
-- **RigidBody.** `type` (`'dynamic'` or `'kinematic'`), `mass`, `gravityScale`, `linearDamping`, `angularDamping`, `lockRotations`, `velocity` (initial). It needs a `Collider` on the same entity (`rigid-body-without-collider`). A dynamic body is Rapier's: the engine writes the entity's position and rotation from it after every step; `linearVelocity` (get and set) and `applyImpulse` are its public API (`grounded` is always false on it). A kinematic body is a character: each step it moves through Rapier's character controller by `desiredVelocity` (`{ x, z }`, set by a motor) and its own vertical velocity under gravity, climbs steps up to `stepHeight`, stands on slopes up to `maxSlope` degrees and slides down steeper ones, sticks to the ground within `snapDistance`, pushes dynamic bodies, ignores sensors, and `jump(speed)` launches it while `grounded` and reports whether it did. Setting its entity's position teleports it, with no fall speed left. `validate_project` reports a `type` outside its options, a number outside its range or a `velocity` that is not three numbers as `invalid-rigid-body-param`; at runtime such a body is not created and one warning says why. `CharacterMotor` (`@waica/behaviors`) is the stock motor: `speed`, `jumpSpeed` and five action names, walking on the world axes (`-z` is forward, diagonals at the cardinal speed), consuming the jump press only when it jumped; `character-motor-without-body` reports one without a kinematic `RigidBody` and a `Collider`.
+- **RigidBody.** `type` (`'dynamic'` or `'kinematic'`), `mass`, `gravityScale`, `linearDamping`, `angularDamping`, `lockRotations`, `velocity` (initial). It needs a `Collider` on the same entity (`rigid-body-without-collider`). A dynamic body is Rapier's: the engine writes the entity's position and rotation from it after every step; `linearVelocity` (get and set) and `applyImpulse` are its public API (`grounded` is always false on it). A kinematic body is a character: each step it moves through Rapier's character controller by `desiredVelocity` (`{ x, z }`, set by a motor) and its own vertical velocity under gravity, climbs steps up to `stepHeight`, stands on slopes up to `maxSlope` degrees and slides down steeper ones, sticks to the ground within `snapDistance`, pushes dynamic bodies, ignores sensors, and `jump(speed)` launches it while `grounded` and reports whether it did. Setting its entity's position teleports it, with no fall speed left. `validate_project` reports a `type` outside its options, a number outside its range or a `velocity` that is not three numbers as `invalid-rigid-body-param`; at runtime such a body is not created and one warning says why. `CharacterMotor` (`@waica/behaviors`) is the stock motor: `speed`, `jumpSpeed`, `turnSpeed` and five action names, walking on the world axes (`-z` is forward, diagonals at the cardinal speed), consuming the jump press only when it jumped; `character-motor-without-body` reports one without a kinematic `RigidBody` and a `Collider`, and `invalid-character-motor-param` a param outside the range its spec declares.
+- **Character.** A 3D character faces where it walks by turning, not by directional clips or flips (issue #166): each step it has a non-zero desired velocity, `CharacterMotor` turns the entity's yaw toward it through `turnYawToward(node, dirX, dirZ, turnSpeed, dt)` (`@waica/behaviors`; the target yaw is `atan2(dirX, dirZ)`, so a glTF's +z front leads; the shortest arc, at most `turnSpeed` degrees per second), and with no input, or a `speed` of 0, the yaw holds. `turnSpeed` defaults to 540 (about a third of a second for a U-turn), `0` snaps, and the kinematic body is unaffected: it keeps the rotation it spawned with, so give a turning character a `Collider` that looks the same from every side — a capsule or a sphere with no x/z `offset` — or the model and a box or offset collider disagree about where it ends. The `character` role (`CHARACTER_ROLE`, `CHARACTER_STATE_GRAPH`, `characterUpdate`) is the 3D counterpart of `player`: `idle`, `walk`, `jump` and `fall` on the signals its update emits by reading the kinematic `RigidBody` — `land` plus `move` (planar speed above 0.1 u/s) or `stop` on the ground, `rise` or `fall` in the air once it has vertical speed (air with none — the spawn, the steps while Rapier loads, the step after a teleport — reports nothing) — while the motor keeps reading the input itself; an `Animator` beside the machine plays each state's clip (a per-state `clip` maps `idle` to a pack's `Idle`). A project registers it with `defineRole('character', CHARACTER_ROLE)` in `src/roles/character.ts`; `validate_project` recognizes a `@waica/behaviors` role passed by reference there, so its states report no `no-state-code`.
 - **Contacts and sensors.** Components on an entity with a solid `Collider` get `onBodyContact({ entity, other, normal, point })` once per step for each entity they touch, the normal pointing from the entity to the other; kinematic bodies included, so a character hears the floor and the walls it touches. A `Collider{ sensor: true }` is the 3D `Hitbox`: it fires `onCollide(other)` every step it overlaps another collider, on each side whose `collidesWith` names the other's `layer` (ADR 0016); a solid collider is told only if it declares its own mask, and a sensor with the default mask (`['*']`) is not told about fixed solid colliders (the level's walls and floors), as a Hitbox never sees a Solid — a mask naming their layer still is.
 - **Queries.** `game.query` gains 3D forms told apart by argument shape: `ray(origin, direction, maxDistance, filter?)` returns the first solid collider (`{ entity, collider, distance, point, normal }`, sensors never block it), `area({ shape: 'box', center, size } | { shape: 'sphere', center, radius }, filter?)` and `point(at, filter?)` return the entities whose sensor colliders intersect or contain them, `nearest(at, filter?)` the closest transform with `z`. The filter object is the 2D one; its `where` runs after Rapier has answered, so it may throw or change the scene, and `area` answers `[]` for a volume that is not a finite box or sphere. A form in the other space's scene throws an error naming the space. Rapier updates what queries read inside the step, so the engine refreshes it when bodies came or went.
 - **Runtime Snapshot.** `space`, `view` (`{ kind: 'orthographic', position, zoom }` or `{ kind: 'perspective', position, target, fov }`) and, in a 3D scene, `lighting.sun[]` and `lighting.pointLights[]`, and `physics: { state: 'loading' | 'ready' | 'failed', gravity, bodies: [{ entity, id, type: 'fixed' | 'dynamic' | 'kinematic', velocity, grounded }] }` (bodies in spawn order, never filtered).
 - **Editor.** A 3D scene opens read-only: the viewport draws it through its perspective camera (the one Play uses) with no gesture, grid or gizmo; the inspector edits X/Y/Z, rotation and scale, and a perspective camera's position, target and fov.
 
+## State machines
+
+A `StateMachine` owns a character's per-frame logic: its `states` and their `transitions` are prefab data, the state code comes from the role's logic set (`defineRole`, `defineStates`), and `current` names the active state. Each transition is `{ on, to }`; a trigger is one of:
+
+- `input:<action>` — an unconsumed press of the action this Simulation Step; the transition spends it.
+- `timer:<seconds>` — the state has been active for at least that long (exact at the fixed step: `timer:0.3` is 18 steps).
+- `signal:<name>` — the state code queued `fsm.signal(name)` this step or the last.
+- `clip:end` — the Clip Target reports the clip the current state asked for finished (issue #166). It fires on the step after the clip's last frame has been held for its whole duration, and never for a looping clip (`validate_project` warns `clip-end-on-looping-clip`, the directional `<state>-<dir>` clips and the contract's fallbacks included). A state whose clip the target lacks keeps the previous clip playing but never reads its end as its own. Re-entering a state whose one-shot clip already ended replays it.
+
+Entering a state plays the clip of its name (or its `clip` override) through the entity's **Clip Target**: the first sibling component that plays clips — an `AnimatedSprite` in a 2D scene, an `Animator` in a 3D one — found by `isClipTarget` (a `play` function and a `clipNames` member), not by class. The directional contract resolves `<state>-<dir>` against the target's `clipNames` and mirrors only a target that defines `setFlipX`; a mirrored clip on a target without it plays unmirrored and warns once per state. A turn that only mirrors the running clip (west playing east flipped) re-applies the mirror and leaves the clip alone — a finished one-shot keeps its last frame — while a turn onto another clip name plays it. A clip the target lacks warns once and keeps the previous one; a target whose clips are pending (an `Animator` whose glb is loading) is asked anyway and remembers the request.
+
 ## Component lifecycle
 
 Waica keeps the lifecycle boundaries distinct:

package/dist/animation/clip-player.d.ts

@@ -14,6 +14,13 @@ export declare class ClipPlayer {
     private fps;
     private loop;
     private t;
+    /**
+     * Whether a non-looping clip has played through: its time reached
+     * `frames.length / fps` (the moment the last frame has been held for its
+     * whole duration), with the fixed-step epsilon so 30 steps of 1/60 s end a
+     * 0.5 s clip on the 30th. A looping clip never finishes; `set` clears it.
+     */
+    get finished(): boolean;
     set(clip: ClipDef): void;
     /** Advances the clock and returns the sheet frame to show. */
     advance(dt: number): number;

package/dist/animation/clip-player.js

@@ -8,6 +8,15 @@ export class ClipPlayer {
     fps = 1;
     loop = true;
     t = 0;
+    /**
+     * Whether a non-looping clip has played through: its time reached
+     * `frames.length / fps` (the moment the last frame has been held for its
+     * whole duration), with the fixed-step epsilon so 30 steps of 1/60 s end a
+     * 0.5 s clip on the 30th. A looping clip never finishes; `set` clears it.
+     */
+    get finished() {
+        return !this.loop && this.t + SIMULATION_TIME_EPSILON >= this.frames.length / this.fps;
+    }
     set(clip) {
         this.frames = clip.frames.length > 0 ? clip.frames : [0];
         this.fps = clip.fps;

package/dist/animation/clip-target.d.ts

@@ -0,0 +1,38 @@
+import type { Component } from '../component.js';
+/**
+ * The Clip Target (issue #166): the one sibling component a StateMachine
+ * plays clips through — `AnimatedSprite` in a 2D scene, `Animator` in a 3D
+ * one. The machine asks for a clip by name on entering a state, reads which
+ * names exist and which one runs, and learns from `clipFinished` that a
+ * one-shot clip ended (the `clip:end` trigger). `setFlipX` is the 2D
+ * directional contract's mirror; a target without it is never flipped.
+ */
+export interface ClipTarget {
+    /** The clip playing now, undefined (or absent) before the first `play`. */
+    readonly current?: string;
+    /** Every name `play` accepts. */
+    readonly clipNames: readonly string[];
+    /** True once a non-looping clip reached its end; false again after `play`. */
+    readonly clipFinished: boolean;
+    /**
+     * True while the target expects clips it cannot list yet (an Animator
+     * whose glb is loading): the machine asks for a clip anyway and the target
+     * remembers the request. Absent or false, an empty `clipNames` means the
+     * target has no clips, and a missing clip warns.
+     */
+    readonly clipsPending?: boolean;
+    play(name: string): void;
+    /**
+     * The 2D mirror. A target without it is never flipped: a directional clip
+     * resolved through a mirror plays unmirrored there, and the machine warns
+     * once per state.
+     */
+    setFlipX?(flip: boolean): void;
+}
+/**
+ * Duck-typed like the facing provider: the first sibling with a `play`
+ * function and a `clipNames` member is the target, whatever its class. The
+ * member is tested with `in`, never read: a target computes `clipNames` in a
+ * getter, and this runs on every Simulation Step of every machine.
+ */
+export declare function isClipTarget(component: Component): component is Component & ClipTarget;

package/dist/animation/clip-target.js

@@ -0,0 +1,9 @@
+/**
+ * Duck-typed like the facing provider: the first sibling with a `play`
+ * function and a `clipNames` member is the target, whatever its class. The
+ * member is tested with `in`, never read: a target computes `clipNames` in a
+ * getter, and this runs on every Simulation Step of every machine.
+ */
+export function isClipTarget(component) {
+    return 'play' in component && typeof component.play === 'function' && 'clipNames' in component;
+}

package/dist/animation/pose-hash.d.ts

@@ -0,0 +1,10 @@
+import * as THREE from 'three/webgpu';
+/** The 32-bit FNV-1a hash of `text` (UTF-8), as eight lowercase hex digits. Synchronous and dependency-free, the same on every backend. */
+export declare function fnv1a(text: string): string;
+/**
+ * A fingerprint of a rig's pose (issue #166 CA-10): FNV-1a over every bone's
+ * local quaternion and position rounded to 1e-4, in skeleton order, skeleton
+ * by skeleton. Empty with no skinned mesh under `root`. Two frames of the same
+ * clip differ; the same step of the same clip hashes alike on every platform.
+ */
+export declare function poseHash(root: THREE.Object3D): string;

package/dist/animation/pose-hash.js

@@ -0,0 +1,43 @@
+import * as THREE from 'three/webgpu';
+const FNV_OFFSET = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+/** The 32-bit FNV-1a hash of `text` (UTF-8), as eight lowercase hex digits. Synchronous and dependency-free, the same on every backend. */
+export function fnv1a(text) {
+    let hash = FNV_OFFSET;
+    for (const byte of new TextEncoder().encode(text)) {
+        hash ^= byte;
+        hash = Math.imul(hash, FNV_PRIME) >>> 0;
+    }
+    return hash.toString(16).padStart(8, '0');
+}
+const round = (value) => (Math.round(value * 1e4) / 1e4).toFixed(4);
+/** A skinned mesh, typed for what a glTF gives it (the generics three leaves at `any`). */
+function isSkinnedMesh(object) {
+    return object instanceof THREE.SkinnedMesh;
+}
+/** The skinned meshes under `root`, in traversal order. */
+function skinnedMeshesUnder(root) {
+    const found = [];
+    root.traverse((object) => {
+        if (isSkinnedMesh(object))
+            found.push(object);
+    });
+    return found;
+}
+/**
+ * A fingerprint of a rig's pose (issue #166 CA-10): FNV-1a over every bone's
+ * local quaternion and position rounded to 1e-4, in skeleton order, skeleton
+ * by skeleton. Empty with no skinned mesh under `root`. Two frames of the same
+ * clip differ; the same step of the same clip hashes alike on every platform.
+ */
+export function poseHash(root) {
+    const parts = [];
+    for (const mesh of skinnedMeshesUnder(root)) {
+        for (const bone of mesh.skeleton.bones) {
+            const { x, y, z, w } = bone.quaternion;
+            const { x: px, y: py, z: pz } = bone.position;
+            parts.push([x, y, z, w, px, py, pz].map(round).join(','));
+        }
+    }
+    return parts.length === 0 ? '' : fnv1a(parts.join(';'));
+}

package/dist/components/animated-sprite.d.ts

@@ -1,5 +1,6 @@
 import { Component, type ComponentSpace } from '../component.js';
 import { type ClipDef } from '../animation/clip-player.js';
+import type { ClipTarget } from '../animation/clip-target.js';
 import { type SheetCell, type SheetDef } from '../animation/sheet.js';
 import type { YSortParticipant } from '../render-sort.js';
 /**
@@ -12,7 +13,7 @@ import type { YSortParticipant } from '../render-sort.js';
  * per frame, anchored bottom-center — width/height size the sheet's largest
  * frame and smaller ones keep their feet planted.
  */
-export declare class AnimatedSprite extends Component implements YSortParticipant {
+export declare class AnimatedSprite extends Component implements YSortParticipant, ClipTarget {
     static componentName: string;
     static space: ComponentSpace;
     static updateAfter: readonly string[];
@@ -96,6 +97,10 @@ export declare class AnimatedSprite extends Component implements YSortParticipan
     initialClip?: string;
     /** Clip currently playing. */
     current?: string;
+    /** The names a StateMachine can ask for (the Clip Target seam, issue #166). */
+    get clipNames(): readonly string[];
+    /** True once a non-looping clip has held its last frame for its whole duration; false after `play`. */
+    get clipFinished(): boolean;
     private readonly player;
     private sheets;
     private texs;
@@ -105,7 +110,12 @@ export declare class AnimatedSprite extends Component implements YSortParticipan
     private frameScaleX;
     private frameScaleY;
     onReady(): void;
-    /** Switches clip; repeating the same name doesn't restart the animation. */
+    /**
+     * Switches clip. Repeating the running clip's name doesn't restart it; once
+     * a non-looping clip has finished it does (issue #166 CA-3), so a state
+     * re-entered after its one-shot clip ended replays it instead of reporting
+     * `clip:end` on every step.
+     */
     play(name: string): void;
     onUpdate(dt: number): void;
     onDestroy(): void;

package/dist/components/animated-sprite.js

@@ -151,6 +151,14 @@ export class AnimatedSprite extends Component {
     initialClip;
     /** Clip currently playing. */
     current;
+    /** The names a StateMachine can ask for (the Clip Target seam, issue #166). */
+    get clipNames() {
+        return Object.keys(this.clips);
+    }
+    /** True once a non-looping clip has held its last frame for its whole duration; false after `play`. */
+    get clipFinished() {
+        return this.player.finished;
+    }
     player = new ClipPlayer();
     sheets = [];
     texs = [];
@@ -206,9 +214,14 @@ export class AnimatedSprite extends Component {
         if (this.initialClip)
             this.play(this.initialClip);
     }
-    /** Switches clip; repeating the same name doesn't restart the animation. */
+    /**
+     * Switches clip. Repeating the running clip's name doesn't restart it; once
+     * a non-looping clip has finished it does (issue #166 CA-3), so a state
+     * re-entered after its one-shot clip ended replays it instead of reporting
+     * `clip:end` on every step.
+     */
     play(name) {
-        if (this.current === name)
+        if (this.current === name && !this.player.finished)
             return;
         const clip = this.clips[name];
         if (!clip)

package/dist/components/animator.d.ts

@@ -0,0 +1,98 @@
+import type { ClipTarget } from '../animation/clip-target.js';
+import { Component, type ComponentSpace } from '../component.js';
+/** Per-clip overrides, keyed by the glTF's clip name: a one-shot (`loop: false`) and a playback rate. */
+export interface AnimatorClipOverride {
+    /** Defaults to true; false plays the clip once and holds its last pose. */
+    loop?: boolean;
+    /** Playback rate; 1 by default, 2 finishes in half the time. */
+    speed?: number;
+}
+/** What `inspect_runtime` shows of an Animator. */
+export interface AnimatorState {
+    loaded: boolean;
+    /** The playing clip; null before the first play (an undefined would project as an unsupported marker). */
+    current: string | null;
+    /** The current action's time in seconds (0 with none). */
+    time: number;
+    /** False before the model loaded or with no clip playing. */
+    playing: boolean;
+    /** The pose fingerprint of the rig (see poseHash); empty with no skeleton. */
+    poseHash: string;
+}
+/**
+ * Plays the glTF clips of the Model beside it (issue #166, ADR 0029): the
+ * 3D Clip Target. One AnimationMixer over the Model's own clone, one action
+ * per clip, advanced by the Simulation Step in onUpdate — nothing runs per
+ * render frame, so the pose is deterministic and visible step by step. A
+ * StateMachine finds it like it finds an AnimatedSprite and plays the clip of
+ * each state; `clip:end` fires when a `loop: false` clip finishes. A `play`
+ * before the model loaded is remembered and applied when it settles;
+ * otherwise `initialClip` plays then. In a 2D scene it creates nothing.
+ */
+export declare class Animator extends Component implements ClipTarget {
+    static componentName: string;
+    static space: ComponentSpace;
+    static updateAfter: readonly string[];
+    static params: {
+        initialClip: {
+            label: string;
+        };
+        fade: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    static transient: string[];
+    /** The clip that plays once the model settles, when nothing asked for one before. */
+    initialClip: string;
+    /** Crossfade between clips, in seconds; 0 cuts. */
+    fade: number;
+    /**
+     * Per-clip overrides by glTF clip name (authored in JSON, like
+     * AnimatedSprite.clips). Read when the actions are built, as the model
+     * settles: a change after that applies on the next build (a Model rebuild).
+     */
+    clips: Record<string, AnimatorClipOverride>;
+    /** The clip playing now; undefined before the first play. */
+    current: string | undefined;
+    private mixer;
+    private readonly actions;
+    private active;
+    /** A play asked for before the model loaded. */
+    private requested;
+    private finished;
+    private root;
+    private readonly warned;
+    private attached;
+    /** The Model handle the mixer was built over, or is waiting on: a Model rebuild replaces it (review of PR #168). */
+    private handle;
+    /** The clip names, computed once per build: the StateMachine reads them every step. */
+    private names;
+    /** True while clips are expected but not listed yet (the glb is loading); false once built, or once no Model can provide them. */
+    private pending;
+    get clipNames(): readonly string[];
+    get clipFinished(): boolean;
+    get clipsPending(): boolean;
+    onReady(): void;
+    /** Plays a clip: a no-op for the running one, a restart for a finished one, a crossfade from any other over `fade` seconds. */
+    play(name: string): void;
+    onUpdate(dt: number): void;
+    onDestroy(): void;
+    inspectState(): AnimatorState;
+    /**
+     * Takes the sibling Model's handle and builds the mixer when it settles. A
+     * Model later in the component order is not there at onReady, so the first
+     * onUpdate tries once more (`final`); a primitive Model warns at once, a
+     * missing one once it is certain, and either way exactly once.
+     */
+    private attach;
+    /** Forgets the Model's old clone and keeps the clip it played as the request for the next build. */
+    private detach;
+    /** Stops and drops the mixer, its actions and the clone they ran over. */
+    private release;
+    private build;
+    private configure;
+    private warnOnce;
+}

package/dist/components/animator.js

@@ -0,0 +1,197 @@
+import * as THREE from 'three/webgpu';
+import { poseHash } from '../animation/pose-hash.js';
+import { Component } from '../component.js';
+import { reportRejection } from '../report-rejection.js';
+import { Model } from './model.js';
+/**
+ * Plays the glTF clips of the Model beside it (issue #166, ADR 0029): the
+ * 3D Clip Target. One AnimationMixer over the Model's own clone, one action
+ * per clip, advanced by the Simulation Step in onUpdate — nothing runs per
+ * render frame, so the pose is deterministic and visible step by step. A
+ * StateMachine finds it like it finds an AnimatedSprite and plays the clip of
+ * each state; `clip:end` fires when a `loop: false` clip finishes. A `play`
+ * before the model loaded is remembered and applied when it settles;
+ * otherwise `initialClip` plays then. In a 2D scene it creates nothing.
+ */
+export class Animator extends Component {
+    static componentName = 'Animator';
+    static space = '3d';
+    static updateAfter = ['StateMachine'];
+    static params = {
+        initialClip: { label: 'Initial clip' },
+        fade: { label: 'Fade (s)', min: 0, max: 1, step: 0.05 },
+    };
+    static transient = ['current', 'mixer', 'actions', 'active', 'requested', 'finished', 'root', 'warned', 'attached', 'handle', 'names', 'pending'];
+    /** The clip that plays once the model settles, when nothing asked for one before. */
+    initialClip = '';
+    /** Crossfade between clips, in seconds; 0 cuts. */
+    fade = 0.15;
+    /**
+     * Per-clip overrides by glTF clip name (authored in JSON, like
+     * AnimatedSprite.clips). Read when the actions are built, as the model
+     * settles: a change after that applies on the next build (a Model rebuild).
+     */
+    clips = {};
+    /** The clip playing now; undefined before the first play. */
+    current;
+    mixer = null;
+    actions = new Map();
+    active = null;
+    /** A play asked for before the model loaded. */
+    requested;
+    finished = false;
+    root = null;
+    warned = new Set();
+    attached = false;
+    /** The Model handle the mixer was built over, or is waiting on: a Model rebuild replaces it (review of PR #168). */
+    handle = null;
+    /** The clip names, computed once per build: the StateMachine reads them every step. */
+    names = [];
+    /** True while clips are expected but not listed yet (the glb is loading); false once built, or once no Model can provide them. */
+    pending = false;
+    get clipNames() {
+        return this.names;
+    }
+    get clipFinished() {
+        return this.finished;
+    }
+    get clipsPending() {
+        return this.pending;
+    }
+    onReady() {
+        if (this.game.space !== '3d')
+            return;
+        this.pending = true;
+        this.attach();
+    }
+    /** Plays a clip: a no-op for the running one, a restart for a finished one, a crossfade from any other over `fade` seconds. */
+    play(name) {
+        if (this.game.space !== '3d')
+            return;
+        if (!this.mixer) {
+            this.requested = name;
+            return;
+        }
+        const action = this.actions.get(name);
+        if (!action) {
+            this.warnOnce(name, `[waica] "${this.entity.name}": no clip "${name}"`);
+            return;
+        }
+        if (action === this.active && !this.finished)
+            return;
+        const previous = this.active;
+        this.active = action;
+        this.current = name;
+        this.finished = false;
+        action.reset().setEffectiveWeight(1).play();
+        if (!previous || previous === action)
+            return;
+        if (this.fade <= 0)
+            previous.stop();
+        else
+            previous.crossFadeTo(action, this.fade, false);
+    }
+    onUpdate(dt) {
+        if (this.game.space !== '3d')
+            return;
+        // A rebuilt Model (a new src or shape) draws a new clone: the mixer over
+        // the old one would animate a graph nobody draws, so it is torn down and
+        // the clip it was playing is asked for again on the new one.
+        if (this.attached && (this.entity.get(Model)?.handle ?? null) !== this.handle)
+            this.detach();
+        if (!this.attached)
+            this.attach(true);
+        this.mixer?.update(dt);
+    }
+    onDestroy() {
+        this.release();
+        this.pending = false;
+    }
+    inspectState() {
+        return {
+            loaded: this.mixer !== null,
+            current: this.current ?? null,
+            time: this.active?.time ?? 0,
+            playing: this.active !== null && this.active.isRunning(),
+            poseHash: this.root ? poseHash(this.root) : '',
+        };
+    }
+    /**
+     * Takes the sibling Model's handle and builds the mixer when it settles. A
+     * Model later in the component order is not there at onReady, so the first
+     * onUpdate tries once more (`final`); a primitive Model warns at once, a
+     * missing one once it is certain, and either way exactly once.
+     */
+    attach(final = false) {
+        const model = this.entity.get(Model);
+        const handle = model?.handle;
+        if (!handle) {
+            if ((model && !model.src) || final) {
+                this.attached = true;
+                this.pending = false;
+                this.warnOnce('model', `[waica] "${this.entity.name}": Animator needs a Model with a src beside it; nothing plays`);
+            }
+            return;
+        }
+        this.attached = true;
+        this.handle = handle;
+        reportRejection(handle.settled.then((outcome) => {
+            // Only the handle still attached builds: a Model rebuilt meanwhile has a newer one.
+            if (outcome === 'loaded' && this.entity.alive && !this.mixer && this.handle === handle)
+                this.build(handle);
+        }), 'animator model settle');
+    }
+    /** Forgets the Model's old clone and keeps the clip it played as the request for the next build. */
+    detach() {
+        this.requested = this.current ?? this.requested;
+        this.release();
+        this.attached = false;
+        this.pending = true;
+    }
+    /** Stops and drops the mixer, its actions and the clone they ran over. */
+    release() {
+        this.mixer?.stopAllAction();
+        if (this.mixer && this.root)
+            this.mixer.uncacheRoot(this.root);
+        this.mixer = null;
+        this.active = null;
+        this.current = undefined;
+        this.finished = false;
+        this.actions.clear();
+        this.names = [];
+        this.root = null;
+        this.handle = null;
+    }
+    build(handle) {
+        const mixer = new THREE.AnimationMixer(handle.root);
+        this.mixer = mixer;
+        this.root = handle.root;
+        for (const clip of handle.animations)
+            this.actions.set(clip.name, this.configure(mixer.clipAction(clip), clip.name));
+        this.names = [...this.actions.keys()];
+        this.pending = false;
+        mixer.addEventListener('finished', (event) => {
+            if (event.action === this.active)
+                this.finished = true;
+        });
+        const first = this.requested ?? this.initialClip;
+        this.requested = undefined;
+        if (first)
+            this.play(first);
+    }
+    configure(action, name) {
+        const override = this.clips[name];
+        if (override?.loop === false) {
+            action.setLoop(THREE.LoopOnce, 1);
+            action.clampWhenFinished = true;
+        }
+        action.timeScale = override?.speed ?? 1;
+        return action;
+    }
+    warnOnce(key, message) {
+        if (this.warned.has(key))
+            return;
+        this.warned.add(key);
+        console.warn(message);
+    }
+}

package/dist/components/model.d.ts

@@ -1,4 +1,5 @@
 import * as THREE from 'three/webgpu';
+import type { ModelHandle } from '../assets/model-cache.js';
 import { Component, type ComponentSpace } from '../component.js';
 export type ModelShape = 'box' | 'sphere' | 'plane';
 /**
@@ -37,6 +38,13 @@ export declare class Model extends Component {
     static transient: string[];
     /** What this Model draws, under the entity's node; null until it is ready. The Pointer ray-casts against it. */
     root: THREE.Group | null;
+    /**
+     * The handle of the glTF it draws (issue #166 CA-6): `handle.root` is the
+     * child of `root`, `handle.animations` its clips once settled — what an
+     * Animator beside it plays. Null for a primitive, in a 2D scene and before
+     * the component is ready; replaced on every rebuild.
+     */
+    handle: ModelHandle | null;
     private _src;
     private _shape;
     private _color;

package/dist/components/model.js

@@ -32,9 +32,16 @@ export class Model extends Component {
         color: { label: 'Color', kind: 'color' },
         size: { label: 'Size', min: 0.01, step: 0.1 },
     };
-    static transient = ['root'];
+    static transient = ['root', 'handle'];
     /** What this Model draws, under the entity's node; null until it is ready. The Pointer ray-casts against it. */
     root = null;
+    /**
+     * The handle of the glTF it draws (issue #166 CA-6): `handle.root` is the
+     * child of `root`, `handle.animations` its clips once settled — what an
+     * Animator beside it plays. Null for a primitive, in a 2D scene and before
+     * the component is ready; replaced on every rebuild.
+     */
+    handle = null;
     _src = '';
     _shape = 'box';
     _color = 0xffffff;
@@ -87,10 +94,13 @@ export class Model extends Component {
     build() {
         if (!this.root)
             return;
-        if (this._src)
-            this.root.add(this.game.assets.model(this._src).root);
-        else
+        if (this._src) {
+            this.handle = this.game.assets.model(this._src);
+            this.root.add(this.handle.root);
+        }
+        else {
             this.buildPrimitive(this.root);
+        }
     }
     buildPrimitive(root) {
         const material = new THREE.MeshStandardNodeMaterial({ color: this._color });
@@ -108,6 +118,7 @@ export class Model extends Component {
     /** Empties the root and disposes the primitive this Model created; a glTF's clone only leaves the graph. */
     clear() {
         this.root?.clear();
+        this.handle = null;
         if (!this._primitive)
             return;
         this._primitive.mesh.geometry.dispose();

package/dist/index.d.ts

@@ -12,6 +12,8 @@ export type { AudioBackend, AudioResource, BackendPlayHandle, BackendPlayOptions
 export type { AudioChannelState, AudioPlayOptions, LiveSoundInfo, SoundHandle } from './audio/types.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
 export type { AnimationFacingProvider, DirectionalAnimation, DirectionalFallback, ResolvedDirectionalClip, } from './animation/directional.js';
+export { isClipTarget } from './animation/clip-target.js';
+export type { ClipTarget } from './animation/clip-target.js';
 export { isYSortBatchParticipant, isYSortParticipant, ySortZ } from './render-sort.js';
 export type { YSortBatchParticipant, YSortEntry, YSortParticipant } from './render-sort.js';
 export { projectIsometric, screenInputToLogical, unprojectIsometric } from './projection.js';
@@ -63,6 +65,9 @@ export { Sprite } from './components/sprite.js';
 export { Light } from './components/light.js';
 export { Model } from './components/model.js';
 export type { ModelShape } from './components/model.js';
+export { Animator } from './components/animator.js';
+export type { AnimatorClipOverride, AnimatorState } from './components/animator.js';
+export { poseHash } from './animation/pose-hash.js';
 export { Sun } from './components/sun.js';
 export { Collider, COLLIDER_SHAPES } from './components/collider.js';
 export type { ColliderShape } from './components/collider.js';

package/dist/index.js

@@ -3,6 +3,7 @@ export { AssetLoader } from './assets/asset-loader.js';
 export { GltfModelBackend } from './assets/model-backend.js';
 export { AudioSubsystem } from './audio/audio-subsystem.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
+export { isClipTarget } from './animation/clip-target.js';
 export { isYSortBatchParticipant, isYSortParticipant, ySortZ } from './render-sort.js';
 export { projectIsometric, screenInputToLogical, unprojectIsometric } from './projection.js';
 export { spritePlacement } from './sprite-placement.js';
@@ -29,6 +30,8 @@ export { GameUi } from './ui.js';
 export { Sprite } from './components/sprite.js';
 export { Light } from './components/light.js';
 export { Model } from './components/model.js';
+export { Animator } from './components/animator.js';
+export { poseHash } from './animation/pose-hash.js';
 export { Sun } from './components/sun.js';
 export { Collider, COLLIDER_SHAPES } from './components/collider.js';
 export { RigidBody, RIGID_BODY_TYPES } from './components/rigid-body.js';

package/dist/state/state-machine.d.ts

@@ -3,7 +3,7 @@ import type { Entity } from '../entity.js';
 import { type StateHooks } from './hooks.js';
 /** One outgoing edge: when `on` fires, the machine moves to `to`. */
 export interface StateTransitionJson {
-    /** Trigger: 'input:<action>' | 'timer:<seconds>' | 'signal:<name>'. */
+    /** Trigger: 'input:<action>' | 'timer:<seconds>' | 'signal:<name>' | 'clip:end'. */
     on: string;
     to: string;
 }
@@ -13,7 +13,7 @@ export interface StateTransitionJson {
  * transitions instead of a real state.
  */
 export interface StateJson {
-    /** Clip reference resolved against the sibling AnimatedSprite; defaults to the state's name. */
+    /** Clip reference resolved against the sibling Clip Target (an AnimatedSprite or an Animator); defaults to the state's name. */
     clip?: string;
     transitions?: StateTransitionJson[];
 }
@@ -24,6 +24,8 @@ export interface TriggerEnv {
     /** Seconds spent in the current state. */
     elapsed: number;
     signals: ReadonlySet<string>;
+    /** Whether the Clip Target reports its non-looping clip finished (issue #166); false with no target. */
+    clipFinished: boolean;
 }
 /** Whether one trigger fires. Unknown or malformed triggers never fire. */
 export declare function evaluateTrigger(on: string, env: TriggerEnv): boolean;
@@ -41,9 +43,10 @@ export declare function phaseHooks(hooks: StateHooks[], fallback: StateHooks | u
  * logic — only the active state's code moves the body, so behaviors
  * never fight over velocity. States and transitions are prefab data;
  * state code lives in the role's logic set (defineRole / defineStates)
- * picked by `role`. Entering a state plays the sibling AnimatedSprite
- * clip of the same name (or the state's `clip` override); a missing
- * clip warns and keeps the previous one.
+ * picked by `role`. Entering a state plays the clip of the same name (or
+ * the state's `clip` override) through the entity's Clip Target — the
+ * first sibling that plays clips, an AnimatedSprite in 2D or an Animator
+ * in 3D (issue #166); a missing clip warns and keeps the previous one.
  */
 export declare class StateMachine extends Component {
     static componentName: string;
@@ -66,8 +69,17 @@ export declare class StateMachine extends Component {
     private readonly instanceHooks;
     private readonly signals;
     private readonly warnedClips;
+    /** States already warned that their mirrored clip met a target that cannot flip. */
+    private readonly warnedFlips;
     /** Facing last used to resolve a directional clip — detects a turn mid-state. */
     private lastFacing;
+    /**
+     * The clip the current state asked its Clip Target for, undefined when it
+     * asked for nothing (no target, or a clip the target lacks). `clip:end`
+     * reads only this clip: a one-shot left finished by an earlier state never
+     * counts for a state that could not play its own.
+     */
+    private requestedClip;
     onReady(): void;
     /** Adds instance-level hooks on top of the logic set — the escape hatch. */
     on(state: string, hooks: StateHooks): void;
@@ -83,20 +95,32 @@ export declare class StateMachine extends Component {
     private runCollision;
     private enter;
     private playClip;
+    /** The Clip Target: the first sibling that plays clips (duck-typed, like the facing provider). */
+    private clipTarget;
     /**
      * Directional resolution: with an installed contract AND a sibling that
      * reports facing, plays state × facing (mirroring included). Returns false
      * to keep the name-based path — no contract, no facing, no playable clip.
      */
     private playDirectionalClip;
+    /** State × facing through the installed contract and the target's clips, remembering the facing used; undefined keeps the name-based path. */
+    private resolveFacingClip;
+    /**
+     * Applies the resolved mirror. A target without `setFlipX` (an Animator:
+     * 3D faces by turning) plays a mirrored clip unmirrored and warns once
+     * per state, so a 2D target that forgot its mirror is not silent.
+     */
+    private mirror;
     private facingProvider;
     /**
      * playDirectionalClip only runs at enter() time (via playClip), so a
      * facing change that doesn't cross a state boundary — turning while
      * still walking, say — never re-resolves the clip on its own. Catch that
-     * here every frame: same state, new facing, re-run the resolution.
-     * AnimatedSprite.play() no-ops on an unchanged clip name, so this is
-     * cheap when facing hasn't moved the resolved clip.
+     * here every frame: same state, new facing, re-run the resolution. A
+     * turn that only mirrors (west playing east flipped) re-applies the
+     * mirror and leaves the clip alone — a running one keeps its frame and a
+     * finished one-shot keeps its last — so only a turn onto another clip
+     * name plays, as re-entering the state would.
      */
     private reresolveOnFacingChange;
 }

package/dist/state/state-machine.js

@@ -1,6 +1,6 @@
 import { installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from '../animation/directional.js';
+import { isClipTarget } from '../animation/clip-target.js';
 import { Component } from '../component.js';
-import { AnimatedSprite } from '../components/animated-sprite.js';
 import { MAX_CHAINED_HOPS, SIMULATION_TIME_EPSILON } from '../fixed-step.js';
 import { closestLogicSet, logicSet, registeredLogicSets, } from './hooks.js';
 /** Whether one trigger fires. Unknown or malformed triggers never fire. */
@@ -23,6 +23,10 @@ export function evaluateTrigger(on, env) {
         return env.elapsed + SIMULATION_TIME_EPSILON >= Number(arg);
     if (kind === 'signal')
         return env.signals.has(arg);
+    // The target updates after the machine (updateAfter: ['StateMachine']), so
+    // this fires on the Simulation Step after the clip finished, never for a loop.
+    if (kind === 'clip')
+        return arg === 'end' && env.clipFinished;
     return false;
 }
 /** The first firing transition: the state's own edges, then '*''s. */
@@ -46,9 +50,10 @@ export function phaseHooks(hooks, fallback, phase) {
  * logic — only the active state's code moves the body, so behaviors
  * never fight over velocity. States and transitions are prefab data;
  * state code lives in the role's logic set (defineRole / defineStates)
- * picked by `role`. Entering a state plays the sibling AnimatedSprite
- * clip of the same name (or the state's `clip` override); a missing
- * clip warns and keeps the previous one.
+ * picked by `role`. Entering a state plays the clip of the same name (or
+ * the state's `clip` override) through the entity's Clip Target — the
+ * first sibling that plays clips, an AnimatedSprite in 2D or an Animator
+ * in 3D (issue #166); a missing clip warns and keeps the previous one.
  */
 export class StateMachine extends Component {
     static componentName = 'StateMachine';
@@ -62,7 +67,9 @@ export class StateMachine extends Component {
         'instanceHooks',
         'signals',
         'warnedClips',
+        'warnedFlips',
         'lastFacing',
+        'requestedClip',
     ];
     /** The character's role — names the logic set providing its state code. */
     role = '';
@@ -76,8 +83,17 @@ export class StateMachine extends Component {
     instanceHooks = new Map();
     signals = new Set();
     warnedClips = new Set();
+    /** States already warned that their mirrored clip met a target that cannot flip. */
+    warnedFlips = new Set();
     /** Facing last used to resolve a directional clip — detects a turn mid-state. */
     lastFacing;
+    /**
+     * The clip the current state asked its Clip Target for, undefined when it
+     * asked for nothing (no target, or a clip the target lacks). `clip:end`
+     * reads only this clip: a one-shot left finished by an earlier state never
+     * counts for a state that could not play its own.
+     */
+    requestedClip;
     onReady() {
         if (this.role && !logicSet(this.role)) {
             const sets = registeredLogicSets();
@@ -111,10 +127,12 @@ export class StateMachine extends Component {
         this.run('*', 'onUpdate', dt);
         this.run(this.current, 'onUpdate', dt);
         this.elapsed += dt;
+        // The target is found once per step: entering a state never changes it.
+        const target = this.clipTarget();
         // Chained transitions settle within the frame (e.g. land → idle → run),
         // capped so a degenerate cyclic graph can't hang the loop.
         for (let hops = 0; hops < MAX_CHAINED_HOPS; hops++) {
-            const edge = nextTransition(this.states, this.current, this.env());
+            const edge = nextTransition(this.states, this.current, this.env(target));
             // A '*' edge is re-merged against whatever state the loop just
             // entered, so a still-queued signal (signals.clear() only runs after
             // this loop) keeps firing every remaining hop. Without this guard
@@ -145,11 +163,12 @@ export class StateMachine extends Component {
             return;
         this.runCollision(state, other);
     }
-    env() {
+    env(target) {
         return {
             justPressed: (action) => this.game.input.justPressed(action) && !this.game.input.consumed(action),
             elapsed: this.elapsed,
             signals: this.signals,
+            clipFinished: this.requestedClip !== undefined && target?.current === this.requestedClip && target.clipFinished,
         };
     }
     hooksFor(state) {
@@ -182,41 +201,74 @@ export class StateMachine extends Component {
         this.run(state, 'onEnter');
     }
     playClip(state) {
-        const sprite = this.entity.get(AnimatedSprite);
-        if (!sprite)
+        this.requestedClip = undefined;
+        const target = this.clipTarget();
+        if (!target)
             return;
         const clip = this.states[state]?.clip ?? state;
-        if (this.playDirectionalClip(sprite, clip))
+        if (this.playDirectionalClip(target, clip))
             return;
-        if (sprite.clips[clip]) {
-            sprite.play(clip);
+        // A target whose clips are pending (an Animator whose glb is still
+        // loading) is asked anyway and remembers the request (issue #166).
+        if (target.clipsPending || target.clipNames.includes(clip)) {
+            target.play(clip);
+            this.requestedClip = clip;
         }
         else if (!this.warnedClips.has(state)) {
             this.warnedClips.add(state);
             console.warn(`[waica] "${this.entity.name}": no clip "${clip}" for state "${state}" — ` +
-                `keeping "${sprite.current ?? 'none'}"`);
+                `keeping "${target.current ?? 'none'}"`);
         }
     }
+    /** The Clip Target: the first sibling that plays clips (duck-typed, like the facing provider). */
+    clipTarget() {
+        return this.entity.components.find((c) => isClipTarget(c));
+    }
     /**
      * Directional resolution: with an installed contract AND a sibling that
      * reports facing, plays state × facing (mirroring included). Returns false
      * to keep the name-based path — no contract, no facing, no playable clip.
      */
-    playDirectionalClip(sprite, clip) {
+    playDirectionalClip(target, clip) {
+        const resolved = this.resolveFacingClip(target, clip);
+        if (!resolved)
+            return false;
+        this.mirror(target, resolved);
+        target.play(resolved.clip);
+        this.requestedClip = resolved.clip;
+        return true;
+    }
+    /** State × facing through the installed contract and the target's clips, remembering the facing used; undefined keeps the name-based path. */
+    resolveFacingClip(target, clip) {
         const animation = installedDirectionalAnimation();
         if (!animation)
-            return false;
+            return undefined;
         const provider = this.facingProvider();
         if (!provider)
-            return false;
+            return undefined;
         const facing = provider.getAnimationFacing();
         this.lastFacing = facing;
-        const resolved = resolveDirectionalClip(animation, Object.keys(sprite.clips), clip, facing);
-        if (!resolved.clip || !sprite.clips[resolved.clip])
-            return false;
-        sprite.setFlipX(resolved.flip);
-        sprite.play(resolved.clip);
-        return true;
+        const names = target.clipNames;
+        const resolved = resolveDirectionalClip(animation, names, clip, facing);
+        if (!resolved.clip || !names.includes(resolved.clip))
+            return undefined;
+        return { clip: resolved.clip, flip: resolved.flip };
+    }
+    /**
+     * Applies the resolved mirror. A target without `setFlipX` (an Animator:
+     * 3D faces by turning) plays a mirrored clip unmirrored and warns once
+     * per state, so a 2D target that forgot its mirror is not silent.
+     */
+    mirror(target, resolved) {
+        if (target.setFlipX) {
+            target.setFlipX(resolved.flip);
+            return;
+        }
+        if (!resolved.flip || this.warnedFlips.has(this.current))
+            return;
+        this.warnedFlips.add(this.current);
+        console.warn(`[waica] "${this.entity.name}": clip "${resolved.clip}" is mirrored for facing "${this.lastFacing ?? ''}", ` +
+            'but the Clip Target cannot flip — playing it unmirrored');
     }
     facingProvider() {
         return this.entity.components.find((c) => isAnimationFacingProvider(c));
@@ -225,19 +277,28 @@ export class StateMachine extends Component {
      * playDirectionalClip only runs at enter() time (via playClip), so a
      * facing change that doesn't cross a state boundary — turning while
      * still walking, say — never re-resolves the clip on its own. Catch that
-     * here every frame: same state, new facing, re-run the resolution.
-     * AnimatedSprite.play() no-ops on an unchanged clip name, so this is
-     * cheap when facing hasn't moved the resolved clip.
+     * here every frame: same state, new facing, re-run the resolution. A
+     * turn that only mirrors (west playing east flipped) re-applies the
+     * mirror and leaves the clip alone — a running one keeps its frame and a
+     * finished one-shot keeps its last — so only a turn onto another clip
+     * name plays, as re-entering the state would.
      */
     reresolveOnFacingChange() {
         if (!this.current || !installedDirectionalAnimation())
             return;
-        const sprite = this.entity.get(AnimatedSprite);
-        if (!sprite)
+        const target = this.clipTarget();
+        if (!target)
             return;
         const provider = this.facingProvider();
         if (!provider || provider.getAnimationFacing() === this.lastFacing)
             return;
-        this.playDirectionalClip(sprite, this.states[this.current]?.clip ?? this.current);
+        const resolved = this.resolveFacingClip(target, this.states[this.current]?.clip ?? this.current);
+        if (!resolved)
+            return;
+        this.mirror(target, resolved);
+        if (resolved.clip === target.current)
+            return;
+        target.play(resolved.clip);
+        this.requestedClip = resolved.clip;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",