@jgengine/core 0.10.0 → 0.11.0

package/dist/scene/bodyBind.d.ts

@@ -0,0 +1,60 @@
+import type { EntityRole, EntityUpdatePatch, SpawnPositionInput } from "./entityStore.js";
+/**
+ * One sim body's per-tick pose, as the game's simulation computed it — the shape a game already builds
+ * to hand to `setPose`, just declared instead of imperatively pushed. `kind` is the entity catalog name
+ * used only the first time `id` is seen (a respawn/despawn never re-reads it).
+ */
+export interface BodySnapshot {
+    id: string;
+    kind: string;
+    position: SpawnPositionInput;
+    rotationY?: number;
+    rotationX?: number;
+    rotationZ?: number;
+    role?: EntityRole;
+    meta?: unknown;
+}
+/** The options a {@link BodyBindDeps.spawn} call receives for an id seen for the first time. */
+export interface BodyBindSpawnInput {
+    id: string;
+    position: SpawnPositionInput;
+    rotationY?: number;
+    rotationX?: number;
+    rotationZ?: number;
+    role?: EntityRole;
+    meta?: unknown;
+}
+/** The pose a {@link BodyBindDeps.setPose} call receives for an id already bound. */
+export interface BodyBindPose {
+    position: SpawnPositionInput;
+    rotationY?: number;
+    rotationX?: number;
+    rotationZ?: number;
+    dt?: number;
+}
+/** Structural entity-store seam a {@link BodyBind} mirrors onto — satisfied by `ctx.scene.entity` itself. */
+export interface BodyBindDeps {
+    has(id: string): boolean;
+    spawn(kind: string, options: BodyBindSpawnInput): string;
+    despawn(id: string): boolean;
+    setPose(id: string, pose: BodyBindPose): boolean;
+    update(id: string, patch: EntityUpdatePatch): boolean;
+}
+/** The lazily-keyed handle `ctx.scene.entity.bind(key)` returns. */
+export interface BodyBind {
+    /**
+     * Mirror this tick's `bodies` onto scene entities: spawns an id seen for the first time (catalog
+     * `kind` from its snapshot), poses one already bound, despawns one this bind previously spawned that
+     * is now absent from `bodies`. `dt` (when given) derives `velocity` the same as a direct `setPose`.
+     */
+    sync(bodies: Iterable<BodySnapshot>, dt?: number): void;
+    /** Ids this bind currently considers itself responsible for (spawned by, and not yet despawned by, `sync`). */
+    boundIds(): ReadonlySet<string>;
+}
+/**
+ * Mirror a sim's body snapshots onto scene entities each tick — spawn on first sight, pose while bound,
+ * despawn on drop — replacing a per-body `setPose` loop plus its `despawn`/`spawn` respawn dance.
+ *
+ * @capability body-bind mirror sim-body snapshots onto scene entities each tick, no per-body setPose
+ */
+export declare function createBodyBind(deps: BodyBindDeps): BodyBind;

package/dist/scene/bodyBind.js

@@ -0,0 +1,51 @@
+/**
+ * Mirror a sim's body snapshots onto scene entities each tick — spawn on first sight, pose while bound,
+ * despawn on drop — replacing a per-body `setPose` loop plus its `despawn`/`spawn` respawn dance.
+ *
+ * @capability body-bind mirror sim-body snapshots onto scene entities each tick, no per-body setPose
+ */
+export function createBodyBind(deps) {
+    const bound = new Set();
+    return {
+        sync(bodies, dt) {
+            const seen = new Set();
+            for (const body of bodies) {
+                seen.add(body.id);
+                const alreadyBound = bound.has(body.id);
+                if (!alreadyBound && !deps.has(body.id)) {
+                    deps.spawn(body.kind, {
+                        id: body.id,
+                        position: body.position,
+                        rotationY: body.rotationY,
+                        rotationX: body.rotationX,
+                        rotationZ: body.rotationZ,
+                        role: body.role,
+                        meta: body.meta,
+                    });
+                }
+                else {
+                    deps.setPose(body.id, {
+                        position: body.position,
+                        rotationY: body.rotationY,
+                        rotationX: body.rotationX,
+                        rotationZ: body.rotationZ,
+                        ...(dt === undefined ? {} : { dt }),
+                    });
+                    if (body.role !== undefined || body.meta !== undefined) {
+                        deps.update(body.id, { role: body.role, meta: body.meta });
+                    }
+                }
+                bound.add(body.id);
+            }
+            for (const id of bound) {
+                if (seen.has(id))
+                    continue;
+                deps.despawn(id);
+                bound.delete(id);
+            }
+        },
+        boundIds() {
+            return bound;
+        },
+    };
+}

