@waica/cli 0.6.1 → 0.7.0

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

@@ -21,6 +21,8 @@ export interface SceneCameraJson {
     deadzoneWidth?: number;
     deadzoneHeight?: number;
     lookahead?: number;
+    /** Vertical lookahead in world units; 0 (the default) disables it. */
+    lookaheadY?: number;
     smoothing?: number;
     limits?: CameraLimitsJson;
 }
@@ -31,6 +33,7 @@ export interface ResolvedSceneCamera {
     deadzoneWidth: number;
     deadzoneHeight: number;
     lookahead: number;
+    lookaheadY: number;
     smoothing: number;
     limits: CameraLimitsJson | null;
 }
@@ -41,10 +44,24 @@ export declare const CAMERA_DEFAULTS: {
     readonly deadzoneWidth: 2;
     readonly deadzoneHeight: 2.5;
     readonly lookahead: 1.5;
+    readonly lookaheadY: 0;
     readonly smoothing: 6;
 };
 /** Fills a scene's camera block with the engine defaults. */
 export declare function resolveSceneCamera(json?: SceneCameraJson): ResolvedSceneCamera;
+/** Two-axis velocity a followed entity reports for camera lookahead. */
+export interface CameraVelocity {
+    vx: number;
+    vy: number;
+}
+/**
+ * The explicit seam a component opts into so the scene camera can read the
+ * followed entity's velocity — the engine never guesses from field names.
+ */
+export interface CameraVelocityProvider {
+    getCameraVelocity(): CameraVelocity;
+}
+export declare function isCameraVelocityProvider(value: unknown): value is CameraVelocityProvider;
 export interface CameraStepInput {
     /** Current camera center. */
     x: number;
@@ -59,6 +76,8 @@ export interface CameraStepInput {
     } | null;
     /** Followed entity's horizontal velocity, for lookahead. */
     vx: number;
+    /** Followed entity's vertical velocity, for lookaheadY; omitted = 0. */
+    vy?: number;
     dt: number;
 }
 /**

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

@@ -6,6 +6,7 @@ export const CAMERA_DEFAULTS = {
     deadzoneWidth: 2,
     deadzoneHeight: 2.5,
     lookahead: 1.5,
+    lookaheadY: 0,
     smoothing: 6,
 };
 /** Fills a scene's camera block with the engine defaults. */
@@ -17,6 +18,7 @@ export function resolveSceneCamera(json) {
         deadzoneWidth: json?.deadzoneWidth ?? CAMERA_DEFAULTS.deadzoneWidth,
         deadzoneHeight: json?.deadzoneHeight ?? CAMERA_DEFAULTS.deadzoneHeight,
         lookahead: json?.lookahead ?? CAMERA_DEFAULTS.lookahead,
+        lookaheadY: json?.lookaheadY ?? CAMERA_DEFAULTS.lookaheadY,
         smoothing: json?.smoothing ?? CAMERA_DEFAULTS.smoothing,
         limits: json?.limits ?? null,
     };
@@ -28,6 +30,11 @@ function clampAxis(center, halfView, min, max) {
         return (min + max) / 2;
     return Math.min(Math.max(center, min + halfView), max - halfView);
 }
+export function isCameraVelocityProvider(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.getCameraVelocity === 'function');
+}
 /**
  * One simulation step of the camera: deadzone-follow with lookahead and
  * exponential smoothing, then limits. Pure — returns the next center.
@@ -48,6 +55,9 @@ export function stepSceneCamera(cam, input) {
             wantY = input.target.y - Math.sign(dy) * halfDzH;
         if (Math.abs(input.vx) > 1)
             wantX += Math.sign(input.vx) * cam.lookahead;
+        const vy = input.vy ?? 0;
+        if (Math.abs(vy) > 1)
+            wantY += Math.sign(vy) * cam.lookaheadY;
         x = THREE.MathUtils.damp(x, wantX, cam.smoothing, input.dt);
         y = THREE.MathUtils.damp(y, wantY, cam.smoothing, input.dt);
     }

package/dist/mcp/node_modules/@waica/engine/dist/components/animated-sprite.d.ts

@@ -1,6 +1,7 @@
 import { Component } from '../component.js';
 import { type ClipDef } from '../animation/clip-player.js';
 import { type SheetCell, type SheetDef } from '../animation/sheet.js';
+import type { YSortParticipant } from '../render-sort.js';
 /**
  * Sprite animated from one or more spritesheets. The main sheet is the
  * top-level texture/cols/rows (or explicit cells); extraSheets append after
@@ -10,7 +11,7 @@ import { type SheetCell, type SheetDef } from '../animation/sheet.js';
  * so the quad rescales per frame, anchored bottom-center — width/height size
  * the sheet's largest frame and smaller ones keep their feet planted.
  */
