@waica/engine 0.26.0 → 0.28.0

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/game.d.ts

@@ -255,7 +255,7 @@ export declare class Game {
     get projection(): 'isometric' | null;
     /** The live scene's space (`render.space`); `'2d'` with no scene (ADR 0027). */
     get space(): SceneSpace;
-    /** The camera the live scene draws with: orthographic in 2D scenes, perspective in 3D ones. */
+    /** The camera the live scene draws with: orthographic in 2D scenes, perspective in 3D ones, or a host's view camera over a 3D one (`cameraRig.setViewCamera`). */
     get camera(): GameCamera;
     /**
      * Where a logical point falls on the canvas, in CSS px from its top-left

package/dist/game.js

@@ -469,7 +469,7 @@ export class Game {
     get space() {
         return this.sceneSpace;
     }
-    /** The camera the live scene draws with: orthographic in 2D scenes, perspective in 3D ones. */
+    /** The camera the live scene draws with: orthographic in 2D scenes, perspective in 3D ones, or a host's view camera over a 3D one (`cameraRig.setViewCamera`). */
     get camera() {
         return this.cameraRig.camera;
     }

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { AssetLoader } from './assets/asset-loader.js';
 export type { AssetStatus } from './assets/asset-loader.js';
 export type { TextureBackend } from './assets/texture-backend.js';
 export { GltfModelBackend } from './assets/model-backend.js';
+export { glbClipNames } from './assets/glb-clip-names.js';
 export type { LoadedModel, ModelBackend } from './assets/model-backend.js';
 export type { ModelHandle, ModelOutcome } from './assets/model-cache.js';
 export { AudioSubsystem } from './audio/audio-subsystem.js';
@@ -12,6 +13,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';
@@ -47,6 +50,8 @@ export type { ActionName, InjectedActionOperation, InputBindings, InputOptions }
 export { ACTION_HELD_THRESHOLD, firstStandardPadValues, GAMEPAD_CODE_PREFIX, gamepadControl, } from './gamepad.js';
 export type { GamepadControl } from './gamepad.js';
 export { Pointer } from './pointer.js';
+export { raycastPick } from './pointer-raycast.js';
+export type { PickedTarget, PickTarget, RaycastPick, ViewportFraction } from './pointer-raycast.js';
 export type { PointerCamera, PointerDeps, PointerPick, PointerResolution } from './pointer.js';
 export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
 export type { RuntimeBridge, RuntimeBridgeActivation, RuntimeBridgeFailure, RuntimeControlRequest, RuntimeControlResult, RuntimeMetadata, RuntimeMode, } from './runtime-bridge.js';
@@ -63,6 +68,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

@@ -1,8 +1,10 @@
 export { Game } from './game.js';
 export { AssetLoader } from './assets/asset-loader.js';
 export { GltfModelBackend } from './assets/model-backend.js';
+export { glbClipNames } from './assets/glb-clip-names.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';
@@ -22,6 +24,7 @@ export { resolveComponentUpdateSchedule } from './component-update-schedule.js';
 export { Input, DEFAULT_BINDINGS } from './input.js';
 export { ACTION_HELD_THRESHOLD, firstStandardPadValues, GAMEPAD_CODE_PREFIX, gamepadControl, } from './gamepad.js';
 export { Pointer } from './pointer.js';
+export { raycastPick } from './pointer-raycast.js';
 export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
 export { Stats } from './stats.js';
@@ -29,6 +32,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/pointer-raycast.d.ts

@@ -1,17 +1,35 @@
 import * as THREE from 'three/webgpu';
 import type { Entity } from './entity.js';
-import type { PointerPick } from './pointer.js';
 /** A position inside the letterboxed game viewport, as fractions of its width and height. */
 export interface ViewportFraction {
     nx: number;
     ny: number;
 }
+/** What an extra target picks: an entity (an editor's icon for it), or the scene camera's icon. */
+export type PickedTarget = Entity | 'camera';
+/** An object a ray is also tested against, and what a hit on it picks (issue #173 CA-2). */
+export interface PickTarget<Picked extends PickedTarget = PickedTarget> {
+    readonly object: THREE.Object3D;
+    readonly entity: Picked;
+}
+/** A 3D pick: the hit's world point, and the entity (or extra target) hit, or null on the ground. */
+export interface RaycastPick<Picked extends PickedTarget = Entity> {
+    readonly point: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    };
+    readonly entity: Entity | Picked | null;
+}
 /**
  * The pick for a click on a 3D scene (issue #154 CA-12): a ray through the
  * letterboxed point, intersected with the roots of every live Model
- * (recursively, so a glTF's meshes count and a glTF still loading does not).
- * The nearest hit wins, with its world-space point. With no hit the pick has
- * no entity and the point where the ray meets the ground plane y = 0; a ray
- * that never meets it (it looks at the sky) yields no pick.
+ * (recursively, so a glTF's meshes count, posed where its skeleton is, and a
+ * glTF still loading does not) and with the `extra` targets a host adds (the
+ * editor's icons, issue #173 CA-2; one that is hidden, or whose entity is
+ * dead, is skipped). The nearest hit wins, with its
+ * world-space point. With no hit the pick has no entity and the point where
+ * the ray meets the ground plane y = 0; a ray that never meets it (it looks
+ * at the sky) yields no pick.
  */
