@waica/behaviors 0.20.0 → 0.21.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/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.21.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.21.0"
   }
 }