@waica/engine 0.19.0 → 0.19.2

package/dist/components/tilemap.js

@@ -5,6 +5,7 @@ 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';
+import { reportRejection } from '../report-rejection.js';
 /** One authorable cell map rendered as a single merged geometry. */
 export class Tilemap extends Component {
     static componentName = 'Tilemap';
@@ -218,14 +219,14 @@ export class Tilemap extends Component {
         // happens if the texture was replaced or the component destroyed
         // meanwhile.
         const { texture, settled } = this.game.assets.texture(requested);
-        void settled.then((outcome) => {
+        reportRejection(settled.then((outcome) => {
             if (this.loadedTexture !== texture || this.texture !== requested)
                 return;
             if (outcome === 'loaded')
                 this.rebuildGeometry();
             else
                 this.dropFailedTexture();
-        });
+        }), 'tilemap texture settle');
         if (this.pixelArt) {
             texture.magFilter = THREE.NearestFilter;
             texture.minFilter = THREE.NearestFilter;
@@ -260,56 +261,66 @@ export class Tilemap extends Component {
         const mesh = this.mesh;
         if (!mesh)
             return;
-        const positions = [];
-        const uvs = [];
-        const indices = [];
+        const buffers = { positions: [], uvs: [], 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,
-            };
+            const sheet = this.sheetSize();
             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);
+                this.pushTileQuad(buffers.positions, index % width, Math.floor(index / width));
+                buffers.uvs.push(...this.tileUvs(tile, sheet));
+                const vertex = buffers.positions.length / 3 - 4;
+                buffers.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));
+        geometry.setAttribute('position', new THREE.Float32BufferAttribute(buffers.positions, 3));
+        geometry.setAttribute('uv', new THREE.Float32BufferAttribute(buffers.uvs, 2));
+        geometry.setIndex(new THREE.BufferAttribute(new Uint32Array(buffers.indices), 1));
         mesh.geometry.dispose();
         mesh.geometry = geometry;
     }
