@waica/engine 0.6.1 → 0.8.0

package/dist/index.d.ts

@@ -1,7 +1,15 @@
 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 { projectIsometric, screenInputToLogical, unprojectIsometric } from './projection.js';
+export type { ProjectedPoint } from './projection.js';
+export { spritePlacement } from './sprite-placement.js';
+export type { SpritePlacement, SpritePlacementInput } from './sprite-placement.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';
@@ -25,14 +33,19 @@ export { Solid } from './components/solid.js';
 export { Hitbox } from './components/hitbox.js';
 export { DynamicBody } from './components/dynamic-body.js';
 export { AnimatedSprite } from './components/animated-sprite.js';
+export { Tilemap } from './components/tilemap.js';
 export { aabbOverlap } from './aabb.js';
 export { resolveSolidAxis } from './solid-axis.js';
 export type { CollisionAxis, SolidAxisOptions } from './solid-axis.js';
+export { isSolidSource, sceneSolids, SOLID_SOURCE_SYMBOL } from './scene-solids.js';
+export type { SolidSource } from './scene-solids.js';
+export { cellAt, cellBounds, cellIndex } from './tilemap-grid.js';
+export type { TilemapCell, TilemapCellBounds, TilemapGridSpec, } from './tilemap-grid.js';
 export { COLLISION_SHAPES, DEFAULT_COLLISION_POLYGON, collisionBounds, collisionOverlap, collisionVertices, resolveCollisionPoints, } from './collision-shape.js';
 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,9 @@
 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 { projectIsometric, screenInputToLogical, unprojectIsometric } from './projection.js';
+export { spritePlacement } from './sprite-placement.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';
@@ -15,8 +19,11 @@ export { Solid } from './components/solid.js';
 export { Hitbox } from './components/hitbox.js';
 export { DynamicBody } from './components/dynamic-body.js';
 export { AnimatedSprite } from './components/animated-sprite.js';
+export { Tilemap } from './components/tilemap.js';
 export { aabbOverlap } from './aabb.js';
 export { resolveSolidAxis } from './solid-axis.js';
+export { isSolidSource, sceneSolids, SOLID_SOURCE_SYMBOL } from './scene-solids.js';
+export { cellAt, cellBounds, cellIndex } from './tilemap-grid.js';
 export { COLLISION_SHAPES, DEFAULT_COLLISION_POLYGON, collisionBounds, collisionOverlap, collisionVertices, resolveCollisionPoints, } from './collision-shape.js';
 export { Emitter } from './events.js';
 export { loadScene, spawnFromJson, resolveEntityComponents, resolveProps } from './scene.js';

package/dist/projection.d.ts

@@ -0,0 +1,14 @@
+export interface ProjectedPoint {
+    x: number;
+    y: number;
+}
+/**
+ * Maps screen-relative input into the logical square-grid world used by
+ * isometric simulation. The orthogonal rotation/reflection preserves input
+ * magnitude and angles; vectors longer than one are clamped after mapping.
+ */
+export declare function screenInputToLogical(ix: number, iy: number): ProjectedPoint;
+/** Fixed 2:1 map from logical world coordinates to render coordinates. */
+export declare function projectIsometric(lx: number, ly: number): ProjectedPoint;
+/** Exact inverse of projectIsometric. */
+export declare function unprojectIsometric(x: number, y: number): ProjectedPoint;

package/dist/projection.js

@@ -0,0 +1,30 @@
+const cleanZero = (value) => (value === 0 ? 0 : value);
+/**
+ * Maps screen-relative input into the logical square-grid world used by
+ * isometric simulation. The orthogonal rotation/reflection preserves input
+ * magnitude and angles; vectors longer than one are clamped after mapping.
+ */
+export function screenInputToLogical(ix, iy) {
+    let x = (ix - iy) / Math.SQRT2;
+    let y = (-ix - iy) / Math.SQRT2;
+    const length = Math.hypot(x, y);
+    if (length > 1) {
+        x /= length;
+        y /= length;
+    }
+    return { x: cleanZero(x), y: cleanZero(y) };
+}
+/** Fixed 2:1 map from logical world coordinates to render coordinates. */
+export function projectIsometric(lx, ly) {
+    return {
+        x: cleanZero(lx - ly),
+        y: cleanZero(-(lx + ly) / 2),
+    };
+}
+/** Exact inverse of projectIsometric. */
+export function unprojectIsometric(x, y) {
+    return {
+        x: cleanZero(x / 2 - y),
+        y: cleanZero(-x / 2 - y),
+    };
+}

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-solids.d.ts

