@jgengine/core 0.9.0 → 0.11.0

package/dist/scene/entityStore.d.ts

@@ -22,9 +22,16 @@ export interface SceneEntity<TMeta = unknown> {
     role: EntityRole;
     movement: EntityMovement;
     behaviors: readonly BehaviorDescriptor[];
-    /** Game-defined per-instance data set at `spawn`/`update` and carried to `renderEntity`/queries — narrow with a cast or type guard on read (#286.1); never encode state in the id/name string. */
+    /** Game-defined per-instance data set at `spawn`/`update` and carried to `renderEntity`/queries — narrow with {@link entityMetaOf} (or a type guard) on read (#286.1); never encode state in the id/name string. */
     meta: TMeta;
 }
+/**
+ * Narrow `entity.meta` with a type guard — prefer this over `entity.meta as T` so failed shapes return `null`
+ * instead of lying to the type checker.
+ *
+ * @capability entity-meta cast-free narrow of SceneEntity.meta via a type guard
+ */
+export declare function entityMetaOf<T>(entity: SceneEntity<unknown>, isMeta: (value: unknown) => value is T): T | null;
 /** Ground speed (horizontal magnitude of velocity) in world units per second. Scale to km/h or mph in game code. */
 export declare function groundSpeed(entity: SceneEntity<unknown>): number;
 export declare function movedWhileFrozen(entity: SceneEntity<unknown>, threshold?: number): boolean;
@@ -65,6 +72,28 @@ export type EntityUpdatePatch<TMeta = unknown> = Partial<Pick<SceneEntity<TMeta>
     /** Accepts the same friendly shapes as `spawn`/`setPose` (#286.13). Raw patch semantics — velocity is not derived; use `setPose` with `dt` for that. */
     position?: SpawnPositionInput;
 };