-export declare function raycastPick(camera: THREE.PerspectiveCamera, at: ViewportFraction, entities: readonly Entity[]): PointerPick | null;
+export declare function raycastPick<Picked extends PickedTarget = Entity>(camera: THREE.PerspectiveCamera, at: ViewportFraction, entities: readonly Entity[], extra?: readonly PickTarget<Picked>[]): RaycastPick<Picked> | null;

package/dist/pointer-raycast.js

@@ -16,33 +16,63 @@ function modelRoots(entities) {
     }
     return roots;
 }
-/** The entity whose Model root `object` hangs under. */
-function ownerOf(object, roots) {
+/** What `object` picks: the target or Model root it hangs under, nearest first. */
+function ownerOf(object, owners) {
     for (let node = object; node; node = node.parent) {
-        const entity = roots.get(node);
-        if (entity)
-            return entity;
+        const owner = owners.get(node);
+        if (owner)
+            return owner;
     }
     return null;
 }
+/** Whether `target` is drawn and still picks something: itself and every ancestor visible, and its entity alive. */
+function isPickable(target) {
+    if (target.entity !== 'camera' && !target.entity.alive)
+        return false;
+    for (let node = target.object; node; node = node.parent) {
+        if (!node.visible)
+            return false;
+    }
+    return true;
+}
+/** The extra targets' hits: tested whatever their layers, since an editor overlay lives on the Emissive layer alone. */
+function extraHits(targets) {
+    if (targets.length === 0)
+        return [];
+    const own = raycaster.layers.mask;
+    raycaster.layers.enableAll();
+    try {
+        return raycaster.intersectObjects(targets.filter(isPickable).map((target) => target.object), true);
+    }
+    finally {
+        raycaster.layers.mask = own;
+    }
+}
 /**
  * The pick for a click on a 3D scene (issue #154 CA-12): a ray through the
  * letterboxed point, intersected with the roots of every live Model
- * (recursively, so a glTF's meshes count and a glTF still loading does not).
- * The nearest hit wins, with its world-space point. With no hit the pick has
- * no entity and the point where the ray meets the ground plane y = 0; a ray
- * that never meets it (it looks at the sky) yields no pick.
+ * (recursively, so a glTF's meshes count, posed where its skeleton is, and a
+ * glTF still loading does not) and with the `extra` targets a host adds (the
+ * editor's icons, issue #173 CA-2; one that is hidden, or whose entity is
+ * dead, is skipped). The nearest hit wins, with its
+ * world-space point. With no hit the pick has no entity and the point where
+ * the ray meets the ground plane y = 0; a ray that never meets it (it looks
+ * at the sky) yields no pick.
  */
-export function raycastPick(camera, at, entities) {
+// eslint-disable-next-line max-params -- the signature spec #173 fixes: the Pointer's three inputs plus the optional extra targets; bundling them would be an unrelated bag
+export function raycastPick(camera, at, entities, extra = []) {
     camera.updateMatrixWorld();
     raycaster.setFromCamera(new THREE.Vector2(at.nx * 2 - 1, 1 - at.ny * 2), camera);
     const roots = modelRoots(entities);
+    const owners = new Map(roots);
+    for (const target of extra)
+        owners.set(target.object, target.entity);
     // A click can land before the first frame has placed anything.
-    for (const root of roots.keys())
-        root.updateWorldMatrix(true, true);
-    const [hit] = raycaster.intersectObjects([...roots.keys()], true);
+    for (const object of owners.keys())
+        object.updateWorldMatrix(true, true);
+    const [hit] = [...raycaster.intersectObjects([...roots.keys()], true), ...extraHits(extra)].sort((a, b) => a.distance - b.distance);
     if (hit)
-        return { entity: ownerOf(hit.object, roots), point: { x: hit.point.x, y: hit.point.y, z: hit.point.z } };
+        return { entity: ownerOf(hit.object, owners), point: { x: hit.point.x, y: hit.point.y, z: hit.point.z } };
     const ground = raycaster.ray.intersectPlane(GROUND, new THREE.Vector3());
     return ground ? { entity: null, point: { x: ground.x, y: ground.y, z: ground.z } } : null;
 }

package/dist/runtime-view-snapshot.js

@@ -6,7 +6,8 @@ function vector(value) {
     return [clean(value.x), clean(value.y), clean(value.z)];
 }
 export function viewSnapshot(game) {
-    const camera = game.camera;
+    // The scene's own camera: a host's view camera is not part of the simulated game, and `lookDistance` is the scene camera's.
+    const camera = game.cameraRig.sceneCamera;
     if (!isPerspectiveCamera(camera)) {
         return { kind: 'orthographic', position: [clean(camera.position.x), clean(camera.position.y)], zoom: game.view };
     }

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;
 }