@waica/behaviors 0.18.0 → 0.19.1

package/dist/click-to-move.js

@@ -75,7 +75,13 @@ function waypointsToward(game, mover, target) {
     const plan = planPath(grid, pointOf(mover), target);
     if (!plan)
         return [];
-    return plan.cells.map((cell) => grid.cellCenter(cell));
+    return plan.cells.map((cell) => {
+        const center = grid.cellCenter(cell);
+        // Invariant: planPath only returns cells of the grid it planned on.
+        if (!center)
+            throw new Error(`Planned cell (${cell.column}, ${cell.row}) is outside its navigation grid`);
+        return center;
+    });
 }
 function spawnMarker(clickToMove, game, mover, at) {
     const marker = game.spawn(`${mover.name}:click-marker`);
@@ -101,8 +107,7 @@ function spawnMarker(clickToMove, game, mover, at) {
 }
 /** Consumes the leading waypoints already reached; returns the direction to what's left. */
 function followWaypoints(clickToMove, mover, waypoints) {
-    while (waypoints.length > 0) {
-        const next = waypoints[0];
+    for (let next = waypoints[0]; next !== undefined; next = waypoints[0]) {
         const gap = distance(pointOf(mover), next);
         if (gap <= clickToMove.arrivalTolerance) {
             waypoints.shift();
@@ -168,7 +173,7 @@ function startOrder(clickToMove, entity, game, pick) {
         // An entity without Health/Interactable: fall through to a ground order.
     }
     const waypoints = waypointsToward(game, entity, pick.point);
-    const destination = waypoints.length > 0 ? waypoints[waypoints.length - 1] : pick.point;
+    const destination = waypoints.at(-1) ?? pick.point;
     clickToMove.order = { kind: 'ground', waypoints, destination };
     spawnMarker(clickToMove, game, entity, destination);
 }

package/dist/grid-motor.d.ts

@@ -1,6 +1,6 @@
 import { Component, type AnimationFacingProvider, type CameraVelocity, type CameraVelocityProvider } from '@waica/engine';
 /** Shared velocity, collision and provider behavior for square-grid motors. */
-export declare abstract class GridMotor<Facing extends string> extends Component implements CameraVelocityProvider, AnimationFacingProvider {
+export declare abstract class GridMotor extends Component implements CameraVelocityProvider, AnimationFacingProvider {
     static displayName: string;
     static params: {
         moveSpeed: {
@@ -47,7 +47,8 @@ export declare abstract class GridMotor<Facing extends string> extends Component
     hitboxHeight: number;
     vx: number;
     vy: number;
-    abstract facing: Facing;
+    /** Each motor narrows this to its own facing vocabulary. */
+    abstract facing: string;
     /** The scene camera reads follow velocity through this explicit seam. */
     getCameraVelocity(): CameraVelocity;
     /** The StateMachine resolves directional clips through this explicit seam. */

package/dist/grid-player-role.js

@@ -8,9 +8,9 @@ import { Respawnable } from './respawnable.js';
 /** Seconds the attack swing and the hurt stun each keep the body from the player. */
 const ATTACK_SECONDS = 0.3;
 const HURT_SECONDS = 0.3;
-/** Builds the common player graph and role around one genre-specific grid motor. */
-export function createGridPlayerRole(Motor, description) {
-    const graph = {
+/** The common player graph; fresh per role so no two roles share a mutable graph. */
+function gridPlayerGraph() {
+    return {
         initial: 'idle',
         states: {
             idle: {
@@ -50,7 +50,10 @@ export function createGridPlayerRole(Motor, description) {
             },
         },
     };
-    const update = (ctx, dt) => {
+}
+/** The body update: keyboard input, else a live Move Order, then the motor step and move/stop signal. */
+function gridPlayerUpdate(Motor) {
+    return (ctx, dt) => {
         const { entity, game, fsm } = ctx;
         const motor = entity.get(Motor);
         if (!motor)
@@ -78,6 +81,26 @@ export function createGridPlayerRole(Motor, description) {
         motor.step(dt);
         fsm.signal(motor.speed() > motor.walkThreshold ? 'move' : 'stop');
     };
+}
+/** Sets the motor's knockback velocity away from the last damage source, else back from its facing. */
+function knockBack({ entity, game }, motor) {
+    const source = entity.get(Health)?.lastDamageSource;
+    const dx = source ? entity.position.x - source.position.x : 0;
+    const dy = source ? entity.position.y - source.position.y : 0;
+    const distance = Math.hypot(dx, dy);
+    let away = distance > 0 ? { x: dx / distance, y: dy / distance } : undefined;
+    if (!away) {
+        // No source (or one standing on top of us): recoil from the facing.
+        const forward = logicalDirection(motor.facing, game.projection);
+        away = forward ? { x: -forward.x, y: -forward.y } : { x: 0, y: 0 };
+    }
+    motor.vx = away.x * motor.knockbackSpeed;
+    motor.vy = away.y * motor.knockbackSpeed;
+}
+/** Builds the common player graph and role around one genre-specific grid motor. */
+export function createGridPlayerRole(Motor, description) {
+    const graph = gridPlayerGraph();
+    const update = gridPlayerUpdate(Motor);
     const role = {
         description,
         driver: Motor.componentName,
@@ -112,22 +135,10 @@ export function createGridPlayerRole(Motor, description) {
                 onUpdate() { },
             },
             hurt: {
-                onEnter({ entity, game }) {
-                    const motor = entity.get(Motor);
-                    if (!motor)
-                        return;
-                    const source = entity.get(Health)?.lastDamageSource;
-                    const dx = source ? entity.position.x - source.position.x : 0;
-                    const dy = source ? entity.position.y - source.position.y : 0;
-                    const distance = Math.hypot(dx, dy);
-                    let away = distance > 0 ? { x: dx / distance, y: dy / distance } : undefined;
-                    if (!away) {
-                        // No source (or one standing on top of us): recoil from the facing.
-                        const forward = logicalDirection(motor.facing, game.projection);
-                        away = forward ? { x: -forward.x, y: -forward.y } : { x: 0, y: 0 };
-                    }
-                    motor.vx = away.x * motor.knockbackSpeed;
-                    motor.vy = away.y * motor.knockbackSpeed;
+                onEnter(ctx) {
+                    const motor = ctx.entity.get(Motor);
+                    if (motor)
+                        knockBack(ctx, motor);
                 },
                 // The shove resolves against Solids like any movement; no input.
                 onUpdate({ entity }, dt) {

package/dist/iso-motor.d.ts

@@ -7,7 +7,7 @@ export type IsoFacing = ScreenFacing;
  * shared GridMotor integrates and collides in logical square-grid space.
  * State code owns the frame; this component has no onUpdate of its own.
  */
-export declare class IsoMotor extends GridMotor<IsoFacing> {
+export declare class IsoMotor extends GridMotor {
     static componentName: string;
     facing: IsoFacing;
     /**

package/dist/pathfinding.js

@@ -35,6 +35,13 @@ function neighbors(grid, cell) {
 function stepCost(dc, dr) {
     return dc !== 0 && dr !== 0 ? Math.SQRT2 : 1;
 }
+/** The best known cost of a cell A* has already scored (every open or current cell has one). */
+function scoreOf(gScore, cellKey) {
+    const score = gScore.get(cellKey);
+    if (score === undefined)
+        throw new Error(`A* has no score for cell ${cellKey}`);
+    return score;
+}
 /** Octile distance: admissible heuristic for 8-way movement with unit/√2 costs. */
 function octile(a, b) {
     const dx = Math.abs(a.column - b.column);
@@ -51,8 +58,7 @@ export function reachableCells(grid, start) {
         return [];
     const visited = new Map([[key(start), start]]);
     const queue = [start];
-    while (queue.length > 0) {
-        const current = queue.shift();
+    for (let current = queue.shift(); current !== undefined; current = queue.shift()) {
         for (const next of neighbors(grid, current)) {
             const k = key(next);
             if (visited.has(k))
@@ -84,7 +90,7 @@ export function findPath(grid, start, goal) {
         let current;
         let bestF = Infinity;
         for (const [k, cell] of open) {
-            const f = gScore.get(k) + octile(cell, goal);
+            const f = scoreOf(gScore, k) + octile(cell, goal);
             if (f < bestF) {
                 bestF = f;
                 currentKey = k;
@@ -96,8 +102,7 @@ export function findPath(grid, start, goal) {
         if (currentKey === goalKey) {
             const path = [current];
             let trace = currentKey;
-            while (cameFrom.has(trace)) {
-                const previous = cameFrom.get(trace);
+            for (let previous = cameFrom.get(trace); previous; previous = cameFrom.get(trace)) {
                 path.unshift(previous);
                 trace = key(previous);
             }
@@ -106,7 +111,7 @@ export function findPath(grid, start, goal) {
         }
         open.delete(currentKey);
         closed.add(currentKey);
-        const currentG = gScore.get(currentKey);
+        const currentG = scoreOf(gScore, currentKey);
         for (const next of neighbors(grid, current)) {
             const nextKey = key(next);
             if (closed.has(nextKey))

package/dist/scene-transition.d.ts

@@ -1,4 +1,4 @@
-import { Component, type Entity } from '@waica/engine';
+import { Component, type CameraEffectColor, type Entity } from '@waica/engine';
 /**
  * Replaces the live scene with `scene` (its file's stem, e.g.
  * "cave.scene.json" -> "cave") when fired — a door, or any entity a player
@@ -13,6 +13,12 @@ import { Component, type Entity } from '@waica/engine';
  * it needs a sibling Interactable and fires from the shared nearest-wins
  * interact scan (interactable.ts's fireInteract), so a door and an NPC in
  * range arbitrate themselves with no new rule.
+ *
+ * With fadeSeconds > 0 it hides the swap behind a Fade (issue #74): the
+ * view fades to fadeColor over fadeSeconds, the destination loads, and the
+ * Fade clears over the same fadeSeconds in the incoming scene. Simulation
+ * and input keep running; while its outgoing fade runs, this component
+ * ignores further triggers. fadeSeconds 0 (the default) is a hard cut.
  */
 export declare class SceneTransition extends Component {
     static componentName: string;
@@ -24,10 +30,25 @@ export declare class SceneTransition extends Component {
             label: string;
             options: string[];
         };
+        fadeSeconds: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        fadeColor: {
+            label: string;
+        };
     };
     /** Destination scene name. */
     scene: string;
     trigger: 'overlap' | 'interact';
+    /** Seconds of each half of the fade (out, then clear); 0 = hard cut. */
+    fadeSeconds: number;
+    /** `'black'`, `'white'` or `'#rrggbb'`. */
+    fadeColor: CameraEffectColor;
+    /** True while the outgoing fade runs: further triggers do nothing. */
+    private _fadingOut;
     onReady(): void;
     onCollide(_other: Entity): void;
     onInteract(_initiator: Entity): void;

package/dist/scene-transition.js

@@ -14,16 +14,30 @@ import { Interactable } from './interactable.js';
  * it needs a sibling Interactable and fires from the shared nearest-wins
  * interact scan (interactable.ts's fireInteract), so a door and an NPC in
  * range arbitrate themselves with no new rule.
+ *
+ * With fadeSeconds > 0 it hides the swap behind a Fade (issue #74): the
+ * view fades to fadeColor over fadeSeconds, the destination loads, and the
+ * Fade clears over the same fadeSeconds in the incoming scene. Simulation
+ * and input keep running; while its outgoing fade runs, this component
+ * ignores further triggers. fadeSeconds 0 (the default) is a hard cut.
  */
 export class SceneTransition extends Component {
     static componentName = 'SceneTransition';
     static params = {
         scene: { label: 'Scene' },
         trigger: { label: 'Trigger', options: ['overlap', 'interact'] },
+        fadeSeconds: { label: 'Fade seconds', min: 0, max: 5, step: 0.05 },
+        fadeColor: { label: 'Fade color' },
     };
     /** Destination scene name. */
     scene = '';
     trigger = 'overlap';
+    /** Seconds of each half of the fade (out, then clear); 0 = hard cut. */
+    fadeSeconds = 0;
+    /** `'black'`, `'white'` or `'#rrggbb'`. */
+    fadeColor = 'black';
+    /** True while the outgoing fade runs: further triggers do nothing. */
+    _fadingOut = false;
     onReady() {
         if (this.trigger === 'interact' && !this.entity.has(Interactable)) {
             console.warn(`[waica] SceneTransition on "${this.entity.name}" has trigger:"interact" but no ` +
@@ -41,6 +55,72 @@ export class SceneTransition extends Component {
         this.fire();
     }
     fire() {
-        this.game.loadSceneByName(this.scene);
+        if (!(this.fadeSeconds > 0)) {
+            this.game.loadSceneByName(this.scene);
+            return;
+        }
+        if (this._fadingOut)
+            return;
+        const { game, fadeSeconds } = this;
+        const sceneAtFadeStart = game.sceneName;
+        const fadeHandle = game.cameraEffects.fade({ to: this.fadeColor, seconds: fadeSeconds });
+        this._fadingOut = true;
+        // Scheduled on Game Time, not on `fade.done`: a promise settles in a
+        // microtask, after a whole multi-step frame or Runtime Bridge `step`,
+        // while this timer fires on the exact step the fade has covered the view.
+        //
+        // Session-scoped and un-owned (issue #74 review): a mid-fade scene
+        // change (another transition, a Runtime Bridge `scene` op, a host
+        // reset) cancels scene-scoped work, and Entity.destroy() cancels an
+        // owned timer whatever its scope. Either would otherwise strand the
+        // Fade at opacity 1 with nothing left to clear it, since the Fade
+        // itself is session-scoped and keeps advancing on its own. This timer
+        // always runs; it swaps only if the door is still alive and the scene
+        // it started the fade in is still live, and it always queues the
+        // 'clear'.
+        game.time.after(fadeSeconds, () => {
+            // Superseded (PR #98 review): the Fade is one shared, session-scoped
+            // layer — a second door, or any other `cameraEffects.fade(...)`
+            // call, replaces this fade outright instead of queueing behind it
+            // (CameraEffects.fade() cancels whatever is running). `fadeHandle
+            // .superseded` is read synchronously here, never `.done`: that
+            // Promise only notifies its `.then()` in a microtask, and nothing
+            // flushes the microtask queue between this Game Time-scheduled
+            // callback and the many Simulation Steps that led up to it (same
+            // reasoning as scheduling the swap itself on Game Time instead of
+            // on `fade.done`, above). It is set once, synchronously, only when
+            // a *later* fade call actually replaces this one while it is still
+            // running — never for this door's own fade completing on its own,
+            // whatever step that lands on (`fire()` runs mid-`dispatchCollisions`
+            // for a real overlap, one Simulation Step "behind" where `game.time`
+            // sees this same call start, which would otherwise look identical
+            // to a supersession). If it is true, somebody else now owns the
+            // shared layer and its eventual 'clear': this door must not swap
+            // under their partial cover, and must not queue a 'clear' of its
+            // own that would cancel their fade. Nothing is in flight to
+            // protect, so the latch resets right away — the door can be
+            // triggered again if the player is still on it.
+            if (fadeHandle.superseded) {
+                this._fadingOut = false;
+                return;
+            }
+            if (this.entity.alive && game.sceneName === sceneAtFadeStart) {
+                game.loadSceneByName(this.scene);
+            }
+            // `_fadingOut` stays true here (PR #98 review): loadSceneByName
+            // above only *queues* the swap mid-frame, it doesn't apply it until
+            // the next frame. Dropping the guard now would let the rest of
+            // this same step's dispatchCollisions re-fire on the door, still
+            // alive and still overlapped, in the outgoing scene — a second
+            // fire() that schedules an orphan timer whose 'clear' lands in the
+            // new scene and cancels whatever legitimate fade is running there.
+            // Reset it only in the zero-delay follow-up below, once the queued
+            // swap has applied and the door has died with its scene (or, if
+            // the swap was skipped, once there is nothing left to re-arm).
+            game.time.after(0, () => {
+                this._fadingOut = false;
+                game.cameraEffects.fade({ to: 'clear', seconds: fadeSeconds });
+            }, { scope: 'session' });
+        }, { scope: 'session' });
     }
 }

package/dist/topdown-motor.d.ts

@@ -6,7 +6,7 @@ export type TopDownFacing = 'n' | 's' | 'e' | 'w';
  * step(). Eight-direction input is normalized so diagonals match cardinal
  * speed; movement has no gravity and resolves each axis against Solids.
  */
-export declare class TopDownMotor extends GridMotor<TopDownFacing> {
+export declare class TopDownMotor extends GridMotor {
     static componentName: string;
     /** Four-direction facing; starts looking at the camera. */
     facing: TopDownFacing;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/behaviors",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "description": "Waica built-in behaviors — the curated game-feel library",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,6 @@
     }
   },
   "dependencies": {
-    "@waica/engine": "^0.18.0"
+    "@waica/engine": "^0.19.1"
   }
 }