@waica/engine 0.7.0 → 0.9.0

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

@@ -21,6 +21,18 @@ export declare class AnimatedSprite extends Component implements YSortParticipan
         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;
@@ -56,6 +68,12 @@ export declare class AnimatedSprite extends Component implements YSortParticipan
     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;
@@ -83,7 +101,7 @@ export declare class AnimatedSprite extends Component implements YSortParticipan
     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,6 +20,8 @@ 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 = [
@@ -82,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.
@@ -182,16 +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.flipX ? -1 : 1), this._height * this.frameScaleY, 1);
-        // Bottom-center anchor: a shrunk frame keeps its feet on the quad's floor.
-        // 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;
+        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

@@ -14,6 +14,18 @@ export declare class Sprite extends Component implements YSortParticipant {
         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;
@@ -37,6 +49,12 @@ export declare class Sprite extends Component implements YSortParticipant {
     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;
@@ -51,5 +69,6 @@ export declare class Sprite extends Component implements YSortParticipant {
     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;
@@ -101,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() {
@@ -110,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)

package/dist/components/tilemap.d.ts

@@ -0,0 +1,113 @@
+import { Component } from '../component.js';
+import { SOLID_SOURCE_SYMBOL, type SolidSource } from '../scene-solids.js';
+import { type TilemapCell, type TilemapCellBounds } from '../tilemap-grid.js';
+import { Solid } from './solid.js';
+/** One authorable cell map rendered as a single merged geometry. */
+export declare class Tilemap extends Component implements SolidSource {
+    static componentName: string;
+    static params: {
+        color: {
+            label: string;
+        };
+        cols: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        rows: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        mapWidth: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        mapHeight: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        cellSize: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        layer: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+    };
+    static transient: string[];
+    readonly [SOLID_SOURCE_SYMBOL] = true;
+    private _texture;
+    get texture(): string;
+    set texture(value: string);
+    private _color;
+    get color(): number;
+    set color(value: number);
+    private _cols;
+    get cols(): number;
+    set cols(value: number);
+    private _rows;
+    get rows(): number;
+    set rows(value: number);
+    private _gridOffsetX;
+    get gridOffsetX(): number;
+    set gridOffsetX(value: number);
+    private _gridOffsetY;
+    get gridOffsetY(): number;
+    set gridOffsetY(value: number);
+    private _spacingX;
+    get spacingX(): number;
+    set spacingX(value: number);
+    private _spacingY;
+    get spacingY(): number;
+    set spacingY(value: number);
+    private _cellWidth;
+    get cellWidth(): number;
+    set cellWidth(value: number);
+    private _cellHeight;
+    get cellHeight(): number;
+    set cellHeight(value: number);
+    private _pixelArt;
+    get pixelArt(): boolean;
+    set pixelArt(value: boolean);
+    private _mapWidth;
+    get mapWidth(): number;
+    set mapWidth(value: number);
+    private _mapHeight;
+    get mapHeight(): number;
+    set mapHeight(value: number);
+    private _cellSize;
+    get cellSize(): number;
+    set cellSize(value: number);
+    private _cells;
+    get cells(): number[];
+    set cells(value: number[]);
+    private _solidTiles;
+    get solidTiles(): number[];
+    set solidTiles(value: number[]);
+    private _layer;
+    get layer(): number;
+    set layer(value: number);
+    private mesh?;
+    private loadedTexture?;
+    private derivedSolids;
+    onReady(): void;
+    onProjectionChange(): void;
+    onDestroy(): void;
+    solids(): readonly Solid[];
+    cellIndex(column: number, row: number): number | null;
+    cellAt(logicalX: number, logicalY: number): TilemapCell | null;
+    cellBounds(column: number, row: number): TilemapCellBounds | null;
+    private gridSpec;
+    private rebuildMap;
+    private rebuildMaterial;
+    private makeMaterial;
+    private rebuildGeometry;
+    private rebuildSolids;
+}

package/dist/components/tilemap.js

@@ -0,0 +1,316 @@
+import * as THREE from 'three';
+import { sheetCell } from '../animation/sheet.js';
+import { Component } from '../component.js';
+import { projectIsometric } from '../projection.js';
+import { SOLID_SOURCE_SYMBOL } from '../scene-solids.js';
+import { cellAt as gridCellAt, cellBounds as gridCellBounds, cellIndex as gridCellIndex, } from '../tilemap-grid.js';
+import { Solid } from './solid.js';
+const loader = new THREE.TextureLoader();
+/** One authorable cell map rendered as a single merged geometry. */
+export class Tilemap extends Component {
+    static componentName = 'Tilemap';
+    static params = {
+        color: { label: 'color' },
+        cols: { label: 'tileset columns', min: 1, step: 1 },
+        rows: { label: 'tileset rows', min: 1, step: 1 },
+        mapWidth: { label: 'map width', min: 1, step: 1 },
+        mapHeight: { label: 'map height', min: 1, step: 1 },
+        cellSize: { label: 'cell size', min: 0.05, step: 0.25 },
+        layer: { label: 'layer', min: -5, max: 5, step: 1 },
+    };
+    static transient = ['mesh', 'loadedTexture', 'derivedSolids'];
+    [SOLID_SOURCE_SYMBOL] = true;
+    _texture = '';
+    get texture() {
+        return this._texture;
+    }
+    set texture(value) {
+        this._texture = value;
+        this.rebuildMaterial();
+    }
+    _color = 0xffffff;
+    get color() {
+        return this._color;
+    }
+    set color(value) {
+        this._color = value;
+        this.rebuildMaterial();
+    }
+    _cols = 1;
+    get cols() {
+        return this._cols;
+    }
+    set cols(value) {
+        this._cols = value;
+        this.rebuildGeometry();
+    }
+    _rows = 1;
+    get rows() {
+        return this._rows;
+    }
+    set rows(value) {
+        this._rows = value;
+        this.rebuildGeometry();
+    }
+    _gridOffsetX = 0;
+    get gridOffsetX() {
+        return this._gridOffsetX;
+    }
+    set gridOffsetX(value) {
+        this._gridOffsetX = value;
+        this.rebuildGeometry();
+    }
+    _gridOffsetY = 0;
+    get gridOffsetY() {
+        return this._gridOffsetY;
+    }
+    set gridOffsetY(value) {
+        this._gridOffsetY = value;
+        this.rebuildGeometry();
+    }
+    _spacingX = 0;
+    get spacingX() {
+        return this._spacingX;
+    }
+    set spacingX(value) {
+        this._spacingX = value;
+        this.rebuildGeometry();
+    }
+    _spacingY = 0;
+    get spacingY() {
+        return this._spacingY;
+    }
+    set spacingY(value) {
+        this._spacingY = value;
+        this.rebuildGeometry();
+    }
+    _cellWidth = 0;
+    get cellWidth() {
+        return this._cellWidth;
+    }
+    set cellWidth(value) {
+        this._cellWidth = value;
+        this.rebuildGeometry();
+    }
+    _cellHeight = 0;
+    get cellHeight() {
+        return this._cellHeight;
+    }
+    set cellHeight(value) {
+        this._cellHeight = value;
+        this.rebuildGeometry();
+    }
+    _pixelArt = true;
+    get pixelArt() {
+        return this._pixelArt;
+    }
+    set pixelArt(value) {
+        this._pixelArt = value;
+        this.rebuildMaterial();
+    }
+    _mapWidth = 1;
+    get mapWidth() {
+        return this._mapWidth;
+    }
+    set mapWidth(value) {
+        this._mapWidth = value;
+        this.rebuildMap();
+    }
+    _mapHeight = 1;
+    get mapHeight() {
+        return this._mapHeight;
+    }
+    set mapHeight(value) {
+        this._mapHeight = value;
+        this.rebuildMap();
+    }
+    _cellSize = 1;
+    get cellSize() {
+        return this._cellSize;
+    }
+    set cellSize(value) {
+        this._cellSize = value;
+        this.rebuildMap();
+    }
+    _cells = [];
+    get cells() {
+        return this._cells;
+    }
+    set cells(value) {
+        this._cells = [...value];
+        this.rebuildMap();
+    }
+    _solidTiles = [];
+    get solidTiles() {
+        return this._solidTiles;
+    }
+    set solidTiles(value) {
+        this._solidTiles = [...value];
+        this.rebuildSolids();
+    }
+    _layer = 0;
+    get layer() {
+        return this._layer;
+    }
+    set layer(value) {
+        this._layer = value;
+        this.rebuildGeometry();
+    }
+    mesh;
+    loadedTexture;
+    derivedSolids = [];
+    onReady() {
+        this.mesh = new THREE.Mesh(new THREE.BufferGeometry(), this.makeMaterial());
+        this.entity.node.add(this.mesh);
+        this.rebuildMaterial();
+        this.rebuildMap();
+    }
+    onProjectionChange() {
+        this.rebuildGeometry();
+    }
+    onDestroy() {
+        this.mesh?.removeFromParent();
+        this.mesh?.geometry.dispose();
+        this.mesh?.material.dispose();
+        this.loadedTexture?.dispose();
+        this.loadedTexture = undefined;
+        this.derivedSolids = [];
+    }
+    solids() {
+        return this.derivedSolids;
+    }
+    cellIndex(column, row) {
+        return gridCellIndex(this.mapWidth, this.mapHeight, column, row);
+    }
+    cellAt(logicalX, logicalY) {
+        return gridCellAt(this.gridSpec(), logicalX, logicalY);
+    }
+    cellBounds(column, row) {
+        return gridCellBounds(this.gridSpec(), column, row);
+    }
+    gridSpec() {
+        return {
+            mapWidth: this.mapWidth,
+            mapHeight: this.mapHeight,
+            cellSize: this.cellSize,
+            originX: this.entity?.position.x ?? 0,
+            originY: this.entity?.position.y ?? 0,
+        };
+    }
+    rebuildMap() {
+        this.rebuildGeometry();
+        this.rebuildSolids();
+    }
+    rebuildMaterial() {
+        const mesh = this.mesh;
+        if (!mesh)
+            return;
+        this.loadedTexture?.dispose();
+        this.loadedTexture = undefined;
+        mesh.material.dispose();
+        mesh.material = this.makeMaterial();
+        if (!this.texture)
+            return;
+        const requested = this.texture;
+        const texture = loader.load(requested, () => {
+            if (this.loadedTexture === texture && this.texture === requested)
+                this.rebuildGeometry();
+        });
+        if (this.pixelArt) {
+            texture.magFilter = THREE.NearestFilter;
+            texture.minFilter = THREE.NearestFilter;
+        }
+        texture.colorSpace = THREE.SRGBColorSpace;
+        this.loadedTexture = texture;
+        mesh.material.map = texture;
+        mesh.material.color.set(0xffffff);
+        mesh.material.needsUpdate = true;
+    }
+    makeMaterial() {
+        return new THREE.MeshBasicMaterial({
+            color: this.color,
+            transparent: true,
+        });
+    }
+    rebuildGeometry() {
+        const mesh = this.mesh;
+        if (!mesh)
+            return;
+        const positions = [];
+        const uvs = [];
+        const indices = [];
+        const width = Math.max(0, Math.floor(this.mapWidth));
+        const height = Math.max(0, Math.floor(this.mapHeight));
+        const size = this.cellSize;
+        if (Number.isFinite(size) && size > 0) {
+            const image = this.loadedTexture?.image;
+            const imageWidth = image?.width && image.width > 0 ? image.width : Math.max(1, this.cols);
+            const imageHeight = image?.height && image.height > 0 ? image.height : Math.max(1, this.rows);
+            const frameParams = {
+                gridOffsetX: this.gridOffsetX,
+                gridOffsetY: this.gridOffsetY,
+                spacingX: this.spacingX,
+                spacingY: this.spacingY,
+                cellWidth: this.cellWidth,
+                cellHeight: this.cellHeight,
+            };
+            for (let index = 0; index < width * height; index++) {
+                const tile = this.cells[index] ?? -1;
+                if (!Number.isFinite(tile) || tile < 0)
+                    continue;
+                const column = index % width;
+                const row = Math.floor(index / width);
+                const logicalCenterX = (column + 0.5) * size;
+                const logicalCenterY = (row + 0.5) * size;
+                const center = this.game.projection === 'isometric'
+                    ? projectIsometric(logicalCenterX, logicalCenterY)
+                    : { x: logicalCenterX, y: logicalCenterY };
+                const halfWidth = this.game.projection === 'isometric' ? size : size / 2;
+                const halfHeight = size / 2;
+                const z = this.layer * 0.01;
+                positions.push(center.x - halfWidth, center.y - halfHeight, z, center.x + halfWidth, center.y - halfHeight, z, center.x + halfWidth, center.y + halfHeight, z, center.x - halfWidth, center.y + halfHeight, z);
+                const frame = sheetCell(imageWidth, imageHeight, this.cols, this.rows, tile, frameParams);
+                const left = frame.x / imageWidth;
+                const right = (frame.x + frame.width) / imageWidth;
+                const bottom = 1 - (frame.y + frame.height) / imageHeight;
+                const top = 1 - frame.y / imageHeight;
+                uvs.push(left, bottom, right, bottom, right, top, left, top);
+                const vertex = positions.length / 3 - 4;
+                indices.push(vertex, vertex + 1, vertex + 2, vertex, vertex + 2, vertex + 3);
+            }
+        }
+        const geometry = new THREE.BufferGeometry();
+        geometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3));
+        geometry.setAttribute('uv', new THREE.Float32BufferAttribute(uvs, 2));
+        geometry.setIndex(new THREE.BufferAttribute(new Uint32Array(indices), 1));
+        mesh.geometry.dispose();
+        mesh.geometry = geometry;
+    }
+    rebuildSolids() {
+        if (!this.entity || !this.game)
+            return;
+        const solids = new Set(this.solidTiles);
+        const width = Math.max(0, Math.floor(this.mapWidth));
+        const height = Math.max(0, Math.floor(this.mapHeight));
+        const next = [];
+        for (let index = 0; index < width * height; index++) {
+            const tile = this.cells[index] ?? -1;
+            if (!solids.has(tile))
+                continue;
+            const column = index % width;
+            const row = Math.floor(index / width);
+            const bounds = this.cellBounds(column, row);
+            if (!bounds)
+                continue;
+            const solid = new Solid();
+            solid.entity = this.entity;
+            solid.game = this.game;
+            solid.width = this.cellSize;
+            solid.height = this.cellSize;
+            solid.offsetX = bounds.centerX - this.entity.position.x;
+            solid.offsetY = bounds.centerY - this.entity.position.y;
+            next.push(solid);
+        }
+        this.derivedSolids = next;
+    }
+}

package/dist/entity.d.ts

@@ -10,10 +10,13 @@ export declare class Entity {
     readonly name: string;
     readonly node: THREE.Group<THREE.Object3DEventMap>;
     readonly components: Component[];
+    private logicalPosition;
     private destroyed;
     get alive(): boolean;
     constructor(game: Game, name: string);
     get position(): THREE.Vector3;
+    /** Keeps identity scenes zero-copy while projected scenes own a logical transform. */
+    setProjected(projected: boolean): void;
     get scale(): THREE.Vector3;
     add<T extends Component>(Class: ComponentClass<T>, props?: Partial<T>): T;
     get<T extends Component>(Class: ComponentClass<T>): T | undefined;

package/dist/entity.js

@@ -8,6 +8,7 @@ export class Entity {
     name;
     node = new THREE.Group();
     components = [];
+    logicalPosition = null;
     destroyed = false;
     get alive() {
         return !this.destroyed;
@@ -17,7 +18,18 @@ export class Entity {
         this.name = name;
     }
     get position() {
-        return this.node.position;
+        return this.logicalPosition ?? this.node.position;
+    }
+    /** Keeps identity scenes zero-copy while projected scenes own a logical transform. */
+    setProjected(projected) {
+        if (projected === (this.logicalPosition !== null))
+            return;
+        if (projected) {
+            this.logicalPosition = this.node.position.clone();
+            return;
+        }
+        this.node.position.copy(this.logicalPosition);
+        this.logicalPosition = null;
     }
     get scale() {
         return this.node.scale;

package/dist/game.d.ts

@@ -62,6 +62,7 @@ export declare class Game {
     private viewHeight;
     private sceneCamera;
     private renderSort;
+    private sceneProjection;
     private lastTime;
     private runtimeBridge;
     constructor(options: GameOptions);
@@ -91,6 +92,8 @@ export declare class Game {
     stop(): void;
     /** Internal: called by Entity.destroy(). */
     removeEntity(entity: Entity): void;
+    /** The scene's render projection; null keeps logical and render space identical. */
+    get projection(): 'isometric' | null;
     /** Visible world height (2D camera zoom). */
     get view(): number;
     setViewHeight(value: number): void;
@@ -105,6 +108,7 @@ export declare class Game {
     private renderSurface;
     private componentUpdateSchedule;
     private updateSceneCamera;
+    private renderPoint;
     private dispatchCollisions;
     private resize;
 }

package/dist/game.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 { projectIsometric } from './projection.js';
 import { isYSortParticipant, ySortZ } from './render-sort.js';
 import { registryEntry, spawnFromJson } from './scene.js';
 import { Stats } from './stats.js';
@@ -42,6 +43,7 @@ export class Game {
     viewHeight;
     sceneCamera = null;
     renderSort = null;
+    sceneProjection = null;
     lastTime = 0;
     runtimeBridge = null;
     constructor(options) {
@@ -63,6 +65,7 @@ export class Game {
     /** Creates a live entity in the scene. */
     spawn(name) {
         const entity = new Entity(this, name);
+        entity.setProjected(this.sceneProjection === 'isometric');
         this.entities.push(entity);
         this.scene.add(entity.node);
         return entity;
@@ -115,6 +118,15 @@ export class Game {
      */
     setSceneRender(json) {
         this.renderSort = json?.sort === 'y' ? 'y' : null;
+        const projection = json?.projection === 'isometric' ? 'isometric' : null;
+        if (projection === this.sceneProjection)
+            return;
+        this.sceneProjection = projection;
+        for (const entity of this.entities) {
+            entity.setProjected(projection === 'isometric');
+            for (const component of entity.components)
+                component.onProjectionChange?.(projection);
+        }
     }
     /**
      * Adopts a scene's camera block: jumps to its framing and, while
@@ -130,11 +142,11 @@ export class Game {
         // With a follow target the declared position is moot: start centered on
         // the target so play begins framed like the editor shows it.
         const followed = this.sceneCamera.follow ? this.find(this.sceneCamera.follow) : undefined;
-        const [x, y] = followed
-            ? [followed.position.x, followed.position.y]
-            : this.sceneCamera.position;
-        this.camera.position.x = x;
-        this.camera.position.y = y;
+        const center = followed
+            ? this.renderPoint(followed.position.x, followed.position.y)
+            : { x: this.sceneCamera.position[0], y: this.sceneCamera.position[1] };
+        this.camera.position.x = center.x;
+        this.camera.position.y = center.y;
         this.setViewHeight(this.sceneCamera.zoom);
     }
     start() {
@@ -168,6 +180,10 @@ export class Game {
         if (i !== -1)
             this.entities.splice(i, 1);
     }
+    /** The scene's render projection; null keeps logical and render space identical. */
+    get projection() {
+        return this.sceneProjection;
+    }
     /** Visible world height (2D camera zoom). */
     get view() {
         return this.viewHeight;
@@ -233,7 +249,7 @@ export class Game {
             for (const component of entity.components) {
                 if (isYSortParticipant(component)) {
                     participants.push(component);
-                    entries.push({ layer: component.layer, y: entity.position.y });
+                    entries.push({ layer: component.layer, y: entity.node.position.y });
                 }
             }
         }
@@ -242,6 +258,13 @@ export class Game {
             participant.setSortZ(z[index]);
     }
     renderSurface() {
+        if (this.sceneProjection === 'isometric') {
+            for (const entity of this.entities) {
+                const projected = projectIsometric(entity.position.x, entity.position.y);
+                entity.node.position.x = projected.x;
+                entity.node.position.y = projected.y;
+            }
+        }
         if (this.renderSort === 'y')
             this.applyYSort();
         this.ui.setActive(this.simulate);
@@ -291,19 +314,28 @@ export class Game {
         const followed = cam.follow ? this.find(cam.follow) : undefined;
         const provider = followed?.components.find((c) => isCameraVelocityProvider(c));
         const velocity = provider?.getCameraVelocity();
+        const target = followed
+            ? this.renderPoint(followed.position.x, followed.position.y)
+            : null;
+        const renderVelocity = velocity
+            ? this.renderPoint(velocity.vx, velocity.vy)
+            : { x: 0, y: 0 };
         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: velocity?.vx ?? 0,
-            vy: velocity?.vy ?? 0,
+            target,
+            vx: renderVelocity.x,
+            vy: renderVelocity.y,
             dt,
         });
         this.camera.position.x = next.x;
         this.camera.position.y = next.y;
     }
+    renderPoint(x, y) {
+        return this.sceneProjection === 'isometric' ? projectIsometric(x, y) : { x, y };
+    }
     dispatchCollisions() {
         const boxed = this.entities.filter((e) => e.has(Hitbox));
         for (let i = 0; i < boxed.length; i++) {

package/dist/index.d.ts

@@ -4,6 +4,10 @@ export { installDirectionalAnimation, installedDirectionalAnimation, isAnimation
 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';
@@ -29,9 +33,14 @@ 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';

package/dist/index.js

@@ -1,6 +1,8 @@
 export { Game } from './game.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';
@@ -17,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/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

@@ -31,10 +31,12 @@ export interface PrefabJson {
 /** Scene-wide render options (v3). */
 export interface SceneRenderJson {
     /**
-     * 'y' orders same-layer sprites by their entity's world Y — lower Y renders
+     * '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;

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/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.7.0",
+  "version": "0.9.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",