@waica/behaviors 0.10.0 → 0.11.0

package/dist/click-to-move.d.ts

@@ -0,0 +1,92 @@
+import { Component, type Entity, type StateContext } from '@waica/engine';
+import { type GridPoint } from './navigation-grid.js';
+interface GroundOrder {
+    kind: 'ground';
+    waypoints: GridPoint[];
+    /** The resolved cell center, for an exact snap on arrival (CA-4). */
+    destination: GridPoint;
+}
+interface NpcOrder {
+    kind: 'npc';
+    target: Entity;
+    waypoints: GridPoint[];
+    lastPlannedTarget: GridPoint | null;
+}
+interface AttackOrder {
+    kind: 'attack';
+    target: Entity;
+    waypoints: GridPoint[];
+    lastPlannedTarget: GridPoint | null;
+}
+type MoveOrder = GroundOrder | NpcOrder | AttackOrder;
+/** The minimal motor contract driveAttackOrder/driveGroundOrder need. */
+interface ClickToMoveMotor {
+    facing: string;
+    run(inputX: number, inputY: number, dt: number): void;
+    halt(): void;
+}
+/**
+ * Pointer-issued objective for a grid player role (CA-4/CA-5/CA-6): a click
+ * on open ground walks there, on an Interactable walks up and triggers its
+ * line, on a foreign Health walks into melee range and re-engages until it
+ * dies or disappears. Passive like a motor — driveClickToMove, called from
+ * the grid player role's update, does the driving; state code owns the
+ * frame.
+ */
+export declare class ClickToMove extends Component {
+    static componentName: string;
+    static displayName: string;
+    static params: {
+        arrivalTolerance: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        markerWidth: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        markerHeight: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        markerColor: {
+            label: string;
+        };
+        markerTexture: {
+            label: string;
+        };
+    };
+    static transient: string[];
+    /** Distance (logical units) counted as "arrived" at a waypoint or destination. */
+    arrivalTolerance: number;
+    /** Destination marker size (CA-8); a diamond/circle sized to taste per archetype. */
+    markerWidth: number;
+    markerHeight: number;
+    markerColor: number;
+    /** Empty draws a flat-color circle (the generic default); set to texture a diamond etc. */
+    markerTexture: string;
+    /** The live order, if any — exposed for tests and inspection, not authored. */
+    order: MoveOrder | null;
+    /** The ground-order destination marker entity, if one is currently shown. */
+    marker: Entity | null;
+    /** Cancels the active order (if any) and removes its marker (CA-4/CA-7). */
+    cancel(): void;
+    onDestroy(): void;
+    private despawnMarker;
+}
+/**
+ * Drives the active Move Order for one frame: drains a newly arrived click
+ * (replacing whatever order was active), then advances the live order and
+ * returns the logical-space direction the caller should move the motor
+ * along, or null to stand still. Called only while the role's shared body
+ * update runs (idle/walk) — never during attack/hurt/dead, which is exactly
+ * how a hurt stun pauses the order and a swing can't be interrupted (CA-7).
+ */
+export declare function driveClickToMove({ entity, game }: StateContext, motor: ClickToMoveMotor): GridPoint | null;
+export {};

package/dist/click-to-move.js

