@jgengine/core 0.11.0 → 0.12.0

package/dist/runtime/context/scene.js

@@ -0,0 +1,291 @@
+import { createBodyBind } from "../../scene/bodyBind.js";
+import { createEntityStatsApi, seedStatValues, } from "../../scene/entityStats.js";
+import { createEntityStore, } from "../../scene/entityStore.js";
+import { createForms } from "../../scene/form.js";
+import { fittedEntityColliders, fittedObjectColliders, scaledEntityColliders, scaledObjectColliders, } from "../../scene/colliders.js";
+import { raycastObjects, raycastObjectsAll } from "../../scene/objectQuery.js";
+import { createObjectStore, objectVisualScale } from "../../scene/objectStore.js";
+import { createPaintLayer } from "../../scene/paintLayer.js";
+import { createSelectionSet } from "../../scene/selection.js";
+import { createSceneRaycast, } from "../../scene/sceneRaycast.js";
+import { createSpatialApi } from "../../scene/spatial.js";
+import { createTargeting } from "../../scene/targeting.js";
+import { notifyAfter } from "../../store/changeSignal.js";
+/** @internal */
+export function createSceneSubsystem(d) {
+    const { content, signalNotify, ground, events, time, occluder } = d;
+    const entities = createEntityStore();
+    const objects = createObjectStore();
+    entities.subscribe(signalNotify);
+    objects.subscribe(signalNotify);
+    const statsByInstance = new Map();
+    const entityStats = notifyAfter(createEntityStatsApi((instanceId) => statsByInstance.get(instanceId)), ["set", "delta"], signalNotify);
+    function ensureInstanceStats(instanceId) {
+        let map = statsByInstance.get(instanceId);
+        if (map === undefined) {
+            map = {};
+            statsByInstance.set(instanceId, map);
+        }
+        return map;
+    }
+    function catalogEntry(instanceId) {
+        const entity = entities.get(instanceId);
+        return entity === null ? undefined : content.entityById?.(entity.name);
+    }
+    function catalogObject(instanceId) {
+        const object = objects.get(instanceId);
+        return object === null ? undefined : content.objectById?.(object.catalogId);
+    }
+    let spatialGeneration = 0;
+    const candidateIds = [];
+    let candidateIdsDirty = true;
+    function refreshCandidateIds() {
+        if (!candidateIdsDirty)
+            return candidateIds;
+        candidateIds.length = 0;
+        for (const entity of entities.list())
+            candidateIds.push(entity.id);
+        candidateIdsDirty = false;
+        return candidateIds;
+    }
+    const spatial = createSpatialApi({
+        resolvePosition: (instanceId) => entities.get(instanceId)?.position,
+        candidates: refreshCandidateIds,
+        grid: { cellSize: 8 },
+        getVersion: () => spatialGeneration,
+        ...(occluder !== undefined ? { occluder } : {}),
+    });
+    entities.subscribe(() => {
+        candidateIdsDirty = true;
+        spatialGeneration += 1;
+        spatial.invalidate();
+    });
+    const entityColliders = new Map();
+    const objectColliders = new Map();
+    const fittedEntityByKind = new Map();
+    const fittedObjectByCatalogId = new Map();
+    function fittedEntitySetFor(kind) {
+        const cached = fittedEntityByKind.get(kind);
+        if (cached !== undefined)
+            return cached;
+        const model = d.models?.entity?.(kind);
+        const fitted = model === null || model === undefined ? null : fittedEntityColliders(model);
+        fittedEntityByKind.set(kind, fitted);
+        return fitted;
+    }
+    function fittedObjectSetFor(catalogId) {
+        const cached = fittedObjectByCatalogId.get(catalogId);
+        if (cached !== undefined)
+            return cached;
+        const model = d.models?.object?.(catalogId);
+        const fitted = model === null || model === undefined ? null : fittedObjectColliders(model);
+        fittedObjectByCatalogId.set(catalogId, fitted);
+        return fitted;
+    }
+    function entityCollidersOf(instanceId) {
+        const override = entityColliders.get(instanceId);
+        if (override !== undefined)
+            return override;
+        const entry = catalogEntry(instanceId);
+        if (entry?.colliders !== undefined)
+            return entry.colliders;
+        const kind = entities.get(instanceId)?.name;
+        if (kind !== undefined) {
+            const fitted = fittedEntitySetFor(kind);
+            if (fitted !== null)
+                return fitted;
+        }
+        const scale = entry?.scale;
+        if (scale !== undefined && scale !== 1)
+            return scaledEntityColliders(scale);
+        return null;
+    }
+    function entityVisualScaleOf(instanceId) {
+        return catalogEntry(instanceId)?.scale ?? 1;
+    }
+    function objectCollidersOf(instanceId) {
+        const override = objectColliders.get(instanceId);
+        if (override !== undefined)
+            return override;
+        const catalog = catalogObject(instanceId);
+        if (catalog?.colliders !== undefined)
+            return catalog.colliders;
+        if (catalog?.halfExtents !== undefined)
+            return null;
+        const object = objects.get(instanceId);
+        if (object === null)
+            return null;
+        const fitted = fittedObjectSetFor(object.catalogId);
+        if (fitted !== null)
+            return fitted;
+        if (object.visual?.scale === undefined)
+            return null;
+        return scaledObjectColliders(objectVisualScale(object.visual));
+    }
+    const targeting = notifyAfter(createTargeting({
+        candidates: () => [...refreshCandidateIds()],
+        classify(_fromId, toId) {
+            const role = catalogEntry(toId)?.role;
+            return role === "enemy" || role === "hostile" ? "hostile" : "friendly";
+        },
+        distance: (fromId, toId) => spatial.distance(fromId, toId),
+    }), ["setTarget", "cycleTarget"], signalNotify);
+    const combatSpatial = {
+        inRadius: (center, radius) => spatial.inRadius(center, radius),
+        hasLineOfSight: (from, to) => {
+            if (typeof from === "string")
+                return spatial.hasLineOfSight(from, to);
+            const toPos = entities.get(to)?.position;
+            if (toPos === undefined)
+                return false;
+            if (occluder === undefined)
+                return true;
+            return !occluder(from, toPos);
+        },
+        positionOf: (instanceId) => entities.get(instanceId)?.position,
+    };
+    const sceneRaycast = createSceneRaycast({
+        entities: {
+            list: () => entities.list().map((entity) => ({
+                id: entity.id,
+                position: entity.position,
+                rotationY: entity.rotationY,
+                name: entity.name,
+            })),
+            collidersOf: entityCollidersOf,
+            inRadius: (center, radius) => spatial.inRadius(center, radius),
+            get: (id) => {
+                const entity = entities.get(id);
+                if (entity === null)
+                    return null;
+                return { id: entity.id, position: entity.position, rotationY: entity.rotationY, name: entity.name };
+            },
+        },
+        objects: {
+            list: () => objects.list(),
+            inBox: (min, max) => objects.inBox(min, max),
+            collidersOf: objectCollidersOf,
+            halfExtentsOf: (catalogId) => content.objectById?.(catalogId)?.halfExtents ?? null,
+        },
+        terrain: ground,
+    });
+    const forms = notifyAfter(createForms({ entities, time, events }), ["shapeshift", "revert"], signalNotify);
+    const paintLayer = notifyAfter(createPaintLayer(), ["paint", "clear"], signalNotify);
+    let onAfterSpawn = () => { };
+    let onAfterDespawn = () => { };
+    function spawnEntity(name, spawnOptions) {
+        const entry = content.entityById?.(name);
+        const walkSpeed = spawnOptions?.movement?.walkSpeed ?? entry?.movement?.walkSpeed;
+        const options = walkSpeed === undefined
+            ? spawnOptions
+            : { ...spawnOptions, movement: { ...spawnOptions?.movement, walkSpeed } };
+        const instanceId = entities.spawn(name, options);
+        onAfterSpawn(instanceId);
+        statsByInstance.set(instanceId, entry?.stats === undefined ? {} : seedStatValues(entry.stats));
+        return instanceId;
+    }
+    function despawnEntity(instanceId) {
+        const existed = entities.despawn(instanceId);
+        statsByInstance.delete(instanceId);
+        targeting.clearAll(instanceId);
+        entityColliders.delete(instanceId);
+        onAfterDespawn(instanceId);
+        return existed;
+    }
+    function moveEntityTowardCommit(instanceId, target, options) {
+        const next = spatial.moveToward(instanceId, target, options);
+        if (next === null)
+            return null;
+        const current = entities.get(instanceId);
+        if (current === null)
+            return null;
+        let rotationY = current.rotationY;
+        if (options.face === true) {
+            const dx = next[0] - current.position[0];
+            const dz = next[2] - current.position[2];
+            if (Math.hypot(dx, dz) > 1e-9)
+                rotationY = Math.atan2(dx, dz);
+        }
+        entities.setPose(instanceId, { position: next, rotationY });
+        return next;
+    }
+    function resetAllToSpawn(filter) {
+        let count = 0;
+        for (const entity of entities.list()) {
+            if (filter !== undefined && !filter(entity))
+                continue;
+            if (entities.resetToSpawn(entity.id))
+                count += 1;
+        }
+        return count;
+    }
+    const bodyBinds = new Map();
+    function bind(key) {
+        const existing = bodyBinds.get(key);
+        if (existing !== undefined)
+            return existing;
+        const created = createBodyBind({
+            has: (id) => entities.get(id) !== null,
+            spawn: spawnEntity,
+            despawn: despawnEntity,
+            setPose: entities.setPose,
+            update: entities.update,
+        });
+        bodyBinds.set(key, created);
+        return created;
+    }
+    const objectSelection = notifyAfter(createSelectionSet(), ["add", "remove", "toggle", "replace", "clear"], signalNotify);
+    const sceneObjects = {
+        ...objects,
+        remove(instanceId) {
+            const existed = objects.remove(instanceId);
+            if (existed)
+                objectSelection.remove(instanceId);
+            return existed;
+        },
+        catalog: (instanceId) => catalogObject(instanceId) ?? null,
+        raycast: (input) => raycastObjects(objects, input),
+        raycastAll: (input) => raycastObjectsAll(objects, input),
+        setColliders(instanceId, colliders) {
+            if (colliders === null)
+                objectColliders.delete(instanceId);
+            else
+                objectColliders.set(instanceId, colliders);
+            signalNotify();
+        },
+        collidersOf: objectCollidersOf,
+        selection: objectSelection,
+    };
+    return {
+        entities,
+        objects,
+        statsByInstance,
+        entityStats,
+        ensureInstanceStats,
+        catalogEntry,
+        catalogObject,
+        spatial,
+        combatSpatial,
+        sceneRaycast,
+        targeting,
+        entityColliders,
+        objectColliders,
+        entityCollidersOf,
+        objectCollidersOf,
+        entityVisualScaleOf,
+        forms,
+        paintLayer,
+        spawnEntity,
+        despawnEntity,
+        moveEntityTowardCommit,
+        resetAllToSpawn,
+        bind,
+        sceneObjects,
+        setOnAfterSpawn(fn) {
+            onAfterSpawn = fn;
+        },
+        setOnAfterDespawn(fn) {
+            onAfterDespawn = fn;
+        },
+    };
+}