@@ -0,0 +1,16 @@
+import { Solid } from './components/solid.js';
+import type { Entity } from './entity.js';
+import type { Game } from './game.js';
+/** Explicit opt-in brand for components that derive collision Solids. */
+export declare const SOLID_SOURCE_SYMBOL: unique symbol;
+/** Component seam for geometry that derives one or more collision Solids. */
+export interface SolidSource {
+    readonly [SOLID_SOURCE_SYMBOL]: true;
+    solids(): readonly Solid[];
+}
+export declare function isSolidSource(value: unknown): value is SolidSource;
+/**
+ * All static collision geometry in stable entity/component order. Without a
+ * SolidSource this is exactly one direct Solid per entity, as before.
+ */
+export declare function sceneSolids(game: Game, except?: Entity): Solid[];

package/dist/scene-solids.js

@@ -0,0 +1,28 @@
+import { Solid } from './components/solid.js';
+/** Explicit opt-in brand for components that derive collision Solids. */
+export const SOLID_SOURCE_SYMBOL = Symbol('waica.solidSource');
+export function isSolidSource(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return candidate[SOLID_SOURCE_SYMBOL] === true && typeof candidate.solids === 'function';
+}
+/**
+ * All static collision geometry in stable entity/component order. Without a
+ * SolidSource this is exactly one direct Solid per entity, as before.
+ */
+export function sceneSolids(game, except) {
+    const result = [];
+    for (const entity of game.entities) {
+        if (entity === except)
+            continue;
+        const direct = entity.get(Solid);
+        if (direct)
+            result.push(direct);
+        for (const component of entity.components ?? []) {
+            if (isSolidSource(component))
+                result.push(...component.solids());
+        }
+    }
+    return result;
+}

package/dist/scene.d.ts

@@ -28,10 +28,22 @@ export interface PrefabJson {
     type: 'character' | 'object' | 'tile';
     components: SceneComponentJson[];
 }
+/** Scene-wide render options (v3). */
+export interface SceneRenderJson {
+    /**
+     * 'y' orders same-layer sprites by their render-space Y — lower Y renders
+     * in front (top-down depth). Absent: spawn order breaks same-layer ties.
+     */
+    sort?: 'y';
+    /** Logical positions are projected to the fixed 2:1 render lattice. */
+    projection?: 'isometric';
+}
 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/solid-axis.js

@@ -1,5 +1,6 @@
 import { collisionBounds, collisionOverlap } from './collision-shape.js';
 import { Solid } from './components/solid.js';
