@waica/engine 0.26.0 → 0.28.0

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.28.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",