@waica/cli 0.8.0 → 0.9.0

package/dist/mcp/node_modules/@waica/behaviors/dist/health.js

@@ -7,6 +7,8 @@ import { Component, StateMachine } from '@waica/engine';
  * otherwise miss forever, leaving the entity undead at 0 HP.
  */
 const DEATH_EPSILON = 1e-9;
+/** Seconds each blink phase lasts while invulnerable: 10 Hz on/off. */
+const BLINK_PERIOD = 0.1;
 /**
  * Where a 'signal:death' from `current` could land: the targets of every
  * death edge on the current state or on '*'. Mirrors the merge
@@ -44,19 +46,56 @@ export class Health extends Component {
     static params = {
         max: { label: 'Max health', min: 1, max: 20, step: 1 },
         invulnerability: { label: 'Invulnerability', min: 0, max: 5, step: 0.1 },
+        stat: { label: 'Stat', ref: 'stat' },
     };
-    static transient = ['current', 'invulnerable', 'deathPending', 'expectedStates'];
+    static transient = [
+        'current',
+        'invulnerable',
+        'deathPending',
+        'expectedStates',
+        'lastDamageSource',
+        'blinkClock',
+    ];
     max = 3;
     /** Seconds of immunity granted by taking a hit. 0 disables i-frames. */
     invulnerability = 0;
+    /**
+     * Stat that mirrors `current` (a HUD binds to it with `{{stat}}`). Empty
+     * publishes nothing: the stat is the project's to declare.
+     */
+    stat = '';
     /** Health left; 0 is dead. Filled in from max on ready. */
     current = 0;
+    /** Whoever dealt the last accepted hit, for the state that reacts to it. */
+    lastDamageSource;
     /** Seconds left in the invulnerability window. */
     invulnerable = 0;
+    /** Seconds into the current blink, for the 10 Hz toggle. */
+    blinkClock = 0;
+    /** Whether the node is being flashed: exactly while a window is open. */
+    get blinking() {
+        return this.invulnerable > 0;
+    }
     /** Whether the signalled death must be checked on this component's next update. */
     deathPending = false;
     /** States the death signal was supposed to reach. */
     expectedStates = [];
