@waica/cli 0.3.0

package/dist/mcp/node_modules/@waica/behaviors/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/mcp/node_modules/@waica/behaviors/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/mcp/node_modules/@waica/behaviors/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/mcp/node_modules/@waica/behaviors/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/mcp/node_modules/@waica/behaviors/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/mcp/node_modules/@waica/behaviors/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/mcp/node_modules/@waica/behaviors/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/mcp/node_modules/@waica/behaviors/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/mcp/node_modules/@waica/behaviors/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/mcp/node_modules/@waica/behaviors/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/dist/mcp/node_modules/@waica/behaviors/package.json

@@ -0,0 +1,24 @@
+{
+  "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"
+  }
+}

package/dist/mcp/node_modules/@waica/engine/dist/aabb.d.ts

@@ -0,0 +1,2 @@
+/** Do two center+size AABBs overlap? Edges that merely touch don't count. */
+export declare function aabbOverlap(ax: number, ay: number, aw: number, ah: number, bx: number, by: number, bw: number, bh: number): boolean;

package/dist/mcp/node_modules/@waica/engine/dist/aabb.js

@@ -0,0 +1,4 @@
+/** Do two center+size AABBs overlap? Edges that merely touch don't count. */
+export function aabbOverlap(ax, ay, aw, ah, bx, by, bw, bh) {
+    return Math.abs(ax - bx) * 2 < aw + bw && Math.abs(ay - by) * 2 < ah + bh;
+}

package/dist/mcp/node_modules/@waica/engine/dist/animation/clip-player.d.ts

@@ -0,0 +1,20 @@
+export interface ClipDef {
+    /** Frame indices inside the spritesheet (row×cols + col). */
+    frames: number[];
+    fps: number;
+    /** Defaults to true; with false it sticks on the last frame. */
+    loop?: boolean;
+}
+/**
+ * Advances a clip through time. Pure logic (no three, no DOM) so it can
+ * be tested deterministically.
+ */
+export declare class ClipPlayer {
+    private frames;
+    private fps;
+    private loop;
+    private t;
+    set(clip: ClipDef): void;
+    /** Advances the clock and returns the sheet frame to show. */
+    advance(dt: number): number;
+}

package/dist/mcp/node_modules/@waica/engine/dist/animation/clip-player.js

@@ -0,0 +1,24 @@
+/**
+ * Advances a clip through time. Pure logic (no three, no DOM) so it can
+ * be tested deterministically.
+ */
+export class ClipPlayer {
+    frames = [0];
+    fps = 1;
+    loop = true;
+    t = 0;
+    set(clip) {
+        this.frames = clip.frames.length > 0 ? clip.frames : [0];
+        this.fps = clip.fps;
+        this.loop = clip.loop ?? true;
+        this.t = 0;
+    }
+    /** Advances the clock and returns the sheet frame to show. */
+    advance(dt) {
+        this.t += dt;
+        const idx = Math.floor(this.t * this.fps);
+        const n = this.frames.length;
+        const clamped = this.loop ? idx % n : Math.min(idx, n - 1);
+        return this.frames[clamped] ?? 0;
+    }
+}

package/dist/mcp/node_modules/@waica/engine/dist/animation/contract.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Animation contract: the archetype declares which clips a character
+ * needs and how to degrade when one is missing. It's the centerpiece of
+ * the "the engine tells you which assets you need" thesis (DESIGN.md §2
+ * and §4): the game works from minute zero with whatever is there, and
+ * the editor (H2) will show the gaps as a checklist.
+ */
+export interface AnimationContract {
+    /** Clips the archetype expects to exist. */
+    required: string[];
+    /** Degradation chain: if a clip is missing, which one replaces it. */
+    fallbacks: Record<string, string>;
+}
+/**
+ * Resolves which clip to play: the requested one if it exists, otherwise
+ * it follows the fallback chain, and as a last resort the first available
+ * clip.
+ */
+export declare function resolveClip(contract: AnimationContract, available: Iterable<string>, wanted: string): string | undefined;
+/** Which contract clips are missing — what the editor will show as gaps. */
+export declare function missingClips(contract: AnimationContract, available: Iterable<string>): string[];