@jgengine/core 0.10.0 → 0.12.0

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])));
+            }
+        },
     };
 }

package/dist/scene/sceneKinds.d.ts

@@ -0,0 +1,256 @@
+/**
+ * The parametric-studio seam: a registry that maps an editor object `kind` to a typed parameter
+ * schema (drives the inspector + `meta` parse/validation), an optional pure-data `resolve` (turns a
+ * document object into renderable data), and `+ Add` menu metadata. Registering a kind lets a third
+ * party ship a new authorable "studio" (pole line, water, bookcase) — schema + resolver here, a
+ * matching renderer in `shell` — without editing editor or engine files. Scatter is the proof adopter.
+ */
+/** Which document collection a scene kind lives in. Drives placement + which `meta` bag holds params. */
+export type SceneKindTarget = "path" | "marker" | "volume";
+/** A closed-polygon area vs an open polyline, for path-target kinds. Ignored for marker/volume kinds. */
+export type ScenePathShape = "area" | "line";
+/** One weighted entry in a `weightedList` param — an item id and its relative spawn weight. */
+export interface WeightedParamEntry {
+    item: string;
+    weight: number;
+}
+/** A numeric slider row: bounded range with a live readout. */
+export interface RangeParamField {
+    type: "range";
+    key: string;
+    label?: string;
+    /** Optional group id — the inspector renders fields sharing a group under one collapsible section. */
+    group?: string;
+    min: number;
+    max: number;
+    step?: number;
+    default: number;
+    /** Suffix shown next to the readout, e.g. "m" or "/m²". */
+    unit?: string;
+}
+/** A free numeric input, optionally clamped. */
+export interface NumberParamField {
+    type: "number";
+    key: string;
+    label?: string;
+    /** Optional group id — the inspector renders fields sharing a group under one collapsible section. */
+    group?: string;
+    step?: number;
+    default: number;
+    min?: number;
+    max?: number;
+}
+/** A checkbox. */
+export interface BoolParamField {
+    type: "bool";
+    key: string;
+    label?: string;
+    /** Optional group id — the inspector renders fields sharing a group under one collapsible section. */
+    group?: string;
+    default: boolean;
+}
+/** A dropdown of fixed string options. */
+export interface SelectParamField {
+    type: "select";
+    key: string;
+    label?: string;
+    /** Optional group id — the inspector renders fields sharing a group under one collapsible section. */
+    group?: string;
+    options: readonly {
+        value: string;
+        label?: string;
+    }[];
+    default: string;
+}
+/** A hex color picker. */
+export interface ColorParamField {
+    type: "color";
+    key: string;
+    label?: string;
+    /** Optional group id — the inspector renders fields sharing a group under one collapsible section. */
+    group?: string;
+    default: string;
+}
+/** A free string input. */
+export interface TextParamField {
+    type: "text";
+    key: string;
+    label?: string;
+    /** Optional group id — the inspector renders fields sharing a group under one collapsible section. */
+    group?: string;
+    default: string;
+}
+/** A seed string with a reroll button — same seed reproduces the same generated result. */
+export interface SeedParamField {
+    type: "seed";
+    key: string;
+    label?: string;
+    /** Optional group id — the inspector renders fields sharing a group under one collapsible section. */
+    group?: string;
+    default: string;
+}
+/** A repeatable list of weighted `{ item, weight }` rows (species palette, book set, …). */
+export interface WeightedListParamField {
+    type: "weightedList";
+    key: string;
+    label?: string;
+    /** Optional group id — the inspector renders fields sharing a group under one collapsible section. */
+    group?: string;
+    /** Placeholder for the item id input. */
+    itemLabel?: string;
+    default: readonly WeightedParamEntry[];
+}
+/**
+ * A button row that runs a built-in inspector action on its group — currently `"randomize"` (reroll
+ * the group's numeric/seed/bool/select fields within their bounds) or `"reset"` (restore group
+ * defaults). Carries no persisted value; purely a control.
+ */
+export interface ActionParamField {
+    type: "action";
+    key: string;
+    label?: string;
+    group?: string;
+    action: "randomize" | "reset";
+}
+/** One row in a kind's parameter schema — the union the generic inspector knows how to render. */
+export type ParamField = RangeParamField | NumberParamField | BoolParamField | SelectParamField | ColorParamField | TextParamField | SeedParamField | WeightedListParamField | ActionParamField;
+/** A named, optionally-collapsed section the inspector groups fields under (by `field.group === id`). */
+export interface ParamGroup {
+    id: string;
+    label: string;
+    /** Start collapsed. Default expanded. */
+    collapsed?: boolean;
+}
+/**
+ * A named slider/weight bundle for a kind — a saved set of field values the inspector (or the
+ * `apply_preset` verb) writes into an object's `meta` in one patch, ready to tweak afterwards.
+ * Presets are plain data on the schema, so kinds ship archetypes and games can override the
+ * registration with their own.
+ */
+export interface ParamPreset {
+    id: string;
+    label?: string;
+    /** Field values the preset writes; fields not listed keep their current values. */
+    values: Readonly<Record<string, unknown>>;
+}
+/** A kind's full parameter surface: an ordered list of fields the inspector renders top-to-bottom. */
+export interface ParamSchema {
+    fields: readonly ParamField[];
+    /** Optional named sections; fields reference one by `group`. Ungrouped fields render first, headerless. */
+    groups?: readonly ParamGroup[];
+    /** Optional named field-value bundles the inspector offers as one-click applies. */
+    presets?: readonly ParamPreset[];
+}
+/** Look up a schema preset by id, or undefined — the seam `apply_preset` and games resolve bundles through. */
+export declare function findSchemaPreset(schema: ParamSchema, id: string): ParamPreset | undefined;
+/** Parsed params after `parseParams`: every schema field present with a validated, defaulted value. */
+export type ParsedParams = Record<string, number | boolean | string | WeightedParamEntry[]>;
+/**
+ * Parse a raw `meta` bag against a schema into typed params — every field present, invalid/missing
+ * values replaced by the field default, numbers clamped to their range. The single parser every
+ * studio shares instead of hand-writing its own `metaNumber`/`metaBool` ladder.
+ */
+export declare function parseParams(schema: ParamSchema, meta: Record<string, unknown> | undefined): ParsedParams;
+/** One validation problem found by {@link validateParams}: which field and why. */
+export interface ParamIssue {
+    key: string;
+    message: string;
+}
+/**
+ * Check a raw `meta` bag against a schema without mutating it — reports out-of-range numbers, unknown
+ * select values, and wrong types. Empty array means valid. Used by `set_meta` to reject bad agent
+ * patches before they land in the document.
+ * @internal
+ */
+export declare function validateParams(schema: ParamSchema, meta: Record<string, unknown> | undefined): ParamIssue[];
+/**
+ * A `meta` patch that randomizes every field in `groupId` within its bounds — the "randomize" button's
+ * behavior, pure and injectable so it's deterministic in tests. Ranges/numbers land in `[min, max]`
+ * (integer-rounded when `step >= 1`), bools/selects pick uniformly, seeds get a fresh token, colors a
+ * random mid-tone. Text and weighted lists are left untouched.
+ * @internal
+ */
+export declare function randomizeGroupParams(schema: ParamSchema, groupId: string | undefined, random: () => number): Record<string, unknown>;
+/** A `meta` patch restoring every field in `groupId` to its schema default — the "reset" button. @internal */
+export declare function resetGroupParams(schema: ParamSchema, groupId: string | undefined): Record<string, unknown>;
+/** The `meta` patch that fills a fresh object of a kind with its schema defaults. @internal */
+export declare function defaultParamMeta(schema: ParamSchema): Record<string, unknown>;
+/**
+ * A registered scene kind — everything the editor/engine need to author and render a studio without
+ * bespoke code. `schema` drives the inspector + parse; `resolve` (optional) turns one document object
+ * into pure renderable data a matching `shell` renderer consumes; `add*` fields build the `+ Add` menu.
+ * @typeParam TResolved — the kind's renderable payload (scatter instances, pole+cable set, …).
+ */
+export interface SceneKindDefinition<TResolved = unknown> {
+    kind: string;
+    target: SceneKindTarget;
+    /** Human label for the inspector header and `+ Add` entry. */
+    label: string;
+    schema: ParamSchema;
+    /** For path kinds: closed area (default) or open line. Ignored for markers/volumes. */
+    pathShape?: ScenePathShape;
+    /** `+ Add` menu section this kind lists under (e.g. "Studios"). Omit to hide from the menu. */
+    addCategory?: string;
+    /** Accent color for the inspector panel + `+ Add` entry, as a hex string. */
+    accent?: string;
+    /**
+     * Turn one document object (its geometry + parsed params) into pure renderable data. Pure — no
+     * three.js/DOM. Omitted for kinds whose renderer reads the object directly. `object` is the raw
+     * marker/volume/path; `params` is `parseParams(schema, object.meta)`.
+     */
+    resolve?: (object: SceneKindObject, params: ParsedParams, context: SceneKindResolveContext) => TResolved;
+    /** Optional one-line readout under the inspector fields (estimate, dimensions) — owned by the studio. */
+    note?: (object: SceneKindObject, params: ParsedParams) => string;
+}
+/** The raw document object a resolver receives — shape shared by markers, volumes, and paths. */
+export interface SceneKindObject {
+    id: string;
+    kind: string;
+    meta?: Record<string, unknown>;
+    /** Present for path targets: the polyline/polygon points (XZ used). */
+    points?: readonly {
+        x: number;
+        y: number;
+        z: number;
+    }[];
+    /** Present for marker targets: the placed position. */
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Present for volume targets: the region center. */
+    center?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Present for volume targets: box half-extents. */
+    halfExtents?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Present for volume targets: sphere/cylinder radius. */
+    radius?: number;
+    rotationY?: number;
+}
+/** Ground sampler + options a resolver may read (terrain height/normal snap). */
+export interface SceneKindResolveContext {
+    sampleHeight?: (x: number, z: number) => number;
+    sampleNormal?: (x: number, z: number) => readonly [number, number, number];
+}
+/**
+ * Register a scene kind — the plug-in point for a new parametric studio. Idempotent per `kind` (last
+ * registration wins), so a game's registration overrides a default. Call at module load; the editor
+ * inspector, `+ Add` menu, and `AuthoredScene` renderer lookup all read this registry.
+ */
+export declare function registerSceneKind<TResolved>(definition: SceneKindDefinition<TResolved>): void;
+/** The registered definition for a kind, or undefined if the kind is a plain (non-studio) kind. @internal */
+export declare function getSceneKind(kind: string): SceneKindDefinition | undefined;
+/** True when a kind has a registered studio definition (schema/inspector/renderer). @internal */
+export declare function isSceneKind(kind: string): boolean;
+/** Every registered kind, optionally filtered by target, in registration order. @internal */
+export declare function listSceneKinds(target?: SceneKindTarget): SceneKindDefinition[];
+/** Parse a document object's `meta` against its registered kind schema, or `null` if unregistered. @internal */
+export declare function parseSceneKindParams(object: SceneKindObject): ParsedParams | null;