+/**
+ * Per-entity scratch and cooldown timers, auto-cleared on despawn (#533.8) — the home for AI state
+ * (next-shot-at, alert level) that would otherwise be smuggled through the serializable `meta` or a
+ * hand-pruned module-level map. Keys share one namespace per entity: `arm`/`ready`/`remaining` store a
+ * deadline under a key, `get`/`set` store arbitrary scratch.
+ */
+export interface EntityBlackboard {
+    /** Read a scratch value; `undefined` if unset or the entity has despawned. */
+    get<T>(id: string, key: string): T | undefined;
+    /** Write a scratch value; does not notify subscribers, and clears when the entity despawns. */
+    set(id: string, key: string, value: unknown): void;
+    has(id: string, key: string): boolean;
+    delete(id: string, key: string): void;
+    /** Drop all scratch and timers for one entity. */
+    clear(id: string): void;
+    /** Arm a cooldown for `key` that stays busy until absolute time `untilMs`. */
+    arm(id: string, key: string, untilMs: number): void;
+    /** True when no cooldown is armed for `key`, or its deadline has passed. */
+    ready(id: string, key: string, nowMs: number): boolean;
+    /** Milliseconds until the armed cooldown elapses; 0 when ready. */
+    remaining(id: string, key: string, nowMs: number): number;
+}
 export interface EntityStore<TMeta = unknown> {
     spawn(name: string, options?: SpawnOptions<TMeta>): string;
     despawn(id: string): boolean;
@@ -74,10 +103,21 @@ export interface EntityStore<TMeta = unknown> {
     setPoseConstraint(id: string, constraint: PoseConstraint | null): void;
     get(id: string): SceneEntity<TMeta> | null;
     list(): readonly SceneEntity<TMeta>[];
+    /** Stable-identity list of live entity ids; identity changes only on spawn/despawn/hydrate, not on pose writes. Pair with {@link subscribeMembership} for membership-only React subscriptions that skip per-frame pose churn (#625). */
+    ids(): readonly string[];
     clear(): void;
     subscribe(listener: () => void): () => void;
+    /** Notified only when the entity set changes (spawn/despawn/hydrate), never on a pose or field update — the render tree re-reconciles on membership, individual markers read live poses imperatively. */
+    subscribeMembership(listener: () => void): () => void;
     snapshot(): readonly SceneEntity<TMeta>[];
+    /**
+     * Apply a `snapshot()` (e.g. from an authoritative host) to this store — the counterpart of `snapshot()`
+     * for host→client world mirroring: spawns entities present in the snapshot but not here, overwrites
+     * existing ones field-for-field (including velocity), and despawns any local entity absent from it.
+     */
+    hydrate(entities: readonly SceneEntity<TMeta>[]): void;
     spawnPoseOf(id: string): SpawnPose | null;
     resetToSpawn(id: string): boolean;
+    blackboard: EntityBlackboard;
 }
 export declare function createEntityStore<TMeta = unknown>(): EntityStore<TMeta>;

package/dist/scene/entityStore.js

@@ -1,4 +1,13 @@
 import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
+/**
+ * Narrow `entity.meta` with a type guard — prefer this over `entity.meta as T` so failed shapes return `null`
+ * instead of lying to the type checker.
+ *
+ * @capability entity-meta cast-free narrow of SceneEntity.meta via a type guard
+ */
+export function entityMetaOf(entity, isMeta) {
+    return isMeta(entity.meta) ? entity.meta : null;
+}
 /** Ground speed (horizontal magnitude of velocity) in world units per second. Scale to km/h or mph in game code. */
 export function groundSpeed(entity) {
     return Math.hypot(entity.velocity[0], entity.velocity[2]);
@@ -21,7 +30,34 @@ export function createEntityStore() {
     const store = createObservableKeyedStore();
     const spawnPoses = new Map();
     const constraints = new Map();
+    const blackboards = new Map();
     let nextCounter = 1;
+    const blackboard = {
+        get: (id, key) => blackboards.get(id)?.get(key),
+        set(id, key, value) {
+            const board = blackboards.get(id) ?? new Map();
+            board.set(key, value);
+            blackboards.set(id, board);
+        },
+        has: (id, key) => blackboards.get(id)?.has(key) ?? false,
+        delete(id, key) {
+            blackboards.get(id)?.delete(key);
+        },
+        clear(id) {
+            blackboards.delete(id);
+        },
+        arm(id, key, untilMs) {
+            this.set(id, key, untilMs);
+        },
+        ready(id, key, nowMs) {
+            const until = blackboards.get(id)?.get(key);
+            return typeof until !== "number" || nowMs >= until;
+        },
+        remaining(id, key, nowMs) {
+            const until = blackboards.get(id)?.get(key);
+            return typeof until === "number" ? Math.max(0, until - nowMs) : 0;
+        },
+    };
     function generateId() {
         let id = `entity-${nextCounter}`;
         while (store.has(id)) {
@@ -39,6 +75,7 @@ export function createEntityStore() {
                     return options.id;
                 if (onExisting === "throw")
                     throw new Error(`Scene entity id "${options.id}" is already spawned.`);
+                blackboards.delete(options.id);
             }
             const id = options.id ?? generateId();
             const position = toEntityPosition(options.position);
@@ -64,6 +101,7 @@ export function createEntityStore() {
             store.delete(id);
             spawnPoses.delete(id);
             constraints.delete(id);
+            blackboards.delete(id);
             return existed;
         },
         update(id, patch) {
@@ -138,18 +176,54 @@ export function createEntityStore() {
         list() {
             return store.arraySnapshot();
         },
+        ids() {
+            return store.keysSnapshot();
+        },
         clear() {
             for (const entity of store.arraySnapshot()) {
                 store.delete(entity.id);
             }
             constraints.clear();
+            blackboards.clear();
         },
         subscribe(listener) {
             return store.subscribe(listener);
         },
+        subscribeMembership(listener) {
+            return store.subscribeMembership(listener);
+        },
         snapshot() {
             return store.arraySnapshot();
         },
+        hydrate(entities) {
+            const incoming = new Set(entities.map((entity) => entity.id));
+            for (const current of store.arraySnapshot()) {
+                if (!incoming.has(current.id)) {
+                    store.delete(current.id);
+                    spawnPoses.delete(current.id);
+                    constraints.delete(current.id);
+                    blackboards.delete(current.id);
+                }
+            }
+            for (const entity of entities) {
+                store.set(entity.id, {
+                    id: entity.id,
+                    name: entity.name,
+                    position: entity.position,
+                    rotationY: entity.rotationY,
+                    rotationX: entity.rotationX,
+                    rotationZ: entity.rotationZ,
+                    velocity: entity.velocity,
+                    role: entity.role,
+                    movement: entity.movement,
+                    behaviors: entity.behaviors,
+                    meta: entity.meta,
+                });
+                if (!spawnPoses.has(entity.id)) {
+                    spawnPoses.set(entity.id, { position: entity.position, rotationY: entity.rotationY });
+                }
+            }
+        },
         spawnPoseOf(id) {
             return spawnPoses.get(id) ?? null;
         },
@@ -164,5 +238,6 @@ export function createEntityStore() {
             store.set(id, current);
             return true;
         },
+        blackboard,
     };
 }

package/dist/scene/facing.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The forward-axis convention: a generator or scene kind declares which way its "front" faces (a
+ * bookcase's open/book face, a building's entrance) once, as data, instead of leaving every placement
+ * to hand-tuned `rotationY` trial-and-error. `StudioStage`'s `faceCamera` (`@jgengine/shell/scene/
+ * StudioStage`) reads the declared axis to auto-orient a product shot; a placement tool can read the
+ * same field to face a freshly dropped asset toward the camera/path by default. `DEFAULT_FORWARD`
+ * (+Z) is what a generator/scene-kind gets when it omits `forward` — build your front toward it.
+ * @capability forward-axis declared front convention for parametric assets — auto-orient product shots
+ */
+export declare const DEFAULT_FORWARD: readonly [number, number, number];
+/**
+ * The yaw (radians, around Y) that rotates `forward` so it points from `origin` toward `target`, both
+ * XZ points. Pure — no three.js — so `StudioStage.faceCamera` and any future placement tool share one
+ * tested formula instead of re-deriving atan2 math per call site. Only `forward`'s X/Z components
+ * matter (yaw is a rotation about Y); returns 0 when `origin` and `target` coincide.
+ * @internal — consumed through `StudioStage`'s `faceCamera` prop, not called directly by game code.
+ */
+export declare function yawToFace(forward: readonly [number, number, number], origin: readonly [number, number], target: readonly [number, number]): number;

package/dist/scene/facing.js

@@ -0,0 +1,26 @@
+/**
+ * The forward-axis convention: a generator or scene kind declares which way its "front" faces (a
+ * bookcase's open/book face, a building's entrance) once, as data, instead of leaving every placement
+ * to hand-tuned `rotationY` trial-and-error. `StudioStage`'s `faceCamera` (`@jgengine/shell/scene/
+ * StudioStage`) reads the declared axis to auto-orient a product shot; a placement tool can read the
+ * same field to face a freshly dropped asset toward the camera/path by default. `DEFAULT_FORWARD`
+ * (+Z) is what a generator/scene-kind gets when it omits `forward` — build your front toward it.
+ * @capability forward-axis declared front convention for parametric assets — auto-orient product shots
+ */
+export const DEFAULT_FORWARD = [0, 0, 1];
+/**
+ * The yaw (radians, around Y) that rotates `forward` so it points from `origin` toward `target`, both
+ * XZ points. Pure — no three.js — so `StudioStage.faceCamera` and any future placement tool share one
+ * tested formula instead of re-deriving atan2 math per call site. Only `forward`'s X/Z components
+ * matter (yaw is a rotation about Y); returns 0 when `origin` and `target` coincide.
+ * @internal — consumed through `StudioStage`'s `faceCamera` prop, not called directly by game code.
+ */
+export function yawToFace(forward, origin, target) {
+    const dx = target[0] - origin[0];
+    const dz = target[1] - origin[1];
+    if (dx === 0 && dz === 0)
+        return 0;
+    const angleToTarget = Math.atan2(dx, dz);
+    const angleForward = Math.atan2(forward[0], forward[2]);
+    return angleToTarget - angleForward;
+}

package/dist/scene/modelSockets.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Generic named-socket reader for loaded 3D models. Walks a node tree (any object with `.name`,
+ * `.position`, and `.children` — structurally satisfied by `THREE.Object3D`) and collects the local
+ * offsets of nodes whose name marks an attachment point. Genre-agnostic: wire anchors on a pylon,
+ * muzzle/hand mounts on a character, hardpoints on a ship, seat/decal slots on furniture — anything
+ * an artist tags with an empty in the GLB. Pure data (no three.js import), so it lives in core.
+ *
+ * @capability model-sockets named attachment points read from a model
+ */
+/** Minimal shape of a model node this reader walks — structurally satisfied by `THREE.Object3D`. */
+export interface ModelNode {
+    name: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    children?: readonly ModelNode[];
+}
+/** One resolved socket: its node name and local-space offset from the model origin. */
+export interface ModelSocket {
+    name: string;
+    offset: readonly [number, number, number];
+}
+/** Default socket-name matcher: "socket", "wire", "attach", "anchor", "mount", "hardpoint" (any case). */
+export declare const SOCKET_PATTERN: RegExp;
+/**
+ * Depth-first collect every socket-named node's local offset, sorted by descending Y then ascending X
+ * so socket indices are stable across loads (top first, left-to-right). Empty when the model tags
+ * none — callers then fall back to computed offsets. Pass a custom `pattern` for a bespoke naming
+ * convention.
+ */
+export declare function readNamedSockets(root: ModelNode, pattern?: RegExp): ModelSocket[];

package/dist/scene/modelSockets.js

@@ -0,0 +1,29 @@
+/**
+ * Generic named-socket reader for loaded 3D models. Walks a node tree (any object with `.name`,
+ * `.position`, and `.children` — structurally satisfied by `THREE.Object3D`) and collects the local
+ * offsets of nodes whose name marks an attachment point. Genre-agnostic: wire anchors on a pylon,
+ * muzzle/hand mounts on a character, hardpoints on a ship, seat/decal slots on furniture — anything
+ * an artist tags with an empty in the GLB. Pure data (no three.js import), so it lives in core.
+ *
+ * @capability model-sockets named attachment points read from a model
+ */
+/** Default socket-name matcher: "socket", "wire", "attach", "anchor", "mount", "hardpoint" (any case). */
+export const SOCKET_PATTERN = /socket|wire|attach|anchor|mount|hardpoint/i;
+/**
+ * Depth-first collect every socket-named node's local offset, sorted by descending Y then ascending X
+ * so socket indices are stable across loads (top first, left-to-right). Empty when the model tags
+ * none — callers then fall back to computed offsets. Pass a custom `pattern` for a bespoke naming
+ * convention.
+ */
+export function readNamedSockets(root, pattern = SOCKET_PATTERN) {
+    const found = [];
+    const walk = (node) => {
+        if (pattern.test(node.name))
+            found.push({ name: node.name, offset: [node.position.x, node.position.y, node.position.z] });
+        for (const child of node.children ?? [])
+            walk(child);
+    };
+    walk(root);
+    found.sort((a, b) => b.offset[1] - a.offset[1] || a.offset[0] - b.offset[0]);
+    return found;
+}

package/dist/scene/objectQuery.d.ts

@@ -24,6 +24,8 @@ declare function intersectAabb(origin: EntityPosition, direction: EntityPosition
     distance: number;
     normal: EntityPosition;
 } | null;
+/** @internal */
 export declare function raycastObjects(source: ObjectRaycastSource, input: ObjectRaycastInput): ObjectRaycastHit | null;
+/** @internal */
 export declare function raycastObjectsAll(source: ObjectRaycastSource, input: ObjectRaycastInput): ObjectRaycastHit[];
 export { intersectAabb, normalize as normalizeDirection };

package/dist/scene/objectQuery.js

@@ -102,6 +102,7 @@ function resolveCandidates(source, origin, direction, maxDistance, halfExtents)
     const bounds = raySegmentBounds(origin, direction, maxDistance, halfExtents);
     return source.inBox(bounds.min, bounds.max);
 }
+/** @internal */
 export function raycastObjects(source, input) {
     const direction = normalize(input.direction);
     if (direction[0] === 0 && direction[1] === 0 && direction[2] === 0)
@@ -120,6 +121,7 @@ export function raycastObjects(source, input) {
     }
     return nearest;
 }
+/** @internal */
 export function raycastObjectsAll(source, input) {
     const direction = normalize(input.direction);
     if (direction[0] === 0 && direction[1] === 0 && direction[2] === 0)

package/dist/scene/objectStore.d.ts

@@ -31,10 +31,14 @@ export interface ObjectStore {
     setVisual(instanceId: string, visual: ObjectVisual | undefined): boolean;
     get(instanceId: string): SceneObject | null;
     list(filter?: ObjectListFilter): readonly SceneObject[];
+    /** Stable-identity list of all placed object ids; identity changes only on place/remove, not on move/rotate/setVisual. Pair with {@link subscribeMembership} for membership-only React subscriptions (#625). */
+    ids(): readonly string[];
     at(x: number, y: number, z: number, tolerance?: number): SceneObject[];
     inBox(min: EntityPosition, max: EntityPosition): readonly SceneObject[];
     clear(): void;
     subscribe(listener: () => void): () => void;
+    /** Notified only when the object set changes (place/remove), never on move/rotate/setVisual — markers read live poses imperatively. */
+    subscribeMembership(listener: () => void): () => void;
     snapshot(): readonly SceneObject[];
 }
 export declare function createObjectStore(): ObjectStore;

package/dist/scene/objectStore.js

@@ -112,6 +112,9 @@ export function createObjectStore() {
                 return all;
             return all.filter((object) => object.parentSpace === filter.parentSpace);
         },
+        ids() {
+            return store.keysSnapshot();
+        },
         at(x, y, z, tolerance = 0) {
             const minCx = cellIndexOf(x - tolerance);
             const maxCx = cellIndexOf(x + tolerance);
@@ -180,6 +183,9 @@ export function createObjectStore() {
         subscribe(listener) {
             return store.subscribe(listener);
         },
+        subscribeMembership(listener) {
+            return store.subscribeMembership(listener);
+        },
         snapshot() {
             return store.arraySnapshot();
         },

package/dist/scene/possession.d.ts

@@ -17,6 +17,10 @@ export interface PossessionDeps {
     entities: PossessionEntities;
     events?: PossessionEvents;
 }
+export interface PossessionSnapshot {
+    owned: Record<string, readonly string[]>;
+    active: Record<string, string>;
+}
 export interface Possession {
     own(userId: string, entityId: string): void;
     disown(userId: string, entityId: string): void;
@@ -26,5 +30,9 @@ export interface Possession {
     possess(userId: string, entityId: string): {
         reason: string;
     } | null;
+    /** Snapshot every user's owned entities and active pawn for a whole-world save. */
+    snapshotAll(): PossessionSnapshot;
+    /** Restore every user's owned entities and active pawn from a {@link snapshotAll} payload. Entity roles are restored by the entity snapshot, not re-applied here. */
+    hydrateAll(state: PossessionSnapshot): void;
 }
 export declare function createPossession(deps: PossessionDeps): Possession;

package/dist/scene/possession.js

@@ -47,5 +47,19 @@ export function createPossession(deps) {
             deps.events?.emit("possession.swapped", { userId, entityId, previousEntityId });
             return null;
         },
+        snapshotAll() {
+            const ownedOut = {};
+            for (const [userId, set] of owned)
+                ownedOut[userId] = Array.from(set);
+            return { owned: ownedOut, active: Object.fromEntries(activeByUser) };
+        },
+        hydrateAll(state) {
+            owned.clear();
+            for (const [userId, ids] of Object.entries(state.owned))
+                owned.set(userId, new Set(ids));
+            activeByUser.clear();
+            for (const [userId, entityId] of Object.entries(state.active))
+                activeByUser.set(userId, entityId);
+        },
     };
 }

package/dist/scene/roster.d.ts

@@ -18,6 +18,9 @@ export interface Roster {
     setEquipped(userId: string, entryId: string, equipped: boolean): RosterEntry | null;
     snapshot(userId: string): readonly RosterEntry[];
     hydrate(userId: string, entries: readonly RosterEntry[]): void;
+    /** Whole-store capture across every owner — the world-save/replication seam (per-owner `snapshot` can't enumerate owners). */
+    snapshotAll(): Record<string, readonly RosterEntry[]>;
+    hydrateAll(data: Record<string, readonly RosterEntry[]>): void;
 }
 export interface RosterDeps {
     now?: () => number;

package/dist/scene/roster.js

@@ -53,5 +53,17 @@ export function createRoster(deps = {}) {
         hydrate(userId, entries) {
             rosters.set(userId, new Map(entries.map((entry) => [entry.id, entry])));
         },
+        snapshotAll() {
+            const out = {};
+            for (const [userId, entries] of rosters)
+                out[userId] = Array.from(entries.values());
+            return out;
+        },
+        hydrateAll(data) {
+            rosters.clear();
+            for (const [userId, entries] of Object.entries(data)) {
+                rosters.set(userId, new Map(entries.map((entry) => [entry.id, entry])));
+            }
+        },
     };
 }