@waica/engine 0.19.0 → 0.19.2

package/dist/runtime-inspection.js

@@ -1,4 +1,5 @@
 import { anchoredPiecesOf } from './ui.js';
+import { componentClassOf } from './component-registry.js';
 export const RUNTIME_PROJECTION_LIMITS = {
     depth: 5,
     entries: 100,
@@ -11,7 +12,7 @@ function marker(context, path, kind, detail = {}) {
     return { $waica: kind, ...detail };
 }
 function isPlainRecord(value) {
-    const prototype = Object.getPrototypeOf(value);
+    const prototype = Reflect.getPrototypeOf(value);
     return prototype === Object.prototype || prototype === null;
 }
 const textEncoder = new TextEncoder();
@@ -41,17 +42,8 @@ function projectValue(value, path, context, depth = 0) {
     }
     if (value === null || typeof value === 'boolean')
         return value;
-    if (typeof value === 'string') {
-        const bytes = utf8Bytes(value);
-        if (bytes <= RUNTIME_PROJECTION_LIMITS.stringBytes)
-            return value;
-        return marker(context, path, 'truncated', {
-            reason: 'string',
-            preview: stringPreview(value, RUNTIME_PROJECTION_LIMITS.stringBytes),
-            originalLength: value.length,
-            originalBytes: bytes,
-        });
-    }
+    if (typeof value === 'string')
+        return projectString(value, path, context);
     if (typeof value === 'bigint')
         return { $waica: 'bigint', value: value.toString() };
     if (typeof value === 'number') {
@@ -66,69 +58,93 @@ function projectValue(value, path, context, depth = 0) {
     if (previousPath)
         return marker(context, path, 'cycle', { path: previousPath });
     context.seen.set(value, path);
+    return projectObject(value, { path, depth }, context);
+}
+function projectString(value, path, context) {
+    const bytes = utf8Bytes(value);
+    if (bytes <= RUNTIME_PROJECTION_LIMITS.stringBytes)
+        return value;
+    return marker(context, path, 'truncated', {
+        reason: 'string',
+        preview: stringPreview(value, RUNTIME_PROJECTION_LIMITS.stringBytes),
+        originalLength: value.length,
+        originalBytes: bytes,
+    });
+}
+/** Projects a not-yet-seen object: dates, collections and plain records; anything else is unsupported. */
+function projectObject(value, site, context) {
+    const { path } = site;
     if (value instanceof Date) {
         return Number.isFinite(value.getTime())
             ? { $waica: 'date', value: value.toISOString() }
             : marker(context, path, 'error', { message: 'Invalid Date' });
     }
-    if (Array.isArray(value)) {
-        const entries = value.slice(0, RUNTIME_PROJECTION_LIMITS.entries)
-            .map((entry, index) => projectValue(entry, `${path}[${index}]`, context, depth + 1));
-        const omitted = value.length - entries.length;
-        if (omitted > 0) {
-            entries.push(marker(context, path, 'truncated', { reason: 'entries', omitted }));
-        }
-        return entries;
-    }
-    if (value instanceof Map) {
-        const sourceEntries = [...value.entries()];
-        const entries = sourceEntries.slice(0, RUNTIME_PROJECTION_LIMITS.entries)
-            .map(([key, entry], index) => [
-            projectValue(key, `${path}.entries[${index}].key`, context, depth + 1),
-            projectValue(entry, `${path}.entries[${index}].value`, context, depth + 1),
-        ]);
-        const omitted = sourceEntries.length - entries.length;
-        return {
-            $waica: 'map',
-            entries,
-            ...(omitted > 0
-                ? { truncated: marker(context, path, 'truncated', { reason: 'entries', omitted }) }
-                : {}),
-        };
-    }
-    if (value instanceof Set) {
-        const sourceValues = [...value];
-        const values = sourceValues.slice(0, RUNTIME_PROJECTION_LIMITS.entries)
-            .map((entry, index) => projectValue(entry, `${path}.values[${index}]`, context, depth + 1));
-        const omitted = sourceValues.length - values.length;
-        return {
-            $waica: 'set',
-            values,
-            ...(omitted > 0
-                ? { truncated: marker(context, path, 'truncated', { reason: 'entries', omitted }) }
-                : {}),
-        };
-    }
-    if (isPlainRecord(value)) {
-        const keys = Object.keys(value).sort();
-        const projected = Object.fromEntries(keys.slice(0, RUNTIME_PROJECTION_LIMITS.entries)
-            .map((key) => [
-            key,
-            projectValue(value[key], `${path}.${key}`, context, depth + 1),
-        ]));
-        const omitted = keys.length - Object.keys(projected).length;
-        if (omitted === 0)
-            return projected;
-        return marker(context, path, 'truncated', {
-            reason: 'entries',
-            omitted,
-            value: projected,
-        });
-    }
+    if (Array.isArray(value))
+        return projectArray(value, site, context);
+    if (value instanceof Map)
+        return projectMap(value, site, context);
+    if (value instanceof Set)
+        return projectSet(value, site, context);
+    if (isPlainRecord(value))
+        return projectRecord(value, site, context);
     return marker(context, path, 'unsupported', {
         type: value.constructor?.name ?? 'object',
     });
 }
+function projectArray(value, { path, depth }, context) {
+    const entries = value.slice(0, RUNTIME_PROJECTION_LIMITS.entries)
+        .map((entry, index) => projectValue(entry, `${path}[${index}]`, context, depth + 1));
+    const omitted = value.length - entries.length;
+    if (omitted > 0) {
+        entries.push(marker(context, path, 'truncated', { reason: 'entries', omitted }));
+    }
+    return entries;
+}
+function projectMap(value, { path, depth }, context) {
+    const sourceEntries = [...value.entries()];
+    const entries = sourceEntries.slice(0, RUNTIME_PROJECTION_LIMITS.entries)
+        .map(([key, entry], index) => [
+        projectValue(key, `${path}.entries[${index}].key`, context, depth + 1),
+        projectValue(entry, `${path}.entries[${index}].value`, context, depth + 1),
+    ]);
+    const omitted = sourceEntries.length - entries.length;
+    return {
+        $waica: 'map',
+        entries,
+        ...(omitted > 0
+            ? { truncated: marker(context, path, 'truncated', { reason: 'entries', omitted }) }
+            : {}),
+    };
+}
+function projectSet(value, { path, depth }, context) {
+    const sourceValues = [...value];
+    const values = sourceValues.slice(0, RUNTIME_PROJECTION_LIMITS.entries)
+        .map((entry, index) => projectValue(entry, `${path}.values[${index}]`, context, depth + 1));
+    const omitted = sourceValues.length - values.length;
+    return {
+        $waica: 'set',
+        values,
+        ...(omitted > 0
+            ? { truncated: marker(context, path, 'truncated', { reason: 'entries', omitted }) }
+            : {}),
+    };
+}
+function projectRecord(value, { path, depth }, context) {
+    const keys = Object.keys(value).sort();
+    const projected = Object.fromEntries(keys.slice(0, RUNTIME_PROJECTION_LIMITS.entries)
+        .map((key) => [
+        key,
+        projectValue(value[key], `${path}.${key}`, context, depth + 1),
+    ]));
+    const omitted = keys.length - Object.keys(projected).length;
+    if (omitted === 0)
+        return projected;
+    return marker(context, path, 'truncated', {
+        reason: 'entries',
+        omitted,
+        value: projected,
+    });
+}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -154,7 +170,7 @@ function componentState(component, path, context) {
             continue;
         const valuePath = `${path}.${key}`;
         try {
-            const value = component[key];
+            const value = Reflect.get(component, key);
             if (typeof value === 'function')
                 continue;
             state[key] = projectValue(value, valuePath, context, 1);
@@ -208,6 +224,27 @@ function capAnchored(snapshot) {
     }
     return capped;
 }
+/** An entity's position, rotation (with its Euler order) and scale, as plain numbers. */
+function transformSnapshot(entity) {
+    return {
+        position: {
+            x: entity.position.x,
+            y: entity.position.y,
+            z: entity.position.z,
+        },
+        rotation: {
+            x: entity.node.rotation.x,
+            y: entity.node.rotation.y,
+            z: entity.node.rotation.z,
+            order: entity.node.rotation.order,
+        },
+        scale: {
+            x: entity.scale.x,
+            y: entity.scale.y,
+            z: entity.scale.z,
+        },
+    };
+}
 export class RuntimeInspector {
     game;
     ids = new WeakMap();
@@ -227,7 +264,7 @@ export class RuntimeInspector {
             if (nameFilter && !nameFilter.has(entity.name))
                 return [];
             const components = entity.components.flatMap((component, index) => {
-                const Class = component.constructor;
+                const Class = componentClassOf(component);
                 if (componentFilter && !componentFilter.has(Class.componentName))
                     return [];
                 const context = { issues: projectionIssues, seen: new Map() };
@@ -242,24 +279,7 @@ export class RuntimeInspector {
             return [{
                     id,
                     name: entity.name,
-                    transform: {
-                        position: {
-                            x: entity.position.x,
-                            y: entity.position.y,
-                            z: entity.position.z,
-                        },
-                        rotation: {
-                            x: entity.node.rotation.x,
-                            y: entity.node.rotation.y,
-                            z: entity.node.rotation.z,
-                            order: entity.node.rotation.order,
-                        },
-                        scale: {
-                            x: entity.scale.x,
-                            y: entity.scale.y,
-                            z: entity.scale.z,
-                        },
-                    },
+                    transform: transformSnapshot(entity),
                     components,
                 }];
         });

package/dist/scene.d.ts

@@ -86,7 +86,6 @@ export declare function resolveProps(props: Record<string, unknown> | undefined,
  * are never mutated; merged components are fresh objects.
  */
 export declare function resolveEntityComponents(entity: SceneEntityJson, prefabs?: Record<string, PrefabJson>): SceneComponentJson[];
-/** Instantiates a scene entity into the game. */
 export declare function spawnFromJson(game: Game, json: SceneEntityJson, registry: SceneRegistry): Entity;
 /**
  * Loads a full scene into the game, replacing whatever scene is already

package/dist/scene.js

@@ -56,6 +56,39 @@ export function resolveEntityComponents(entity, prefabs) {
     return [...fromPrefab, ...inline];
 }
 /** Instantiates a scene entity into the game. */
+/**
+ * Every member Component declares, checked against the class by `satisfies`:
+ * adding a member without listing it here fails to compile.
+ */
+const COMPONENT_MEMBERS = {
+    entity: true,
+    game: true,
+    inspectState: true,
+    onReady: true,
+    onUpdate: true,
+    onProjectionChange: true,
+    onCollide: true,
+    onContact: true,
+    onInteract: true,
+    onDestroy: true,
+};
+/**
+ * Scene props set none of Component's own members, so as far as the type
+ * system is concerned they are a Partial<Component> (their other keys are the
+ * subclass's public props, which Entity.add assigns).
+ */
+function isComponentProps(props) {
+    return Object.keys(props).every((key) => !Object.hasOwn(COMPONENT_MEMBERS, key));
+}
+/** Scene JSON props with any Component member dropped and reported. */
+function sceneProps(props, type, entityName) {
+    const dropped = Object.keys(props).filter((key) => Object.hasOwn(COMPONENT_MEMBERS, key));
+    const kept = Object.fromEntries(Object.entries(props).filter(([key]) => !dropped.includes(key)));
+    if (dropped.length > 0) {
+        console.warn(`[waica] component "${type}" on "${entityName}" ignores scene props that name Component members: ${dropped.join(', ')}`);
+    }
+    return isComponentProps(kept) ? kept : {};
+}
 export function spawnFromJson(game, json, registry) {
     const entity = game.spawn(json.name);
     if (json.position)
@@ -70,7 +103,7 @@ export function spawnFromJson(game, json, registry) {
         // code. A throwing constructor or onReady costs that one component —
         // never the rest of the scene, and never the editor hosting it.
         try {
-            entity.add(Class, resolveProps(comp.props, registry));
+            entity.add(Class, sceneProps(resolveProps(comp.props, registry), comp.type, json.name));
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);

package/dist/spatial-broadphase.js

@@ -47,12 +47,23 @@ function eachCell(range, visit) {
             visit(cellKey(x, y));
     }
 }
-/**
- * Package-internal fresh uniform grid. Bodies above the fixed occupancy cap
- * remain in an overflow bucket and are conservatively visible everywhere.
- */
-export function createSpatialBroadphase(sources, cellSize, isIndexable = usableCollisionBody) {
-    const entries = sources
+/** The value of the indexed entry at `index`; buckets and overflow only hold indices into `entries`. */
+function entryValue(entries, index) {
+    const entry = entries[index];
+    if (!entry)
+        throw new Error(`Spatial broadphase has no entry at index ${index}`);
+    return entry.value;
+}
+/** The entry index stored at `position` of a bucket that is iterated within its bounds. */
+function indexAt(bucket, position) {
+    const index = bucket[position];
+    if (index === undefined)
+        throw new Error(`Spatial broadphase bucket has no index at position ${position}`);
+    return index;
+}
+/** The indexable sources in query order, each with the cell range it covers. */
+function spatialEntries(sources, cellSize, isIndexable) {
+    return sources
         .map((source, serial) => {
         if (!isIndexable(source.body))
             return null;
@@ -64,6 +75,8 @@ export function createSpatialBroadphase(sources, cellSize, isIndexable = usableC
     })
         .filter((entry) => entry !== null)
         .sort((a, b) => a.order - b.order || a.serial - b.serial);
+}
+function spatialGrid(entries) {
     const buckets = new Map();
     const overflow = [];
     for (const [index, entry] of entries.entries()) {
@@ -79,6 +92,43 @@ export function createSpatialBroadphase(sources, cellSize, isIndexable = usableC
                 buckets.set(key, [index]);
         });
     }
+    return { buckets, overflow };
+}
+/** Distinct index pairs sharing a cell, or involving an overflow entry, in ascending order. */
+function candidatePairIndices(grid, entryCount) {
+    const pairKeys = new Set();
+    const width = entryCount;
+    const addPair = (left, right) => {
+        if (left === right)
+            return;
+        const first = Math.min(left, right);
+        const second = Math.max(left, right);
+        pairKeys.add(first * width + second);
+    };
+    for (const bucket of grid.buckets.values()) {
+        for (let left = 0; left < bucket.length; left += 1) {
+            for (let right = left + 1; right < bucket.length; right += 1) {
+                addPair(indexAt(bucket, left), indexAt(bucket, right));
+            }
+        }
+    }
+    for (const overflowIndex of grid.overflow) {
+        for (let index = 0; index < entryCount; index += 1) {
+            addPair(overflowIndex, index);
+        }
+    }
+    return [...pairKeys]
+        .map((key) => [Math.floor(key / width), key % width])
+        .sort(([a1, a2], [b1, b2]) => a1 - b1 || a2 - b2);
+}
+/**
+ * Package-internal fresh uniform grid. Bodies above the fixed occupancy cap
+ * remain in an overflow bucket and are conservatively visible everywhere.
+ */
+export function createSpatialBroadphase(sources, cellSize, isIndexable = usableCollisionBody) {
+    const entries = spatialEntries(sources, cellSize, isIndexable);
+    const grid = spatialGrid(entries);
+    const { buckets, overflow } = grid;
     return {
         stats: { indexed: entries.length - overflow.length, overflow: overflow.length },
         candidates(bounds) {
@@ -92,36 +142,12 @@ export function createSpatialBroadphase(sources, cellSize, isIndexable = usableC
             });
             return [...selected]
                 .sort((a, b) => a - b)
-                .map((index) => entries[index].value);
+                .map((index) => entryValue(entries, index));
         },
         pairs() {
-            const pairKeys = new Set();
-            const width = entries.length;
-            const addPair = (left, right) => {
-                if (left === right)
-                    return;
-                const first = Math.min(left, right);
-                const second = Math.max(left, right);
-                pairKeys.add(first * width + second);
-            };
-            for (const bucket of buckets.values()) {
-                for (let left = 0; left < bucket.length; left += 1) {
-                    for (let right = left + 1; right < bucket.length; right += 1) {
-                        addPair(bucket[left], bucket[right]);
-                    }
-                }
-            }
-            for (const overflowIndex of overflow) {
-                for (let index = 0; index < entries.length; index += 1) {
-                    addPair(overflowIndex, index);
-                }
-            }
-            return [...pairKeys]
-                .map((key) => [Math.floor(key / width), key % width])
-                .sort(([a1, a2], [b1, b2]) => a1 - b1 || a2 - b2)
-                .map(([first, second]) => [
-                entries[first].value,
-                entries[second].value,
+            return candidatePairIndices(grid, entries.length).map(([first, second]) => [
+                entryValue(entries, first),
+                entryValue(entries, second),
             ]);
         },
     };

package/dist/spatial-query-geometry.js

@@ -1,11 +1,18 @@
 import { collisionVertices, } from './collision-shape.js';
 /** Internal absolute tolerance shared by point and ray boundary rules. */
 export const SPATIAL_QUERY_EPSILON = 1e-9;
+/** The item at an `index` the caller already bounded to `items.length`. */
+function itemAt(items, index) {
+    const item = items[index];
+    if (item === undefined)
+        throw new Error(`Spatial query geometry has no item at index ${index} of ${items.length}`);
+    return item;
+}
 function signedArea(points) {
     let twiceArea = 0;
     for (let index = 0; index < points.length; index += 1) {
-        const point = points[index];
-        const next = points[(index + 1) % points.length];
+        const point = itemAt(points, index);
+        const next = itemAt(points, (index + 1) % points.length);
         twiceArea += point[0] * next[1] - next[0] * point[1];
     }
     return twiceArea / 2;
@@ -46,8 +53,8 @@ function pointOnSegment(point, a, b) {
 function polygonPointLocation(polygon, point) {
     let inside = false;
     for (let index = 0, previous = polygon.length - 1; index < polygon.length; previous = index, index += 1) {
-        const a = polygon[index];
-        const b = polygon[previous];
+        const a = itemAt(polygon, index);
+        const b = itemAt(polygon, previous);
         if (pointOnSegment(point, a, b))
             return 'boundary';
         const crosses = (a[1] > point[1]) !== (b[1] > point[1]) &&
@@ -130,12 +137,13 @@ function groupEvents(events) {
     const sorted = [...events].sort((a, b) => a.distance === b.distance ? a.edgeOrder - b.edgeOrder : a.distance - b.distance);
     const groups = [];
     for (const event of sorted) {
-        const current = groups.at(-1);
+        let current = groups.at(-1);
         if (!current || Math.abs(event.distance - current.distance) > SPATIAL_QUERY_EPSILON) {
-            groups.push({ distance: event.distance, normals: [] });
+            current = { distance: event.distance, normals: [] };
+            groups.push(current);
         }
         if (event.normal) {
-            groups.at(-1).normals.push({ edgeOrder: event.edgeOrder, normal: event.normal });
+            current.normals.push({ edgeOrder: event.edgeOrder, normal: event.normal });
         }
     }
     return groups.map((group) => ({
@@ -167,6 +175,30 @@ function selectVertexNormal(normals, direction, crossing) {
     }
     return selected;
 }
+/** Every edge's ray events, for each edge with a usable outward normal. */
+function polygonEdgeEvents(polygon, winding, ray) {
+    const events = [];
+    for (let index = 0; index < polygon.length; index += 1) {
+        const a = itemAt(polygon, index);
+        const b = itemAt(polygon, (index + 1) % polygon.length);
+        const normal = edgeNormal(a, b, winding);
+        if (!normal)
+            continue;
+        events.push(...edgeEvents(ray.origin, ray.direction, ray.maxDistance, a, b, normal, index));
+    }
+    return events;
+}
+/**
+ * Whether the ray enters or leaves the polygon at an event group, from where
+ * it was just before and just after it. A ray starting on the boundary and
+ * heading inside counts as entering.
+ */
+function boundaryCrossing(distance, before, after) {
+    if ((before === 'outside' || (distance === 0 && before === 'boundary')) && after === 'inside') {
+        return 'entry';
+    }
+    return before === 'inside' && after === 'outside' ? 'exit' : null;
+}
 function polygonRay(body, origin, direction, maxDistance) {
     const polygon = collisionVertices(body);
     if (!polygon.every(([x, y]) => Number.isFinite(x) && Number.isFinite(y)))
@@ -175,21 +207,12 @@ function polygonRay(body, origin, direction, maxDistance) {
     if (Math.abs(area) <= SPATIAL_QUERY_EPSILON)
         return null;
     const winding = area > 0 ? 1 : -1;
-    const events = [];
-    for (let index = 0; index < polygon.length; index += 1) {
-        const a = polygon[index];
-        const b = polygon[(index + 1) % polygon.length];
-        const normal = edgeNormal(a, b, winding);
-        if (!normal)
-            continue;
-        events.push(...edgeEvents(origin, direction, maxDistance, a, b, normal, index));
-    }
-    const groups = groupEvents(events);
+    const groups = groupEvents(polygonEdgeEvents(polygon, winding, { origin, direction, maxDistance }));
     const originLocation = polygonPointLocation(polygon, origin);
     const scale = Math.max(Math.abs(body.width), Math.abs(body.height), 1);
     const terminalProbe = Math.max(SPATIAL_QUERY_EPSILON * 4, Math.min(scale * 1e-6, 1e-3));
     for (let index = 0; index < groups.length; index += 1) {
-        const group = groups[index];
+        const group = itemAt(groups, index);
         if (group.distance > maxDistance + SPATIAL_QUERY_EPSILON)
             break;
         const previous = groups[index - 1];
@@ -198,15 +221,7 @@ function polygonRay(body, origin, direction, maxDistance) {
             ? originLocation
             : polygonPointLocation(polygon, pointAlongRay(origin, direction, previous ? (previous.distance + group.distance) / 2 : group.distance / 2));
         const afterLocation = polygonPointLocation(polygon, pointAlongRay(origin, direction, next ? (group.distance + next.distance) / 2 : group.distance + terminalProbe));
-        let crossing = null;
-        if ((beforeLocation === 'outside' ||
-            (group.distance === 0 && beforeLocation === 'boundary')) &&
-            afterLocation === 'inside') {
-            crossing = 'entry';
-        }
-        else if (beforeLocation === 'inside' && afterLocation === 'outside') {
-            crossing = 'exit';
-        }
+        const crossing = boundaryCrossing(group.distance, beforeLocation, afterLocation);
         if (!crossing)
             continue;
         const normal = selectVertexNormal(group.normals, direction, crossing);
@@ -257,14 +272,12 @@ function ellipseRay(body, origin, direction, maxDistance) {
         halfChordDistance <= SPATIAL_QUERY_EPSILON) {
         return null;
     }
-    const roots = [
-        (closestParameter - halfChordParameter) / directionScale,
-        (closestParameter + halfChordParameter) / directionScale,
-    ];
-    const rawDistance = roots[0] >= -SPATIAL_QUERY_EPSILON
-        ? roots[0]
-        : roots[1] > SPATIAL_QUERY_EPSILON
-            ? roots[1]
+    const nearRoot = (closestParameter - halfChordParameter) / directionScale;
+    const farRoot = (closestParameter + halfChordParameter) / directionScale;
+    const rawDistance = nearRoot >= -SPATIAL_QUERY_EPSILON
+        ? nearRoot
+        : farRoot > SPATIAL_QUERY_EPSILON
+            ? farRoot
             : undefined;
     if (rawDistance === undefined || !inRayRange(rawDistance, maxDistance))
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.19.0",
+  "version": "0.19.2",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",
@@ -20,7 +20,7 @@
     }
   },
   "dependencies": {
-    "@types/three": "^0.185.1",
-    "three": "^0.185.1"
+    "@types/three": "^0.186.0",
+    "three": "^0.186.1"
   }
 }