@waica/cli 0.8.0 → 0.9.0

package/dist/mcp/node_modules/@waica/archetype-isometric/dist/prefabs.js

@@ -1,25 +1,35 @@
 import { ISO_PLAYER_STATE_GRAPH, NPC_STATE_GRAPH, PATROLLER_STATE_GRAPH, } from '@waica/behaviors';
 const SHIPPED_DIRECTIONS = ['n', 'ne', 'e', 'se', 's'];
-function directionalClips(includePlain) {
+/** One row per shipped facing: idle · walk×3 · attack×3 · hurt×2 · death×2. */
+const SHEET_COLUMNS = 11;
+const SOUTH_ROW = SHIPPED_DIRECTIONS.indexOf('s') * SHEET_COLUMNS;
+/** Transparent texels under the boots in every Puny cell, in render units (9 / 16). */
+const BOOTS_OFFSET = -9 / 16;
+function directionalClips({ plain = false, attacks = false }) {
     const clips = {};
     SHIPPED_DIRECTIONS.forEach((direction, row) => {
-        const first = row * 4;
+        const first = row * SHEET_COLUMNS;
         clips[`idle-${direction}`] = { frames: [first], fps: 2 };
         clips[`walk-${direction}`] = {
             frames: [first + 1, first + 2, first + 3, first + 2],
             fps: 8,
         };
+        if (attacks) {
+            clips[`attack-${direction}`] = { frames: [first + 4, first + 5, first + 6], fps: 12, loop: false };
+        }
+        clips[`hurt-${direction}`] = { frames: [first + 7, first + 8], fps: 8, loop: false };
+        clips[`death-${direction}`] = { frames: [first + 9, first + 10], fps: 4, loop: false };
     });
-    if (includePlain) {
-        clips['idle'] = { frames: [16], fps: 2 };
-        clips['walk'] = { frames: [17, 18, 19, 18], fps: 8 };
+    if (plain) {
+        clips['idle'] = { frames: [SOUTH_ROW], fps: 2 };
+        clips['walk'] = { frames: [SOUTH_ROW + 1, SOUTH_ROW + 2, SOUTH_ROW + 3, SOUTH_ROW + 2], fps: 8 };
     }
     return clips;
 }
-function characterSprite(texture, includePlain = false) {
+function characterSprite(texture, options = {}) {
     return {
         texture,
-        cols: 4,
+        cols: SHEET_COLUMNS,
         rows: 5,
         spacingX: 1,
         spacingY: 1,
@@ -27,11 +37,16 @@ function characterSprite(texture, includePlain = false) {
         width: 2,
         height: 2,
         anchorY: 0,
-        clips: directionalClips(includePlain),
-        initialClip: includePlain ? 'idle' : 'idle-s',
+        // The Puny bodies stand 9 texels above their cell's bottom edge; shift the
+        // quad down so the boots sit on the entity's position (its footprint),
+        // instead of floating half a unit up the screen — over a water diamond
+        // the body is actually stopped short of.
+        offsetY: BOOTS_OFFSET,
+        clips: directionalClips(options),
+        initialClip: options.plain ? 'idle' : 'idle-s',
     };
 }
-export const ISOMETRIC_HERO_SPRITE = characterSprite('waica:iso-hero');
+export const ISOMETRIC_HERO_SPRITE = characterSprite('waica:iso-hero', { attacks: true });
 const MAP_WIDTH = 16;
 const MAP_HEIGHT = 16;
 const GRASS = 0;
@@ -68,8 +83,9 @@ export const ISOMETRIC_PREFABS = {
                 },
             },
             { type: 'Hitbox', props: { width: 0.8, height: 0.8 } },
+            { type: 'MeleeAttack' },
             { type: 'Respawnable' },
-            { type: 'Health', props: { max: 3, invulnerability: 1 } },
+            { type: 'Health', props: { max: 3, invulnerability: 1, stat: 'health' } },
         ],
     },
     'characters/villager': {
@@ -78,7 +94,7 @@ export const ISOMETRIC_PREFABS = {
         components: [
             {
                 type: 'AnimatedSprite',
-                props: characterSprite('waica:iso-villager', true),
+                props: characterSprite('waica:iso-villager', { plain: true }),
             },
             {
                 type: 'StateMachine',
@@ -99,8 +115,10 @@ export const ISOMETRIC_PREFABS = {
             {
                 type: 'AnimatedSprite',
                 props: {
-                    ...characterSprite('waica:iso-orc', true),
-                    initialClip: 'walk',
+                    ...characterSprite('waica:iso-orc', { attacks: true }),
+                    // Patrol reports facing, so the orc resolves directional clips
+                    // from the first frame: it starts down its rail, screen south-east.
+                    initialClip: 'walk-se',
                 },
             },
             { type: 'Patrol', props: { axis: 'horizontal', distance: 2, speed: 2 } },
@@ -114,6 +132,7 @@ export const ISOMETRIC_PREFABS = {
             },
             { type: 'Hitbox', props: { width: 0.8, height: 0.7 } },
             { type: 'Hazard', props: { stompable: false, contactDamage: 1 } },
+            { type: 'Health', props: { max: 2, invulnerability: 0.3 } },
         ],
     },
     'objects/crate': {

package/dist/mcp/node_modules/@waica/archetype-isometric/dist/registry-data.js

@@ -1,5 +1,5 @@
 import { AnimatedSprite, Hitbox, Solid, Sprite, StateMachine, Tilemap, } from '@waica/engine';
-import { Chaser, Collectible, Hazard, Health, Interactable, IsoMotor, Lifetime, Patrol, Respawnable, } from '@waica/behaviors';
+import { Chaser, Collectible, Hazard, Health, Interactable, IsoMotor, Lifetime, MeleeAttack, Patrol, Respawnable, } from '@waica/behaviors';
 import { ISOMETRIC_ART } from './art.js';
 import { ISOMETRIC_PREFABS } from './prefabs.js';
 import { ISOMETRIC_UI } from './ui.js';
@@ -13,6 +13,7 @@ export const ISOMETRIC_REGISTRY_DATA = {
         Hitbox,
         StateMachine,
         IsoMotor,
+        MeleeAttack,
         Interactable,
         Collectible,
         Patrol,

package/dist/mcp/node_modules/@waica/archetype-isometric/dist/scene-default.js

@@ -1,8 +1,19 @@
+/**
+ * Full-map framing plus a follow feel tuned for the diamond: a tight dead
+ * zone and no horizontal lookahead (the engine's step kicks in every time
+ * the player crosses walking speed, which lurches on short runs), a little
+ * vertical lead, and softer smoothing than the platformer default.
+ */
 function isometricCamera() {
     return {
         position: [0, -8],
         zoom: 12,
         limits: { minX: -16, maxX: 16, minY: -16, maxY: 0 },
+        deadzoneWidth: 0.5,
+        deadzoneHeight: 0.5,
+        lookahead: 0,
+        lookaheadY: 0.5,
+        smoothing: 4,
     };
 }
 /** A logical 16x16 meadow projected into a 2:1 diamond at render time. */
@@ -12,7 +23,6 @@ export const ISOMETRIC_SCENE = {
     camera: {
         ...isometricCamera(),
         follow: 'Player',
-        lookaheadY: 1,
     },
     entities: [
         { name: 'Ground', prefab: 'tiles/ground', position: [0, 0] },
@@ -38,7 +48,7 @@ export const ISOMETRIC_SCENE = {
         { name: 'Rock-1', prefab: 'objects/rock', position: [5, 11] },
         { name: 'Rock-2', prefab: 'objects/rock', position: [9, 4] },
     ],
-    ui: ['crate-counter'],
+    ui: ['crate-counter', 'health'],
 };
 /** Blank projects retain the diamond grid and full-map framing. */
 export const ISOMETRIC_BLANK_SCENE = {

package/dist/mcp/node_modules/@waica/archetype-isometric/dist/ui.js

@@ -12,6 +12,19 @@ export const ISOMETRIC_UI = {
   }
 </style>
 <div class="crate-counter">📦 {{points}}</div>
+`,
+    health: `<style>
+  .health {
+    position: absolute;
+    top: 12px;
+    right: 12px;
+    font: 600 20px system-ui, sans-serif;
+    color: #ef476f;
+    text-shadow: 0 1px 3px #000a;
+    user-select: none;
+  }
+</style>
+<div class="health">♥ {{health}}</div>
 `,
     ...INTERACTABLE_UI,
 };

package/dist/mcp/node_modules/@waica/archetype-isometric/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/archetype-isometric",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Waica isometric archetype — logical-grid action adventures with screen-relative movement",
   "license": "MIT",
   "type": "module",
@@ -24,7 +24,7 @@
     }
   },
   "dependencies": {
-    "@waica/behaviors": "^0.8.0",
-    "@waica/engine": "^0.8.0"
+    "@waica/behaviors": "^0.9.0",
+    "@waica/engine": "^0.9.0"
   }
 }

package/dist/mcp/node_modules/@waica/archetype-platformer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/archetype-platformer",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Waica platformer archetype — opinionated setup for side-scrolling platformers",
   "license": "MIT",
   "type": "module",
@@ -24,7 +24,7 @@
     }
   },
   "dependencies": {
-    "@waica/behaviors": "^0.8.0",
-    "@waica/engine": "^0.8.0"
+    "@waica/behaviors": "^0.9.0",
+    "@waica/engine": "^0.9.0"
   }
 }

package/dist/mcp/node_modules/@waica/archetype-topdown/dist/animation.d.ts

@@ -2,6 +2,7 @@ import type { DirectionalAnimation } from '@waica/engine';
 /**
  * The archetype's directional animation contract: four facings with west
  * mirrored from east art (the stock sheets only draw s/n/e), clips named
- * `<state>-<dir>`, and walk falling back to idle when a sheet lacks it.
+ * `<state>-<dir>`, and every pose the shared player graph can enter (walk,
+ * attack, hurt, death) falling back to idle when a sheet lacks it.
  */
 export declare const TOPDOWN_ANIMATION: DirectionalAnimation;

package/dist/mcp/node_modules/@waica/archetype-topdown/dist/animation.js

@@ -1,10 +1,14 @@
 /**
  * The archetype's directional animation contract: four facings with west
  * mirrored from east art (the stock sheets only draw s/n/e), clips named
- * `<state>-<dir>`, and walk falling back to idle when a sheet lacks it.
+ * `<state>-<dir>`, and every pose the shared player graph can enter (walk,
+ * attack, hurt, death) falling back to idle when a sheet lacks it.
  */
 export const TOPDOWN_ANIMATION = {
     directions: ['n', 's', 'e', 'w'],
     fallbacks: { w: { dir: 'e', flip: true } },
-    contract: { required: ['idle'], fallbacks: { walk: 'idle' } },
+    contract: {
+        required: ['idle'],
+        fallbacks: { walk: 'idle', attack: 'idle', hurt: 'idle', death: 'idle' },
+    },
 };

package/dist/mcp/node_modules/@waica/archetype-topdown/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/archetype-topdown",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Waica top-down archetype — opinionated setup for Zelda-like overhead adventures",
   "license": "MIT",
   "type": "module",
@@ -24,7 +24,7 @@
     }
   },
   "dependencies": {
-    "@waica/behaviors": "^0.8.0",
-    "@waica/engine": "^0.8.0"
+    "@waica/behaviors": "^0.9.0",
+    "@waica/engine": "^0.9.0"
   }
 }

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

@@ -0,0 +1,18 @@
+import { type ProjectedPoint } from '@waica/engine';
+/** The eight screen-relative facings a directional contract can declare. */
+export type ScreenFacing = 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw';
+export declare const SCREEN_FACINGS: readonly ScreenFacing[];
+/**
+ * The eight-way facing a screen-relative input reads as — signs only, so a
+ * tiny diagonal component still counts. Undefined for no input, which lets
+ * the caller keep whatever it was facing.
+ */
+export declare function facingForInput(inputX: number, inputY: number): ScreenFacing | undefined;
+/** The screen sign pair behind a facing; undefined for a name the table lacks. */
+export declare function facingVector(facing: string): ProjectedPoint | undefined;
+/**
+ * The unit vector a facing points along in the scene's logical space: the
+ * screen vector itself without a projection, or its image on the logical
+ * diamond under the isometric one — the same mapping the motors move along.
+ */
+export declare function logicalDirection(facing: string, projection: 'isometric' | null): ProjectedPoint | undefined;

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

@@ -0,0 +1,56 @@
+import { screenInputToLogical } from '@waica/engine';
+export const SCREEN_FACINGS = ['n', 'ne', 'e', 'se', 's', 'sw', 'w', 'nw'];
+/** Facing → screen sign pair (x right, y up), the inverse of facingForInput. */
+const FACING_VECTORS = {
+    n: { x: 0, y: 1 },
+    ne: { x: 1, y: 1 },
+    e: { x: 1, y: 0 },
+    se: { x: 1, y: -1 },
+    s: { x: 0, y: -1 },
+    sw: { x: -1, y: -1 },
+    w: { x: -1, y: 0 },
+    nw: { x: -1, y: 1 },
+};
+/**
+ * The eight-way facing a screen-relative input reads as — signs only, so a
+ * tiny diagonal component still counts. Undefined for no input, which lets
+ * the caller keep whatever it was facing.
+ */
+export function facingForInput(inputX, inputY) {
+    if (inputX === 0 && inputY === 0)
+        return undefined;
+    if (inputY > 0) {
+        if (inputX > 0)
+            return 'ne';
+        if (inputX < 0)
+            return 'nw';
+        return 'n';
+    }
+    if (inputY < 0) {
+        if (inputX > 0)
+            return 'se';
+        if (inputX < 0)
+            return 'sw';
+        return 's';
+    }
+    return inputX > 0 ? 'e' : 'w';
+}
+/** The screen sign pair behind a facing; undefined for a name the table lacks. */
+export function facingVector(facing) {
+    const vector = FACING_VECTORS[facing];
+    return vector ? { ...vector } : undefined;
+}
+/**
+ * The unit vector a facing points along in the scene's logical space: the
+ * screen vector itself without a projection, or its image on the logical
+ * diamond under the isometric one — the same mapping the motors move along.
+ */
+export function logicalDirection(facing, projection) {
+    const vector = facingVector(facing);
+    if (!vector)
+        return undefined;
+    if (projection === 'isometric')
+        return screenInputToLogical(vector.x, vector.y);
+    const length = Math.hypot(vector.x, vector.y);
+    return { x: vector.x / length, y: vector.y / length };
+}

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

@@ -27,6 +27,12 @@ export declare abstract class GridMotor<Facing extends string> extends Component
             max: number;
             step: number;
         };
+        knockbackSpeed: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
     };
     static transient: string[];
     moveSpeed: number;
@@ -34,6 +40,8 @@ export declare abstract class GridMotor<Facing extends string> extends Component
     deceleration: number;
     /** Speed above this reads as walking (the idle ↔ walk edge). */
     walkThreshold: number;
+    /** How hard a hit shoves the body away from its source (the hurt state). */
+    knockbackSpeed: number;
     /** The character's AABB hitbox — a footprint, shorter than the sprite. */
     hitboxWidth: number;
     hitboxHeight: number;

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

@@ -7,6 +7,7 @@ export class GridMotor extends Component {
         acceleration: { label: 'Acceleration', min: 5, max: 200, step: 5 },
         deceleration: { label: 'Deceleration', min: 5, max: 200, step: 5 },
         walkThreshold: { label: 'Walk threshold', min: 0, max: 5, step: 0.1 },
+        knockbackSpeed: { label: 'Knockback speed', min: 0, max: 30, step: 0.5 },
     };
     static transient = ['vx', 'vy', 'facing'];
     moveSpeed = 6;
@@ -14,6 +15,8 @@ export class GridMotor extends Component {
     deceleration = 80;
     /** Speed above this reads as walking (the idle ↔ walk edge). */
     walkThreshold = 0.5;
+    /** How hard a hit shoves the body away from its source (the hurt state). */
+    knockbackSpeed = 8;
     /** The character's AABB hitbox — a footprint, shorter than the sprite. */
     hitboxWidth = 0.9;
     hitboxHeight = 0.6;

package/dist/mcp/node_modules/@waica/behaviors/dist/grid-player-role.d.ts

@@ -1,9 +1,14 @@
 import { type Component, type ComponentClass, type RoleDefinition, type RoleGraph, type StateContext } from '@waica/engine';
 interface PlayerMotor extends Component {
     walkThreshold: number;
+    knockbackSpeed: number;
+    facing: string;
+    vx: number;
+    vy: number;
     run(inputX: number, inputY: number, dt: number): void;
     step(dt: number): void;
     speed(): number;
+    halt(): void;
 }
 interface GridPlayerRoleParts {
     graph: RoleGraph;

package/dist/mcp/node_modules/@waica/behaviors/dist/grid-player-role.js

@@ -1,28 +1,52 @@
 import {} from '@waica/engine';
+import { logicalDirection } from './facing.js';
 import { Health } from './health.js';
 import { interactUpdate } from './interactable.js';
+import { MeleeAttack } from './melee-attack.js';
 import { Respawnable } from './respawnable.js';
+/** Seconds the attack swing and the hurt stun each keep the body from the player. */
+const ATTACK_SECONDS = 0.3;
+const HURT_SECONDS = 0.3;
 /** Builds the common player graph and role around one genre-specific grid motor. */
 export function createGridPlayerRole(Motor, description) {
     const graph = {
         initial: 'idle',
         states: {
             idle: {
-                transitions: [{ on: 'signal:move', to: 'walk' }],
+                transitions: [
+                    { on: 'input:attack', to: 'attack' },
+                    { on: 'signal:move', to: 'walk' },
+                ],
             },
             walk: {
-                transitions: [{ on: 'signal:stop', to: 'idle' }],
+                transitions: [
+                    { on: 'input:attack', to: 'attack' },
+                    { on: 'signal:stop', to: 'idle' },
+                ],
+            },
+            // One swing, body frozen; the strike itself lands on entry.
+            attack: {
+                transitions: [{ on: `timer:${ATTACK_SECONDS}`, to: 'idle' }],
+            },
+            // Knocked back and stunned for a beat; the '*' edge below gets it here.
+            hurt: {
+                transitions: [{ on: `timer:${HURT_SECONDS}`, to: 'idle' }],
             },
             dead: {
-                // Freeze on idle (resolved directionally) rather than name a death
-                // clip the stock sheets do not have and warn every frame.
-                clip: 'idle',
+                // The death pose, resolved directionally like every other clip.
+                clip: 'death',
                 transitions: [{ on: 'timer:0.8', to: 'idle' }],
             },
-            // Dying is the same from every state, so the edge lives on '*'. Its
-            // presence is also the contract Health checks before signalling: a graph
-            // without it gets its entity destroyed instead.
-            '*': { transitions: [{ on: 'signal:death', to: 'dead' }] },
+            // Dying and getting hurt are the same from every state, so both edges
+            // live on '*' — death first, so a lethal hit never lands in hurt. The
+            // death edge is also the contract Health checks before signalling: a
+            // graph without it gets its entity destroyed instead.
+            '*': {
+                transitions: [
+                    { on: 'signal:death', to: 'dead' },
+                    { on: 'signal:hurt', to: 'hurt' },
+                ],
+            },
         },
     };
     const update = ({ entity, game, fsm }, dt) => {
@@ -54,6 +78,44 @@ export function createGridPlayerRole(Motor, description) {
             default: { onUpdate: update },
             idle: { onUpdate: update },
             walk: { onUpdate: update },
+            attack: {
+                onEnter({ entity }) {
+                    const motor = entity.get(Motor);
+                    if (!motor)
+                        return;
+                    motor.halt();
+                    entity.get(MeleeAttack)?.strike(motor.facing);
+                },
+                // Explicit no-op: without it the state would inherit the default
+                // body update and keep walking through the swing.
+                onUpdate() { },
+            },
+            hurt: {
+                onEnter({ entity, game }) {
+                    const motor = entity.get(Motor);
+                    if (!motor)
+                        return;
+                    const source = entity.get(Health)?.lastDamageSource;
+                    const dx = source ? entity.position.x - source.position.x : 0;
+                    const dy = source ? entity.position.y - source.position.y : 0;
+                    const distance = Math.hypot(dx, dy);
+                    let away = distance > 0 ? { x: dx / distance, y: dy / distance } : undefined;
+                    if (!away) {
+                        // No source (or one standing on top of us): recoil from the facing.
+                        const forward = logicalDirection(motor.facing, game.projection);
+                        away = forward ? { x: -forward.x, y: -forward.y } : { x: 0, y: 0 };
+                    }
+                    motor.vx = away.x * motor.knockbackSpeed;
+                    motor.vy = away.y * motor.knockbackSpeed;
+                },
+                // The shove resolves against Solids like any movement; no input.
+                onUpdate({ entity }, dt) {
+                    entity.get(Motor)?.step(dt);
+                },
+                onExit({ entity }) {
+                    entity.get(Motor)?.halt();
+                },
+            },
             // Coming back is what leaving death means, so it hangs off onExit: any
             // other way out of this state (a project's own edge) revives too.
             dead: {

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

@@ -41,19 +41,40 @@ export declare class Health extends Component {
             max: number;
             step: number;
         };
+        stat: {
+            label: string;
+            ref: 'stat';
+        };
     };
     static transient: string[];
     max: number;
     /** Seconds of immunity granted by taking a hit. 0 disables i-frames. */
     invulnerability: number;
+    /**
+     * Stat that mirrors `current` (a HUD binds to it with `{{stat}}`). Empty
+     * publishes nothing: the stat is the project's to declare.
+     */
+    stat: string;
     /** Health left; 0 is dead. Filled in from max on ready. */
     current: number;
+    /** Whoever dealt the last accepted hit, for the state that reacts to it. */
+    lastDamageSource: Entity | undefined;
     /** Seconds left in the invulnerability window. */
     private invulnerable;
+    /** Seconds into the current blink, for the 10 Hz toggle. */
+    private blinkClock;
+    /** Whether the node is being flashed: exactly while a window is open. */
+    get blinking(): boolean;
     /** Whether the signalled death must be checked on this component's next update. */
     private deathPending;
     /** States the death signal was supposed to reach. */
     private 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(): Record<string, unknown>;
     onReady(): void;
     onUpdate(dt: number): void;
     /**
@@ -73,6 +94,14 @@ export declare class Health extends Component {
     damage(amount: number, source?: Entity): void;
     /** Gives health back, capped at max. heal(Infinity) is a full restore. */
     heal(amount: number): void;
+    /** Mirrors current into the named stat, when one is named. */
+    private publish;
+    /**
+     * 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.
+     */
+    private blink;
     /**
      * Announces the death, then lets the role decide — but only if it says it
      * can: a graph with no death edge would swallow the signal silently, so