@waica/engine 0.25.0 → 0.27.0

package/dist/spatial-query.d.ts

@@ -4,7 +4,8 @@ import { Hitbox } from './components/hitbox.js';
 import { Solid } from './components/solid.js';
 import type { Entity } from './entity.js';
 import type { Game } from './game.js';
-type ComponentClasses = readonly ComponentClass[];
+import { type Point3d, type QueryVolume3d, type RayHit3d } from './spatial-query-3d.js';
+export type ComponentClasses = readonly ComponentClass[];
 type QueryEntity<Classes extends ComponentClasses> = Classes extends readonly [] ? Entity : EntityWith<Classes>;
 /** An Entity whose required component classes return non-optional instances. */
 export interface EntityWith<Classes extends ComponentClasses> extends Entity {
@@ -57,21 +58,34 @@ type NearestGuardFilter<Classes extends ComponentClasses, Narrowed extends Query
 /** Public logical-space spatial-query service owned by every Game. */
 export interface SpatialQuery {
     /** Hitbox owners with positive interior overlap, mask-agnostic and in Entity order. */
-    area<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(body: CollisionBody, filter: SpatialGuardFilter<Classes, Narrowed>): Narrowed[];
-    area<Classes extends ComponentClasses = readonly []>(body: CollisionBody, filter: SpatialQueryFilter<Classes>): QueryEntity<Classes>[];
-    area(body: CollisionBody, filter?: SpatialQueryFilter): Entity[];
+    area<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(body: CollisionBody | QueryVolume3d, filter: SpatialGuardFilter<Classes, Narrowed>): Narrowed[];
+    /** In a 3D scene `area` takes a volume and returns the entities whose sensor colliders intersect it, in Entity order. */
+    area<Classes extends ComponentClasses = readonly []>(body: CollisionBody | QueryVolume3d, filter: SpatialQueryFilter<Classes>): QueryEntity<Classes>[];
+    area(body: CollisionBody | QueryVolume3d, filter?: SpatialQueryFilter): Entity[];
     /** Hitbox owners that strictly contain a point, mask-agnostic and in Entity order. */
     point<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(x: number, y: number, filter: SpatialGuardFilter<Classes, Narrowed>): Narrowed[];
     point<Classes extends ComponentClasses = readonly []>(x: number, y: number, filter: SpatialQueryFilter<Classes>): QueryEntity<Classes>[];
     point(x: number, y: number, filter?: SpatialQueryFilter): Entity[];
+    /** 3D scenes: entities whose sensor colliders contain the point, in Entity order. */
+    point<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(at: Point3d, filter: SpatialGuardFilter<Classes, Narrowed>): Narrowed[];
+    point<Classes extends ComponentClasses = readonly []>(at: Point3d, filter: SpatialQueryFilter<Classes>): QueryEntity<Classes>[];
+    point(at: Point3d, filter?: SpatialQueryFilter): Entity[];
     /** Closest filtered logical transform; equal distances retain Entity order. */
     nearest<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(x: number, y: number, filter: NearestGuardFilter<Classes, Narrowed>): Narrowed | null;
     nearest<Classes extends ComponentClasses = readonly []>(x: number, y: number, filter: NearestSpatialQueryFilter<Classes>): QueryEntity<Classes> | null;
     nearest(x: number, y: number, filter?: NearestSpatialQueryFilter): Entity | null;
+    /** 3D scenes: the closest filtered transform, z included. */
+    nearest<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(at: Point3d, filter: NearestGuardFilter<Classes, Narrowed>): Narrowed | null;
+    nearest<Classes extends ComponentClasses = readonly []>(at: Point3d, filter: NearestSpatialQueryFilter<Classes>): QueryEntity<Classes> | null;
+    nearest(at: Point3d, filter?: NearestSpatialQueryFilter): Entity | null;
     /** First strict crossing of direct or source-derived Solid geometry. */
     ray<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(x: number, y: number, dx: number, dy: number, maxDistance: number, filter: SpatialGuardFilter<Classes, Narrowed>): RayHit<Narrowed> | null;
     ray<Classes extends ComponentClasses = readonly []>(x: number, y: number, dx: number, dy: number, maxDistance: number, filter: SpatialQueryFilter<Classes>): RayHit<QueryEntity<Classes>> | null;
     ray(x: number, y: number, dx: number, dy: number, maxDistance: number, filter?: SpatialQueryFilter): RayHit | null;
+    /** 3D scenes: the first solid collider along the ray (sensors never block it); `direction` need not be a unit vector. */
+    ray<Classes extends ComponentClasses = readonly [], Narrowed extends QueryEntity<Classes> = QueryEntity<Classes>>(origin: Point3d, direction: Point3d, maxDistance: number, filter: SpatialGuardFilter<Classes, Narrowed>): RayHit3d<Narrowed> | null;
+    ray<Classes extends ComponentClasses = readonly []>(origin: Point3d, direction: Point3d, maxDistance: number, filter: SpatialQueryFilter<Classes>): RayHit3d<QueryEntity<Classes>> | null;
+    ray(origin: Point3d, direction: Point3d, maxDistance: number, filter?: SpatialQueryFilter): RayHit3d | null;
 }
 export interface HitboxCandidate {
     readonly entity: Entity;

package/dist/spatial-query.js

@@ -3,6 +3,7 @@ import { collisionBounds, collisionOverlap, } from './collision-shape.js';
 import { Hitbox } from './components/hitbox.js';
 import { Solid } from './components/solid.js';
 import { createHitboxBroadphase, createSolidBroadphase, } from './spatial-broadphase.js';
+import { SpatialQuery3d } from './spatial-query-3d.js';
 import { collisionBodyContainsPoint, collisionBodyRay, SPATIAL_QUERY_EPSILON, usableCollisionBody, } from './spatial-query-geometry.js';
 function indexedCandidateProviders(game) {
     return {
@@ -162,7 +163,62 @@ class LinearSpatialQuery {
         return result;
     }
 }
+/** A volume names its place by `center`; a collision body by `x` and `y`. */
+const isVolume = (value) => typeof value === 'object' && value !== null && 'center' in value;
+const isRay3d = (args) => typeof args[0] === 'object';
+/**
+ * Sends each call to the form its arguments name and refuses the form of the
+ * other space with an error naming both (issue #159 CA-21): the 2D forms read
+ * Hitboxes and Solids and take numbers or a collision body; the 3D forms read
+ * the physics world and take `{ x, y, z }` objects.
+ */
+class SpaceSpatialQuery {
+    game;
+    flat;
+    solid;
+    constructor(game, flat) {
+        this.game = game;
+        this.flat = flat;
+        this.solid = new SpatialQuery3d(game, { matchesCommon: matchesCommonFilter });
+    }
+    area(first, filter) {
+        if (isVolume(first))
+            return this.in3d('area').area(first, filter);
+        this.require('area', '2d');
+        return this.flat.area(first, filter);
+    }
+    point(first, second, third) {
+        if (typeof first === 'object')
+            return this.in3d('point').point(first, typeof second === 'object' ? second : undefined);
+        this.require('point', '2d');
+        return this.flat.point(first, typeof second === 'number' ? second : Number.NaN, third);
+    }
+    nearest(first, second, third) {
+        if (typeof first === 'object')
+            return this.in3d('nearest').nearest(first, typeof second === 'object' ? second : undefined);
+        this.require('nearest', '2d');
+        return this.flat.nearest(first, typeof second === 'number' ? second : Number.NaN, third);
+    }
+    ray(...args) {
+        if (isRay3d(args)) {
+            const [origin, direction, maxDistance, filter] = args;
+            return this.in3d('ray').ray({ origin, direction }, maxDistance, filter);
+        }
+        this.require('ray', '2d');
+        return this.flat.ray(...args);
+    }
+    in3d(operation) {
+        this.require(operation, '3d');
+        return this.solid;
+    }
+    require(operation, space) {
+        // Only a 3D scene turns the 2D forms away; anything else (no scene, or a stand-in Game) is the 2D world.
+        if (space === '3d' ? this.game.space === '3d' : this.game.space !== '3d')
+            return;
+        throw new Error(`game.query.${operation}: the ${space === '3d' ? '3D' : '2D'} form needs a ${space} scene, and the live scene is ${this.game.space}.`);
+    }
+}
 /** Package-internal constructor; only the SpatialQuery interface is public. */
 export function createSpatialQuery(game, candidates = indexedCandidateProviders(game), instrumentation) {
-    return new LinearSpatialQuery(candidates, instrumentation);
+    return new SpaceSpatialQuery(game, new LinearSpatialQuery(candidates, instrumentation));
 }

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.25.0",
+  "version": "0.27.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
     }
   },
   "dependencies": {
+    "@dimforge/rapier3d-deterministic-compat": "0.21.0",
     "@types/three": "^0.186.0",
     "three": "^0.186.1"
   }