package/dist/runtime/context/snapshotCodecs.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shallow wire codecs for {@link SnapshotModule.decode} — reject obviously wrong shapes so hydrate
+ * never receives bare casts of garbage. Fail soft (return `null`); deeper field validation stays with
+ * each subsystem's hydrate.
+ * @internal
+ */
+/** @internal Reject non-arrays; return a typed array or null. */
+export declare function decodeArray<T = unknown>(raw: unknown): T[] | null;
+/** @internal Reject non-plain objects; return a typed record or null. */
+export declare function decodeRecord<T = unknown>(raw: unknown): Record<string, T> | null;
+/** @internal Reject non-[string, T][] entry lists; return entries or null. */
+export declare function decodeEntries<T = unknown>(raw: unknown): readonly (readonly [string, T])[] | null;

package/dist/runtime/context/snapshotCodecs.js

@@ -0,0 +1,26 @@
+/**
+ * Shallow wire codecs for {@link SnapshotModule.decode} — reject obviously wrong shapes so hydrate
+ * never receives bare casts of garbage. Fail soft (return `null`); deeper field validation stays with
+ * each subsystem's hydrate.
+ * @internal
+ */
+/** @internal Reject non-arrays; return a typed array or null. */
+export function decodeArray(raw) {
+    return Array.isArray(raw) ? raw : null;
+}
+/** @internal Reject non-plain objects; return a typed record or null. */
+export function decodeRecord(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    return raw;
+}
+/** @internal Reject non-[string, T][] entry lists; return entries or null. */
+export function decodeEntries(raw) {
+    if (!Array.isArray(raw))
+        return null;
+    for (const entry of raw) {
+        if (!Array.isArray(entry) || entry.length < 2 || typeof entry[0] !== "string")
+            return null;
+    }
+    return raw;
+}