+    /** The loaded sheet image's size, or one pixel per sheet cell until it arrives. */
+    sheetSize() {
+        const image = this.loadedTexture?.image;
+        return {
+            width: image?.width && image.width > 0 ? image.width : Math.max(1, this.cols),
+            height: image?.height && image.height > 0 ? image.height : Math.max(1, this.rows),
+        };
+    }
+    /** The four corners of a cell's quad, projected for the Game, on this layer's depth. */
+    pushTileQuad(positions, column, row) {
+        const size = this.cellSize;
+        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);
+    }
+    /** The UVs of a tile's sheet cell, in the quad's corner order. */
+    tileUvs(tile, sheet) {
+        const frame = sheetCell(sheet.width, sheet.height, this.cols, this.rows, tile, {
+            gridOffsetX: this.gridOffsetX,
+            gridOffsetY: this.gridOffsetY,
+            spacingX: this.spacingX,
+            spacingY: this.spacingY,
+            cellWidth: this.cellWidth,
+            cellHeight: this.cellHeight,
+        });
+        const left = frame.x / sheet.width;
+        const right = (frame.x + frame.width) / sheet.width;
+        const bottom = 1 - (frame.y + frame.height) / sheet.height;
+        const top = 1 - frame.y / sheet.height;
+        return [left, bottom, right, bottom, right, top, left, top];
+    }
     rebuildSolids() {
         if (!this.entity || !this.game)
             return;

package/dist/entity.js

@@ -22,13 +22,15 @@ export class Entity {
     }
     /** Keeps identity scenes zero-copy while projected scenes own a logical transform. */
     setProjected(projected) {
-        if (projected === (this.logicalPosition !== null))
-            return;
+        const logical = this.logicalPosition;
         if (projected) {
-            this.logicalPosition = this.node.position.clone();
+            if (logical === null)
+                this.logicalPosition = this.node.position.clone();
             return;
         }
-        this.node.position.copy(this.logicalPosition);
+        if (logical === null)
+            return;
+        this.node.position.copy(logical);
         this.logicalPosition = null;
     }
     get scale() {

package/dist/game.js

@@ -5,7 +5,7 @@ import { AudioSubsystem } from './audio/audio-subsystem.js';
 import { dispatchCollisions as dispatchHitboxCollisions } from './collision-dispatch.js';
 import { isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera, } from './camera.js';
 import { advanceCameraEffects, CameraEffects, layoutCameraEffects } from './camera-effects.js';
-import { resolveComponentUpdateSchedule } from './component-update-schedule.js';
+import { implementsOnUpdate, resolveComponentUpdateSchedule } from './component-update-schedule.js';
 import { Entity } from './entity.js';
 import { Emitter } from './events.js';
 import { consumeSimulationSteps, MAX_CHAINED_HOPS, SIMULATION_STEP, snapElapsedToStep, } from './fixed-step.js';
@@ -20,6 +20,16 @@ import { loadScene, registryEntry, spawnFromJson, } from './scene.js';
 import { createSpatialQuery } from './spatial-query.js';
 import { Stats } from './stats.js';
 import { anchoredPiecesOf, GameUi } from './ui.js';
+import { componentClassOf } from './component-registry.js';
+/** Maps a resolved update order back to the entity's components; the order only names components it was built from. */
+function componentsInOrder(order, byName) {
+    return order.map((name) => {
+        const component = byName.get(name);
+        if (!component)
+            throw new Error(`Component update schedule names "${name}", which is not on the entity`);
+        return component;
+    });
+}
 /**
  * Engine core: loop, unified 2D/3D three scene, orthographic camera,
  * entities with components, and input. See DESIGN.md.
@@ -265,7 +275,7 @@ export class Game {
     }
     /** Applies persisted overrides to a freshly added component. */
     applyParamOverrides(entity, component) {
-        const Class = component.constructor;
+        const Class = componentClassOf(component);
         const override = this.paramOverrides[entity.name]?.[Class.componentName];
         if (override)
             Object.assign(component, override);
@@ -535,8 +545,12 @@ export class Game {
             }
         }
         const z = ySortZ(entries);
-        for (const [index, participant] of participants.entries())
-            participant.setSortZ(z[index]);
+        for (const [index, participant] of participants.entries()) {
+            const sortZ = z[index];
+            if (sortZ === undefined)
+                throw new Error(`ySortZ returned no z for y-sort participant ${index}`);
+            participant.setSortZ(sortZ);
+        }
     }
     renderSurface() {
         if (this.sceneProjection === 'isometric') {
@@ -578,11 +592,11 @@ export class Game {
         const names = [];
         const signatureParts = [];
         for (const component of components) {
-            const Class = component.constructor;
+            const Class = componentClassOf(component);
             const name = Class.componentName;
             names.push(name);
             byName.set(name, component);
-            signatureParts.push(`${name}:${typeof Class.prototype.onUpdate === 'function' ? 'updates' : 'passive'}:` +
+            signatureParts.push(`${name}:${implementsOnUpdate(Class) ? 'updates' : 'passive'}:` +
                 [...new Set(Class.updateAfter ?? [])].sort().join(','));
         }
         const signature = signatureParts.sort().join('|');
@@ -592,13 +606,13 @@ export class Game {
         // when nothing about this entity's components changed since last time.
         const cached = this.updateScheduleCache.get(entity);
         if (cached && cached.signature === signature) {
-            return cached.order.map((name) => byName.get(name));
+            return componentsInOrder(cached.order, byName);
         }
         const registry = {
             ...(this.registry?.components ?? {}),
         };
         for (const component of components) {
-            const Class = component.constructor;
+            const Class = componentClassOf(component);
             registry[Class.componentName] = Class;
         }
         const result = resolveComponentUpdateSchedule(names, registry);
@@ -613,7 +627,7 @@ export class Game {
         }
         this.invalidUpdateCompositions.delete(entity);
         this.updateScheduleCache.set(entity, { signature, order: result.order });
-        return result.order.map((name) => byName.get(name));
+        return componentsInOrder(result.order, byName);
     }
     updateSceneCamera(dt) {
         const cam = this.sceneCamera;

package/dist/pointer.js

@@ -148,15 +148,32 @@ export class Pointer {
                 }
             }
         }
-        if (hits.length === 0)
-            return null;
-        if (hits.length === 1)
-            return hits[0].entity;
-        const z = ySortZ(hits.map((h) => ({ layer: h.layer, y: h.y })));
-        let bestIndex = 0;
-        for (let i = 1; i < hits.length; i += 1)
-            if (z[i] > z[bestIndex])
-                bestIndex = i;
-        return hits[bestIndex].entity;
+        return frontMostHit(hits);
     }
 }
+/** The front-most hit under y-sort; on an exact z tie the earlier hit wins. */
+function frontMostHit(hits) {
+    const [first] = hits;
+    if (!first)
+        return null;
+    if (hits.length === 1)
+        return first.entity;
+    const z = ySortZ(hits.map((h) => ({ layer: h.layer, y: h.y })));
+    let best = first;
+    let bestZ = zOfHit(z, 0);
+    for (const [index, hit] of hits.entries()) {
+        const hitZ = zOfHit(z, index);
+        if (hitZ > bestZ) {
+            best = hit;
+            bestZ = hitZ;
+        }
+    }
+    return best.entity;
+}
+/** `ySortZ` returns one z per entry, so every hit index has one. */
+function zOfHit(z, index) {
+    const value = z[index];
+    if (value === undefined)
+        throw new Error(`ySortZ returned no z for pointer hit ${index}`);
+    return value;
+}

package/dist/render-sort.js

@@ -4,6 +4,13 @@ export function isYSortParticipant(value) {
         typeof value.layer === 'number' &&
         typeof value.setSortZ === 'function');
 }
+/** The Y of the entry at `index`, which `ySortZ` only reads for indices it grouped from `entries`. */
+function entryY(entries, index) {
+    const entry = entries[index];
+    if (!entry)
+        throw new Error(`ySortZ has no entry at index ${index}`);
+    return entry.y;
+}
 /**
  * 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
@@ -22,14 +29,13 @@ export function ySortZ(entries) {
         else
             byLayer.set(entry.layer, [index]);
     }
-    const layers = [...byLayer.keys()].sort((a, b) => a - b);
+    const layers = [...byLayer].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];
+    for (const [i, [layer, indices]] of layers.entries()) {
+        const next = layers[i + 1]?.[0];
         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 ordered = [...indices].sort((a, b) => entryY(entries, b) - entryY(entries, a));
         const step = width / (ordered.length + 1);
         for (const [rank, index] of ordered.entries()) {
             z[index] = layer * 0.01 + (rank + 1) * step;

package/dist/report-rejection.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Observes a task the engine starts without awaiting (a texture settling, an
+ * AudioContext state change): its rejection is logged once as a `[waica]`
+ * error instead of surfacing as an unhandled rejection. Internal; not part of
+ * the package entry.
+ */
+export declare function reportRejection(task: Promise<unknown>, context: string): void;

package/dist/report-rejection.js

@@ -0,0 +1,12 @@
+/**
+ * Observes a task the engine starts without awaiting (a texture settling, an
+ * AudioContext state change): its rejection is logged once as a `[waica]`
+ * error instead of surfacing as an unhandled rejection. Internal; not part of
+ * the package entry.
+ */
+export function reportRejection(task, context) {
+    task.catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[waica] ${context} failed: ${message}`);
+    });
+}

package/dist/runtime-bridge.d.ts

@@ -106,6 +106,10 @@ export declare class EngineRuntimeBridge implements RuntimeBridge {
     metadata(): RuntimeMetadata;
     inspect(filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
     control(request: RuntimeControlRequest): RuntimeControlResult;
+    private injectAction;
+    /** Advances whole Simulation Steps while paused. */
+    private step;
+    private loadScene;
     /** Counts one Simulation Step, whoever ran it (paused stepping or real-time playback). */
     private advance;
     unregister(): void;

package/dist/runtime-bridge.js

@@ -96,29 +96,11 @@ export class EngineRuntimeBridge {
             case 'press':
             case 'hold':
             case 'release':
-                if (!this.host.injectAction(request.action, request.operation)) {
-                    const available = this.host.availableActions();
-                    throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unknown action "${request.action}". Available actions: ${available.join(', ') || '(none)'}.`, available);
-                }
+                this.injectAction(request);
                 break;
