@waica/engine 0.6.0 → 0.7.0

package/dist/animation/directional.d.ts

@@ -0,0 +1,48 @@
+import type { AnimationContract } from './contract.js';
+/**
+ * Directional animation contract: the archetype declares which facing
+ * directions exist, how clips are named per direction (`<state>-<dir>`),
+ * and how a missing direction degrades — including mirroring, so west can
+ * reuse east art flipped. Extends the base AnimationContract thesis to
+ * genres where characters face more than one way (top-down, isometric).
+ */
+export interface DirectionalFallback<Dir extends string = string> {
+    dir: Dir;
+    /** Mirror the resolved clip horizontally (e.g. west plays east flipped). */
+    flip?: boolean;
+}
+export interface DirectionalAnimation<Dir extends string = string> {
+    /** Declared facing directions, e.g. ['n', 's', 'e', 'w'] — 8 for isometric. */
+    directions: readonly Dir[];
+    /** Directional degradation: a missing facing resolves to another, optionally mirrored. */
+    fallbacks?: Partial<Record<Dir, DirectionalFallback<Dir>>>;
+    /** State-level degradation chain applied when no directional clip resolves. */
+    contract: AnimationContract;
+}
+export interface ResolvedDirectionalClip {
+    clip: string | undefined;
+    flip: boolean;
+}
+/**
+ * Resolves state × facing to a playable clip: the exact `<state>-<dir>`
+ * clip, else the declared directional fallback chain (accumulating flips).
+ * On a dead end, walks the base AnimationContract's state fallback chain
+ * (cycle-safe) and, for each candidate state in turn, retries the
+ * directional chain against it before trying its bare name. An invalid
+ * facing, or a chain that dead-ends everywhere, resolves to nothing rather
+ * than guessing — the caller's name-based fallback path handles that.
+ */
+export declare function resolveDirectionalClip(animation: DirectionalAnimation, available: Iterable<string>, state: string, facing: string): ResolvedDirectionalClip;
+/** Installs (or clears, with null) the active directional contract. */
+export declare function installDirectionalAnimation(animation: DirectionalAnimation | null): void;
+/** The active directional contract, if an archetype installed one. */
+export declare function installedDirectionalAnimation(): DirectionalAnimation | null;
+/**
+ * The explicit seam a driving component (a motor) opts into so StateMachine
+ * can resolve directional clips: it reports the entity's current facing as
+ * one of the contract's declared directions.
+ */
+export interface AnimationFacingProvider {
+    getAnimationFacing(): string;
+}
+export declare function isAnimationFacingProvider(value: unknown): value is AnimationFacingProvider;

package/dist/animation/directional.js

@@ -0,0 +1,68 @@
+/**
+ * Walks the exact `<state>-<dir>` clip, then the declared directional
+ * fallback chain (accumulating flips), cycle-safe. Undefined at a dead end —
+ * callers decide what to try next, instead of this reaching for anything else.
+ */
+function directionalChain(animation, available, state, facing) {
+    const seen = new Set();
+    let dir = facing;
+    let flip = false;
+    while (dir && !seen.has(dir)) {
+        const candidate = `${state}-${dir}`;
+        if (available.has(candidate))
+            return { clip: candidate, flip };
+        seen.add(dir);
+        const fallback = animation.fallbacks?.[dir];
+        if (!fallback)
+            break;
+        if (fallback.flip)
+            flip = !flip;
+        dir = fallback.dir;
+    }
+    return undefined;
+}
+/**
+ * Resolves state × facing to a playable clip: the exact `<state>-<dir>`
+ * clip, else the declared directional fallback chain (accumulating flips).
+ * On a dead end, walks the base AnimationContract's state fallback chain
+ * (cycle-safe) and, for each candidate state in turn, retries the
+ * directional chain against it before trying its bare name. An invalid
+ * facing, or a chain that dead-ends everywhere, resolves to nothing rather
+ * than guessing — the caller's name-based fallback path handles that.
+ */
+export function resolveDirectionalClip(animation, available, state, facing) {
+    if (!animation.directions.includes(facing))
+        return { clip: undefined, flip: false };
+    const set = new Set(available);
+    const direct = directionalChain(animation, set, state, facing);
+    if (direct)
+        return direct;
+    const seenStates = new Set();
+    let candidate = state;
+    while (candidate && !seenStates.has(candidate)) {
+        seenStates.add(candidate);
+        if (candidate !== state) {
+            const viaDirection = directionalChain(animation, set, candidate, facing);
+            if (viaDirection)
+                return viaDirection;
+        }
+        if (set.has(candidate))
+            return { clip: candidate, flip: false };
+        candidate = animation.contract.fallbacks[candidate];
+    }
+    return { clip: undefined, flip: false };
+}
+let installed = null;
+/** Installs (or clears, with null) the active directional contract. */
+export function installDirectionalAnimation(animation) {
+    installed = animation;
+}
+/** The active directional contract, if an archetype installed one. */
+export function installedDirectionalAnimation() {
+    return installed;
+}
+export function isAnimationFacingProvider(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.getAnimationFacing === 'function');
+}

package/dist/archetype.d.ts

@@ -1,3 +1,4 @@
+import type { DirectionalAnimation } from './animation/directional.js';
 import type { InputBindings } from './input.js';
 import type { PrefabJson, SceneEntityJson, SceneJson, SceneRegistry } from './scene.js';
 import type { ArchetypeBundle } from './state/hooks.js';
@@ -30,6 +31,8 @@ export interface ArchetypeManifest {
     bindings: Readonly<InputBindings>;
     actionLabels: Readonly<Record<string, string>>;
     bundle: ArchetypeBundle;
+    /** Directional animation contract, for genres where characters face around. */
+    animation?: DirectionalAnimation;
 }
 /** Browser manifest enriched with URLs produced by an asset-aware bundler. */
 export interface BrowserArchetypeManifest extends ArchetypeManifest {

package/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/package.json

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