@waica/behaviors 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayrton Marini and Waica contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/chaser.d.ts

@@ -0,0 +1,59 @@
+import { Component, type RoleDefinition, type RoleGraph } from '@waica/engine';
+export type ChaserMode = 'walker' | 'ghost' | 'flyer';
+/**
+ * Pursuit toward the player while they are within sight range, in one of
+ * three modes: a walker paces the ground (X only, gravity, blocked by
+ * Solids), a ghost floats straight at them through everything, a flyer
+ * floats straight at them but walls and ceilings stop it.
+ * Passive like a motor: no onUpdate of its own — the 'chaser' logic set's
+ * chase state calls step(dt), so the StateMachine stays the single owner
+ * of the frame.
+ */
+export declare class Chaser extends Component {
+    static componentName: string;
+    static params: {
+        mode: {
+            label: string;
+            options: string[];
+        };
+        range: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        speed: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        gravity: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    mode: ChaserMode;
+    range: number;
+    speed: number;
+    gravity: number;
+    private vy;
+    private target;
+    /** The player is the live entity whose StateMachine declares that role. */
+    private findTarget;
+    /** One chase step in the current mode, flipping the sprite toward prey. */
+    step(dt: number): void;
+    /** Ground pursuit: chase on X when in sight; gravity and Solids always rule. */
+    private stepWalker;
+    /** Straight-line pursuit; the flyer sweeps against Solids, the ghost doesn't. */
+    private stepAirborne;
+    /** Resolves this mode's body through the engine's shared Solid solver. */
+    private resolveAxis;
+    /** AABB sized by the sibling Hitbox (chassis default if none). */
+    private collisionBody;
+}
+/** The state graph new chasing characters start with, as prefab data. */
+export declare const CHASER_STATE_GRAPH: RoleGraph;
+export declare const CHASER_ROLE: RoleDefinition;

package/dist/chaser.js

@@ -0,0 +1,127 @@
+import { Component, Hitbox, resolveSolidAxis, } from '@waica/engine';
+import { isPlayer } from './player-identity.js';
+/**
+ * Pursuit toward the player while they are within sight range, in one of
+ * three modes: a walker paces the ground (X only, gravity, blocked by
+ * Solids), a ghost floats straight at them through everything, a flyer
+ * floats straight at them but walls and ceilings stop it.
+ * Passive like a motor: no onUpdate of its own — the 'chaser' logic set's
+ * chase state calls step(dt), so the StateMachine stays the single owner
+ * of the frame.
+ */
+export class Chaser extends Component {
+    static componentName = 'Chaser';
+    static params = {
+        mode: { label: 'Mode', options: ['walker', 'ghost', 'flyer'] },
+        range: { label: 'Sight range', min: 1, max: 30, step: 0.5 },
+        speed: { label: 'Speed', min: 0.5, max: 15, step: 0.5 },
+        gravity: { label: 'Gravity (walker)', min: 5, max: 120, step: 1 },
+    };
+    mode = 'walker';
+    range = 6;
+    speed = 3;
+    gravity = 42;
+    vy = 0;
+    target;
+    /** The player is the live entity whose StateMachine declares that role. */
+    findTarget() {
+        if (!this.target?.alive || !isPlayer(this.target)) {
+            this.target = this.entity.game.entities.find(isPlayer);
+        }
+        return this.target;
+    }
+    /** One chase step in the current mode, flipping the sprite toward prey. */
+    step(dt) {
+        if (this.mode === 'walker')
+            this.stepWalker(dt);
+        else
+            this.stepAirborne(dt);
+    }
+    /** Ground pursuit: chase on X when in sight; gravity and Solids always rule. */
+    stepWalker(dt) {
+        const pos = this.entity.position;
+        const target = this.findTarget();
+        const dx = target ? target.position.x - pos.x : 0;
+        if (target && Math.abs(dx) <= this.range && Math.abs(dx) > 0.05) {
+            const dir = dx > 0 ? 1 : -1;
+            const previous = pos.x;
+            pos.x += dir * Math.min(this.speed * dt, Math.abs(dx));
+            this.resolveAxis('x', previous);
+            this.entity.scale.x = dir;
+        }
+        // Gravity applies in and out of sight — a walker spawned midair lands.
+        this.vy = Math.max(this.vy - this.gravity * dt, -22);
+        const previous = pos.y;
+        pos.y += this.vy * dt;
+        this.resolveAxis('y', previous);
+    }
+    /** Straight-line pursuit; the flyer sweeps against Solids, the ghost doesn't. */
+    stepAirborne(dt) {
+        const pos = this.entity.position;
+        const target = this.findTarget();
+        if (!target)
+            return;
+        const dx = target.position.x - pos.x;
+        const dy = target.position.y - pos.y;
+        const dist = Math.hypot(dx, dy);
+        // The inner deadband keeps it from jittering on top of the player.
+        if (dist > this.range || dist < 0.1)
+            return;
+        const move = Math.min(this.speed * dt, dist);
+        const solid = this.mode === 'flyer';
+        const previousX = pos.x;
+        pos.x += (dx / dist) * move;
+        if (solid)
+            this.resolveAxis('x', previousX);
+        const previousY = pos.y;
+        pos.y += (dy / dist) * move;
+        if (solid)
+            this.resolveAxis('y', previousY);
+        if (Math.abs(dx) > 0.05)
+            this.entity.scale.x = dx > 0 ? 1 : -1;
+    }
+    /** Resolves this mode's body through the engine's shared Solid solver. */
+    resolveAxis(axis, previous) {
+        const collided = resolveSolidAxis({
+            entity: this.entity,
+            axis,
+            previous,
+            body: () => this.collisionBody(),
+        });
+        if (collided && axis === 'y')
+            this.vy = 0;
+    }
+    /** AABB sized by the sibling Hitbox (chassis default if none). */
+    collisionBody() {
+        const box = this.entity.get(Hitbox);
+        return {
+            x: this.entity.position.x + (box?.offsetX ?? 0),
+            y: this.entity.position.y + (box?.offsetY ?? 0),
+            width: box?.width ?? 0.9,
+            height: box?.height ?? 0.95,
+            shape: 'rectangle',
+        };
+    }
+}
+/** The state graph new chasing characters start with, as prefab data. */
+export const CHASER_STATE_GRAPH = {
+    initial: 'chase',
+    states: { chase: {} },
+};
+// The pursuer role. One state out of the box; give chasing characters more
+// states by registering on top (defineStates('chaser', { flee: {...} }))
+// plus prefab data.
+export const CHASER_ROLE = {
+    description: 'Hunts the player when they come within sight range. Its Mode picks ' +
+        'the body: a walker paces the ground with gravity, a ghost floats ' +
+        'through walls, a flyer floats but walls stop it. Its states move Chaser.',
+    driver: 'Chaser',
+    graph: CHASER_STATE_GRAPH,
+    states: {
+        chase: {
+            onUpdate({ entity }, dt) {
+                entity.get(Chaser)?.step(dt);
+            },
+        },
+    },
+};

package/dist/collectible.d.ts

@@ -0,0 +1,25 @@
+import { Component, type Entity } from '@waica/engine';
+/**
+ * Collected when the entity with the player role touches
+ * it: adds its value to a stat, fires onCollect and destroys itself.
+ * Requires Hitbox on both entities.
+ */
+export declare class Collectible extends Component {
+    static componentName: string;
+    static params: {
+        value: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        stat: {
+            label: string;
+        };
+    };
+    value: number;
+    /** Stat receiving the value ('' collects without counting anywhere). */
+    stat: string;
+    onCollect?: (value: number) => void;
+    onCollide(other: Entity): void;
+}

package/dist/collectible.js

@@ -0,0 +1,27 @@
+import { Component } from '@waica/engine';
+import { isPlayer } from './player-identity.js';
+/**
+ * Collected when the entity with the player role touches
+ * it: adds its value to a stat, fires onCollect and destroys itself.
+ * Requires Hitbox on both entities.
+ */
+export class Collectible extends Component {
+    static componentName = 'Collectible';
+    static params = {
+        value: { label: 'Value', min: 1, max: 100, step: 1 },
+        stat: { label: 'Adds to stat' },
+    };
+    value = 1;
+    /** Stat receiving the value ('' collects without counting anywhere). */
+    stat = 'points';
+    onCollect;
+    onCollide(other) {
+        if (!isPlayer(other))
+            return;
+        this.onCollect?.(this.value);
+        if (this.stat)
+            this.game.stats.add(this.stat, this.value);
+        this.game.events.emit('collect', this.value);
+        this.entity.destroy();
+    }
+}

package/dist/hazard.d.ts

@@ -0,0 +1,29 @@
+import { Component, type Entity } from '@waica/engine';
+export type HazardTouch = 'stomp' | 'hurt';
+/**
+ * Touching a hazard by stomping it from above (falling, with the feet
+ * above its center) squashes it; any other contact hurts.
+ * Pure, so the decision is testable without the engine.
+ */
+export declare function resolveHazardTouch(playerVy: number, playerBottom: number, hazardY: number, stompable: boolean): HazardTouch;
+/**
+ * Hurts the player on contact. If stompable (Mario-style), stomping it
+ * destroys it and bounces the player. Requires Hitbox on both entities.
+ */
+export declare class Hazard extends Component {
+    static componentName: string;
+    static params: {
+        stompable: {
+            label: string;
+        };
+        bounce: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    stompable: boolean;
+    bounce: number;
+    onCollide(other: Entity): void;
+}

package/dist/hazard.js

@@ -0,0 +1,42 @@
+import { Component } from '@waica/engine';
+import { PlatformerMotor } from './platformer-motor.js';
+import { isPlayer } from './player-identity.js';
+import { Respawnable } from './respawnable.js';
+/**
+ * Touching a hazard by stomping it from above (falling, with the feet
+ * above its center) squashes it; any other contact hurts.
+ * Pure, so the decision is testable without the engine.
+ */
+export function resolveHazardTouch(playerVy, playerBottom, hazardY, stompable) {
+    if (stompable && playerVy < 0 && playerBottom > hazardY)
+        return 'stomp';
+    return 'hurt';
+}
+/**
+ * Hurts the player on contact. If stompable (Mario-style), stomping it
+ * destroys it and bounces the player. Requires Hitbox on both entities.
+ */
+export class Hazard extends Component {
+    static componentName = 'Hazard';
+    static params = {
+        stompable: { label: 'Stompable' },
+        bounce: { label: 'Stomp bounce', min: 0, max: 30, step: 0.5 },
+    };
+    stompable = true;
+    bounce = 10;
+    onCollide(other) {
+        if (!isPlayer(other))
+            return;
+        const motor = other.get(PlatformerMotor);
+        if (motor) {
+            const playerBottom = other.position.y - motor.hitboxHeight / 2;
+            const touch = resolveHazardTouch(motor.vy, playerBottom, this.entity.position.y, this.stompable);
+            if (touch === 'stomp') {
+                this.entity.destroy();
+                motor.vy = this.bounce;
+                return;
+            }
+        }
+        other.get(Respawnable)?.respawn();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { PlatformerMotor } from './platformer-motor.js';
+export { PLAYER_ROLE, PLAYER_STATE_GRAPH, playerUpdate } from './player-states.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';
+export { NPC_ROLE, NPC_STATE_GRAPH } from './npc.js';
+export { Hazard, resolveHazardTouch, type HazardTouch } from './hazard.js';
+export { Respawnable } from './respawnable.js';
+export { Lifetime } from './lifetime.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+export { PlatformerMotor } from './platformer-motor.js';
+export { PLAYER_ROLE, PLAYER_STATE_GRAPH, playerUpdate } from './player-states.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';
+export { NPC_ROLE, NPC_STATE_GRAPH } from './npc.js';
+export { Hazard, resolveHazardTouch } from './hazard.js';
+export { Respawnable } from './respawnable.js';
+export { Lifetime } from './lifetime.js';

package/dist/lifetime.d.ts

@@ -0,0 +1,16 @@
+import { Component } from '@waica/engine';
+/** Destroys its entity after a configurable amount of simulated time. */
+export declare class Lifetime extends Component {
+    static componentName: string;
+    static params: {
+        seconds: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    seconds: number;
+    private elapsed;
+    onUpdate(dt: number): void;
+}

package/dist/lifetime.js

@@ -0,0 +1,19 @@
+import { Component } from '@waica/engine';
+/** Destroys its entity after a configurable amount of simulated time. */
+export class Lifetime extends Component {
+    static componentName = 'Lifetime';
+    static params = {
+        seconds: { label: 'Seconds', min: 0.05, max: 60, step: 0.05 },
+    };
+    seconds = 1;
+    elapsed = 0;
+    onUpdate(dt) {
+        // The frame that destroys the entity still iterates a copy of its
+        // components: stop counting instead of destroying twice.
+        if (!this.entity.alive)
+            return;
+        this.elapsed += dt;
+        if (this.elapsed >= this.seconds)
+            this.entity.destroy();
+    }
+}

package/dist/npc.d.ts

@@ -0,0 +1,4 @@
+import { type RoleDefinition, type RoleGraph } from '@waica/engine';
+/** The state graph new NPCs start with, as prefab data. */
+export declare const NPC_STATE_GRAPH: RoleGraph;
+export declare const NPC_ROLE: RoleDefinition;

package/dist/npc.js

@@ -0,0 +1,14 @@
+import {} from '@waica/engine';
+/** The state graph new NPCs start with, as prefab data. */
+export const NPC_STATE_GRAPH = {
+    initial: 'idle',
+    states: { idle: {} },
+};
+// The bystander role: no driver and no code — the character stands where
+// you put it, playing its idle animation, and hurts no one. Bring it to
+// life by adding states (defineStates('npc', {...})) and behaviours.
+export const NPC_ROLE = {
+    description: 'Stands where you put it — no input, no movement, harmless. Good for ' +
+        'villagers and signposts. Give it states to bring it to life.',
+    graph: NPC_STATE_GRAPH,
+};

package/dist/patrol.d.ts

@@ -0,0 +1,43 @@
+import { Component, type RoleDefinition, type RoleGraph } from '@waica/engine';
+export type PatrolAxis = 'horizontal' | 'vertical';
+/**
+ * Rail patrol: back and forth `distance` units from the starting
+ * position along one axis — sideways or up and down — turning around
+ * at the ends (with a sprite flip when walking sideways).
+ * Passive like a motor: no onUpdate of its own — the 'patroller' logic
+ * set's walk state calls step(dt), so the StateMachine stays the single
+ * owner of the frame.
+ */
+export declare class Patrol extends Component {
+    static componentName: string;
+    static params: {
+        axis: {
+            label: string;
+            options: string[];
+        };
+        distance: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        speed: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    axis: PatrolAxis;
+    distance: number;
+    speed: number;
+    private originX;
+    private originY;
+    private dir;
+    onReady(): void;
+    /** One patrol step: advance, turn at the rail's ends, flip the sprite. */
+    step(dt: number): void;
+}
+/** The state graph new patrolling characters start with, as prefab data. */
+export declare const PATROLLER_STATE_GRAPH: RoleGraph;
+export declare const PATROLLER_ROLE: RoleDefinition;

package/dist/patrol.js

@@ -0,0 +1,68 @@
+import { Component } from '@waica/engine';
+/**
+ * Rail patrol: back and forth `distance` units from the starting
+ * position along one axis — sideways or up and down — turning around
+ * at the ends (with a sprite flip when walking sideways).
+ * Passive like a motor: no onUpdate of its own — the 'patroller' logic
+ * set's walk state calls step(dt), so the StateMachine stays the single
+ * owner of the frame.
+ */
+export class Patrol extends Component {
+    static componentName = 'Patrol';
+    static params = {
+        axis: { label: 'Axis', options: ['horizontal', 'vertical'] },
+        distance: { label: 'Distance', min: 0.5, max: 20, step: 0.5 },
+        speed: { label: 'Speed', min: 0.5, max: 15, step: 0.5 },
+    };
+    axis = 'horizontal';
+    distance = 3;
+    speed = 2;
+    // Both origins are captured so a live axis switch keeps a valid rail.
+    originX = 0;
+    originY = 0;
+    dir = 1;
+    onReady() {
+        this.originX = this.entity.position.x;
+        this.originY = this.entity.position.y;
+    }
+    /** One patrol step: advance, turn at the rail's ends, flip the sprite. */
+    step(dt) {
+        const pos = this.entity.position;
+        const vertical = this.axis === 'vertical';
+        const key = vertical ? 'y' : 'x';
+        const origin = vertical ? this.originY : this.originX;
+        let next = pos[key] + this.dir * this.speed * dt;
+        if (next > origin + this.distance) {
+            next = origin + this.distance;
+            this.dir = -1;
+        }
+        else if (next < origin - this.distance) {
+            next = origin - this.distance;
+            this.dir = 1;
+        }
+        pos[key] = next;
+        if (!vertical)
+            this.entity.scale.x = this.dir;
+    }
+}
+/** The state graph new patrolling characters start with, as prefab data. */
+export const PATROLLER_STATE_GRAPH = {
+    initial: 'walk',
+    states: { walk: {} },
+};
+// The walking-critter role. One state out of the box; give patrolling
+// characters more states by registering on top (defineStates('patroller',
+// { chasing: {...} })) plus prefab data.
+export const PATROLLER_ROLE = {
+    description: 'Walks back and forth on its own along a rail — no player input, no ' +
+        'gravity. Good for critters and moving hazards. Its states move Patrol.',
+    driver: 'Patrol',
+    graph: PATROLLER_STATE_GRAPH,
+    states: {
+        walk: {
+            onUpdate({ entity }, dt) {
+                entity.get(Patrol)?.step(dt);
+            },
+        },
+    },
+};

package/dist/platformer-motor.d.ts

@@ -0,0 +1,124 @@
+import { Component } 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
+ * StateMachine is the only owner of the frame; this is the toolbox the
+ * active state moves the body with. The out-of-the-box game feel a
+ * beginner doesn't know they need lives here: coyote time, jump
+ * buffering, jump cut (releasing jumps shorter) and squash & stretch.
+ * Per-axis collision against the scene's Solids — deterministic genre
+ * movement (Celeste-style), not "realistic" physics.
+ */
+export declare class PlatformerMotor extends Component {
+    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;
+        };
+        jumpVelocity: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        gravity: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        maxFallSpeed: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        coyoteTime: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        jumpBuffer: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        jumpCutStrength: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        runThreshold: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        squashStretch: {
+            label: string;
+        };
+    };
+    moveSpeed: number;
+    acceleration: number;
+    deceleration: number;
+    jumpVelocity: number;
+    gravity: number;
+    maxFallSpeed: number;
+    coyoteTime: number;
+    jumpBuffer: number;
+    /** >1 applies extra gravity while rising without holding jump. */
+    jumpCutStrength: number;
+    /** |vx| above this reads as running (the idle ↔ run edge). */
+    runThreshold: number;
+    squashStretch: boolean;
+    /** The character's AABB hitbox. */
+    hitboxWidth: number;
+    hitboxHeight: number;
+    vx: number;
+    vy: number;
+    grounded: boolean;
+    /** 1 facing right, -1 facing left. */
+    facing: number;
+    private coyoteTimer;
+    private bufferTimer;
+    private squashX;
+    private squashY;
+    /**
+     * Per-frame bookkeeping: forgiveness timers, squash decay and the
+     * facing flip. The logic set's '*' hook runs it in every state, so
+     * coyote and buffer survive state transitions.
+     */
+    tick(dt: number): void;
+    /** Accelerates toward dir (-1..1) * moveSpeed, flipping facing. */
+    runTowards(dir: number, dt: number): void;
+    /** A buffered jump press within coyote time — the frame to call jump(). */
+    wantsJump(): boolean;
+    jump(): void;
+    /** Gravity with jump cut: rising without holding jump falls sooner. */
+    applyGravity(dt: number): void;
+    /** Integrates velocity and resolves collisions against Solids. */
+    step(dt: number): void;
+    halt(): void;
+    private applySquash;
+    private resolveAxis;
+    private collisionBody;
+}

package/dist/platformer-motor.js

@@ -0,0 +1,146 @@
+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
+ * StateMachine is the only owner of the frame; this is the toolbox the
+ * active state moves the body with. The out-of-the-box game feel a
+ * beginner doesn't know they need lives here: coyote time, jump
+ * buffering, jump cut (releasing jumps shorter) and squash & stretch.
+ * Per-axis collision against the scene's Solids — deterministic genre
+ * movement (Celeste-style), not "realistic" physics.
+ */
+export class PlatformerMotor extends Component {
+    static componentName = 'PlatformerMotor';
+    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 },
+        jumpVelocity: { label: 'Jump impulse', min: 2, max: 40, step: 0.5 },
+        gravity: { label: 'Gravity', min: 5, max: 120, step: 1 },
+        maxFallSpeed: { label: 'Max fall speed', min: 5, max: 60, step: 1 },
+        coyoteTime: { label: 'Coyote time (s)', min: 0, max: 0.4, step: 0.01 },
+        jumpBuffer: { label: 'Jump buffer (s)', min: 0, max: 0.4, step: 0.01 },
+        jumpCutStrength: { label: 'Jump cut', min: 1, max: 6, step: 0.1 },
+        runThreshold: { label: 'Run threshold', min: 0, max: 5, step: 0.1 },
+        squashStretch: { label: 'Squash & stretch' },
+    };
+    moveSpeed = 9;
+    acceleration = 60;
+    deceleration = 80;
+    jumpVelocity = 14;
+    gravity = 42;
+    maxFallSpeed = 22;
+    coyoteTime = 0.1;
+    jumpBuffer = 0.12;
+    /** >1 applies extra gravity while rising without holding jump. */
+    jumpCutStrength = 2.5;
+    /** |vx| above this reads as running (the idle ↔ run edge). */
+    runThreshold = 0.5;
+    squashStretch = true;
+    /** The character's AABB hitbox. */
+    hitboxWidth = 0.9;
+    hitboxHeight = 0.95;
+    vx = 0;
+    vy = 0;
+    grounded = false;
+    /** 1 facing right, -1 facing left. */
+    facing = 1;
+    coyoteTimer = 0;
+    bufferTimer = 0;
+    squashX = 1;
+    squashY = 1;
+    /**
+     * Per-frame bookkeeping: forgiveness timers, squash decay and the
+     * facing flip. The logic set's '*' hook runs it in every state, so
+     * coyote and buffer survive state transitions.
+     */
+    tick(dt) {
+        this.coyoteTimer = this.grounded ? this.coyoteTime : this.coyoteTimer - dt;
+        this.bufferTimer = this.game.input.justPressed('jump')
+            ? this.jumpBuffer
+            : this.bufferTimer - dt;
+        this.squashX = THREE.MathUtils.damp(this.squashX, 1, 12, dt);
+        this.squashY = THREE.MathUtils.damp(this.squashY, 1, 12, dt);
+        this.entity.scale.set(this.facing * this.squashX, this.squashY, 1);
+    }
+    /** Accelerates toward dir (-1..1) * moveSpeed, flipping facing. */
+    runTowards(dir, dt) {
+        const target = dir * this.moveSpeed;
+        const rate = dir !== 0 ? this.acceleration : this.deceleration;
+        this.vx = THREE.MathUtils.damp(this.vx, target, rate / this.moveSpeed, dt);
+        if (dir !== 0)
+            this.facing = dir < 0 ? -1 : 1;
+    }
+    /** A buffered jump press within coyote time — the frame to call jump(). */
+    wantsJump() {
+        return this.bufferTimer > 0 && this.coyoteTimer > 0;
+    }
+    jump() {
+        this.vy = this.jumpVelocity;
+        this.coyoteTimer = 0;
+        this.bufferTimer = 0;
+        // The press that launched this jump is spent: a "key press jump"
+        // transition needs a NEW press, not the one already used here.
+        this.game.input.consume('jump');
+        this.applySquash(0.8, 1.25);
+    }
+    /** Gravity with jump cut: rising without holding jump falls sooner. */
+    applyGravity(dt) {
+        const cut = this.vy > 0 && !this.game.input.held('jump') ? this.jumpCutStrength : 1;
+        this.vy = Math.max(this.vy - this.gravity * cut * dt, -this.maxFallSpeed);
+    }
+    /** Integrates velocity and resolves collisions against Solids. */
+    step(dt) {
+        const pos = this.entity.position;
+        const wasAirborne = !this.grounded;
+        const previousX = pos.x;
+        pos.x += this.vx * dt;
+        this.resolveAxis('x', previousX);
+        this.grounded = false;
+        const previousY = pos.y;
+        pos.y += this.vy * dt;
+        this.resolveAxis('y', previousY);
+        if (wasAirborne && this.grounded)
+            this.applySquash(1.25, 0.8);
+    }
+    halt() {
+        this.vx = 0;
+        this.vy = 0;
+    }
+    applySquash(x, y) {
+        if (!this.squashStretch)
+            return;
+        this.squashX = x;
+        this.squashY = y;
+    }
+    resolveAxis(axis, previous) {
+        const collided = resolveSolidAxis({
+            entity: this.entity,
+            axis,
+            previous,
+            body: () => this.collisionBody(),
+        });
+        if (!collided)
+            return;
+        if (axis === 'x') {
+            this.vx = 0;
+        }
+        else if (this.vy <= 0) {
+            this.vy = 0;
+            this.grounded = true;
+        }
+        else {
+            this.vy = 0;
+        }
+    }
+    collisionBody() {
+        return {
+            x: this.entity.position.x,
+            y: this.entity.position.y,
+            width: this.hitboxWidth,
+            height: this.hitboxHeight,
+            shape: 'rectangle',
+        };
+    }
+}

package/dist/player-identity.d.ts

@@ -0,0 +1,3 @@
+import { type Entity } from '@waica/engine';
+/** Player identity is the role contract, independent of the movement driver. */
+export declare function isPlayer(entity: Entity): boolean;

package/dist/player-identity.js

@@ -0,0 +1,5 @@
+import { StateMachine } from '@waica/engine';
+/** Player identity is the role contract, independent of the movement driver. */
+export function isPlayer(entity) {
+    return entity.get(StateMachine)?.role === 'player';
+}

package/dist/player-states.d.ts

@@ -0,0 +1,18 @@
+import { type RoleDefinition, type RoleGraph, type StateContext } from '@waica/engine';
+/**
+ * The 'player' role: the character you control. All four 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 player characters start with, as prefab data. */
+export declare const PLAYER_STATE_GRAPH: RoleGraph;
+/**
+ * One body update shared by every default state: move, jump, gravity,
+ * 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 playerUpdate({ entity, game, fsm }: StateContext, dt: number): void;
+export declare const PLAYER_ROLE: RoleDefinition;

package/dist/player-states.js

@@ -0,0 +1,95 @@
+import {} from '@waica/engine';
+import { PlatformerMotor } from './platformer-motor.js';
+/**
+ * The 'player' role: the character you control. All four 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 player characters start with, as prefab data. */
+export const PLAYER_STATE_GRAPH = {
+    initial: 'idle',
+    states: {
+        idle: {
+            transitions: [
+                { on: 'signal:move', to: 'run' },
+                { on: 'signal:rise', to: 'jump' },
+                { on: 'signal:fall', to: 'fall' },
+            ],
+        },
+        run: {
+            transitions: [
+                { on: 'signal:stop', to: 'idle' },
+                { on: 'signal:rise', to: 'jump' },
+                { on: 'signal:fall', to: 'fall' },
+            ],
+        },
+        jump: {
+            transitions: [
+                { on: 'signal:fall', to: 'fall' },
+                { on: 'signal:land', to: 'idle' },
+            ],
+        },
+        fall: {
+            // 'rise' from here is the coyote jump (and hazard stomp bounces).
+            transitions: [
+                { on: 'signal:rise', to: 'jump' },
+                { on: 'signal:land', to: 'idle' },
+            ],
+        },
+    },
+};
+/**
+ * One body update shared by every default state: move, jump, gravity,
+ * 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 playerUpdate({ entity, game, fsm }, dt) {
+    const motor = entity.get(PlatformerMotor);
+    if (!motor)
+        return;
+    motor.runTowards(game.input.axis(), dt);
+    if (motor.wantsJump())
+        motor.jump();
+    motor.applyGravity(dt);
+    motor.step(dt);
+    if (motor.grounded) {
+        fsm.signal('land');
+        fsm.signal(Math.abs(motor.vx) > motor.runThreshold ? 'move' : 'stop');
+    }
+    else {
+        fsm.signal(motor.vy > 0 ? 'rise' : 'fall');
+    }
+}
+export const PLAYER_ROLE = {
+    description: 'You control this character with the project controls: run and jump ' +
+        'with platformer physics and curated game feel (coyote time, jump ' +
+        'buffering). Its states move the Motor.',
+    driver: 'PlatformerMotor',
+    graph: PLAYER_STATE_GRAPH,
+    signals: {
+        move: 'on the ground and moving',
+        stop: 'on the ground and standing still',
+        rise: 'airborne, going up',
+        fall: 'airborne, going down',
+        land: 'just touched the ground',
+    },
+    states: {
+        // Always-hook: motor bookkeeping (coyote/buffer timers, squash, facing)
+        // must survive custom states like a dash, so it runs in every state.
+        '*': {
+            onUpdate({ entity }, dt) {
+                entity.get(PlatformerMotor)?.tick(dt);
+            },
+        },
+        // 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: playerUpdate },
+        idle: { onUpdate: playerUpdate },
+        run: { onUpdate: playerUpdate },
+        jump: { onUpdate: playerUpdate },
+        fall: { onUpdate: playerUpdate },
+    },
+};

package/dist/respawnable.d.ts

@@ -0,0 +1,23 @@
+import { Component } from '@waica/engine';
+/**
+ * Remembers the spawn point and puts the entity back there on death
+ * (falling off the world or touching a Hazard).
+ */
+export declare class Respawnable extends Component {
+    static componentName: string;
+    static displayName: string;
+    static params: {
+        killY: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    /** Falling below this height respawns. */
+    killY: number;
+    private spawn;
+    onReady(): void;
+    respawn(): void;
+    onUpdate(): void;
+}

package/dist/respawnable.js

@@ -0,0 +1,27 @@
+import { Component, THREE } from '@waica/engine';
+import { PlatformerMotor } from './platformer-motor.js';
+/**
+ * Remembers the spawn point and puts the entity back there on death
+ * (falling off the world or touching a Hazard).
+ */
+export class Respawnable extends Component {
+    static componentName = 'Respawnable';
+    static displayName = 'Respawn';
+    static params = {
+        killY: { label: 'Kill height', min: -50, max: 0, step: 1 },
+    };
+    /** Falling below this height respawns. */
+    killY = -12;
+    spawn = new THREE.Vector3();
+    onReady() {
+        this.spawn.copy(this.entity.position);
+    }
+    respawn() {
+        this.entity.position.copy(this.spawn);
+        this.entity.get(PlatformerMotor)?.halt();
+    }
+    onUpdate() {
+        if (this.entity.position.y < this.killY)
+            this.respawn();
+    }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@waica/behaviors",
+  "version": "0.3.0",
+  "description": "Waica built-in behaviors — the curated game-feel library",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chichex/waica",
+    "directory": "packages/behaviors"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@waica/engine": "^0.3.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  }
+}