-            case 'step': {
-                if (this.mode !== 'paused') {
-                    throw new RuntimeBridgeOperationError('runtime-invalid-state', 'step is only available while the Runtime Bridge is paused.');
-                }
-                // A caller-chosen dt is rejected outright, never ignored: a pre-ADR-0014
-                // client that still sends one would otherwise believe it stepped by it.
-                if ('dt' in request) {
-                    throw new RuntimeBridgeOperationError('runtime-operation-failed', 'step takes no dt: it advances whole Simulation Steps of 1/60 s each; pass frames (1 through 600) instead.');
-                }
-                const frames = request.frames ?? 1;
-                if (!Number.isInteger(frames) || frames < 1 || frames > 600) {
-                    throw new RuntimeBridgeOperationError('runtime-operation-failed', 'frames must be an integer from 1 through 600.');
-                }
-                for (let index = 0; index < frames; index += 1) {
-                    this.host.step(() => this.advance());
-                }
+            case 'step':
+                this.step(request);
                 break;
-            }
             case 'click': {
                 if (!Number.isFinite(request.x) || !Number.isFinite(request.y)) {
                     throw new RuntimeBridgeOperationError('runtime-operation-failed', 'x and y must be finite numbers.');
@@ -126,13 +108,9 @@ export class EngineRuntimeBridge {
                 this.host.click(request.x, request.y);
                 break;
             }
-            case 'scene': {
-                if (!this.host.loadScene(request.scene)) {
-                    const available = this.host.availableScenes();
-                    throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unknown scene "${request.scene}". Available scenes: ${available.join(', ') || '(none)'}.`, undefined, available);
-                }
+            case 'scene':
+                this.loadScene(request.scene);
                 break;
-            }
             default: {
                 const unsupported = request;
                 throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unsupported runtime control operation "${unsupported.operation}".`);
@@ -140,6 +118,36 @@ export class EngineRuntimeBridge {
         }
         return { ...this.metadata(), heldActions: this.host.heldActions() };
     }
+    injectAction(request) {
+        if (this.host.injectAction(request.action, request.operation))
+            return;
+        const available = this.host.availableActions();
+        throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unknown action "${request.action}". Available actions: ${available.join(', ') || '(none)'}.`, available);
+    }
+    /** Advances whole Simulation Steps while paused. */
+    step(request) {
+        if (this.mode !== 'paused') {
+            throw new RuntimeBridgeOperationError('runtime-invalid-state', 'step is only available while the Runtime Bridge is paused.');
+        }
+        // A caller-chosen dt is rejected outright, never ignored: a pre-ADR-0014
+        // client that still sends one would otherwise believe it stepped by it.
+        if ('dt' in request) {
+            throw new RuntimeBridgeOperationError('runtime-operation-failed', 'step takes no dt: it advances whole Simulation Steps of 1/60 s each; pass frames (1 through 600) instead.');
+        }
+        const frames = request.frames ?? 1;
+        if (!Number.isInteger(frames) || frames < 1 || frames > 600) {
+            throw new RuntimeBridgeOperationError('runtime-operation-failed', 'frames must be an integer from 1 through 600.');
+        }
+        for (let index = 0; index < frames; index += 1) {
+            this.host.step(() => this.advance());
+        }
+    }
+    loadScene(scene) {
+        if (this.host.loadScene(scene))
+            return;
+        const available = this.host.availableScenes();
+        throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unknown scene "${scene}". Available scenes: ${available.join(', ') || '(none)'}.`, undefined, available);
+    }
     /** Counts one Simulation Step, whoever ran it (paused stepping or real-time playback). */
     advance() {
         this.frame += 1;