+import { sceneSolids } from './scene-solids.js';
 const CONTACT_TOLERANCE = 1e-7;
 function bodyFor(solid) {
     return {
@@ -19,10 +20,7 @@ function bodyFor(solid) {
 export function resolveSolidAxis({ entity, axis, previous, body, onContact, }) {
     const position = entity.position;
     const target = position[axis];
-    const solids = entity.game.entities
-        .filter((other) => other !== entity)
-        .map((other) => other.get(Solid))
-        .filter((solid) => solid !== undefined);
+    const solids = sceneSolids(entity.game, entity);
     position[axis] = previous;
     // Preserve the established spawn-inside-wall bail: pre-existing overlaps
     // are ignored for this move rather than becoming arbitrary push-out rules.

package/dist/sprite-placement.d.ts

@@ -0,0 +1,22 @@
+export interface SpritePlacementInput {
+    width: number;
+    height: number;
+    offsetX: number;
+    offsetY: number;
+    anchorX: number;
+    anchorY: number;
+    flipX: boolean;
+    frameScaleX: number;
+    frameScaleY: number;
+}
+export interface SpritePlacement {
+    x: number;
+    y: number;
+    scaleX: number;
+    scaleY: number;
+}
+/**
+ * Places a displayed frame inside its full-size sprite box. The declared
+ * anchor belongs to that box; smaller animation frames retain its floor.
+ */
+export declare function spritePlacement(input: SpritePlacementInput): SpritePlacement;

package/dist/sprite-placement.js

@@ -0,0 +1,14 @@
+/**
+ * Places a displayed frame inside its full-size sprite box. The declared
+ * anchor belongs to that box; smaller animation frames retain its floor.
+ */
+export function spritePlacement(input) {
+    const boxX = input.offsetX + (0.5 - input.anchorX) * input.width;
+    const floorY = input.offsetY - input.anchorY * input.height;
+    return {
+        x: input.flipX ? -boxX : boxX,
+        y: floorY + (input.height * input.frameScaleY) / 2,
+        scaleX: input.width * input.frameScaleX * (input.flipX ? -1 : 1),
+        scaleY: input.height * input.frameScaleY,
+    };
+}

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/dist/tilemap-grid.d.ts

@@ -0,0 +1,26 @@
+export interface TilemapGridSpec {
+    mapWidth: number;
+    mapHeight: number;
+    cellSize: number;
+    originX?: number;
+    originY?: number;
+}
+export interface TilemapCell {
+    column: number;
+    row: number;
+    index: number;
+}
+export interface TilemapCellBounds {
+    left: number;
+    right: number;
+    bottom: number;
+    top: number;
+    centerX: number;
+    centerY: number;
+}
+/** Row-major index for a map cell, or null outside a valid map. */
+export declare function cellIndex(mapWidth: number, mapHeight: number, column: number, row: number): number | null;
+/** Cell containing a logical point, relative to the Tilemap entity origin. */
+export declare function cellAt(spec: TilemapGridSpec, logicalX: number, logicalY: number): TilemapCell | null;
+/** Logical bounds and center of one map cell. */
+export declare function cellBounds(spec: TilemapGridSpec, column: number, row: number): TilemapCellBounds | null;

package/dist/tilemap-grid.js

@@ -0,0 +1,41 @@
+function dimension(value) {
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+/** Row-major index for a map cell, or null outside a valid map. */
+export function cellIndex(mapWidth, mapHeight, column, row) {
+    const width = dimension(mapWidth);
+    const height = dimension(mapHeight);
+    if (!Number.isInteger(column) || !Number.isInteger(row))
+        return null;
+    if (column < 0 || row < 0 || column >= width || row >= height)
+        return null;
+    return row * width + column;
+}
+/** Cell containing a logical point, relative to the Tilemap entity origin. */
+export function cellAt(spec, logicalX, logicalY) {
+    const size = spec.cellSize;
+    if (!Number.isFinite(size) || size <= 0)
+        return null;
+    const column = Math.floor((logicalX - (spec.originX ?? 0)) / size);
+    const row = Math.floor((logicalY - (spec.originY ?? 0)) / size);
+    const index = cellIndex(spec.mapWidth, spec.mapHeight, column, row);
+    return index === null ? null : { column, row, index };
+}
+/** Logical bounds and center of one map cell. */
+export function cellBounds(spec, column, row) {
+    if (cellIndex(spec.mapWidth, spec.mapHeight, column, row) === null)
+        return null;
+    const size = spec.cellSize;
+    if (!Number.isFinite(size) || size <= 0)
+        return null;
+    const left = (spec.originX ?? 0) + column * size;
+    const bottom = (spec.originY ?? 0) + row * size;
+    return {
+        left,
+        right: left + size,
+        bottom,
+        top: bottom + size,
+        centerX: left + size / 2,
+        centerY: bottom + size / 2,
+    };
+}

package/package.json

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