@waica/engine 0.6.1 → 0.8.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/component.d.ts

@@ -63,6 +63,8 @@ export declare abstract class Component {
     onReady?(): void;
     /** Runs once per frame. */
     onUpdate?(dt: number): void;
+    /** Runs after the scene changes between identity and projected rendering. */
+    onProjectionChange?(projection: 'isometric' | null): void;
     /** Runs when this entity's Hitbox overlaps another one's. */
     onCollide?(other: Entity): void;
     /** Runs when this entity's DynamicBody physically contacts a Solid. */

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: {
@@ -20,6 +21,18 @@ export declare class AnimatedSprite extends Component {
         offsetY: {
             label: string;
         };
+        anchorX: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        anchorY: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
         layer: {
             label: string;
             min: number;
@@ -55,10 +68,22 @@ export declare class AnimatedSprite extends Component {
     set offsetX(value: number);
     get offsetY(): number;
     set offsetY(value: number);
+    private _anchorX;
+    private _anchorY;
+    get anchorX(): number;
+    set anchorX(value: number);
+    get anchorY(): number;
+    set anchorY(value: number);
     pixelArt: boolean;
     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. */
@@ -76,7 +101,7 @@ export declare class AnimatedSprite extends Component {
     onUpdate(dt: number): void;
     onDestroy(): void;
     private showFrame;
-    /** Repositions/rescales the quad from size, offsets and the frame scale. */
+    /** Repositions/rescales the displayed frame inside its anchored full-size box. */
     private syncQuad;
     private applyFrame;
 }

package/dist/components/animated-sprite.js

@@ -2,7 +2,9 @@ import * as THREE from 'three';
 import { Component } from '../component.js';
 import { ClipPlayer } from '../animation/clip-player.js';
 import { locateFrame, sheetCell } from '../animation/sheet.js';
+import { spritePlacement } from '../sprite-placement.js';
 const loader = new THREE.TextureLoader();
+const clampAnchor = (value) => Math.min(1, Math.max(0, value));
 /**
  * Sprite animated from one or more spritesheets. The main sheet is the
  * top-level texture/cols/rows (or explicit cells); extraSheets append after
@@ -18,10 +20,13 @@ export class AnimatedSprite extends Component {
     static params = {
         offsetX: { label: 'x offset' },
         offsetY: { label: 'y offset' },
+        anchorX: { label: 'x anchor', min: 0, max: 1, step: 0.25 },
+        anchorY: { label: 'y anchor', min: 0, max: 1, step: 0.25 },
         layer: { label: 'layer', min: -5, max: 5, step: 1 },
     };
     static transient = [
         'current',
+        'flipX',
         'player',
         'sheets',
         'texs',
@@ -81,6 +86,22 @@ export class AnimatedSprite extends Component {
         this._offsetY = value;
         this.syncQuad();
     }
+    _anchorX = 0.5;
+    _anchorY = 0.5;
+    get anchorX() {
+        return this._anchorX;
+    }
+    set anchorX(value) {
+        this._anchorX = clampAnchor(value);
+        this.syncQuad();
+    }
+    get anchorY() {
+        return this._anchorY;
+    }
+    set anchorY(value) {
+        this._anchorY = clampAnchor(value);
+        this.syncQuad();
+    }
     pixelArt = true;
     // Draw order among sprites: higher layers render in front. Same-layer
     // sprites fall back to spawn order, so give overlap an explicit layer.
@@ -93,6 +114,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. */
@@ -167,14 +202,24 @@ export class AnimatedSprite extends Component {
         this.frame = index;
         this.applyFrame();
     }
-    /** Repositions/rescales the quad from size, offsets and the frame scale. */
+    /** Repositions/rescales the displayed frame inside its anchored full-size box. */
     syncQuad() {
         if (!this.mesh)
             return;
-        this.mesh.scale.set(this._width * this.frameScaleX, 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;
-        this.mesh.position.y = this._offsetY - (this._height * (1 - this.frameScaleY)) / 2;
+        const placement = spritePlacement({
+            width: this.width,
+            height: this.height,
+            offsetX: this.offsetX,
+            offsetY: this.offsetY,
+            anchorX: this.anchorX,
+            anchorY: this.anchorY,
+            flipX: this.flipX,
+            frameScaleX: this.frameScaleX,
+            frameScaleY: this.frameScaleY,
+        });
+        this.mesh.position.x = placement.x;
+        this.mesh.position.y = placement.y;
+        this.mesh.scale.set(placement.scaleX, placement.scaleY, 1);
     }
     applyFrame() {
         const located = locateFrame(this.sheets, this.frame);

package/dist/components/dynamic-body.js

@@ -1,5 +1,6 @@
 import { COLLISION_SHAPES, collisionBounds, collisionOverlap, resolveCollisionPoints, } from '../collision-shape.js';
 import { Component } from '../component.js';
+import { sceneSolids } from '../scene-solids.js';
 import { resolveSolidAxis } from '../solid-axis.js';
 import { Solid } from './solid.js';
 /** Stable tie order for equal-distance initial-overlap recovery. */
@@ -161,10 +162,7 @@ export class DynamicBody extends Component {
         return { entity: solid.entity, solid, axis, normal };
     }
     solids() {
-        return this.game.entities
-            .filter((entity) => entity !== this.entity)
-            .map((entity) => entity.get(Solid))
-            .filter((solid) => solid !== undefined);
+        return sceneSolids(this.game, this.entity);
     }
     collisionBody() {
         return {

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: {
@@ -13,6 +14,18 @@ export declare class Sprite extends Component {
         offsetY: {
             label: string;
         };
+        anchorX: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        anchorY: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
         layer: {
             label: string;
             min: number;
@@ -36,17 +49,26 @@ export declare class Sprite extends Component {
     set offsetX(value: number);
     get offsetY(): number;
     set offsetY(value: number);
+    private _anchorX;
+    private _anchorY;
+    get anchorX(): number;
+    set anchorX(value: number);
+    get anchorY(): number;
+    set anchorY(value: number);
     /** Optional texture URL; with pixelArt on it filters in nearest. */
     texture?: string;
     pixelArt: boolean;
     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);
     private mesh?;
     onReady(): void;
     onDestroy(): void;
+    private syncQuad;
     private createGeometry;
 }

package/dist/components/sprite.js

@@ -1,6 +1,8 @@
 import * as THREE from 'three';
 import { Component } from '../component.js';
+import { spritePlacement } from '../sprite-placement.js';
 const loader = new THREE.TextureLoader();
+const clampAnchor = (value) => Math.min(1, Math.max(0, value));
 /**
  * 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).
@@ -10,6 +12,8 @@ export class Sprite extends Component {
     static params = {
         offsetX: { label: 'x offset' },
         offsetY: { label: 'y offset' },
+        anchorX: { label: 'x anchor', min: 0, max: 1, step: 0.25 },
+        anchorY: { label: 'y anchor', min: 0, max: 1, step: 0.25 },
         layer: { label: 'layer', min: -5, max: 5, step: 1 },
     };
     static transient = ['mesh'];
@@ -22,14 +26,14 @@ export class Sprite extends Component {
     }
     set width(value) {
         this._width = value;
-        this.mesh?.scale.set(this._width, this._height, 1);
+        this.syncQuad();
     }
     get height() {
         return this._height;
     }
     set height(value) {
         this._height = value;
-        this.mesh?.scale.set(this._width, this._height, 1);
+        this.syncQuad();
     }
     _color = 0xffffff;
     get color() {
@@ -46,16 +50,30 @@ export class Sprite extends Component {
     }
     set offsetX(value) {
         this._offsetX = value;
-        if (this.mesh)
-            this.mesh.position.x = value;
+        this.syncQuad();
     }
     get offsetY() {
         return this._offsetY;
     }
     set offsetY(value) {
         this._offsetY = value;
-        if (this.mesh)
-            this.mesh.position.y = value;
+        this.syncQuad();
+    }
+    _anchorX = 0.5;
+    _anchorY = 0.5;
+    get anchorX() {
+        return this._anchorX;
+    }
+    set anchorX(value) {
+        this._anchorX = clampAnchor(value);
+        this.syncQuad();
+    }
+    get anchorY() {
+        return this._anchorY;
+    }
+    set anchorY(value) {
+        this._anchorY = clampAnchor(value);
+        this.syncQuad();
     }
     /** Optional texture URL; with pixelArt on it filters in nearest. */
     texture;
@@ -71,6 +89,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;
@@ -96,8 +119,8 @@ export class Sprite extends Component {
             material.color.set(0xffffff);
         }
         this.mesh = new THREE.Mesh(this.createGeometry(), material);
-        this.mesh.scale.set(this._width, this._height, 1);
-        this.mesh.position.set(this._offsetX, this._offsetY, this.layer * 0.01);
+        this.mesh.position.z = this.layer * 0.01;
+        this.syncQuad();
         this.entity.node.add(this.mesh);
     }
     onDestroy() {
@@ -105,6 +128,24 @@ export class Sprite extends Component {
         this.mesh?.geometry.dispose();
         this.mesh?.material.dispose();
     }
+    syncQuad() {
+        if (!this.mesh)
+            return;
+        const placement = spritePlacement({
+            width: this.width,
+            height: this.height,
+            offsetX: this.offsetX,
+            offsetY: this.offsetY,
+            anchorX: this.anchorX,
+            anchorY: this.anchorY,
+            flipX: false,
+            frameScaleX: 1,
+            frameScaleY: 1,
+        });
+        this.mesh.position.x = placement.x;
+        this.mesh.position.y = placement.y;
+        this.mesh.scale.set(placement.scaleX, placement.scaleY, 1);
+    }
     createGeometry() {
         return this._shape === 'circle'
             ? new THREE.CircleGeometry(0.5, 32)