-export declare class AnimatedSprite extends Component {
+export declare class AnimatedSprite extends Component implements YSortParticipant {
     static componentName: string;
     static updateAfter: readonly string[];
     static params: {
@@ -59,6 +60,12 @@ export declare class AnimatedSprite extends Component {
     private _layer;
     get layer(): number;
     set layer(value: number);
+    /** Y-sort pass hook: overrides the layer-derived z for this frame. */
+    setSortZ(z: number): void;
+    /** Mirrored state, readable by Runtime Snapshots; write via setFlipX. */
+    flipX: boolean;
+    /** Mirrors the quad horizontally — directional clips reuse east art for west. */
+    setFlipX(value: boolean): void;
     clips: Record<string, ClipDef>;
     initialClip?: string;
     /** Clip currently playing. */

package/dist/mcp/node_modules/@waica/engine/dist/components/animated-sprite.js

@@ -22,6 +22,7 @@ export class AnimatedSprite extends Component {
     };
     static transient = [
         'current',
+        'flipX',
         'player',
         'sheets',
         'texs',
@@ -93,6 +94,20 @@ export class AnimatedSprite extends Component {
         if (this.mesh)
             this.mesh.position.z = value * 0.01;
     }
+    /** Y-sort pass hook: overrides the layer-derived z for this frame. */
+    setSortZ(z) {
+        if (this.mesh)
+            this.mesh.position.z = z;
+    }
+    /** Mirrored state, readable by Runtime Snapshots; write via setFlipX. */
+    flipX = false;
+    /** Mirrors the quad horizontally — directional clips reuse east art for west. */
+    setFlipX(value) {
+        if (this.flipX === value)
+            return;
+        this.flipX = value;
+        this.syncQuad();
+    }
     clips = {};
     initialClip;
     /** Clip currently playing. */
@@ -171,9 +186,11 @@ export class AnimatedSprite extends Component {
     syncQuad() {
         if (!this.mesh)
             return;
-        this.mesh.scale.set(this._width * this.frameScaleX, this._height * this.frameScaleY, 1);
+        this.mesh.scale.set(this._width * this.frameScaleX * (this.flipX ? -1 : 1), this._height * this.frameScaleY, 1);
         // Bottom-center anchor: a shrunk frame keeps its feet on the quad's floor.
-        this.mesh.position.x = this._offsetX;
+        // The offset mirrors along with the art, or a flipped sprite with a
+        // nonzero offsetX would shift to the wrong side.
+        this.mesh.position.x = this.flipX ? -this._offsetX : this._offsetX;
         this.mesh.position.y = this._offsetY - (this._height * (1 - this.frameScaleY)) / 2;
     }
     applyFrame() {

package/dist/mcp/node_modules/@waica/engine/dist/components/sprite.d.ts

@@ -1,10 +1,11 @@
 import { Component } from '../component.js';
+import type { YSortParticipant } from '../render-sort.js';
 export type SpriteShape = 'rectangle' | 'circle';
 /**
  * Textured or flat-color quad. In the unified pipeline, a 2D sprite is a
  * plane in front of the orthographic camera (see DESIGN.md §6, decision 2).
  */
-export declare class Sprite extends Component {
+export declare class Sprite extends Component implements YSortParticipant {
     static componentName: string;
     static params: {
         offsetX: {
@@ -42,6 +43,8 @@ export declare class Sprite extends Component {
     private _layer;
     get layer(): number;
     set layer(value: number);
+    /** Y-sort pass hook: overrides the layer-derived z for this frame. */
+    setSortZ(z: number): void;
     private _shape;
     get shape(): SpriteShape;
     set shape(value: SpriteShape);

package/dist/mcp/node_modules/@waica/engine/dist/components/sprite.js

@@ -71,6 +71,11 @@ export class Sprite extends Component {
         if (this.mesh)
             this.mesh.position.z = value * 0.01;
     }
+    /** Y-sort pass hook: overrides the layer-derived z for this frame. */
+    setSortZ(z) {
+        if (this.mesh)
+            this.mesh.position.z = z;
+    }
     _shape = 'rectangle';
     get shape() {
         return this._shape;

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

@@ -4,7 +4,7 @@ import type { Component } from './component.js';
 import { Entity } from './entity.js';
 import { Emitter } from './events.js';
 import { Input, type InputBindings } from './input.js';
-import { type SceneRegistry } from './scene.js';
+import { type SceneRegistry, type SceneRenderJson } from './scene.js';
 import { Stats, type StatValue } from './stats.js';
 import { GameUi } from './ui.js';
 /** Fixed game resolution: the view keeps this aspect, letterboxed. */
@@ -61,6 +61,7 @@ export declare class Game {
     private readonly resolution;
     private viewHeight;
     private sceneCamera;
+    private renderSort;
     private lastTime;
     private runtimeBridge;
     constructor(options: GameOptions);
@@ -76,6 +77,11 @@ export declare class Game {
     applyParamOverrides(entity: Entity, component: Component): void;
     /** Registers a function that runs once per frame. Returns the unsubscribe. */
     onUpdate(fn: UpdateFn): () => void;
+    /**
+     * Adopts a scene's render block. Called by loadScene; without a block the
+     * draw order stays layer-banded with spawn-order ties.
+     */
+    setSceneRender(json?: SceneRenderJson): void;
     /**
      * Adopts a scene's camera block: jumps to its framing and, while
      * simulating, follows/clamps per its settings. Called by loadScene.
@@ -94,6 +100,8 @@ export declare class Game {
     private tick;
     private runFrame;
     private unregisterRuntimeBridge;
+    /** Under y-sort, re-derives every participant's z from layer band + entity Y. */
+    private applyYSort;
     private renderSurface;
     private componentUpdateSchedule;
     private updateSceneCamera;

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

@@ -1,6 +1,6 @@
 import * as THREE from 'three';
 import { collisionOverlap } from './collision-shape.js';
-import { resolveSceneCamera, stepSceneCamera } from './camera.js';
+import { isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera, } from './camera.js';
 import { resolveComponentUpdateSchedule } from './component-update-schedule.js';
 import { Hitbox } from './components/hitbox.js';
 import { Entity } from './entity.js';
@@ -8,6 +8,7 @@ import { Emitter } from './events.js';
 import { Input } from './input.js';
 import { activeRuntimeBridgeHook, EngineRuntimeBridge, } from './runtime-bridge.js';
 import { RuntimeInspector } from './runtime-inspection.js';
+import { isYSortParticipant, ySortZ } from './render-sort.js';
 import { registryEntry, spawnFromJson } from './scene.js';
 import { Stats } from './stats.js';
 import { GameUi } from './ui.js';
@@ -40,6 +41,7 @@ export class Game {
     resolution;
     viewHeight;
     sceneCamera = null;
+    renderSort = null;
     lastTime = 0;
     runtimeBridge = null;
     constructor(options) {
@@ -107,6 +109,13 @@ export class Game {
         this.updateFns.add(fn);
         return () => this.updateFns.delete(fn);
     }
+    /**
+     * Adopts a scene's render block. Called by loadScene; without a block the
+     * draw order stays layer-banded with spawn-order ties.
+     */
+    setSceneRender(json) {
+        this.renderSort = json?.sort === 'y' ? 'y' : null;
+    }
     /**
      * Adopts a scene's camera block: jumps to its framing and, while
      * simulating, follows/clamps per its settings. Called by loadScene.
@@ -216,7 +225,25 @@ export class Game {
         this.runtimeBridge?.unregister();
         this.runtimeBridge = null;
     };
+    /** Under y-sort, re-derives every participant's z from layer band + entity Y. */
+    applyYSort() {
+        const participants = [];
+        const entries = [];
+        for (const entity of this.entities) {
+            for (const component of entity.components) {
+                if (isYSortParticipant(component)) {
+                    participants.push(component);
+                    entries.push({ layer: component.layer, y: entity.position.y });
+                }
+            }
+        }
+        const z = ySortZ(entries);
+        for (const [index, participant] of participants.entries())
+            participant.setSortZ(z[index]);
+    }
     renderSurface() {
+        if (this.renderSort === 'y')
+            this.applyYSort();
         this.ui.setActive(this.simulate);
         if (this.resolution) {
             // Letterbox bars: clear the whole canvas, then render inside the scissor.
@@ -262,14 +289,16 @@ export class Game {
         if (!cam)
             return;
         const followed = cam.follow ? this.find(cam.follow) : undefined;
-        const mover = followed?.components.find((c) => typeof c.vx === 'number');
+        const provider = followed?.components.find((c) => isCameraVelocityProvider(c));
+        const velocity = provider?.getCameraVelocity();
         const next = stepSceneCamera(cam, {
             x: this.camera.position.x,
             y: this.camera.position.y,
             halfW: (this.camera.right - this.camera.left) / 2,
             halfH: this.viewHeight / 2,
             target: followed ? { x: followed.position.x, y: followed.position.y } : null,
-            vx: mover?.vx ?? 0,
+            vx: velocity?.vx ?? 0,
+            vy: velocity?.vy ?? 0,
             dt,
         });
         this.camera.position.x = next.x;

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

@@ -1,7 +1,11 @@
 export { Game } from './game.js';
 export type { GameOptions, GameResolution, SpawnPrefabOptions, UpdateFn, ParamOverrides, } from './game.js';
-export { CAMERA_DEFAULTS, resolveSceneCamera, stepSceneCamera } from './camera.js';
-export type { SceneCameraJson, CameraLimitsJson, ResolvedSceneCamera } from './camera.js';
+export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
+export type { AnimationFacingProvider, DirectionalAnimation, DirectionalFallback, ResolvedDirectionalClip, } from './animation/directional.js';
+export { isYSortParticipant, ySortZ } from './render-sort.js';
+export type { YSortEntry, YSortParticipant } from './render-sort.js';
+export { CAMERA_DEFAULTS, isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera } from './camera.js';
+export type { SceneCameraJson, CameraLimitsJson, CameraVelocity, CameraVelocityProvider, ResolvedSceneCamera, } from './camera.js';
 export { Entity } from './entity.js';
 export { Component } from './component.js';
 export { authoringDefaults } from './authoring-defaults.js';
@@ -32,7 +36,7 @@ export { COLLISION_SHAPES, DEFAULT_COLLISION_POLYGON, collisionBounds, collision
 export type { CollisionBody, CollisionBounds, CollisionPoint, CollisionShape, } from './collision-shape.js';
 export { Emitter } from './events.js';
 export { loadScene, spawnFromJson, resolveEntityComponents, resolveProps } from './scene.js';
-export type { SceneJson, SceneEntityJson, SceneComponentJson, SceneRegistry, PrefabJson } from './scene.js';
+export type { SceneJson, SceneEntityJson, SceneComponentJson, SceneRegistry, SceneRenderJson, PrefabJson, } from './scene.js';
 export { ClipPlayer } from './animation/clip-player.js';
 export type { ClipDef } from './animation/clip-player.js';
 export { sheetCell, sheetFrameCount, locateFrame } from './animation/sheet.js';

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

@@ -1,5 +1,7 @@
 export { Game } from './game.js';
-export { CAMERA_DEFAULTS, resolveSceneCamera, stepSceneCamera } from './camera.js';
+export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
+export { isYSortParticipant, ySortZ } from './render-sort.js';
+export { CAMERA_DEFAULTS, isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera } from './camera.js';
 export { Entity } from './entity.js';
 export { Component } from './component.js';
 export { authoringDefaults } from './authoring-defaults.js';

package/dist/mcp/node_modules/@waica/engine/dist/render-sort.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Y-sort draw ordering: an opt-in render mode (scene JSON `render.sort: 'y'`)
+ * for top-down scenes where "lower on screen" means "closer to the camera".
+ */
+export interface YSortEntry {
+    /** The sprite's layer — the primary draw-order band, exactly as without y-sort. */
+    layer: number;
+    /** The owning entity's world Y — the sort key. Sprite offsets don't shift it. */
+    y: number;
+}
+/**
+ * The explicit seam a component opts into to participate in y-sort: it
+ * exposes its draw-order layer and accepts the per-frame z the pass derives.
+ * Both stock sprite classes implement it; a custom renderable can too.
+ */
+export interface YSortParticipant {
+    readonly layer: number;
+    /** Y-sort pass hook: overrides the layer-derived z for this frame. */
+    setSortZ(z: number): void;
+}
+export declare function isYSortParticipant(value: unknown): value is YSortParticipant;
+/**
+ * Z per entry under y-sort. Each layer keeps its 0.01 band; within a band,
+ * lower Y gets a higher z (renders in front), and exact Y ties keep input
+ * order. Offsets stay strictly inside (layer, layer + 1) × 0.01 for integer
+ * layers — but a fractional layer (e.g. 0.5) can sit closer than that to the
+ * next one present, so each band is capped at the gap to the next distinct
+ * layer above it, never wider than 0.01. Integer layers are always >= 1
+ * apart, so their band is exactly the old fixed 0.01.
+ */
+export declare function ySortZ(entries: readonly YSortEntry[]): number[];

package/dist/mcp/node_modules/@waica/engine/dist/render-sort.js

@@ -0,0 +1,39 @@
+export function isYSortParticipant(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.layer === 'number' &&
+        typeof value.setSortZ === 'function');
+}
+/**
+ * Z per entry under y-sort. Each layer keeps its 0.01 band; within a band,
+ * lower Y gets a higher z (renders in front), and exact Y ties keep input
+ * order. Offsets stay strictly inside (layer, layer + 1) × 0.01 for integer
+ * layers — but a fractional layer (e.g. 0.5) can sit closer than that to the
+ * next one present, so each band is capped at the gap to the next distinct
+ * layer above it, never wider than 0.01. Integer layers are always >= 1
+ * apart, so their band is exactly the old fixed 0.01.
+ */
+export function ySortZ(entries) {
+    const byLayer = new Map();
+    for (const [index, entry] of entries.entries()) {
+        const group = byLayer.get(entry.layer);
+        if (group)
+            group.push(index);
+        else
+            byLayer.set(entry.layer, [index]);
+    }
+    const layers = [...byLayer.keys()].sort((a, b) => a - b);
+    const z = new Array(entries.length);
+    for (const [i, layer] of layers.entries()) {
+        const indices = byLayer.get(layer);
+        const next = layers[i + 1];
+        const width = next === undefined ? 0.01 : Math.min(0.01, (next - layer) * 0.01);
+        // Stable sort: back-to-front is descending Y, ties keep input order.
+        const ordered = [...indices].sort((a, b) => entries[b].y - entries[a].y);
+        const step = width / (ordered.length + 1);
+        for (const [rank, index] of ordered.entries()) {
+            z[index] = layer * 0.01 + (rank + 1) * step;
+        }
+    }
+    return z;
+}

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

@@ -28,10 +28,20 @@ export interface PrefabJson {
     type: 'character' | 'object' | 'tile';
     components: SceneComponentJson[];
 }
+/** Scene-wide render options (v3). */
+export interface SceneRenderJson {
+    /**
+     * 'y' orders same-layer sprites by their entity's world Y — lower Y renders
+     * in front (top-down depth). Absent: spawn order breaks same-layer ties.
+     */
+    sort?: 'y';
+}
 export interface SceneJson {
     waicaScene: 1 | 2 | 3;
     /** The scene's built-in camera (v3); absent = the host keeps control. */
     camera?: SceneCameraJson;
+    /** Draw-order policy (v3); absent = layer bands with spawn-order ties. */
+    render?: SceneRenderJson;
     entities: SceneEntityJson[];
     /** UI pieces (src/ui/*.html) mounted visible when the scene loads. */
     ui?: string[];

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

@@ -82,6 +82,7 @@ export function spawnFromJson(game, json, registry) {
 /** Loads a full scene into the game. */
 export function loadScene(game, scene, registry) {
     game.registry = registry;
+    game.setSceneRender(scene.render);
     for (const entityJson of scene.entities)
         spawnFromJson(game, entityJson, registry);
     // After the spawns: with a follow target, the camera starts centered on it.

package/dist/mcp/node_modules/@waica/engine/dist/state/hooks.d.ts

@@ -63,7 +63,7 @@ export interface ArchetypeBundle {
     /** Extra named logic sets that are not themselves roles. */
     logicSets?: Readonly<Record<string, StateLogic>>;
 }
-/** Clears role definitions and every named logic set. */
+/** Clears role definitions, every named logic set and the directional contract. */
 export declare function resetRegistries(): void;
 /**
  * Replaces the active registry contents with one archetype's complete bundle.

package/dist/mcp/node_modules/@waica/engine/dist/state/hooks.js

@@ -1,3 +1,4 @@
+import { installDirectionalAnimation } from '../animation/directional.js';
 const sets = new Map();
 /**
  * Registers state code under a logic-set name. A role's name is also its
@@ -8,10 +9,11 @@ export function defineStates(name, states) {
     sets.set(name, { ...sets.get(name), ...states });
 }
 const roles = new Map();
-/** Clears role definitions and every named logic set. */
+/** Clears role definitions, every named logic set and the directional contract. */
 export function resetRegistries() {
     roles.clear();
     sets.clear();
+    installDirectionalAnimation(null);
 }
 /**
  * Replaces the active registry contents with one archetype's complete bundle.

package/dist/mcp/node_modules/@waica/engine/dist/state/state-machine.d.ts

@@ -66,6 +66,8 @@ export declare class StateMachine extends Component {
     private readonly instanceHooks;
     private readonly signals;
     private readonly warnedClips;
+    /** Facing last used to resolve a directional clip — detects a turn mid-state. */
+    private lastFacing;
     onReady(): void;
     /** Adds instance-level hooks on top of the logic set — the escape hatch. */
     on(state: string, hooks: StateHooks): void;
@@ -81,4 +83,20 @@ export declare class StateMachine extends Component {
     private runCollision;
     private enter;
     private playClip;
+    /**
+     * Directional resolution: with an installed contract AND a sibling that
+     * reports facing, plays state × facing (mirroring included). Returns false
+     * to keep the name-based path — no contract, no facing, no playable clip.
+     */
+    private playDirectionalClip;
+    private facingProvider;
+    /**
+     * playDirectionalClip only runs at enter() time (via playClip), so a
+     * facing change that doesn't cross a state boundary — turning while
+     * still walking, say — never re-resolves the clip on its own. Catch that
+     * here every frame: same state, new facing, re-run the resolution.
+     * AnimatedSprite.play() no-ops on an unchanged clip name, so this is
+     * cheap when facing hasn't moved the resolved clip.
+     */
+    private reresolveOnFacingChange;
 }

package/dist/mcp/node_modules/@waica/engine/dist/state/state-machine.js

@@ -1,3 +1,4 @@
+import { installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from '../animation/directional.js';
 import { Component } from '../component.js';
 import { AnimatedSprite } from '../components/animated-sprite.js';
 import { closestLogicSet, logicSet, registeredLogicSets, } from './hooks.js';
@@ -47,7 +48,14 @@ export class StateMachine extends Component {
     static params = {
         role: { label: 'Role' },
     };
-    static transient = ['current', 'elapsed', 'instanceHooks', 'signals', 'warnedClips'];
+    static transient = [
+        'current',
+        'elapsed',
+        'instanceHooks',
+        'signals',
+        'warnedClips',
+        'lastFacing',
+    ];
     /** The character's role — names the logic set providing its state code. */
     role = '';
     /** Starting state; defaults to the first declared state. */
@@ -60,6 +68,8 @@ export class StateMachine extends Component {
     instanceHooks = new Map();
     signals = new Set();
     warnedClips = new Set();
+    /** Facing last used to resolve a directional clip — detects a turn mid-state. */
+    lastFacing;
     onReady() {
         if (this.role && !logicSet(this.role)) {
             const sets = registeredLogicSets();
@@ -111,6 +121,7 @@ export class StateMachine extends Component {
             this.enter(edge.to);
         }
         this.signals.clear();
+        this.reresolveOnFacingChange();
     }
     onCollide(other) {
         // The state that was active when the contact happened owns it: a
@@ -167,6 +178,8 @@ export class StateMachine extends Component {
         if (!sprite)
             return;
         const clip = this.states[state]?.clip ?? state;
+        if (this.playDirectionalClip(sprite, clip))
+            return;
         if (sprite.clips[clip]) {
             sprite.play(clip);
         }
@@ -176,4 +189,47 @@ export class StateMachine extends Component {
                 `keeping "${sprite.current ?? 'none'}"`);
         }
     }
+    /**
+     * Directional resolution: with an installed contract AND a sibling that
+     * reports facing, plays state × facing (mirroring included). Returns false
+     * to keep the name-based path — no contract, no facing, no playable clip.
+     */
+    playDirectionalClip(sprite, clip) {
+        const animation = installedDirectionalAnimation();
+        if (!animation)
+            return false;
+        const provider = this.facingProvider();
+        if (!provider)
+            return false;
+        const facing = provider.getAnimationFacing();
+        this.lastFacing = facing;
+        const resolved = resolveDirectionalClip(animation, Object.keys(sprite.clips), clip, facing);
+        if (!resolved.clip || !sprite.clips[resolved.clip])
+            return false;
+        sprite.setFlipX(resolved.flip);
+        sprite.play(resolved.clip);
+        return true;
+    }
+    facingProvider() {
+        return this.entity.components.find((c) => isAnimationFacingProvider(c));
+    }
+    /**
+     * playDirectionalClip only runs at enter() time (via playClip), so a
+     * facing change that doesn't cross a state boundary — turning while
+     * still walking, say — never re-resolves the clip on its own. Catch that
+     * here every frame: same state, new facing, re-run the resolution.
+     * AnimatedSprite.play() no-ops on an unchanged clip name, so this is
+     * cheap when facing hasn't moved the resolved clip.
+     */
+    reresolveOnFacingChange() {
+        if (!this.current || !installedDirectionalAnimation())
+            return;
+        const sprite = this.entity.get(AnimatedSprite);
+        if (!sprite)
+            return;
+        const provider = this.facingProvider();
+        if (!provider || provider.getAnimationFacing() === this.lastFacing)
+            return;
+        this.playDirectionalClip(sprite, this.states[this.current]?.clip ?? this.current);
+    }
 }

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

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

package/dist/mcp/package-resolver.js

@@ -2,6 +2,7 @@ import { access, readFile, realpath } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { KNOWN_ARCHETYPES } from './known-archetypes.js';
 import { workspacePackageRoot } from './workspace-runtime.js';
 /** A declared package that is absent from both the project and MCP bundle. */
 export class PackageUnavailableError extends Error {
@@ -15,8 +16,7 @@ export class PackageUnavailableError extends Error {
 const BUNDLED_SPECIFIERS = new Set([
     '@waica/engine',
     '@waica/behaviors',
-    '@waica/archetype-platformer',
-    '@waica/archetype-platformer/manifest',
+    ...KNOWN_ARCHETYPES.flatMap(({ packageName }) => [packageName, `${packageName}/manifest`]),
 ]);
 const requireBundled = createRequire(import.meta.url);
 /** Node resolution anchored at a game project rather than the MCP host process. */
@@ -26,8 +26,10 @@ export function projectAnchoredRequire(projectPath) {
 const BUILT_ENTRY_BY_SPECIFIER = {
     '@waica/engine': 'dist/index.js',
     '@waica/behaviors': 'dist/index.js',
-    '@waica/archetype-platformer': 'dist/index.js',
-    '@waica/archetype-platformer/manifest': 'dist/manifest.js',
+    ...Object.fromEntries(KNOWN_ARCHETYPES.flatMap(({ packageName }) => [
+        [packageName, 'dist/index.js'],
+        [`${packageName}/manifest`, 'dist/manifest.js'],
+    ])),
 };
 function specifierFor(packageName, subpath) {
     if (!subpath || subpath === '.')
@@ -127,6 +129,10 @@ async function loadBundledModule(specifier, packageRoot) {
             return import('@waica/archetype-platformer');
         case '@waica/archetype-platformer/manifest':
             return import('@waica/archetype-platformer/manifest');
+        case '@waica/archetype-topdown':
+            return import('@waica/archetype-topdown');
+        case '@waica/archetype-topdown/manifest':
+            return import('@waica/archetype-topdown/manifest');
         default:
             throw new PackageUnavailableError(specifier);
     }