@waica/engine 0.6.1 → 0.8.0

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

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

package/dist/game.js

@@ -1,6 +1,6 @@
 import * as THREE from 'three';
 import { collisionOverlap } from './collision-shape.js';
-import { resolveSceneCamera, stepSceneCamera } from './camera.js';
+import { isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera, } from './camera.js';
 import { resolveComponentUpdateSchedule } from './component-update-schedule.js';
 import { Hitbox } from './components/hitbox.js';
 import { Entity } from './entity.js';
@@ -8,6 +8,8 @@ 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';
 import { GameUi } from './ui.js';
@@ -40,6 +42,8 @@ export class Game {
     resolution;
     viewHeight;
     sceneCamera = null;
+    renderSort = null;
+    sceneProjection = null;
     lastTime = 0;
     runtimeBridge = null;
     constructor(options) {
@@ -61,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;
@@ -107,6 +112,22 @@ export class Game {
         this.updateFns.add(fn);
         return () => this.updateFns.delete(fn);
     }
+    /**
+     * Adopts a scene's render block. Called by loadScene; without a block the
+     * draw order stays layer-banded with spawn-order ties.
+     */
+    setSceneRender(json) {
+        this.renderSort = json?.sort === 'y' ? 'y' : null;
+        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
      * simulating, follows/clamps per its settings. Called by loadScene.
@@ -121,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() {
@@ -159,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;
@@ -216,7 +241,32 @@ export class Game {
         this.runtimeBridge?.unregister();
         this.runtimeBridge = null;
     };
+    /** Under y-sort, re-derives every participant's z from layer band + entity Y. */
+    applyYSort() {
+        const participants = [];
+        const entries = [];
+        for (const entity of this.entities) {
+            for (const component of entity.components) {
+                if (isYSortParticipant(component)) {
+                    participants.push(component);
+                    entries.push({ layer: component.layer, y: entity.node.position.y });
+                }
+            }
+        }
+        const z = ySortZ(entries);
+        for (const [index, participant] of participants.entries())
+            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);
         if (this.resolution) {
             // Letterbox bars: clear the whole canvas, then render inside the scissor.
@@ -262,19 +312,30 @@ export class Game {
         if (!cam)
             return;
         const followed = cam.follow ? this.find(cam.follow) : undefined;
-        const mover = followed?.components.find((c) => typeof c.vx === 'number');
+        const provider = followed?.components.find((c) => isCameraVelocityProvider(c));
+        const velocity = provider?.getCameraVelocity();
+        const 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: mover?.vx ?? 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++) {