@@ -0,0 +1,276 @@
+import { Component, Sprite, screenInputToLogical, } from '@waica/engine';
+import { INTERACTABLE_UI_PIECE, Interactable } from './interactable.js';
+import { Health } from './health.js';
+import { MeleeAttack } from './melee-attack.js';
+import { buildNavigationGrid } from './navigation-grid.js';
+import { planPath } from './pathfinding.js';
+/** How close (logical units) counts as "arrived" at a waypoint or the final cell. */
+const DEFAULT_ARRIVAL_TOLERANCE = 0.2;
+/** How far (logical units) a chased target has to move before its path re-plans. */
+const ATTACK_REPLAN_DISTANCE = 0.5;
+/** Same threshold, for an NPC Move Order re-planning toward its target. */
+const NPC_REPLAN_DISTANCE = ATTACK_REPLAN_DISTANCE;
+/**
+ * Pointer-issued objective for a grid player role (CA-4/CA-5/CA-6): a click
+ * on open ground walks there, on an Interactable walks up and triggers its
+ * line, on a foreign Health walks into melee range and re-engages until it
+ * dies or disappears. Passive like a motor — driveClickToMove, called from
+ * the grid player role's update, does the driving; state code owns the
+ * frame.
+ */
+export class ClickToMove extends Component {
+    static componentName = 'ClickToMove';
+    static displayName = 'Click to move';
+    static params = {
+        arrivalTolerance: { label: 'Arrival tolerance', min: 0.05, max: 1, step: 0.05 },
+        markerWidth: { label: 'Marker width', min: 0.1, max: 2, step: 0.05 },
+        markerHeight: { label: 'Marker height', min: 0.1, max: 2, step: 0.05 },
+        markerColor: { label: 'Marker color' },
+        markerTexture: { label: 'Marker texture' },
+    };
+    static transient = ['order', 'marker'];
+    /** Distance (logical units) counted as "arrived" at a waypoint or destination. */
+    arrivalTolerance = DEFAULT_ARRIVAL_TOLERANCE;
+    /** Destination marker size (CA-8); a diamond/circle sized to taste per archetype. */
+    markerWidth = 0.5;
+    markerHeight = 0.25;
+    markerColor = 0xffffff;
+    /** Empty draws a flat-color circle (the generic default); set to texture a diamond etc. */
+    markerTexture = '';
+    /** The live order, if any — exposed for tests and inspection, not authored. */
+    order = null;
+    /** The ground-order destination marker entity, if one is currently shown. */
+    marker = null;
+    /** Cancels the active order (if any) and removes its marker (CA-4/CA-7). */
+    cancel() {
+        this.order = null;
+        this.despawnMarker();
+    }
+    onDestroy() {
+        this.despawnMarker();
+    }
+    despawnMarker() {
+        if (!this.marker)
+            return;
+        if (this.marker.alive)
+            this.marker.destroy();
+        this.marker = null;
+    }
+}
+function pointOf(entity) {
+    return { x: entity.position.x, y: entity.position.y };
+}
+function distance(a, b) {
+    return Math.hypot(a.x - b.x, a.y - b.y);
+}
+function unitToward(from, to) {
+    const gap = distance(from, to);
+    if (gap <= 1e-9)
+        return null;
+    return { x: (to.x - from.x) / gap, y: (to.y - from.y) / gap };
+}
+/** A* waypoints (cell centers) from the mover toward a logical point (CA-2/CA-3). */
+function waypointsToward(game, mover, target) {
+    const grid = buildNavigationGrid(game, [pointOf(mover), target], mover);
+    const plan = planPath(grid, pointOf(mover), target);
+    if (!plan)
+        return [];
+    return plan.cells.map((cell) => grid.cellCenter(cell));
+}
+function spawnMarker(clickToMove, game, mover, at) {
+    const marker = game.spawn(`${mover.name}:click-marker`);
+    marker.position.set(at.x, at.y, 0);
+    if (clickToMove.markerTexture) {
+        marker.add(Sprite, {
+            texture: clickToMove.markerTexture,
+            pixelArt: true,
+            width: clickToMove.markerWidth,
+            height: clickToMove.markerHeight,
+            color: clickToMove.markerColor,
+        });
+    }
+    else {
+        marker.add(Sprite, {
+            shape: 'circle',
+            width: clickToMove.markerWidth,
+            height: clickToMove.markerHeight,
+            color: clickToMove.markerColor,
+        });
+    }
+    clickToMove.marker = marker;
+}
+/** 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];
+        const gap = distance(pointOf(mover), next);
+        if (gap <= clickToMove.arrivalTolerance) {
+            waypoints.shift();
+            continue;
+        }
+        return { x: (next.x - mover.position.x) / gap, y: (next.y - mover.position.y) / gap };
+    }
+    return null;
+}
+/**
+ * Closes the last stretch toward an entity target directly, once the planned
+ * path (nearest-reachable-cell granularity) is exhausted but the live
+ * distance is still outside range/radius. A cell-quantized plan can resolve
+ * one cell short of a target whose own Solid straddles cell boundaries
+ * (CA-2's rasterization blocks at cell resolution); the direct approach
+ * closes that gap the same way normal collision does — GridMotor still
+ * resolves it per axis against every Solid, including the target's own, so
+ * this never walks through anything.
+ */
+function beelineToward(entity, target) {
+    return unitToward(pointOf(entity), pointOf(target));
+}
+/**
+ * Orients the motor's facing toward a point with zero velocity/position
+ * side effects: motor.run's own damped acceleration is a no-op at dt=0
+ * (THREE.MathUtils.damp returns its start value unchanged), so this reuses
+ * each motor's own facing algorithm (iso's eight-way, topdown's dominant
+ * axis) without duplicating it or nudging the mover even a fraction of a
+ * unit. Needed because an attack order that starts (or resumes) already
+ * inside range never otherwise calls motor.run before MeleeAttack.strike
+ * reads motor.facing — a target behind the player's stale facing would be
+ * missed forever (CA-6).
+ */
+function faceToward(motor, projection, from, to) {
+    const direction = unitToward(from, to);
+    if (!direction)
+        return;
+    const screenInput = projection === 'isometric' ? screenInputToLogical(direction.x, direction.y) : direction;
+    motor.run(screenInput.x, screenInput.y, 0);
+}
+function startOrder(clickToMove, entity, game, pick) {
+    clickToMove.cancel();
+    const picked = pick.entity;
+    if (picked && picked !== entity && picked.alive) {
+        if (picked.get(Health)) {
+            clickToMove.order = {
+                kind: 'attack',
+                target: picked,
+                waypoints: waypointsToward(game, entity, pointOf(picked)),
+                lastPlannedTarget: pointOf(picked),
+            };
+            return;
+        }
+        if (picked.get(Interactable)) {
+            clickToMove.order = {
+                kind: 'npc',
+                target: picked,
+                waypoints: waypointsToward(game, entity, pointOf(picked)),
+                lastPlannedTarget: pointOf(picked),
+            };
+            return;
+        }
+        // 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;
+    clickToMove.order = { kind: 'ground', waypoints, destination };
+    spawnMarker(clickToMove, game, entity, destination);
+}
+function driveGroundOrder(clickToMove, entity, order, motor) {
+    const direction = followWaypoints(clickToMove, entity, order.waypoints);
+    if (direction)
+        return direction;
+    // Arrived: snap to the exact destination and kill residual velocity, so
+    // handing control back doesn't coast a few more frames past the tolerance
+    // this same check just confirmed (CA-4's ~0.2-cell arrival is the
+    // resting position, not just the moment the order let go).
+    entity.position.x = order.destination.x;
+    entity.position.y = order.destination.y;
+    motor.halt();
+    clickToMove.cancel(); // arrived (CA-4/CA-8)
+    return null;
+}
+function driveNpcOrder(clickToMove, entity, game, order) {
+    const target = order.target;
+    if (!target.alive) {
+        clickToMove.cancel();
+        return null;
+    }
+    const interactable = target.get(Interactable);
+    if (!interactable) {
+        clickToMove.cancel();
+        return null;
+    }
+    if (distance(pointOf(entity), pointOf(target)) <= interactable.radius) {
+        game.stats.set('npcLine', interactable.line);
+        game.ui.show(INTERACTABLE_UI_PIECE);
+        clickToMove.cancel(); // CA-5: one trigger per arrival, no key simulated
+        return null;
+    }
+    // Follows the NPC and re-plans toward its current position while it
+    // moves, exactly like an attack order (grill decision 8, CA-5) — most
+    // Interactables are stationary so this rarely fires in practice, but a
+    // moving one (a wandering NPC role added later) must still be chased.
+    const targetNow = pointOf(target);
+    const moved = !order.lastPlannedTarget || distance(order.lastPlannedTarget, targetNow) >= NPC_REPLAN_DISTANCE;
+    if (moved || order.waypoints.length === 0) {
+        order.waypoints = waypointsToward(game, entity, targetNow);
+        order.lastPlannedTarget = targetNow;
+    }
+    const direction = followWaypoints(clickToMove, entity, order.waypoints);
+    if (direction)
+        return direction;
+    // Path exhausted (reached the nearest reachable cell) but still outside the
+    // radius: close the rest of the way directly (see beelineToward).
+    return beelineToward(entity, target);
+}
+function driveAttackOrder(clickToMove, entity, game, order, motor) {
+    const target = order.target;
+    // alive alone isn't "not dead": a graph that handles signal:death (the
+    // orc's, the shared player's) keeps the entity alive — possibly
+    // respawning it — while current sits at 0. Health missing entirely is
+    // just as much a reason to stop as a lethal current.
+    const health = target.get(Health);
+    if (!target.alive || !health || health.current <= 0) {
+        clickToMove.cancel(); // CA-6: target died (however its graph handles that) or disappeared
+        return null;
+    }
+    const range = entity.get(MeleeAttack)?.range ?? 1;
+    if (distance(pointOf(entity), pointOf(target)) <= range) {
+        // An order that starts (or resumes) already in range never otherwise
+        // calls motor.run before the swing lands — face the target first.
+        faceToward(motor, game.projection, pointOf(entity), pointOf(target));
+        game.input.injectAction('attack', 'press'); // re-engages via the existing input:attack edge
+        return null;
+    }
+    const targetNow = pointOf(target);
+    const moved = !order.lastPlannedTarget || distance(order.lastPlannedTarget, targetNow) >= ATTACK_REPLAN_DISTANCE;
+    if (moved || order.waypoints.length === 0) {
+        order.waypoints = waypointsToward(game, entity, targetNow);
+        order.lastPlannedTarget = targetNow;
+    }
+    const direction = followWaypoints(clickToMove, entity, order.waypoints);
+    if (direction)
+        return direction;
+    return beelineToward(entity, target);
+}
+/**
+ * Drives the active Move Order for one frame: drains a newly arrived click
+ * (replacing whatever order was active), then advances the live order and
+ * returns the logical-space direction the caller should move the motor
+ * along, or null to stand still. Called only while the role's shared body
+ * update runs (idle/walk) — never during attack/hurt/dead, which is exactly
+ * how a hurt stun pauses the order and a swing can't be interrupted (CA-7).
+ */
+export function driveClickToMove({ entity, game }, motor) {
+    const clickToMove = entity.get(ClickToMove);
+    if (!clickToMove)
+        return null;
+    const picked = game.pointer?.takePending();
+    if (picked)
+        startOrder(clickToMove, entity, game, picked);
+    const order = clickToMove.order;
+    if (!order)
+        return null;
+    if (order.kind === 'ground')
+        return driveGroundOrder(clickToMove, entity, order, motor);
+    if (order.kind === 'npc')
+        return driveNpcOrder(clickToMove, entity, game, order);
+    return driveAttackOrder(clickToMove, entity, game, order, motor);
+}

package/dist/grid-player-role.js

@@ -1,4 +1,5 @@
-import {} from '@waica/engine';
+import { screenInputToLogical, } from '@waica/engine';
+import { ClickToMove, driveClickToMove } from './click-to-move.js';
 import { logicalDirection } from './facing.js';
 import { Health } from './health.js';
 import { interactUpdate } from './interactable.js';
@@ -49,11 +50,31 @@ export function createGridPlayerRole(Motor, description) {
             },
         },
     };
