@waica/behaviors 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export { PlatformerMotor } from './platformer-motor.js';
 export { PLAYER_ROLE, PLAYER_STATE_GRAPH, playerUpdate } from './player-states.js';
+export { TopDownMotor, type TopDownFacing } from './topdown-motor.js';
+export { TOPDOWN_PLAYER_ROLE, TOPDOWN_PLAYER_STATE_GRAPH, topdownPlayerUpdate, } from './topdown-player-states.js';
+export { Interactable, interactUpdate } from './interactable.js';
 export { Collectible } from './collectible.js';
 export { Patrol, PATROLLER_ROLE, PATROLLER_STATE_GRAPH, type PatrolAxis } from './patrol.js';
 export { Chaser, CHASER_ROLE, CHASER_STATE_GRAPH, type ChaserMode } from './chaser.js';

package/dist/index.js

@@ -1,5 +1,8 @@
 export { PlatformerMotor } from './platformer-motor.js';
 export { PLAYER_ROLE, PLAYER_STATE_GRAPH, playerUpdate } from './player-states.js';
+export { TopDownMotor } from './topdown-motor.js';
+export { TOPDOWN_PLAYER_ROLE, TOPDOWN_PLAYER_STATE_GRAPH, topdownPlayerUpdate, } from './topdown-player-states.js';
+export { Interactable, interactUpdate } from './interactable.js';
 export { Collectible } from './collectible.js';
 export { Patrol, PATROLLER_ROLE, PATROLLER_STATE_GRAPH } from './patrol.js';
 export { Chaser, CHASER_ROLE, CHASER_STATE_GRAPH } from './chaser.js';

package/dist/interactable.d.ts