package/dist/runtime/descriptors/baseline.js

@@ -1,4 +1,5 @@
 import { hydrateEntityStats, snapshotEntityStats, } from "../../scene/entityStats.js";
+import { decodeArray, decodeEntries, decodeRecord } from "../context/snapshotCodecs.js";
 /** @internal */
 export const baselineDescriptors = [
     {
@@ -7,6 +8,7 @@ export const baselineDescriptors = [
             replicate: {
                 key: "entities",
                 snapshot: () => d.entities.snapshot(),
+                decode: (raw) => decodeArray(raw),
                 hydrate: (data) => d.entities.hydrate(data),
             },
         }),
@@ -17,6 +19,7 @@ export const baselineDescriptors = [
             replicate: {
                 key: "stats",
                 snapshot: () => snapshotEntityStats(d.statsByInstance),
+                decode: (raw) => decodeRecord(raw),
                 hydrate: (data) => hydrateEntityStats(d.statsByInstance, data),
             },
         }),
@@ -27,6 +30,7 @@ export const baselineDescriptors = [
             replicate: {
                 key: "store",
                 snapshot: () => d.store.snapshot(),
+                decode: (raw) => decodeEntries(raw),
                 hydrate: (data) => d.store.hydrate(data),
             },
         }),
@@ -37,6 +41,7 @@ export const baselineDescriptors = [
             replicate: {
                 key: "feed",
                 snapshot: () => d.feed.snapshot(),
+                decode: (raw) => decodeRecord(raw),
                 hydrate: (data) => d.feed.hydrate(data),
             },
         }),
