@waica/archetype-isometric 0.8.0 → 0.9.0

package/assets/ATTRIBUTION.md

@@ -15,30 +15,51 @@ offline from originals retained outside the repository at
   `Human-Worker-Red.png`, and `Orc-Grunt.png` (each 768×256, 24×8 cells
   of 32×32).
 
-Each output character sheet is 4 columns × 5 rows of native 32×32 cells with
-one transparent pixel between cells. Output columns are source columns 0, 1,
-2 and 3: idle followed by the three walk poses. Output rows and exact source
-cell rectangles are:
+Each output character sheet is 11 columns × 5 rows of native 32×32 cells with
+one transparent pixel between cells (362×164). Output rows are the five
+east-facing rows of the pack; the source row order, verified on the sheets
+themselves (2026-08-29), is `0 s · 1 se · 2 e · 3 ne · 4 n · 5 nw · 6 w · 7 sw`.
+An earlier composition took rows 5/6/7 as `ne/e/se`, which face west, and
+shipped the hero walking the wrong way; the row → facing table below is the
+corrected one.
 
-| Output facing | Source row | Cell rectangles `(left, top, right, bottom)` |
+| Output facing | Source row | Cell rectangle of output column `c` |
 |---|---:|---|
-| `n` | 4 | `(0,128,32,160)`, `(32,128,64,160)`, `(64,128,96,160)`, `(96,128,128,160)` |
-| `ne` | 5 | `(0,160,32,192)`, `(32,160,64,192)`, `(64,160,96,192)`, `(96,160,128,192)` |
-| `e` | 6 | `(0,192,32,224)`, `(32,192,64,224)`, `(64,192,96,224)`, `(96,192,128,224)` |
-| `se` | 7 | `(0,224,32,256)`, `(32,224,64,256)`, `(64,224,96,256)`, `(96,224,128,256)` |
-| `s` | 0 | `(0,0,32,32)`, `(32,0,64,32)`, `(64,0,96,32)`, `(96,0,128,32)` |
-
-The offline composition compared every one of those four poses against the
-source mirror pair. Source row 2 (`w`) is the pixel-exact horizontal mirror of
-row 6 (`e`), row 3 (`nw`) mirrors row 5 (`ne`), and row 1 (`sw`) mirrors row 7
-(`se`) in all three character files. The west rows are therefore intentionally
-absent from the committed sheets and resolve through runtime mirroring.
+| `n` | 4 | `(32·src[c], 128, 32·src[c]+32, 160)` |
+| `ne` | 3 | `(32·src[c], 96, 32·src[c]+32, 128)` |
+| `e` | 2 | `(32·src[c], 64, 32·src[c]+32, 96)` |
+| `se` | 1 | `(32·src[c], 32, 32·src[c]+32, 64)` |
+| `s` | 0 | `(32·src[c], 0, 32·src[c]+32, 32)` |
+
+Output columns are `0 idle · 1–3 walk · 4–6 attack · 7–8 hurt · 9–10 death`.
+`src[c]` is the source column each output column is cut from; the warrior's
+sword/hurt/death poses sit one column earlier than the other two sheets':
+
+| Output file | Character | `src[0..10]` |
+|---|---|---|
+| `waica-iso-hero.png` | `Warrior-Blue.png` | 0, 1, 2, 3, 5, 6, 7, 19, 20, 22, 23 |
+| `waica-iso-villager.png` | `Human-Worker-Red.png` | 0, 1, 2, 3, 6, 7, 8, 20, 21, 22, 23 |
+| `waica-iso-orc.png` | `Orc-Grunt.png` | 0, 1, 2, 3, 6, 7, 8, 20, 21, 22, 23 |
+
+The villager sheet carries the sword columns like the others but declares no
+`attack-*` clips.
+
+### Mirror check
+
+The west rows are absent from the committed sheets and resolve through
+runtime mirroring (`flipX`). The composition compared every used cell of
+source rows 1/2/3 against the horizontal mirror of rows 7/6/5. They are
+**not pixel-exact**: idle/walk poses differ by 1–5 pixels (a hand or a
+strap), and the sword poses by 30–60 pixels because the sword stays in the
+same hand on both sides. Mirroring the east art is therefore a stylistic
+approximation, not a lossless substitute — acceptable for the demo, and the
+reason the human protocol checks the mirrored directions by eye.
 
 | Output file | Character | Output size |
 |---|---|---:|
