@waica/behaviors 0.20.0 → 0.22.0

package/dist/damage-puff.d.ts

@@ -0,0 +1,27 @@
+import { Component } from '@waica/engine';
+/**
+ * A puff from this entity's ParticleEmitter wherever
+ * damage lands. Health announces every accepted hit on `game.events` as
+ * 'damage'; this moves its own (sprite-less) entity to the entity that took
+ * it and bursts there. The emitter should be in `space: 'world'`, so the
+ * puffs already in flight stay where they started when the next hit moves
+ * the source elsewhere. One of these serves every Health in the scene.
+ */
+export declare class DamagePuff extends Component {
+    static componentName: string;
+    static displayName: string;
+    static params: {
+        count: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    /** Particles per hit. */
+    count: number;
+    private unsubscribe?;
+    onReady(): void;
+    onDestroy(): void;
+    private puffAt;
+}

package/dist/damage-puff.js

@@ -0,0 +1,40 @@
+import { Component, Entity, ParticleEmitter } from '@waica/engine';
+/**
+ * A puff from this entity's ParticleEmitter wherever
+ * damage lands. Health announces every accepted hit on `game.events` as
+ * 'damage'; this moves its own (sprite-less) entity to the entity that took
+ * it and bursts there. The emitter should be in `space: 'world'`, so the
+ * puffs already in flight stay where they started when the next hit moves
+ * the source elsewhere. One of these serves every Health in the scene.
+ */
+export class DamagePuff extends Component {
+    static componentName = 'DamagePuff';
+    static displayName = 'Damage puff';
+    static params = {
+        count: { label: 'Particles', min: 1, max: 64, step: 1 },
+    };
+    /** Particles per hit. */
+    count = 10;
+    unsubscribe;
+    onReady() {
+        this.unsubscribe = this.game.events.on('damage', (payload) => this.puffAt(payload));
+    }
+    onDestroy() {
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+    }
+    puffAt(payload) {
+        const target = damagedEntity(payload);
+        const puff = this.entity.get(ParticleEmitter);
+        if (!target || !puff)
+            return;
+        this.entity.position.set(target.position.x, target.position.y, this.entity.position.z);
+        puff.emit(this.count);
+    }
+}
+/** The entity a 'damage' event names, if the payload really carries one. */
+function damagedEntity(payload) {
+    if (typeof payload !== 'object' || payload === null || !('entity' in payload))
+        return undefined;
+    return payload.entity instanceof Entity ? payload.entity : undefined;
+}

package/dist/dust-puffs.d.ts

@@ -0,0 +1,51 @@
+import { Component } from '@waica/engine';
+/**
+ * Dust from this entity's own ParticleEmitter at the
+ * two moments a platformer body meets the ground hard — a small puff when a
+ * jump takes off from the ground, a bigger burst when the body lands. Both
+ * come from the same emitter (the dust look is authored on it in the
+ * prefab); only the count differs. It hooks the StateMachine's own edges
+ * instead of polling:
+ *
+ * - takeoff: entering 'jump' right after leaving 'idle' or 'run'. Leaving
+ *   any other state first counts as airborne: the graph enters 'jump' from
+ *   'fall' in mid-air (a coyote jump, a stomp bounce), and a project state
+ *   such as a dash can do the same. Those raise no dust.
+ * - landing: leaving 'jump' or 'fall' while the motor is grounded. A jump
+ *   whose apex already lands on a ledge goes jump -> idle without a fall.
+ *
+ * To know which state was left, it adds an instance onExit hook to every
+ * state the machine declares (all but '*'). A role's own hooks for those
+ * states still run. A role 'default' onExit, however, only runs for states
+ * without an onExit of their own, so this hook would shadow it. No stock
+ * role declares one.
+ *
+ * Its siblings must already be mounted when it is, so it goes after the
+ * StateMachine and the ParticleEmitter in the prefab.
+ */
+export declare class DustPuffs extends Component {
+    static componentName: string;
+    static displayName: string;
+    static params: {
+        jumpCount: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        landCount: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    static transient: string[];
+    /** Particles when a jump takes off from the ground. */
+    jumpCount: number;
+    /** Particles when the body lands. */
+    landCount: number;
+    /** Whether the last state left was a grounded one: set on every declared state's exit, read on entering 'jump'. */
+    private leftGround;
+    onReady(): void;
+}

package/dist/dust-puffs.js

@@ -0,0 +1,73 @@
+import { Component, ParticleEmitter, StateMachine } from '@waica/engine';
+import { PlatformerMotor } from './platformer-motor.js';
+/** The stock player graph's grounded states: a jump entered from one of these is a takeoff. */
+const GROUND_STATES = ['idle', 'run'];
+/** The airborne states a landing can end: a grounded exit from either is a touchdown. */
+const AIR_STATES = ['jump', 'fall'];
+/**
+ * Dust from this entity's own ParticleEmitter at the
+ * two moments a platformer body meets the ground hard — a small puff when a
+ * jump takes off from the ground, a bigger burst when the body lands. Both
+ * come from the same emitter (the dust look is authored on it in the
+ * prefab); only the count differs. It hooks the StateMachine's own edges
+ * instead of polling:
+ *
+ * - takeoff: entering 'jump' right after leaving 'idle' or 'run'. Leaving
+ *   any other state first counts as airborne: the graph enters 'jump' from
+ *   'fall' in mid-air (a coyote jump, a stomp bounce), and a project state
+ *   such as a dash can do the same. Those raise no dust.
+ * - landing: leaving 'jump' or 'fall' while the motor is grounded. A jump
+ *   whose apex already lands on a ledge goes jump -> idle without a fall.
+ *
+ * To know which state was left, it adds an instance onExit hook to every
+ * state the machine declares (all but '*'). A role's own hooks for those
+ * states still run. A role 'default' onExit, however, only runs for states
+ * without an onExit of their own, so this hook would shadow it. No stock
+ * role declares one.
+ *
+ * Its siblings must already be mounted when it is, so it goes after the
+ * StateMachine and the ParticleEmitter in the prefab.
+ */
+export class DustPuffs extends Component {
+    static componentName = 'DustPuffs';
+    static displayName = 'Dust puffs';
+    static params = {
+        jumpCount: { label: 'Jump puff', min: 0, max: 64, step: 1 },
+        landCount: { label: 'Landing burst', min: 0, max: 64, step: 1 },
+    };
+    static transient = ['leftGround'];
+    /** Particles when a jump takes off from the ground. */
+    jumpCount = 5;
+    /** Particles when the body lands. */
+    landCount = 12;
+    /** Whether the last state left was a grounded one: set on every declared state's exit, read on entering 'jump'. */
+    leftGround = false;
+    onReady() {
+        const machine = this.entity.get(StateMachine);
+        const dust = this.entity.get(ParticleEmitter);
+        if (!machine || !dust) {
+            console.warn(`[waica] "${this.entity.name}": DustPuffs needs a StateMachine and a ParticleEmitter before it.`);
+            return;
+        }
+        for (const state of Object.keys(machine.states)) {
+            if (state === '*')
+                continue;
+            const grounded = GROUND_STATES.includes(state);
+            machine.on(state, { onExit: () => (this.leftGround = grounded) });
+        }
+        for (const state of AIR_STATES) {
+            machine.on(state, {
+                onExit: () => {
+                    if (this.entity.get(PlatformerMotor)?.grounded)
+                        dust.emit(this.landCount);
+                },
+            });
+        }
+        machine.on('jump', {
+            onEnter: () => {
+                if (this.leftGround)
+                    dust.emit(this.jumpCount);
+            },
+        });
+    }
+}

package/dist/dust-trail.d.ts

@@ -0,0 +1,24 @@
+import { Component } from '@waica/engine';
+/**
+ * A soft dust trail while this entity walks. The
+ * ParticleEmitter on the same entity does the continuous emission (its
+ * `rate` and dust look are authored in the prefab, with `emitting: false`);
+ * this only switches `emitting` on when the StateMachine enters the walking
+ * state and off when it leaves it, so the trail stops the moment the body
+ * does and the dust already raised settles on its own.
+ *
+ * Its siblings must already be mounted when it is, so it goes after the
+ * StateMachine and the ParticleEmitter in the prefab.
+ */
+export declare class DustTrail extends Component {
+    static componentName: string;
+    static displayName: string;
+    static params: {
+        state: {
+            label: string;
+        };
+    };
+    /** The state during which the trail is raised. */
+    state: string;
+    onReady(): void;
+}

package/dist/dust-trail.js

@@ -0,0 +1,38 @@
+import { Component, ParticleEmitter, StateMachine } from '@waica/engine';
+/**
+ * A soft dust trail while this entity walks. The
+ * ParticleEmitter on the same entity does the continuous emission (its
+ * `rate` and dust look are authored in the prefab, with `emitting: false`);
+ * this only switches `emitting` on when the StateMachine enters the walking
+ * state and off when it leaves it, so the trail stops the moment the body
+ * does and the dust already raised settles on its own.
+ *
+ * Its siblings must already be mounted when it is, so it goes after the
+ * StateMachine and the ParticleEmitter in the prefab.
+ */
+export class DustTrail extends Component {
+    static componentName = 'DustTrail';
+    static displayName = 'Dust trail';
+    static params = {
+        state: { label: 'State' },
+    };
+    /** The state during which the trail is raised. */
+    state = 'walk';
+    onReady() {
+        const machine = this.entity.get(StateMachine);
+        const dust = this.entity.get(ParticleEmitter);
+        if (!machine || !dust) {
+            console.warn(`[waica] "${this.entity.name}": DustTrail needs a StateMachine and a ParticleEmitter before it.`);
+            return;
+        }
+        dust.emitting = machine.current === this.state;
+        machine.on(this.state, {
+            onEnter: () => {
+                dust.emitting = true;
+            },
+            onExit: () => {
+                dust.emitting = false;
+            },
+        });
+    }
+}

package/dist/facing.d.ts

@@ -3,9 +3,10 @@ import { type ProjectedPoint } from '@waica/engine';
 export type ScreenFacing = 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw';
 export declare const SCREEN_FACINGS: readonly ScreenFacing[];
 /**
- * The eight-way facing a screen-relative input reads as — signs only, so a
- * tiny diagonal component still counts. Undefined for no input, which lets
- * the caller keep whatever it was facing.
+ * The eight-way facing a screen-relative input reads as: the 45° sector its
+ * angle falls in, so an almost-vertical stick faces `n`, not `ne`; every
+ * keyboard input (components in {-1, 0, 1}) lands on its sign pair exactly.
+ * Undefined for no input, which lets the caller keep whatever it was facing.
  */
 export declare function facingForInput(inputX: number, inputY: number): ScreenFacing | undefined;
 /** The screen sign pair behind a facing; undefined for a name the table lacks. */

package/dist/facing.js

@@ -11,29 +11,19 @@ const FACING_VECTORS = {
     w: { x: -1, y: 0 },
     nw: { x: -1, y: 1 },
 };
+/** Counter-clockwise from east, one per 45° sector of the input angle. */
+const FACINGS_BY_SECTOR = ['e', 'ne', 'n', 'nw', 'w', 'sw', 's', 'se'];
 /**
- * The eight-way facing a screen-relative input reads as — signs only, so a
- * tiny diagonal component still counts. Undefined for no input, which lets
- * the caller keep whatever it was facing.
+ * The eight-way facing a screen-relative input reads as: the 45° sector its
+ * angle falls in, so an almost-vertical stick faces `n`, not `ne`; every
+ * keyboard input (components in {-1, 0, 1}) lands on its sign pair exactly.
+ * Undefined for no input, which lets the caller keep whatever it was facing.
  */
 export function facingForInput(inputX, inputY) {
     if (inputX === 0 && inputY === 0)
         return undefined;
-    if (inputY > 0) {
-        if (inputX > 0)
-            return 'ne';
-        if (inputX < 0)
-            return 'nw';
-        return 'n';
-    }
-    if (inputY < 0) {
-        if (inputX > 0)
-            return 'se';
-        if (inputX < 0)
-            return 'sw';
-        return 's';
-    }
-    return inputX > 0 ? 'e' : 'w';
+    const sector = Math.round(Math.atan2(inputY, inputX) / (Math.PI / 4));
+    return FACINGS_BY_SECTOR[(sector + 8) % 8];
 }
 /** The screen sign pair behind a facing; undefined for a name the table lacks. */
 export function facingVector(facing) {

package/dist/grid-player-role.js

@@ -51,25 +51,25 @@ function gridPlayerGraph() {
         },
     };
 }
-/** The body update: keyboard input, else a live Move Order, then the motor step and move/stop signal. */
+/** The body update: directional input (keys or stick), 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)
             return;
-        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).
+        const inputX = game.input.axis('left', 'right');
+        const inputY = game.input.axis('down', 'up');
+        if (inputX !== 0 || inputY !== 0) {
+            // Any directional input — keys or stick — wins and cancels a live Move Order (CA-4).
             entity.get(ClickToMove)?.cancel();
-            motor.run(keyboardX, keyboardY, dt);
+            motor.run(inputX, inputY, 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
+                // same screen-relative input the directional 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);

package/dist/index.d.ts

@@ -23,3 +23,7 @@ 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';
+export { SwingSparks } from './swing-sparks.js';
+export { DamagePuff } from './damage-puff.js';
+export { DustPuffs } from './dust-puffs.js';
+export { DustTrail } from './dust-trail.js';

package/dist/index.js

@@ -21,3 +21,7 @@ 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';
+export { SwingSparks } from './swing-sparks.js';
+export { DamagePuff } from './damage-puff.js';
+export { DustPuffs } from './dust-puffs.js';
+export { DustTrail } from './dust-trail.js';

package/dist/swing-sparks.d.ts

@@ -0,0 +1,32 @@
+import { Component } from '@waica/engine';
+/**
+ * A burst of sparks from this entity's own
+ * ParticleEmitter each time its StateMachine enters the swing state. The
+ * look (color, speed, lifetime) is authored on the emitter in the prefab;
+ * this only decides when, and how many. It hooks the state's onEnter
+ * instead of polling, so it fires exactly once per swing — right after
+ * the role's own onEnter has landed the strike.
+ *
+ * Its siblings must already be mounted when it is, so it goes after the
+ * StateMachine and the ParticleEmitter in the prefab.
+ */
+export declare class SwingSparks extends Component {
+    static componentName: string;
+    static displayName: string;
+    static params: {
+        state: {
+            label: string;
+        };
+        count: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    /** The state whose entry is a swing. */
+    state: string;
+    /** Sparks per swing. */
+    count: number;
+    onReady(): void;
+}

package/dist/swing-sparks.js

@@ -0,0 +1,33 @@
+import { Component, ParticleEmitter, StateMachine } from '@waica/engine';
+/**
+ * A burst of sparks from this entity's own
+ * ParticleEmitter each time its StateMachine enters the swing state. The
+ * look (color, speed, lifetime) is authored on the emitter in the prefab;
+ * this only decides when, and how many. It hooks the state's onEnter
+ * instead of polling, so it fires exactly once per swing — right after
+ * the role's own onEnter has landed the strike.
+ *
+ * Its siblings must already be mounted when it is, so it goes after the
+ * StateMachine and the ParticleEmitter in the prefab.
+ */
+export class SwingSparks extends Component {
+    static componentName = 'SwingSparks';
+    static displayName = 'Swing sparks';
+    static params = {
+        state: { label: 'State' },
+        count: { label: 'Sparks', min: 1, max: 64, step: 1 },
+    };
+    /** The state whose entry is a swing. */
+    state = 'attack';
+    /** Sparks per swing. */
+    count = 14;
+    onReady() {
+        const machine = this.entity.get(StateMachine);
+        const sparks = this.entity.get(ParticleEmitter);
+        if (!machine || !sparks) {
+            console.warn(`[waica] "${this.entity.name}": SwingSparks needs a StateMachine and a ParticleEmitter before it.`);
+            return;
+        }
+        machine.on(this.state, { onEnter: () => sparks.emit(this.count) });
+    }
+}

package/package.json

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