+    /**
+     * What a Runtime Snapshot shows: the authored values, the live ones, and
+     * the last source by name — projecting the whole Entity would drag its
+     * scene node along and bury the numbers that matter.
+     */
+    inspectState() {
+        return {
+            max: this.max,
+            invulnerability: this.invulnerability,
+            stat: this.stat,
+            current: this.current,
+            invulnerable: this.invulnerable,
+            blinking: this.blinking,
+            lastDamageSource: this.lastDamageSource?.name ?? null,
+        };
+    }
     onReady() {
         // The inspector has no min clamp on max, so an authored 0 (or a
         // negative value) is reachable. Without this, current lands at <= 0
@@ -64,12 +103,15 @@ export class Health extends Component {
         // so die() is never reached — permanently invulnerable instead of
         // already dead.
         this.current = Math.max(0, this.max);
+        this.publish();
         if (this.current === 0)
             this.die();
     }
     onUpdate(dt) {
-        if (this.invulnerable > 0)
+        if (this.invulnerable > 0) {
             this.invulnerable = Math.max(0, this.invulnerable - dt);
+            this.blink(dt);
+        }
         if (this.deathPending) {
             this.deathPending = false;
             this.settleDeath();
@@ -108,6 +150,8 @@ export class Health extends Component {
         this.current = Math.max(0, this.current - amount);
         if (this.current < DEATH_EPSILON)
             this.current = 0;
+        this.lastDamageSource = source;
+        this.publish();
         this.game.events.emit('damage', {
             entity: this.entity,
             amount,
@@ -115,14 +159,39 @@ export class Health extends Component {
             source,
         });
         this.invulnerable = this.invulnerability;
-        if (this.current === 0)
+        this.blinkClock = 0;
+        if (this.current === 0) {
             this.die();
+            return;
+        }
+        // Fire-and-forget, like death: a graph with no 'signal:hurt' edge simply
+        // ignores it, so a stunned/knocked-back reaction is the role's to add.
+        this.entity.get(StateMachine)?.signal('hurt');
     }
     /** Gives health back, capped at max. heal(Infinity) is a full restore. */
     heal(amount) {
         if (amount <= 0)
             return;
         this.current = Math.min(this.max, this.current + amount);
+        this.publish();
+    }
+    /** Mirrors current into the named stat, when one is named. */
+    publish() {
+        if (this.stat)
+            this.game.stats.set(this.stat, this.current);
+    }
+    /**
+     * Flashes the node at 10 Hz for as long as the window stays open, and
+     * leaves it visible the frame the window closes — the flash is feedback,
+     * never a state a hit can leave the entity stuck in.
+     */
+    blink(dt) {
+        if (this.invulnerable > 0) {
+            this.blinkClock += dt;
+            this.entity.node.visible = Math.floor(this.blinkClock / BLINK_PERIOD) % 2 === 0;
+            return;
+        }
+        this.entity.node.visible = true;
     }
     /**
      * Announces the death, then lets the role decide — but only if it says it
@@ -130,6 +199,13 @@ export class Health extends Component {
      * destroying is the fallback rather than the exception.
      */
     die() {
+        // The killing blow opened a window like any other hit; close it. The
+        // death pose must hold steady, and a revived entity starts without
+        // leftover immunity. The node is visible here by construction: blink()
+        // restores it the frame a window closes, and a lethal hit only lands
+        // while no window is open.
+        this.invulnerable = 0;
+        this.blinkClock = 0;
         this.game.events.emit('death', { entity: this.entity });
         const machine = this.entity.get(StateMachine);
         const targets = machine ? deathTargets(machine.states, machine.current) : [];

package/dist/mcp/node_modules/@waica/behaviors/dist/index.d.ts

@@ -10,6 +10,7 @@ export { Patrol, PATROLLER_ROLE, PATROLLER_STATE_GRAPH, type PatrolAxis } from '
 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 { MeleeAttack } from './melee-attack.js';
 export { Health, declaresDeathHandling, deathTargets } from './health.js';
 export { Respawnable } from './respawnable.js';
 export { OutOfBounds } from './out-of-bounds.js';

package/dist/mcp/node_modules/@waica/behaviors/dist/index.js

@@ -10,6 +10,7 @@ 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 { MeleeAttack } from './melee-attack.js';
 export { Health, declaresDeathHandling, deathTargets } from './health.js';
 export { Respawnable } from './respawnable.js';
 export { OutOfBounds } from './out-of-bounds.js';

package/dist/mcp/node_modules/@waica/behaviors/dist/iso-motor.d.ts

@@ -1,6 +1,7 @@
+import { type ScreenFacing } from './facing.js';
 import { GridMotor } from './grid-motor.js';
 /** The eight screen-relative facings declared by the isometric archetype. */
-export type IsoFacing = 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw';
+export type IsoFacing = ScreenFacing;
 /**
  * Passive isometric motor. Input and facing are screen-relative while the
  * shared GridMotor integrates and collides in logical square-grid space.
@@ -9,6 +10,12 @@ export type IsoFacing = 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw';
 export declare class IsoMotor extends GridMotor<IsoFacing> {
     static componentName: string;
     facing: IsoFacing;
+    /**
+     * Under the diamond projection neither logical axis is "up the screen", so
+     * the footprint is square: as deep as it is wide, one cell-ish, instead of
+     * the short body top-down uses to let the player overlap a fence's top.
+     */
+    hitboxHeight: number;
     /** Accelerates screen-relative input toward a logical-space velocity. */
     run(inputX: number, inputY: number, dt: number): void;
 }

package/dist/mcp/node_modules/@waica/behaviors/dist/iso-motor.js

@@ -1,24 +1,6 @@
 import { screenInputToLogical } from '@waica/engine';
+import { facingForInput } from './facing.js';
 import { GridMotor } from './grid-motor.js';
-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';
-}
 /**
  * Passive isometric motor. Input and facing are screen-relative while the
  * shared GridMotor integrates and collides in logical square-grid space.
@@ -27,6 +9,12 @@ function facingForInput(inputX, inputY) {
 export class IsoMotor extends GridMotor {
     static componentName = 'IsoMotor';
     facing = 's';
+    /**
+     * Under the diamond projection neither logical axis is "up the screen", so
+     * the footprint is square: as deep as it is wide, one cell-ish, instead of
+     * the short body top-down uses to let the player overlap a fence's top.
+     */
+    hitboxHeight = 0.9;
     /** Accelerates screen-relative input toward a logical-space velocity. */
     run(inputX, inputY, dt) {
         const direction = screenInputToLogical(inputX, inputY);

package/dist/mcp/node_modules/@waica/behaviors/dist/melee-attack.d.ts

@@ -0,0 +1,48 @@
+import { Component, type Entity } from '@waica/engine';
+/**
+ * A short frontal strike. Passive like a motor: state code decides when it
+ * happens (the player's `attack` state) and calls strike(facing); this only
+ * knows where the blow lands and who can be hurt by it. The hit area is a
+ * `range` × `width` rectangle in logical space, laid along the facing from
+ * the attacker's position — under the isometric projection that is the
+ * diamond diagonal screen-east maps to, so "in front" matches the screen.
+ */
+export declare class MeleeAttack extends Component {
+    static componentName: string;
+    static displayName: string;
+    static params: {
+        damage: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        range: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        width: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    damage: number;
+    /** How far in front of the attacker the blow reaches, in world units. */
+    range: number;
+    /** How wide the blow is, across the facing. */
+    width: number;
+    /**
+     * Lands one blow along `facing`: every other living entity with a Hitbox
+     * and a Health inside the strike area takes `damage` once, with this
+     * entity as the source. Returns the entities whose health actually
+     * dropped — a target still inside its invulnerability window is not
+     * counted. An unknown facing strikes nothing.
+     */
+    strike(facing: string): Entity[];
+    /** The oriented rectangle in front of the attacker, as a unit-scaled polygon. */
+    private strikeArea;
+}

package/dist/mcp/node_modules/@waica/behaviors/dist/melee-attack.js

@@ -0,0 +1,83 @@
+import { Component, Hitbox, collisionOverlap, } from '@waica/engine';
+import { logicalDirection } from './facing.js';
+import { Health } from './health.js';
+/**
+ * A short frontal strike. Passive like a motor: state code decides when it
+ * happens (the player's `attack` state) and calls strike(facing); this only
+ * knows where the blow lands and who can be hurt by it. The hit area is a
+ * `range` × `width` rectangle in logical space, laid along the facing from
+ * the attacker's position — under the isometric projection that is the
+ * diamond diagonal screen-east maps to, so "in front" matches the screen.
+ */
+export class MeleeAttack extends Component {
+    static componentName = 'MeleeAttack';
+    static displayName = 'Melee attack';
+    static params = {
+        damage: { label: 'Damage', min: 0, max: 20, step: 1 },
+        range: { label: 'Range', min: 0.5, max: 5, step: 0.5 },
+        width: { label: 'Width', min: 0.5, max: 5, step: 0.5 },
+    };
+    damage = 1;
+    /** How far in front of the attacker the blow reaches, in world units. */
+    range = 1;
+    /** How wide the blow is, across the facing. */
+    width = 1;
+    /**
+     * Lands one blow along `facing`: every other living entity with a Hitbox
+     * and a Health inside the strike area takes `damage` once, with this
+     * entity as the source. Returns the entities whose health actually
+     * dropped — a target still inside its invulnerability window is not
+     * counted. An unknown facing strikes nothing.
+     */
+    strike(facing) {
+        const direction = logicalDirection(facing, this.game.projection);
+        if (!direction)
+            return [];
+        const area = this.strikeArea(direction.x, direction.y);
+        const struck = [];
+        // A copy: a target with no death-handling graph is destroyed on the spot,
+        // which splices it out of the live array mid-loop (Game does the same).
+        for (const other of [...this.game.entities]) {
+            if (other === this.entity || !other.alive)
+                continue;
+            const hitbox = other.get(Hitbox);
+            const health = other.get(Health);
+            if (!hitbox || !health)
+                continue;
+            const body = {
+                x: other.position.x + hitbox.offsetX,
+                y: other.position.y + hitbox.offsetY,
+                width: hitbox.width,
+                height: hitbox.height,
+                shape: hitbox.shape,
+                points: hitbox.points,
+            };
+            if (!collisionOverlap(area, body))
+                continue;
+            const before = health.current;
+            health.damage(this.damage, this.entity);
+            if (health.current < before)
+                struck.push(other);
+        }
+        return struck;
+    }
+    /** The oriented rectangle in front of the attacker, as a unit-scaled polygon. */
+    strikeArea(dx, dy) {
+        const along = { x: (dx * this.range) / 2, y: (dy * this.range) / 2 };
+        const across = { x: (-dy * this.width) / 2, y: (dx * this.width) / 2 };
+        const points = [
+            [-along.x - across.x, -along.y - across.y],
+            [along.x - across.x, along.y - across.y],
+            [along.x + across.x, along.y + across.y],
+            [-along.x + across.x, -along.y + across.y],
+        ];
+        return {
+            x: this.entity.position.x + along.x,
+            y: this.entity.position.y + along.y,
+            width: 1,
+            height: 1,
+            shape: 'polygon',
+            points,
+        };
+    }
+}

package/dist/mcp/node_modules/@waica/behaviors/dist/patrol.d.ts

@@ -1,14 +1,16 @@
-import { Component, type RoleDefinition, type RoleGraph } from '@waica/engine';
+import { Component, type AnimationFacingProvider, 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).
+ * at the ends. It reports which way it walks as seen on screen, so a
+ * directional contract picks the matching clip; without one, walking
+ * sideways flips the sprite by scale instead.
  * 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 {
+export declare class Patrol extends Component implements AnimationFacingProvider {
     static componentName: string;
     static params: {
         axis: {
@@ -36,6 +38,12 @@ export declare class Patrol extends Component {
     private originY;
     private dir;
     onReady(): void;
+    /**
+     * The rail direction as rendered: the logical axis it walks along,
+     * projected when the scene is isometric — a horizontal rail reads as
+     * south-east/north-west there, a vertical one as south-west/north-east.
+     */
+    getAnimationFacing(): string;
     /** One patrol step: advance, turn at the rail's ends, flip the sprite. */
     step(dt: number): void;
 }

package/dist/mcp/node_modules/@waica/behaviors/dist/patrol.js

@@ -1,8 +1,15 @@
-import { Component } from '@waica/engine';
+import { Component, installedDirectionalAnimation, projectIsometric, } from '@waica/engine';
+import { facingForInput } from './facing.js';
+/** Seconds a hit stops the rail. */
+const HURT_SECONDS = 0.25;
+/** Seconds the death pose stays on screen before the entity goes away. */
+const DEATH_SECONDS = 0.5;
 /**
  * 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).
+ * at the ends. It reports which way it walks as seen on screen, so a
+ * directional contract picks the matching clip; without one, walking
+ * sideways flips the sprite by scale instead.
  * 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.
@@ -26,6 +33,18 @@ export class Patrol extends Component {
         this.originX = this.entity.position.x;
         this.originY = this.entity.position.y;
     }
+    /**
+     * The rail direction as rendered: the logical axis it walks along,
+     * projected when the scene is isometric — a horizontal rail reads as
+     * south-east/north-west there, a vertical one as south-west/north-east.
+     */
+    getAnimationFacing() {
+        const vertical = this.axis === 'vertical';
+        const lx = vertical ? 0 : this.dir;
+        const ly = vertical ? this.dir : 0;
+        const screen = this.game.projection === 'isometric' ? projectIsometric(lx, ly) : { x: lx, y: ly };
+        return facingForInput(Math.sign(screen.x), Math.sign(screen.y)) ?? 's';
+    }
     /** One patrol step: advance, turn at the rail's ends, flip the sprite. */
     step(dt) {
         const pos = this.entity.position;
@@ -42,16 +61,32 @@ export class Patrol extends Component {
             this.dir = 1;
         }
         pos[key] = next;
-        if (!vertical)
+        // With a directional contract installed the clip carries the mirroring
+        // (flipX); a scale flip on top would undo it.
+        if (!vertical && !installedDirectionalAnimation())
             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: {} },
+    states: {
+        walk: {},
+        hurt: { transitions: [{ on: `timer:${HURT_SECONDS}`, to: 'walk' }] },
+        // The death pose, resolved directionally like every other clip.
+        dead: { clip: 'death' },
+        // Death first: a lethal hit must never land in hurt. The death edge is
+        // also what makes Health hand the death to this graph instead of
+        // destroying the entity on the spot.
+        '*': {
+            transitions: [
+                { on: 'signal:death', to: 'dead' },
+                { on: 'signal:hurt', to: 'hurt' },
+            ],
+        },
+    },
 };
-// The walking-critter role. One state out of the box; give patrolling
+// The walking-critter role. Walks, flinches, dies; give patrolling
 // characters more states by registering on top (defineStates('patroller',
 // { chasing: {...} })) plus prefab data.
 export const PATROLLER_ROLE = {
@@ -65,5 +100,14 @@ export const PATROLLER_ROLE = {
                 entity.get(Patrol)?.step(dt);
             },
         },
+        // The rail stops for the flinch: no step, nothing else to do.
+        hurt: { onUpdate() { } },
+        // Holds the death pose for a beat, then the body goes away for good.
+        dead: {
+            onUpdate({ entity, fsm }) {
+                if (fsm.elapsed >= DEATH_SECONDS)
+                    entity.destroy();
+            },
+        },
     },
 };

package/dist/mcp/node_modules/@waica/behaviors/package.json

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

package/dist/mcp/node_modules/@waica/engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",

package/dist/mcp/template/src/stats.json

@@ -2,6 +2,7 @@
   "waicaStats": 1,
   "stats": {
     "points": 0,
-    "lives": 3
+    "lives": 3,
+    "health": 3
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Waica in one command — `npx @waica/cli` opens the editor, `waica mcp` serves the MCP server",
   "license": "MIT",
   "type": "module",