package/dist/scene/builtinSceneKinds.d.ts

@@ -0,0 +1,5 @@
+import { type ParamSchema } from "./sceneKinds.js";
+/** The scatter/foliage region schema — the fields the inspector exposed as hand-written `ScatterFields`. */
+export declare const SCATTER_SCHEMA: ParamSchema;
+/** Idempotently registers the engine's built-in environment scene kinds + generators. @internal */
+export declare function registerBuiltinSceneKinds(): void;

package/dist/scene/builtinSceneKinds.js

@@ -0,0 +1,62 @@
+/**
+ * Registers the engine's built-in *environment* scene kinds against the {@link registerSceneKind}
+ * seam: `scatter` (the proof adopter — its inspector, `+ Add` entry, and parse now come from the
+ * registry), `water` (a reusable parametric water surface), `grass_field` (GPU vertex-wind grass), and
+ * `soil` (crack/moss ground-variation patch). These are genre-agnostic engine primitives, like terrain.
+ * Domain studios (poles, bookcases, …) are NOT built in — they register themselves from example/game
+ * code via the same public seam, needing zero engine edits (see `examples/studios`). Call
+ * {@link registerBuiltinSceneKinds} once at startup (idempotent).
+ */
+import { SCATTER_PATH_KIND } from "../world/scatterRegion.js";
+import { registerWaterKind } from "../world/waterKind.js";
+import { registerGrassKind } from "../world/grassKind.js";
+import { registerSoilKind } from "../world/soilKind.js";
+import { registerBuildingGenerator } from "../world/buildingGenerator.js";
+import { registerSceneKind } from "./sceneKinds.js";
+/** The scatter/foliage region schema — the fields the inspector exposed as hand-written `ScatterFields`. */
+export const SCATTER_SCHEMA = {
+    fields: [
+        { type: "range", key: "density", label: "density", min: 0, max: 2, step: 0.01, default: 0.15, unit: "/m²" },
+        { type: "number", key: "minSpacing", label: "spacing", step: 0.25, default: 1.5, min: 0 },
+        { type: "number", key: "minScale", label: "min scale", step: 0.05, default: 0.8, min: 0 },
+        { type: "number", key: "maxScale", label: "max scale", step: 0.05, default: 1.3, min: 0 },
+        { type: "number", key: "maxSlope", label: "max slope", step: 0.05, default: 0, min: 0 },
+        { type: "number", key: "edgeFalloff", label: "edge fade", step: 0.5, default: 0, min: 0 },
+        { type: "bool", key: "alignToNormal", label: "align to slope", default: false },
+        { type: "bool", key: "autoAvoid", label: "auto-avoid gameplay spots", default: true },
+        { type: "weightedList", key: "palette", label: "species (weighted)", itemLabel: "grass / tree id", default: [{ item: "grass", weight: 1 }] },
+        { type: "seed", key: "seed", label: "seed", default: "" },
+    ],
+};
+let registered = false;
+/** Idempotently registers the engine's built-in environment scene kinds + generators. @internal */
+export function registerBuiltinSceneKinds() {
+    if (registered)
+        return;
+    registered = true;
+    registerSceneKind({
+        kind: SCATTER_PATH_KIND,
+        target: "path",
+        label: "Foliage / scatter",
+        pathShape: "area",
+        addCategory: "Studios",
+        accent: "#34d399",
+        schema: SCATTER_SCHEMA,
+        note: (object, params) => {
+            const points = object.points ?? [];
+            if (points.length < 3)
+                return "Draw at least 3 points to close the region.";
+            let area = 0;
+            for (let i = 0, j = points.length - 1; i < points.length; j = i, i += 1) {
+                area += points[j].x * points[i].z - points[i].x * points[j].z;
+            }
+            area = Math.abs(area) / 2;
+            const density = typeof params["density"] === "number" ? params["density"] : 0;
+            return `≈ ${Math.floor(area * density).toLocaleString()} placements over ${Math.round(area).toLocaleString()} m²`;
+        },
+    });
+    registerWaterKind();
+    registerGrassKind();
+    registerSoilKind();
+    registerBuildingGenerator();
+}

package/dist/scene/colliders.d.ts

@@ -37,13 +37,25 @@ export declare const DEFAULT_OBJECT_HALF_EXTENTS: EntityPosition;
 export declare const DEFAULT_ENTITY_BODY_HALF_EXTENTS: EntityPosition;
 /** Entity-local center of the default body hitbox (half its height above the feet). */
 export declare const DEFAULT_ENTITY_BODY_OFFSET: EntityPosition;
+/** @internal */
 export declare function defaultEntityColliders(): EntityColliderSet;