-    const update = ({ entity, game, fsm }, dt) => {
+    const update = (ctx, dt) => {
+        const { entity, game, fsm } = ctx;
         const motor = entity.get(Motor);
         if (!motor)
             return;
-        motor.run(game.input.axis('left', 'right'), game.input.axis('down', 'up'), dt);
+        const keyboardX = game.input.axis('left', 'right');
+        const keyboardY = game.input.axis('down', 'up');
+        if (keyboardX !== 0 || keyboardY !== 0) {
+            // Keyboard movement always wins and cancels a live Move Order (CA-4).
+            entity.get(ClickToMove)?.cancel();
+            motor.run(keyboardX, keyboardY, dt);
+        }
+        else {
+            const driven = driveClickToMove(ctx, motor);
+            if (driven) {
+                // driveClickToMove answers in logical space; motor.run expects the
+                // same screen-relative input keyboard axes already are (IsoMotor
+                // converts internally, TopDownMotor's screen space is logical).
+                const screenInput = game.projection === 'isometric' ? screenInputToLogical(driven.x, driven.y) : driven;
+                motor.run(screenInput.x, screenInput.y, dt);
+            }
+            else {
+                motor.run(0, 0, dt);
+            }
+        }
         motor.step(dt);
         fsm.signal(motor.speed() > motor.walkThreshold ? 'move' : 'stop');
     };
@@ -119,6 +140,11 @@ export function createGridPlayerRole(Motor, description) {
             // Coming back is what leaving death means, so it hangs off onExit: any
             // other way out of this state (a project's own edge) revives too.
             dead: {
+                // Dying cancels any live Move Order outright (CA-7) — hurt only
+                // pauses one (nothing to do there: its onUpdate never runs update()).
+                onEnter({ entity }) {
+                    entity.get(ClickToMove)?.cancel();
+                },
                 // A state without its own onUpdate falls back to the role's default
                 // body update, so this no-op keeps the player still for the death beat.
                 onUpdate() { },

package/dist/index.d.ts

@@ -15,3 +15,8 @@ export { Health, declaresDeathHandling, deathTargets } from './health.js';
 export { Respawnable } from './respawnable.js';
 export { OutOfBounds } from './out-of-bounds.js';
 export { Lifetime } from './lifetime.js';
+export { ClickToMove, driveClickToMove } from './click-to-move.js';
+export { buildNavigationGrid } from './navigation-grid.js';
+export type { GridCell, GridPoint, NavigationGrid } from './navigation-grid.js';
+export { findPath, nearestReachableCell, planPath, reachableCells } from './pathfinding.js';
+export type { PlannedPath } from './pathfinding.js';

package/dist/index.js

@@ -15,3 +15,6 @@ export { Health, declaresDeathHandling, deathTargets } from './health.js';
 export { Respawnable } from './respawnable.js';
 export { OutOfBounds } from './out-of-bounds.js';
 export { Lifetime } from './lifetime.js';
+export { ClickToMove, driveClickToMove } from './click-to-move.js';
+export { buildNavigationGrid } from './navigation-grid.js';
+export { findPath, nearestReachableCell, planPath, reachableCells } from './pathfinding.js';

package/dist/melee-attack.d.ts

@@ -4,7 +4,7 @@ import { Component, type Entity } from '@waica/engine';
  * happens (the player's `attack` state) and calls strike(facing); this only
  * knows where the blow lands and who can be hurt by it. The hit area is a
  * `range` × `width` rectangle in logical space, laid along the facing from
- * the attacker's position — under the isometric projection that is the
+ * the attacker's hitbox — under the isometric projection that is the
  * diamond diagonal screen-east maps to, so "in front" matches the screen.
  */
 export declare class MeleeAttack extends Component {
@@ -43,6 +43,11 @@ export declare class MeleeAttack extends Component {
      * counted. An unknown facing strikes nothing.
      */
     strike(facing: string): Entity[];
-    /** The oriented rectangle in front of the attacker, as a unit-scaled polygon. */
+    /**
+     * The oriented rectangle in front of the attacker, as a unit-scaled polygon.
+     * Anchored on the attacker's own Hitbox — the same offset every target is
+     * read through — so an offset body swings from where it stands, not from
+     * its transform. An attacker without one keeps swinging from its position.
+     */
     private strikeArea;
 }

package/dist/melee-attack.js

@@ -6,7 +6,7 @@ import { Health } from './health.js';
  * happens (the player's `attack` state) and calls strike(facing); this only
  * knows where the blow lands and who can be hurt by it. The hit area is a
  * `range` × `width` rectangle in logical space, laid along the facing from
- * the attacker's position — under the isometric projection that is the
+ * the attacker's hitbox — under the isometric projection that is the
  * diamond diagonal screen-east maps to, so "in front" matches the screen.
  */
 export class MeleeAttack extends Component {
@@ -61,8 +61,14 @@ export class MeleeAttack extends Component {
         }
         return struck;
     }
-    /** The oriented rectangle in front of the attacker, as a unit-scaled polygon. */
+    /**
+     * The oriented rectangle in front of the attacker, as a unit-scaled polygon.
+     * Anchored on the attacker's own Hitbox — the same offset every target is
+     * read through — so an offset body swings from where it stands, not from
+     * its transform. An attacker without one keeps swinging from its position.
+     */
     strikeArea(dx, dy) {
+        const box = this.entity.get(Hitbox);
         const along = { x: (dx * this.range) / 2, y: (dy * this.range) / 2 };
         const across = { x: (-dy * this.width) / 2, y: (dx * this.width) / 2 };
         const points = [
@@ -72,8 +78,8 @@ export class MeleeAttack extends Component {
             [-along.x + across.x, -along.y + across.y],
         ];
         return {
-            x: this.entity.position.x + along.x,
-            y: this.entity.position.y + along.y,
+            x: this.entity.position.x + (box?.offsetX ?? 0) + along.x,
+            y: this.entity.position.y + (box?.offsetY ?? 0) + along.y,
             width: 1,
             height: 1,
             shape: 'polygon',

package/dist/navigation-grid.d.ts

@@ -0,0 +1,34 @@
+import { type Entity, type Game, type TilemapGridSpec } from '@waica/engine';
+export interface GridCell {
+    column: number;
+    row: number;
+}
+export interface GridPoint {
+    x: number;
+    y: number;
+}
+/**
+ * Transient lattice of walkable 1×1 logical cells, rasterized from a scene's
+ * Solids — Tilemap-derived and entity-authored alike (CA-2). Aligned to the
+ * first Tilemap found when one exists; otherwise covers the AABB of the
+ * supplied points (player + destination, typically) and every Solid, plus a
+ * margin. Always derived fresh — never authored, never cached across plans.
+ */
+export interface NavigationGrid {
+    readonly spec: TilemapGridSpec;
+    readonly columns: number;
+    readonly rows: number;
+    isWalkable(cell: GridCell): boolean;
+    /** The cell containing a logical point, or null outside the grid. */
+    cellAt(point: GridPoint): GridCell | null;
+    /** The logical center of a cell; null for a cell outside the grid. */
+    cellCenter(cell: GridCell): GridPoint | null;
+}
+/**
+ * Rasterizes the live scene into a Navigation Grid (CA-2). `points` seeds
+ * the AABB fallback when no Tilemap is present (topdown) — pass at least
+ * the mover's position and the click/target point. `except` (typically the
+ * mover's own entity) is excluded from the blocking Solids, mirroring
+ * sceneSolids' own contract.
+ */
+export declare function buildNavigationGrid(game: Game, points: readonly GridPoint[], except?: Entity): NavigationGrid;

package/dist/navigation-grid.js

@@ -0,0 +1,106 @@
+import { aabbOverlap, cellAt as gridCellAt, cellBounds as gridCellBounds, sceneSolids, Tilemap, } from '@waica/engine';
+/** How far past the covered points/Solids an authorless (Tilemap-less) grid extends. */
+const AABB_MARGIN_CELLS = 1;
+function findTilemap(game) {
+    for (const entity of game.entities) {
+        const tilemap = entity.get(Tilemap);
+        if (tilemap)
+            return tilemap;
+    }
+    return undefined;
+}
+function tilemapSpec(tilemap) {
+    return {
+        mapWidth: tilemap.mapWidth,
+        mapHeight: tilemap.mapHeight,
+        cellSize: tilemap.cellSize,
+        originX: tilemap.entity.position.x,
+        originY: tilemap.entity.position.y,
+    };
+}
+/** AABB of every supplied point plus every Solid's bounds, +1 cell margin. */
+function aabbSpec(game, points, except) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    const consider = (x, y) => {
+        if (x < minX)
+            minX = x;
+        if (y < minY)
+            minY = y;
+        if (x > maxX)
+            maxX = x;
+        if (y > maxY)
+            maxY = y;
+    };
+    for (const point of points)
+        consider(point.x, point.y);
+    for (const solid of sceneSolids(game, except)) {
+        consider(solid.left, solid.top);
+        consider(solid.right, solid.bottom);
+    }
+    if (!Number.isFinite(minX)) {
+        minX = 0;
+        minY = 0;
+        maxX = 0;
+        maxY = 0;
+    }
+    const originX = Math.floor(minX) - AABB_MARGIN_CELLS;
+    const originY = Math.floor(minY) - AABB_MARGIN_CELLS;
+    const mapWidth = Math.max(1, Math.ceil(maxX) + AABB_MARGIN_CELLS - originX);
+    const mapHeight = Math.max(1, Math.ceil(maxY) + AABB_MARGIN_CELLS - originY);
+    return { mapWidth, mapHeight, cellSize: 1, originX, originY };
+}
+/**
+ * Rasterizes the live scene into a Navigation Grid (CA-2). `points` seeds
+ * the AABB fallback when no Tilemap is present (topdown) — pass at least
+ * the mover's position and the click/target point. `except` (typically the
+ * mover's own entity) is excluded from the blocking Solids, mirroring
+ * sceneSolids' own contract.
+ */
+export function buildNavigationGrid(game, points, except) {
+    const tilemap = findTilemap(game);
+    const spec = tilemap ? tilemapSpec(tilemap) : aabbSpec(game, points, except);
+    const columns = Math.max(0, Math.floor(spec.mapWidth));
+    const rows = Math.max(0, Math.floor(spec.mapHeight));
+    const solids = sceneSolids(game, except);
+    const blocked = new Uint8Array(columns * rows);
+    for (let row = 0; row < rows; row += 1) {
+        for (let column = 0; column < columns; column += 1) {
+            const bounds = gridCellBounds(spec, column, row);
+            if (!bounds)
+                continue;
+            const cellCx = bounds.centerX;
+            const cellCy = bounds.centerY;
+            for (const solid of solids) {
+                const solidCx = (solid.left + solid.right) / 2;
+                const solidCy = (solid.top + solid.bottom) / 2;
+                const solidW = solid.right - solid.left;
+                const solidH = solid.top - solid.bottom;
+                if (aabbOverlap(cellCx, cellCy, spec.cellSize, spec.cellSize, solidCx, solidCy, solidW, solidH)) {
+                    blocked[row * columns + column] = 1;
+                    break;
+                }
+            }
+        }
+    }
+    return {
+        spec,
+        columns,
+        rows,
+        isWalkable(cell) {
+            if (cell.column < 0 || cell.row < 0 || cell.column >= columns || cell.row >= rows)
+                return false;
+            return blocked[cell.row * columns + cell.column] === 0;
+        },
+        cellAt(point) {
+            const cell = gridCellAt(spec, point.x, point.y);
+            return cell ? { column: cell.column, row: cell.row } : null;
+        },
+        cellCenter(cell) {
+            const bounds = gridCellBounds(spec, cell.column, cell.row);
+            return bounds ? { x: bounds.centerX, y: bounds.centerY } : null;
+        },
+    };
+}

package/dist/pathfinding.d.ts

@@ -0,0 +1,35 @@
+import type { GridCell, GridPoint, NavigationGrid } from './navigation-grid.js';
+/**
+ * Every cell reachable from `start` under the same 8-way, corner-cut-forbidden
+ * adjacency A* uses — a flood fill, cheapest way to answer "is X reachable"
+ * and to enumerate candidates for the nearest-reachable fallback (CA-3).
+ */
+export declare function reachableCells(grid: NavigationGrid, start: GridCell): GridCell[];
+/**
+ * A* over the Navigation Grid, 8-way with corner-cutting forbidden (CA-3).
+ * Returns the cell path from (excluding) `start` to (including) `goal`, or
+ * null when `goal` isn't reachable from `start` under this adjacency.
+ */
+export declare function findPath(grid: NavigationGrid, start: GridCell, goal: GridCell): GridCell[] | null;
+/**
+ * The reachable-from-`start` cell whose center is nearest the logical point
+ * `to` — the CA-3 fallback for an unreachable or out-of-grid destination.
+ * Ties keep the lowest row then column, for determinism.
+ */
+export declare function nearestReachableCell(grid: NavigationGrid, start: GridCell, to: GridPoint): GridCell | null;
+export interface PlannedPath {
+    /** Cells from (excluding) the start to (including) the resolved target. */
+    cells: GridCell[];
+    /** The resolved target cell — the clicked cell if reachable, else nearest reachable. */
+    targetCell: GridCell;
+    /** Logical center of the resolved target cell. */
+    target: GridPoint;
+}
+/**
+ * Plans a route from a logical point to a logical destination over a fresh
+ * Navigation Grid (CA-2/CA-3): an unreachable or out-of-grid destination
+ * resolves to the nearest reachable cell to the clicked point, and the path
+ * always ends there. Null only when the mover's own position isn't walkable
+ * (should not happen for an entity already standing in the scene).
+ */
+export declare function planPath(grid: NavigationGrid, from: GridPoint, to: GridPoint): PlannedPath | null;

package/dist/pathfinding.js

@@ -0,0 +1,181 @@
+/** 8-way neighborhood; the first four are cardinal, the last four diagonal. */
+const NEIGHBORS = [
+    [1, 0],
+    [-1, 0],
+    [0, 1],
+    [0, -1],
+    [1, 1],
+    [1, -1],
+    [-1, 1],
+    [-1, -1],
+];
+function key(cell) {
+    return `${cell.column},${cell.row}`;
+}
+/**
+ * Walkable neighbors of a cell, corner-cutting forbidden: a diagonal step is
+ * only offered when both adjacent cardinal cells are walkable too (CA-3).
+ */
+function neighbors(grid, cell) {
+    const result = [];
+    for (const [dc, dr] of NEIGHBORS) {
+        const next = { column: cell.column + dc, row: cell.row + dr };
+        if (!grid.isWalkable(next))
+            continue;
+        if (dc !== 0 && dr !== 0) {
+            const cardinalA = { column: cell.column + dc, row: cell.row };
+            const cardinalB = { column: cell.column, row: cell.row + dr };
+            if (!grid.isWalkable(cardinalA) || !grid.isWalkable(cardinalB))
+                continue;
+        }
+        result.push(next);
+    }
+    return result;
+}
+function stepCost(dc, dr) {
+    return dc !== 0 && dr !== 0 ? Math.SQRT2 : 1;
+}
+/** Octile distance: admissible heuristic for 8-way movement with unit/√2 costs. */
+function octile(a, b) {
+    const dx = Math.abs(a.column - b.column);
+    const dy = Math.abs(a.row - b.row);
+    return Math.max(dx, dy) + (Math.SQRT2 - 1) * Math.min(dx, dy);
+}
+/**
+ * Every cell reachable from `start` under the same 8-way, corner-cut-forbidden
+ * adjacency A* uses — a flood fill, cheapest way to answer "is X reachable"
+ * and to enumerate candidates for the nearest-reachable fallback (CA-3).
+ */
+export function reachableCells(grid, start) {
+    if (!grid.isWalkable(start))
+        return [];
+    const visited = new Map([[key(start), start]]);
+    const queue = [start];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        for (const next of neighbors(grid, current)) {
+            const k = key(next);
+            if (visited.has(k))
+                continue;
+            visited.set(k, next);
+            queue.push(next);
+        }
+    }
+    return [...visited.values()];
+}
+/**
+ * A* over the Navigation Grid, 8-way with corner-cutting forbidden (CA-3).
+ * Returns the cell path from (excluding) `start` to (including) `goal`, or
+ * null when `goal` isn't reachable from `start` under this adjacency.
+ */
+export function findPath(grid, start, goal) {
+    if (!grid.isWalkable(start) || !grid.isWalkable(goal))
+        return null;
+    if (start.column === goal.column && start.row === goal.row)
+        return [];
+    const startKey = key(start);
+    const goalKey = key(goal);
+    const gScore = new Map([[startKey, 0]]);
+    const cameFrom = new Map();
+    const open = new Map([[startKey, start]]);
+    const closed = new Set();
+    while (open.size > 0) {
+        let currentKey = '';
+        let current;
+        let bestF = Infinity;
+        for (const [k, cell] of open) {
+            const f = gScore.get(k) + octile(cell, goal);
+            if (f < bestF) {
+                bestF = f;
+                currentKey = k;
+                current = cell;
+            }
+        }
+        if (!current)
+            break;
+        if (currentKey === goalKey) {
+            const path = [current];
+            let trace = currentKey;
+            while (cameFrom.has(trace)) {
+                const previous = cameFrom.get(trace);
+                path.unshift(previous);
+                trace = key(previous);
+            }
+            path.shift(); // drop the start cell — the mover is already there.
+            return path;
+        }
+        open.delete(currentKey);
+        closed.add(currentKey);
+        const currentG = gScore.get(currentKey);
+        for (const next of neighbors(grid, current)) {
+            const nextKey = key(next);
+            if (closed.has(nextKey))
+                continue;
+            const tentativeG = currentG + stepCost(next.column - current.column, next.row - current.row);
+            if (tentativeG < (gScore.get(nextKey) ?? Infinity)) {
+                cameFrom.set(nextKey, current);
+                gScore.set(nextKey, tentativeG);
+                open.set(nextKey, next);
+            }
+        }
+    }
+    return null;
+}
+function squaredDistance(a, b) {
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+    return dx * dx + dy * dy;
+}
+/**
+ * The reachable-from-`start` cell whose center is nearest the logical point
+ * `to` — the CA-3 fallback for an unreachable or out-of-grid destination.
+ * Ties keep the lowest row then column, for determinism.
+ */
+export function nearestReachableCell(grid, start, to) {
+    let best = null;
+    let bestDistance = Infinity;
+    for (const cell of reachableCells(grid, start)) {
+        const center = grid.cellCenter(cell);
+        if (!center)
+            continue;
+        const distance = squaredDistance(center, to);
+        if (distance < bestDistance ||
+            (distance === bestDistance &&
+                best &&
+                (cell.row < best.row || (cell.row === best.row && cell.column < best.column)))) {
+            best = cell;
+            bestDistance = distance;
+        }
+    }
+    return best;
+}
+/**
+ * Plans a route from a logical point to a logical destination over a fresh
+ * Navigation Grid (CA-2/CA-3): an unreachable or out-of-grid destination
+ * resolves to the nearest reachable cell to the clicked point, and the path
+ * always ends there. Null only when the mover's own position isn't walkable
+ * (should not happen for an entity already standing in the scene).
+ */
+export function planPath(grid, from, to) {
+    const startCell = grid.cellAt(from);
+    if (!startCell || !grid.isWalkable(startCell))
+        return null;
+    const rawTargetCell = grid.cellAt(to);
+    const directPath = rawTargetCell ? findPath(grid, startCell, rawTargetCell) : null;
+    let targetCell;
+    let cells;
+    if (rawTargetCell && directPath !== null) {
+        targetCell = rawTargetCell;
+        cells = directPath;
+    }
+    else {
+        targetCell = nearestReachableCell(grid, startCell, to);
+        if (!targetCell)
+            return null;
+        cells = findPath(grid, startCell, targetCell) ?? [];
+    }
+    const target = grid.cellCenter(targetCell);
+    if (!target)
+        return null;
+    return { cells, targetCell, target };
+}

package/package.json

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