-| `waica-iso-hero.png` | `Warrior-Blue.png` | 131×164 |
-| `waica-iso-villager.png` | `Human-Worker-Red.png` | 131×164 |
-| `waica-iso-orc.png` | `Orc-Grunt.png` | 131×164 |
+| `waica-iso-hero.png` | `Warrior-Blue.png` | 362×164 |
+| `waica-iso-villager.png` | `Human-Worker-Red.png` | 362×164 |
+| `waica-iso-orc.png` | `Orc-Grunt.png` | 362×164 |
 
 ## hawkbirdtree isometric tileset
 

package/dist/animation.d.ts

@@ -1,3 +1,7 @@
 import type { DirectionalAnimation } from '@waica/engine';
-/** Five authored facings plus three horizontal mirror fallbacks. */
+/**
+ * Five authored facings plus three horizontal mirror fallbacks; every pose
+ * a character can be asked for (walk, attack, hurt, death) degrades to its
+ * idle, still facing the right way.
+ */
 export declare const ISOMETRIC_ANIMATION: DirectionalAnimation;

package/dist/animation.js

@@ -1,4 +1,8 @@
-/** Five authored facings plus three horizontal mirror fallbacks. */
+/**
+ * Five authored facings plus three horizontal mirror fallbacks; every pose
+ * a character can be asked for (walk, attack, hurt, death) degrades to its
+ * idle, still facing the right way.
+ */
 export const ISOMETRIC_ANIMATION = {
     directions: ['n', 'ne', 'e', 'se', 's', 'sw', 'w', 'nw'],
     fallbacks: {
@@ -6,5 +10,8 @@ export const ISOMETRIC_ANIMATION = {
         nw: { dir: 'ne', flip: true },
         sw: { dir: 'se', flip: true },
     },
-    contract: { required: ['idle'], fallbacks: { walk: 'idle' } },
+    contract: {
+        required: ['idle'],
+        fallbacks: { walk: 'idle', attack: 'idle', hurt: 'idle', death: 'idle' },
+    },
 };

package/dist/controls.js

@@ -4,6 +4,7 @@ export const ISOMETRIC_BINDINGS = {
     left: ['ArrowLeft', 'KeyA'],
     right: ['ArrowRight', 'KeyD'],
     interact: ['KeyE', 'Space'],
+    attack: ['KeyX', 'KeyJ'],
 };
 export const ISOMETRIC_ACTION_LABELS = {
     up: 'Move up',
@@ -11,4 +12,5 @@ export const ISOMETRIC_ACTION_LABELS = {
     left: 'Move left',
     right: 'Move right',
     interact: 'Interact',
+    attack: 'Attack',
 };

package/dist/manifest.js

@@ -8,6 +8,7 @@ import { ISOMETRIC_BLANK_SCENE, ISOMETRIC_SCENE } from './scene-default.js';
 export const ISOMETRIC_ENTITY_ICONS = {
     IsoMotor: '🧭',
     Tilemap: '💎',
+    MeleeAttack: '⚔️',
     Interactable: '💬',
     Collectible: '📦',
     Hazard: '👹',

package/dist/prefabs.d.ts

@@ -1,4 +1,9 @@
 import type { PrefabJson } from '@waica/engine';
+type ClipMap = Record<string, {
+    frames: number[];
+    fps: number;
+    loop?: boolean;
+}>;
 export declare const ISOMETRIC_HERO_SPRITE: {
     texture: string;
     cols: number;
@@ -9,10 +14,9 @@ export declare const ISOMETRIC_HERO_SPRITE: {
     width: number;
     height: number;
     anchorY: number;
-    clips: Record<string, {
-        frames: number[];
-        fps: number;
-    }>;
+    offsetY: number;
+    clips: ClipMap;
     initialClip: string;
 };
 export declare const ISOMETRIC_PREFABS: Record<string, PrefabJson>;
+export {};

package/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/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/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/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/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"
   }
 }