+/** Humanoid damage box uniformly scaled to match a visually scaled mesh, kept grounded (offset stays half its height). At scale 1 this equals `defaultEntityColliders()`.
+ * @internal
+ */
+export declare function scaledEntityColliders(scale: number): EntityColliderSet;
+/** @internal */
 export declare function defaultObjectColliders(halfExtents?: EntityPosition): EntityColliderSet;
-/** Blocking physical body derived from an object's rendered scale: a grounded box spanning the visual (base at y=0, matching the shell's fallback mesh). */
+/** Blocking physical body derived from an object's rendered scale: a grounded box spanning the visual (base at y=0, matching the shell's fallback mesh).
+ * @internal
+ */
 export declare function scaledObjectColliders(scale: readonly [number, number, number]): EntityColliderSet;
+/** @internal */
 export declare function resolveColliders(set: EntityColliderSet | null | undefined): ResolvedCollider[];
+/** @internal */
 export declare function worldOffset(local: EntityPosition | undefined, position: EntityPosition, rotationY: number): EntityPosition;
+/** @internal */
 export declare function colliderWorldCenter(collider: ResolvedCollider, position: EntityPosition, rotationY: number): EntityPosition;
+/** @internal */
 export declare function colliderBounds(collider: ResolvedCollider, position: EntityPosition, rotationY: number): {
     min: EntityPosition;
     max: EntityPosition;

package/dist/scene/colliders.js

@@ -4,6 +4,7 @@ export const DEFAULT_OBJECT_HALF_EXTENTS = [0.5, 0.5, 0.5];
 export const DEFAULT_ENTITY_BODY_HALF_EXTENTS = [0.35, 0.9, 0.35];
 /** Entity-local center of the default body hitbox (half its height above the feet). */
 export const DEFAULT_ENTITY_BODY_OFFSET = [0, 0.9, 0];
+/** @internal */
 export function defaultEntityColliders() {
     return {
         hitboxes: [
@@ -21,6 +22,35 @@ export function defaultEntityColliders() {
         ],
     };
 }
+/** Humanoid damage box uniformly scaled to match a visually scaled mesh, kept grounded (offset stays half its height). At scale 1 this equals `defaultEntityColliders()`.
+ * @internal
+ */
+export function scaledEntityColliders(scale) {
+    return {
+        hitboxes: [
+            {
+                name: "body",
+                purpose: "damage",
+                shape: {
+                    kind: "aabb",
+                    halfExtents: [
+                        DEFAULT_ENTITY_BODY_HALF_EXTENTS[0] * scale,
+                        DEFAULT_ENTITY_BODY_HALF_EXTENTS[1] * scale,
+                        DEFAULT_ENTITY_BODY_HALF_EXTENTS[2] * scale,
+                    ],
+                    offset: [
+                        DEFAULT_ENTITY_BODY_OFFSET[0] * scale,
+                        DEFAULT_ENTITY_BODY_OFFSET[1] * scale,
+                        DEFAULT_ENTITY_BODY_OFFSET[2] * scale,
+                    ],
+                },
+                damageEligible: true,
+                blocks: false,
+            },
+        ],
+    };
+}
+/** @internal */
 export function defaultObjectColliders(halfExtents = DEFAULT_OBJECT_HALF_EXTENTS) {
     return {
         body: {
@@ -32,7 +62,9 @@ export function defaultObjectColliders(halfExtents = DEFAULT_OBJECT_HALF_EXTENTS
         },
     };
 }
-/** Blocking physical body derived from an object's rendered scale: a grounded box spanning the visual (base at y=0, matching the shell's fallback mesh). */
+/** Blocking physical body derived from an object's rendered scale: a grounded box spanning the visual (base at y=0, matching the shell's fallback mesh).
+ * @internal
+ */
 export function scaledObjectColliders(scale) {
     return {
         body: {
@@ -48,6 +80,7 @@ export function scaledObjectColliders(scale) {
         },
     };
 }
+/** @internal */
 export function resolveColliders(set) {
     if (set === null || set === undefined)
         return [];
@@ -71,6 +104,7 @@ function resolveOne(def) {
         blocks,
     };
 }
+/** @internal */
 export function worldOffset(local, position, rotationY) {
     if (local === undefined)
         return position;
@@ -81,9 +115,11 @@ export function worldOffset(local, position, rotationY) {
     const lz = local[2];
     return [position[0] + lx * cos + lz * sin, position[1] + ly, position[2] - lx * sin + lz * cos];
 }
+/** @internal */
 export function colliderWorldCenter(collider, position, rotationY) {
     return worldOffset(collider.shape.offset, position, rotationY);
 }
+/** @internal */
 export function colliderBounds(collider, position, rotationY) {
     const center = colliderWorldCenter(collider, position, rotationY);
     if (collider.shape.kind === "sphere") {

package/dist/scene/entityStats.d.ts

@@ -24,13 +24,21 @@ export type PoolDeltaResult = {
     status: "rejected";
     reason: string;
 };
+/** @internal */
 export declare function getStatValue(map: StatValueMap, statId: string): StatValue | null;
+/** @internal */
 export declare function setStatValue(map: StatValueMap, statId: string, patch: StatValuePatch): StatValueMap;
+/** @internal */
 export declare function applyPoolDelta(map: StatValueMap, statId: string, amount: number): PoolDeltaResult;
+/** @internal */
 export declare function seedStatValues(catalogStats: StatCatalog): StatValueMap;
-/** Deep-copy the per-entity stat maps into a serializable record — the transport counterpart of {@link hydrateEntityStats}. */
+/** Deep-copy the per-entity stat maps into a serializable record — the transport counterpart of {@link hydrateEntityStats}.
+ * @internal
+ */
 export declare function snapshotEntityStats(store: ReadonlyMap<string, StatValueMap>): Record<string, StatValueMap>;
-/** Replace a live stat store with deep copies of a snapshot, clearing entities absent from it. */
+/** Replace a live stat store with deep copies of a snapshot, clearing entities absent from it.
+ * @internal
+ */
 export declare function hydrateEntityStats(store: Map<string, StatValueMap>, data: Record<string, StatValueMap>): void;
 export interface EntityStatsApi {
     get(instanceId: string, statId: string): StatValue | null;
@@ -39,4 +47,5 @@ export interface EntityStatsApi {
         reason: string;
     };
 }
+/** @internal */
 export declare function createEntityStatsApi(resolve: (instanceId: string) => StatValueMap | undefined): EntityStatsApi;

package/dist/scene/entityStats.js

@@ -1,9 +1,11 @@
 function clamp(value, min, max) {
     return Math.min(max, Math.max(min, value));
 }
+/** @internal */
 export function getStatValue(map, statId) {
     return map[statId] ?? null;
 }
+/** @internal */
 export function setStatValue(map, statId, patch) {
     const existing = map[statId];
     const max = patch.max ?? existing?.max ?? 0;
@@ -11,6 +13,7 @@ export function setStatValue(map, statId, patch) {
     const current = clamp(patch.current ?? existing?.current ?? max, min, max);
     return { ...map, [statId]: { current, max, min } };
 }
+/** @internal */
 export function applyPoolDelta(map, statId, amount) {
     const existing = map[statId];
     if (existing === undefined) {
@@ -26,6 +29,7 @@ export function applyPoolDelta(map, statId, amount) {
         hitMax: current === existing.max,
     };
 }
+/** @internal */
 export function seedStatValues(catalogStats) {
     const map = {};
     for (const [statId, declaration] of Object.entries(catalogStats)) {
@@ -35,7 +39,9 @@ export function seedStatValues(catalogStats) {
     }
     return map;
 }
-/** Deep-copy the per-entity stat maps into a serializable record — the transport counterpart of {@link hydrateEntityStats}. */
+/** Deep-copy the per-entity stat maps into a serializable record — the transport counterpart of {@link hydrateEntityStats}.
+ * @internal
+ */
 export function snapshotEntityStats(store) {
     const out = {};
     for (const [instanceId, map] of store) {
@@ -46,7 +52,9 @@ export function snapshotEntityStats(store) {
     }
     return out;
 }
-/** Replace a live stat store with deep copies of a snapshot, clearing entities absent from it. */
+/** Replace a live stat store with deep copies of a snapshot, clearing entities absent from it.
+ * @internal
+ */
 export function hydrateEntityStats(store, data) {
     store.clear();
     for (const [instanceId, map] of Object.entries(data)) {
@@ -56,6 +64,7 @@ export function hydrateEntityStats(store, data) {
         store.set(instanceId, copy);
     }
 }
+/** @internal */
 export function createEntityStatsApi(resolve) {
     return {
         get(instanceId, statId) {

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;
@@ -96,8 +103,12 @@ 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()`

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]);
@@ -167,6 +176,9 @@ export function createEntityStore() {
         list() {
             return store.arraySnapshot();
         },
+        ids() {
+            return store.keysSnapshot();
+        },
         clear() {
             for (const entity of store.arraySnapshot()) {
                 store.delete(entity.id);
@@ -177,6 +189,9 @@ export function createEntityStore() {
         subscribe(listener) {
             return store.subscribe(listener);
         },
+        subscribeMembership(listener) {
+            return store.subscribeMembership(listener);
+        },
         snapshot() {
             return store.arraySnapshot();
         },

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;