package/dist/scene/sceneKinds.js

@@ -0,0 +1,218 @@
+/**
+ * The parametric-studio seam: a registry that maps an editor object `kind` to a typed parameter
+ * schema (drives the inspector + `meta` parse/validation), an optional pure-data `resolve` (turns a
+ * document object into renderable data), and `+ Add` menu metadata. Registering a kind lets a third
+ * party ship a new authorable "studio" (pole line, water, bookcase) — schema + resolver here, a
+ * matching renderer in `shell` — without editing editor or engine files. Scatter is the proof adopter.
+ */
+/** Look up a schema preset by id, or undefined — the seam `apply_preset` and games resolve bundles through. */
+export function findSchemaPreset(schema, id) {
+    return schema.presets?.find((preset) => preset.id === id);
+}
+function num(value, fallback, min, max) {
+    let n = typeof value === "number" && Number.isFinite(value) ? value : fallback;
+    if (min !== undefined)
+        n = Math.max(min, n);
+    if (max !== undefined)
+        n = Math.min(max, n);
+    return n;
+}
+function readWeightedList(value, fallback) {
+    if (!Array.isArray(value))
+        return fallback.map((entry) => ({ ...entry }));
+    const entries = value
+        .filter((entry) => typeof entry === "object" && entry !== null)
+        .map((entry) => ({
+        item: typeof entry.item === "string" ? entry.item : "",
+        weight: num(entry.weight, 1, 0),
+    }))
+        .filter((entry) => entry.item.length > 0);
+    return entries.length > 0 ? entries : fallback.map((entry) => ({ ...entry }));
+}
+/**
+ * Parse a raw `meta` bag against a schema into typed params — every field present, invalid/missing
+ * values replaced by the field default, numbers clamped to their range. The single parser every
+ * studio shares instead of hand-writing its own `metaNumber`/`metaBool` ladder.
+ */
+export function parseParams(schema, meta) {
+    const out = {};
+    for (const field of schema.fields) {
+        const raw = meta?.[field.key];
+        switch (field.type) {
+            case "range":
+                out[field.key] = num(raw, field.default, field.min, field.max);
+                break;
+            case "number":
+                out[field.key] = num(raw, field.default, field.min, field.max);
+                break;
+            case "bool":
+                out[field.key] = typeof raw === "boolean" ? raw : field.default;
+                break;
+            case "select": {
+                const allowed = field.options.some((option) => option.value === raw);
+                out[field.key] = allowed ? raw : field.default;
+                break;
+            }
+            case "color":
+            case "text":
+            case "seed":
+                out[field.key] = typeof raw === "string" ? raw : field.default;
+                break;
+            case "weightedList":
+                out[field.key] = readWeightedList(raw, field.default);
+                break;
+            case "action":
+                break;
+        }
+    }
+    return out;
+}
+/**
+ * Check a raw `meta` bag against a schema without mutating it — reports out-of-range numbers, unknown
+ * select values, and wrong types. Empty array means valid. Used by `set_meta` to reject bad agent
+ * patches before they land in the document.
+ * @internal
+ */
+export function validateParams(schema, meta) {
+    const issues = [];
+    if (meta === undefined)
+        return issues;
+    for (const field of schema.fields) {
+        const raw = meta[field.key];
+        if (raw === undefined)
+            continue;
+        switch (field.type) {
+            case "range":
+                if (typeof raw !== "number" || !Number.isFinite(raw))
+                    issues.push({ key: field.key, message: "expected a number" });
+                else if (raw < field.min || raw > field.max)
+                    issues.push({ key: field.key, message: `out of range ${field.min}..${field.max}` });
+                break;
+            case "number":
+                if (typeof raw !== "number" || !Number.isFinite(raw))
+                    issues.push({ key: field.key, message: "expected a number" });
+                else if ((field.min !== undefined && raw < field.min) || (field.max !== undefined && raw > field.max))
+                    issues.push({ key: field.key, message: "out of range" });
+                break;
+            case "bool":
+                if (typeof raw !== "boolean")
+                    issues.push({ key: field.key, message: "expected a boolean" });
+                break;
+            case "select":
+                if (!field.options.some((option) => option.value === raw))
+                    issues.push({ key: field.key, message: "not an allowed option" });
+                break;
+            case "color":
+            case "text":
+            case "seed":
+                if (typeof raw !== "string")
+                    issues.push({ key: field.key, message: "expected a string" });
+                break;
+            case "weightedList":
+                if (!Array.isArray(raw))
+                    issues.push({ key: field.key, message: "expected an array" });
+                break;
+            case "action":
+                break;
+        }
+    }
+    return issues;
+}
+function randomHex(random) {
+    const channel = () => Math.floor(60 + random() * 180)
+        .toString(16)
+        .padStart(2, "0");
+    return `#${channel()}${channel()}${channel()}`;
+}
+/**
+ * A `meta` patch that randomizes every field in `groupId` within its bounds — the "randomize" button's
+ * behavior, pure and injectable so it's deterministic in tests. Ranges/numbers land in `[min, max]`
+ * (integer-rounded when `step >= 1`), bools/selects pick uniformly, seeds get a fresh token, colors a
+ * random mid-tone. Text and weighted lists are left untouched.
+ * @internal
+ */
+export function randomizeGroupParams(schema, groupId, random) {
+    const patch = {};
+    for (const field of schema.fields) {
+        if (field.group !== groupId)
+            continue;
+        switch (field.type) {
+            case "range": {
+                const value = field.min + random() * (field.max - field.min);
+                patch[field.key] = field.step !== undefined && field.step >= 1 ? Math.round(value) : Math.round(value * 1000) / 1000;
+                break;
+            }
+            case "number": {
+                if (field.min !== undefined && field.max !== undefined)
+                    patch[field.key] = Math.round((field.min + random() * (field.max - field.min)) * 1000) / 1000;
+                else
+                    patch[field.key] = Math.round(field.default * (0.5 + random()) * 1000) / 1000;
+                break;
+            }
+            case "bool":
+                patch[field.key] = random() < 0.5;
+                break;
+            case "select":
+                patch[field.key] = field.options[Math.floor(random() * field.options.length)].value;
+                break;
+            case "seed":
+                patch[field.key] = `r${Math.floor(random() * 1_000_000).toString(36)}`;
+                break;
+            case "color":
+                patch[field.key] = randomHex(random);
+                break;
+            case "text":
+            case "weightedList":
+            case "action":
+                break;
+        }
+    }
+    return patch;
+}
+/** A `meta` patch restoring every field in `groupId` to its schema default — the "reset" button. @internal */
+export function resetGroupParams(schema, groupId) {
+    const patch = {};
+    for (const field of schema.fields) {
+        if (field.group !== groupId || field.type === "action")
+            continue;
+        patch[field.key] = field.type === "weightedList" ? field.default.map((entry) => ({ ...entry })) : field.default;
+    }
+    return patch;
+}
+/** The `meta` patch that fills a fresh object of a kind with its schema defaults. @internal */
+export function defaultParamMeta(schema) {
+    const out = {};
+    for (const field of schema.fields) {
+        if (field.type === "action")
+            continue;
+        out[field.key] = field.type === "weightedList" ? field.default.map((entry) => ({ ...entry })) : field.default;
+    }
+    return out;
+}
+const registry = new Map();
+/**
+ * Register a scene kind — the plug-in point for a new parametric studio. Idempotent per `kind` (last
+ * registration wins), so a game's registration overrides a default. Call at module load; the editor
+ * inspector, `+ Add` menu, and `AuthoredScene` renderer lookup all read this registry.
+ */
+export function registerSceneKind(definition) {
+    registry.set(definition.kind, definition);
+}
+/** The registered definition for a kind, or undefined if the kind is a plain (non-studio) kind. @internal */
+export function getSceneKind(kind) {
+    return registry.get(kind);
+}
+/** True when a kind has a registered studio definition (schema/inspector/renderer). @internal */
+export function isSceneKind(kind) {
+    return registry.has(kind);
+}
+/** Every registered kind, optionally filtered by target, in registration order. @internal */
+export function listSceneKinds(target) {
+    const all = [...registry.values()];
+    return target === undefined ? all : all.filter((definition) => definition.target === target);
+}
+/** Parse a document object's `meta` against its registered kind schema, or `null` if unregistered. @internal */
+export function parseSceneKindParams(object) {
+    const definition = registry.get(object.kind);
+    return definition === undefined ? null : parseParams(definition.schema, object.meta);
+}