@@ -56,8 +61,10 @@ export const baselineDescriptors = [
                     }
                     return byUser;
                 },
+                decode: (raw) => decodeRecord(raw),
                 hydrate: (data) => {
-                    for (const [userId, states] of Object.entries(data)) {
+                    const byUser = data;
+                    for (const [userId, states] of Object.entries(byUser)) {
                         const set = d.inventoryFor(userId);
                         for (const [inventoryId, state] of Object.entries(states))
                             set.replaceState(inventoryId, state);
@@ -72,9 +79,11 @@ export const baselineDescriptors = [
             save: {
                 key: "economy",
                 snapshot: () => Object.fromEntries(d.wallets),
+                decode: (raw) => decodeRecord(raw),
                 hydrate: (data) => {
+                    const wallets = data;
                     d.wallets.clear();
-                    for (const [userId, state] of Object.entries(data)) {
+                    for (const [userId, state] of Object.entries(wallets)) {
                         d.wallets.set(userId, state);
                     }
                     d.signalNotify();
@@ -88,6 +97,10 @@ export const baselineDescriptors = [
             save: {
                 key: "time",
                 snapshot: () => d.time.snapshot(),
+                decode: (raw) => {
+                    const rec = decodeRecord(raw);
+                    return rec === null ? null : rec;
+                },
                 hydrate: (data) => d.time.hydrate(data),
             },
         }),
@@ -98,6 +111,10 @@ export const baselineDescriptors = [
             save: {
                 key: "pose",
                 snapshot: () => d.pose.snapshotAll(),
+                decode: (raw) => {
+                    const rec = decodeRecord(raw);
+                    return rec === null ? null : rec;
+                },
                 hydrate: (data) => d.pose.hydrateAll(data),
             },
         }),
@@ -108,6 +125,10 @@ export const baselineDescriptors = [
             save: {
                 key: "possession",
                 snapshot: () => d.possession.snapshotAll(),
+                decode: (raw) => {
+                    const rec = decodeRecord(raw);
+                    return rec === null ? null : rec;
+                },
                 hydrate: (data) => d.possession.hydrateAll(data),
             },
         }),
@@ -123,8 +144,10 @@ export const baselineDescriptors = [
                         out[userId] = queue.snapshot();
                     return out;
                 },
+                decode: (raw) => decodeRecord(raw),
                 hydrate: (data) => {
-                    for (const [userId, batch] of Object.entries(data)) {
+                    const batches = data;
+                    for (const [userId, batch] of Object.entries(batches)) {
                         d.motionFor(userId).hydrate(batch);
                     }
                 },

package/dist/runtime/descriptors/features.d.ts

@@ -63,6 +63,11 @@ export interface FeatureBuild {
  * {@link FeatureDeps}, and whether it replicates or persists. `createGameContext` iterates the
  * descriptor list instead of hand-wiring each `features.x ? create : undefined` branch — the seam a
  * new feature extends through.
+ *
+ * Feature activation has **one path**: `definition.features` after `defineGame` has already
+ * OR-merged explicit `features: { quest: true }` sugar with system-implied flags via
+ * `mergeSystemFeatures`. Descriptors only call `enabled(features)` against that final map — never
+ * re-check systems or a second flag source.
  * @internal
  */
 export interface FeatureDescriptor {

package/dist/runtime/descriptors/features.js

@@ -10,6 +10,7 @@ import { createUnlocks } from "../../game/unlocks.js";
 import { createRoster } from "../../scene/roster.js";
 import { createConnectedPlayers } from "../../game/connectedPlayers.js";
 import { notifyAfter } from "../../store/changeSignal.js";
+import { decodeArray, decodeRecord } from "../context/snapshotCodecs.js";
 /** @internal */
 export const featureDescriptors = [
     {
@@ -22,6 +23,7 @@ export const featureDescriptors = [
                 save: {
                     key: "unlocks",
                     snapshot: () => unlocks.snapshotAll(),
+                    decode: (raw) => decodeRecord(raw),
                     hydrate: (data) => unlocks.hydrateAll(data),
                 },
             };
@@ -49,6 +51,10 @@ export const featureDescriptors = [
                 replicate: {
                     key: "social",
                     snapshot: () => social.snapshot(),
+                    decode: (rawVal) => {
+                        const rec = decodeRecord(rawVal);
+                        return rec === null ? null : rec;
+                    },
                     hydrate: (data) => social.hydrate(data),
                 },
             };
@@ -74,6 +80,10 @@ export const featureDescriptors = [
                 replicate: {
                     key: "chat",
                     snapshot: () => chat.snapshot(),
+                    decode: (rawVal) => {
+                        const rec = decodeRecord(rawVal);
+                        return rec === null ? null : rec;
+                    },
                     hydrate: (data) => chat.hydrate(data),
                 },
             };
@@ -89,6 +99,7 @@ export const featureDescriptors = [
                 replicate: {
                     key: "leaderboard",
                     snapshot: () => leaderboard.snapshot(),
+                    decode: (raw) => decodeArray(raw),
                     hydrate: (data) => leaderboard.hydrate(data),
                 },
             };
@@ -104,6 +115,7 @@ export const featureDescriptors = [
                 save: {
                     key: "roster",
                     snapshot: () => roster.snapshotAll(),
+                    decode: (raw) => decodeRecord(raw),
                     hydrate: (data) => roster.hydrateAll(data),
                 },
             };
@@ -119,6 +131,7 @@ export const featureDescriptors = [
                 save: {
                     key: "cosmetics",
                     snapshot: () => cosmetics.snapshotAll(),
+                    decode: (raw) => decodeRecord(raw),
                     hydrate: (data) => cosmetics.hydrateAll(data),
                 },
             };
@@ -193,6 +206,7 @@ export const featureDescriptors = [
                 save: {
                     key: "quest",
                     snapshot: () => quest.snapshotAll(),
+                    decode: (raw) => decodeRecord(raw),
                     hydrate: (data) => quest.hydrateAll(data),
                 },
             };
@@ -239,8 +253,10 @@ export const featureDescriptors = [
                             out[id] = cardPile.state();
                         return out;
                     },
+                    decode: (raw) => decodeRecord(raw),
                     hydrate: (data) => {
-                        for (const [id, state] of Object.entries(data)) {
+                        const piles = data;
+                        for (const [id, state] of Object.entries(piles)) {
                             d.cardPiles.get(id)?.reset(state);
                         }
                     },
@@ -262,8 +278,10 @@ export const featureDescriptors = [
                             out[id] = turnLoop.capture();
                         return out;
                     },
+                    decode: (raw) => decodeRecord(raw),
                     hydrate: (data) => {
-                        for (const [id, state] of Object.entries(data)) {
+                        const loops = data;
+                        for (const [id, state] of Object.entries(loops)) {
                             d.turnLoops.get(id)?.restore(state);
                         }
                     },