@@ -0,0 +1,31 @@
+import { Component, type StateContext } from '@waica/engine';
+/**
+ * Something the player can talk to or examine: a dialogue line and the
+ * radius it can be triggered from. The component is pure data — the
+ * player role's always-hook does the lookup (see interactUpdate), so an
+ * NPC stays code-free: Interactable + the npc role is a whole villager.
+ */
+export declare class Interactable extends Component {
+    static componentName: string;
+    static params: {
+        line: {
+            label: string;
+        };
+        radius: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    /** What pressing interact within the radius says. */
+    line: string;
+    radius: number;
+}
+/**
+ * The player role's interact lookup, run by its '*' hook in every state:
+ * pressing interact near an Interactable publishes its line through the
+ * npcLine stat and shows the npc-line UI piece; walking out of every
+ * radius hides it again. Nearest one wins when several are in range.
+ */
+export declare function interactUpdate({ entity, game }: StateContext): void;

package/dist/interactable.js

@@ -0,0 +1,49 @@
+import { Component } from '@waica/engine';
+/**
+ * Something the player can talk to or examine: a dialogue line and the
+ * radius it can be triggered from. The component is pure data — the
+ * player role's always-hook does the lookup (see interactUpdate), so an
+ * NPC stays code-free: Interactable + the npc role is a whole villager.
+ */
+export class Interactable extends Component {
+    static componentName = 'Interactable';
+    static params = {
+        line: { label: 'Line' },
+        radius: { label: 'Radius', min: 0.5, max: 10, step: 0.25 },
+    };
+    /** What pressing interact within the radius says. */
+    line = 'Hello, traveler!';
+    radius = 1.5;
+}
+/**
+ * The player role's interact lookup, run by its '*' hook in every state:
+ * pressing interact near an Interactable publishes its line through the
+ * npcLine stat and shows the npc-line UI piece; walking out of every
+ * radius hides it again. Nearest one wins when several are in range.
+ */
+export function interactUpdate({ entity, game }) {
+    let nearest = null;
+    let nearestDistance = Infinity;
+    for (const other of game.entities) {
+        if (other === entity)
+            continue;
+        const interactable = other.get(Interactable);
+        if (!interactable)
+            continue;
+        const distance = Math.hypot(other.position.x - entity.position.x, other.position.y - entity.position.y);
+        if (distance <= interactable.radius && distance < nearestDistance) {
+            nearest = interactable;
+            nearestDistance = distance;
+        }
+    }
+    if (!nearest) {
+        game.ui.hide('npc-line');
+        return;
+    }
+    if (game.input.justPressed('interact') && !game.input.consumed('interact')) {
+        // The press is spent: an input:interact edge needs a NEW press.
+        game.input.consume('interact');
+        game.stats.set('npcLine', nearest.line);
+        game.ui.show('npc-line');
+    }
+}

package/dist/platformer-motor.d.ts

@@ -1,4 +1,4 @@
-import { Component } from '@waica/engine';
+import { Component, type CameraVelocity, type CameraVelocityProvider } from '@waica/engine';
 /**
  * Passive platformer motor: tuning params, physical state and movement
  * methods for state code to call. It has no onUpdate of its own — the
@@ -9,7 +9,7 @@ import { Component } from '@waica/engine';
  * Per-axis collision against the scene's Solids — deterministic genre
  * movement (Celeste-style), not "realistic" physics.
  */
-export declare class PlatformerMotor extends Component {
+export declare class PlatformerMotor extends Component implements CameraVelocityProvider {
     static componentName: string;
     static displayName: string;
     static params: {
@@ -103,6 +103,8 @@ export declare class PlatformerMotor extends Component {
     private bufferTimer;
     private squashX;
     private squashY;
+    /** The scene camera reads follow velocity through this explicit seam. */
+    getCameraVelocity(): CameraVelocity;
     /**
      * Per-frame bookkeeping: forgiveness timers, squash decay and the
      * facing flip. The logic set's '*' hook runs it in every state, so

package/dist/platformer-motor.js

@@ -1,4 +1,4 @@
-import { Component, resolveSolidAxis, THREE } from '@waica/engine';
+import { Component, resolveSolidAxis, THREE, } from '@waica/engine';
 /**
  * Passive platformer motor: tuning params, physical state and movement
  * methods for state code to call. It has no onUpdate of its own — the
@@ -60,6 +60,10 @@ export class PlatformerMotor extends Component {
     bufferTimer = 0;
     squashX = 1;
     squashY = 1;
+    /** The scene camera reads follow velocity through this explicit seam. */
+    getCameraVelocity() {
+        return { vx: this.vx, vy: this.vy };
+    }
     /**
      * Per-frame bookkeeping: forgiveness timers, squash decay and the
      * facing flip. The logic set's '*' hook runs it in every state, so

package/dist/topdown-motor.d.ts

@@ -0,0 +1,72 @@
+import { Component, type AnimationFacingProvider, type CameraVelocity, type CameraVelocityProvider } from '@waica/engine';
+/** The four facings the top-down animation contract declares. */
+export type TopDownFacing = 'n' | 's' | 'e' | 'w';
+/**
+ * Passive top-down motor: tuning params, physical state and movement
+ * methods for state code to call. It has no onUpdate of its own — the
+ * StateMachine is the only owner of the frame; this is the toolbox the
+ * active state moves the body with. Eight-direction movement with the
+ * input vector normalized so diagonals match cardinal speed, no gravity,
+ * and per-axis collision against the scene's Solids — deterministic
+ * genre movement (Zelda-style), not "realistic" physics.
+ */
+export declare class TopDownMotor extends Component implements CameraVelocityProvider, AnimationFacingProvider {
+    static componentName: string;
+    static displayName: string;
+    static params: {
+        moveSpeed: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        acceleration: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        deceleration: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        walkThreshold: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    static transient: string[];
+    moveSpeed: number;
+    acceleration: number;
+    deceleration: number;
+    /** Speed above this reads as walking (the idle ↔ walk edge). */
+    walkThreshold: number;
+    /** The character's AABB hitbox — a footprint, shorter than the sprite. */
+    hitboxWidth: number;
+    hitboxHeight: number;
+    vx: number;
+    vy: number;
+    /** Four-direction facing; starts looking at the camera. */
+    facing: TopDownFacing;
+    /** The scene camera reads follow velocity through this explicit seam. */
+    getCameraVelocity(): CameraVelocity;
+    /** The StateMachine resolves directional clips through this explicit seam. */
+    getAnimationFacing(): string;
+    /**
+     * Accelerates toward the input vector (each axis -1..1) * moveSpeed.
+     * The vector is normalized so diagonals move at cardinal speed, and
+     * facing follows the dominant input axis — ties keep the last facing.
+     */
+    run(inputX: number, inputY: number, dt: number): void;
+    /** Live speed, for the idle ↔ walk edge. */
+    speed(): number;
+    /** Integrates velocity and resolves each axis against Solids. */
+    step(dt: number): void;
+    halt(): void;
+    private resolveAxis;
+    private collisionBody;
+}

package/dist/topdown-motor.js

@@ -0,0 +1,102 @@
+import { Component, resolveSolidAxis, THREE, } from '@waica/engine';
+/**
+ * Passive top-down motor: tuning params, physical state and movement
+ * methods for state code to call. It has no onUpdate of its own — the
+ * StateMachine is the only owner of the frame; this is the toolbox the
+ * active state moves the body with. Eight-direction movement with the
+ * input vector normalized so diagonals match cardinal speed, no gravity,
+ * and per-axis collision against the scene's Solids — deterministic
+ * genre movement (Zelda-style), not "realistic" physics.
+ */
+export class TopDownMotor extends Component {
+    static componentName = 'TopDownMotor';
+    static displayName = 'Motor';
+    static params = {
+        moveSpeed: { label: 'Speed', min: 1, max: 30, step: 0.5 },
+        acceleration: { label: 'Acceleration', min: 5, max: 200, step: 5 },
+        deceleration: { label: 'Deceleration', min: 5, max: 200, step: 5 },
+        walkThreshold: { label: 'Walk threshold', min: 0, max: 5, step: 0.1 },
+    };
+    static transient = ['vx', 'vy', 'facing'];
+    moveSpeed = 6;
+    acceleration = 60;
+    deceleration = 80;
+    /** Speed above this reads as walking (the idle ↔ walk edge). */
+    walkThreshold = 0.5;
+    /** The character's AABB hitbox — a footprint, shorter than the sprite. */
+    hitboxWidth = 0.9;
+    hitboxHeight = 0.6;
+    vx = 0;
+    vy = 0;
+    /** Four-direction facing; starts looking at the camera. */
+    facing = 's';
+    /** The scene camera reads follow velocity through this explicit seam. */
+    getCameraVelocity() {
+        return { vx: this.vx, vy: this.vy };
+    }
+    /** The StateMachine resolves directional clips through this explicit seam. */
+    getAnimationFacing() {
+        return this.facing;
+    }
+    /**
+     * Accelerates toward the input vector (each axis -1..1) * moveSpeed.
+     * The vector is normalized so diagonals move at cardinal speed, and
+     * facing follows the dominant input axis — ties keep the last facing.
+     */
+    run(inputX, inputY, dt) {
+        let x = inputX;
+        let y = inputY;
+        const length = Math.hypot(x, y);
+        if (length > 1) {
+            x /= length;
+            y /= length;
+        }
+        const rateX = x !== 0 ? this.acceleration : this.deceleration;
+        const rateY = y !== 0 ? this.acceleration : this.deceleration;
+        this.vx = THREE.MathUtils.damp(this.vx, x * this.moveSpeed, rateX / this.moveSpeed, dt);
+        this.vy = THREE.MathUtils.damp(this.vy, y * this.moveSpeed, rateY / this.moveSpeed, dt);
+        const absX = Math.abs(inputX);
+        const absY = Math.abs(inputY);
+        if (absX > absY)
+            this.facing = inputX < 0 ? 'w' : 'e';
+        else if (absY > absX)
+            this.facing = inputY < 0 ? 's' : 'n';
+    }
+    /** Live speed, for the idle ↔ walk edge. */
+    speed() {
+        return Math.hypot(this.vx, this.vy);
+    }
+    /** Integrates velocity and resolves each axis against Solids. */
+    step(dt) {
+        const pos = this.entity.position;
+        const previousX = pos.x;
+        pos.x += this.vx * dt;
+        if (this.resolveAxis('x', previousX))
+            this.vx = 0;
+        const previousY = pos.y;
+        pos.y += this.vy * dt;
+        if (this.resolveAxis('y', previousY))
+            this.vy = 0;
+    }
+    halt() {
+        this.vx = 0;
+        this.vy = 0;
+    }
+    resolveAxis(axis, previous) {
+        return resolveSolidAxis({
+            entity: this.entity,
+            axis,
+            previous,
+            body: () => this.collisionBody(),
+        });
+    }
+    collisionBody() {
+        return {
+            x: this.entity.position.x,
+            y: this.entity.position.y,
+            width: this.hitboxWidth,
+            height: this.hitboxHeight,
+            shape: 'rectangle',
+        };
+    }
+}

package/dist/topdown-player-states.d.ts

@@ -0,0 +1,18 @@
+import { type RoleDefinition, type RoleGraph, type StateContext } from '@waica/engine';
+/**
+ * The top-down 'player' role: the character you control from above. Both
+ * default states share one body update; they differ only in the edges
+ * their prefab data declares. Extending the player is defineStates
+ * ('player', { yourState: {...} }) plus a state in the prefab — never a
+ * fight with a parallel controller.
+ */
+/** The state graph new top-down player characters start with, as prefab data. */
+export declare const TOPDOWN_PLAYER_STATE_GRAPH: RoleGraph;
+/**
+ * One body update shared by every default state: read the four-direction
+ * actions, accelerate, collide, then report what the body is doing as
+ * signals. Unmatched signals are no-ops, so each state only reacts to
+ * the edges its data declares.
+ */
+export declare function topdownPlayerUpdate({ entity, game, fsm }: StateContext, dt: number): void;
+export declare const TOPDOWN_PLAYER_ROLE: RoleDefinition;

package/dist/topdown-player-states.js

@@ -0,0 +1,86 @@
+import {} from '@waica/engine';
+import { Health } from './health.js';
+import { interactUpdate } from './interactable.js';
+import { Respawnable } from './respawnable.js';
+import { TopDownMotor } from './topdown-motor.js';
+/**
+ * The top-down 'player' role: the character you control from above. Both
+ * default states share one body update; they differ only in the edges
+ * their prefab data declares. Extending the player is defineStates
+ * ('player', { yourState: {...} }) plus a state in the prefab — never a
+ * fight with a parallel controller.
+ */
+/** The state graph new top-down player characters start with, as prefab data. */
+export const TOPDOWN_PLAYER_STATE_GRAPH = {
+    initial: 'idle',
+    states: {
+        idle: {
+            transitions: [{ on: 'signal:move', to: 'walk' }],
+        },
+        walk: {
+            transitions: [{ on: 'signal:stop', to: 'idle' }],
+        },
+        dead: {
+            // Freeze on idle (resolved directionally) rather than name a death
+            // clip the stock sheets do not have and warn every frame.
+            clip: 'idle',
+            // A beat before control comes back, so death reads as an event.
+            transitions: [{ on: 'timer:0.8', to: 'idle' }],
+        },
+        // Dying is the same from every state, so the edge lives on '*'. Its
+        // presence is also the contract Health checks before signalling: a graph
+        // without it gets its entity destroyed instead.
+        '*': { transitions: [{ on: 'signal:death', to: 'dead' }] },
+    },
+};
+/**
+ * One body update shared by every default state: read the four-direction
+ * actions, accelerate, collide, then report what the body is doing as
+ * signals. Unmatched signals are no-ops, so each state only reacts to
+ * the edges its data declares.
+ */
+export function topdownPlayerUpdate({ entity, game, fsm }, dt) {
+    const motor = entity.get(TopDownMotor);
+    if (!motor)
+        return;
+    motor.run(game.input.axis('left', 'right'), game.input.axis('down', 'up'), dt);
+    motor.step(dt);
+    fsm.signal(motor.speed() > motor.walkThreshold ? 'move' : 'stop');
+}
+export const TOPDOWN_PLAYER_ROLE = {
+    description: 'You control this character with the project controls: eight-direction ' +
+        'top-down movement with normalized diagonals and no gravity. Its ' +
+        'states move the Motor.',
+    driver: 'TopDownMotor',
+    graph: TOPDOWN_PLAYER_STATE_GRAPH,
+    signals: {
+        move: 'moving',
+        stop: 'standing still',
+    },
+    states: {
+        // Always-hook: the interact lookup must survive custom states like an
+        // attack, so it runs in every state.
+        '*': {
+            onUpdate(ctx) {
+                interactUpdate(ctx);
+            },
+        },
+        // Fallback: a custom state without its own onUpdate keeps the full
+        // body update — its file only has to say what makes it special.
+        default: { onUpdate: topdownPlayerUpdate },
+        idle: { onUpdate: topdownPlayerUpdate },
+        walk: { onUpdate: topdownPlayerUpdate },
+        // 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: {
+            // A state without its own onUpdate falls back to the role's default
+            // body update, so without this no-op the player kept walking for the
+            // whole death beat instead of the graph taking control away.
+            onUpdate() { },
+            onExit({ entity }) {
+                entity.get(Respawnable)?.respawn();
+                entity.get(Health)?.heal(Infinity);
+            },
+        },
+    },
+};

package/package.json

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