@jgengine/core 0.10.0 → 0.12.0

package/dist/scene/companion.d.ts

@@ -0,0 +1,147 @@
+import type { MobVec3 } from "../ai/mobBrain.js";
+import type { StatCatalog, StatValue, StatValueMap } from "./entityStats.js";
+/**
+ * A tamed companion's standing order. Genre-agnostic aggression + posture preset:
+ * - `follow` — heel to the owner and assist whatever the owner is fighting.
+ * - `stay` — hold at `home` and assist the owner's target from there.
+ * - `passive` — heel to the owner and never engage (a pacifist escort).
+ * - `neutral` — heel to the owner and only fight back nearby threats (defensive).
+ * - `aggressive` — heel to the owner and proactively engage nearby threats and the owner's target.
+ */
+export type CompanionCommand = "follow" | "stay" | "passive" | "neutral" | "aggressive";
+/**
+ * Serializable per-companion state: who owns it, its standing order, where it holds, its
+ * leash radius, and its levelled stat pool. Plain data — JSON round-trips without loss.
+ */
+export interface CompanionRecord {
+    id: string;
+    /** Owning user/entity id — the roster ownership tie. */
+    ownerId: string;
+    /** The {@link RosterEntry.id} this companion was tamed from, or `null` when free-standing. */
+    sourceId: string | null;
+    command: CompanionCommand;
+    /** Hold/return anchor used by `stay`; `null` until the owner parks it somewhere. */
+    home: MobVec3 | null;
+    /** Radius the game keeps the companion within of its resolved anchor (feeds a brain's leash distance). */
+    leash: number;
+    level: number;
+    /** Stat points earned from levels and not yet spent via {@link CompanionRoster.spend}. */
+    unspentPoints: number;
+    /** Levelled stat pool, composed over `scene/entityStats`. */
+    stats: StatValueMap;
+}
+/** Per-tick world context the game supplies so a command resolves into a concrete intent. */
+export interface CompanionIntentContext {
+    /** Owner's current world position — the anchor for every non-`stay` mode; `null` when absent. */
+    ownerPosition?: MobVec3 | null;
+    /** The owner's current attack target — the companion assists/aggros it per its command. */
+    ownerTargetId?: string | null;
+    /** Threat ids near the companion the game offers as engage candidates (already proximity-filtered upstream). */
+    threats?: readonly string[];
+}
+/**
+ * The companion's decision for one tick, shaped for `ai/mobBrain`: feed `candidates` into
+ * `MobBrainDeps.candidates()`, treat `leashTo` as the brain's `home`, and pass `leashDistance`
+ * as `leashDistance`. `kind` summarises the posture for HUD/animation.
+ */
+export interface CompanionIntent {
+    /** `follow`/`hold` when idle at the anchor; `engage` a fresh threat; `assist` the owner's target. */
+    kind: "follow" | "hold" | "engage" | "assist";
+    /** Whether the companion leashes to the owner (follow modes) or its `home` (stay). */
+    anchor: "owner" | "home";
+    /** Resolved anchor world point — owner position or `home`; `null` when that point is unknown. */
+    leashTo: MobVec3 | null;
+    /** Leash radius (copied from the record) the game passes to the brain / clamps movement against. */
+    leashDistance: number;
+    /** Threat ids to expose as `MobBrainDeps.candidates()`; empty when the command forbids engaging. */
+    candidates: readonly string[];
+    /** The primary threat to engage/assist this tick — `candidates[0]`; `null` while following/holding. */
+    targetId: string | null;
+}
+/** Rule for turning one spent level-point into a stat gain. Absent from config ⇒ the stat can't be upgraded. */
+export interface CompanionStatUpgrade {
+    /** Amount a single point adds to the stat's `max` (and heals into `current`). */
+    increment: number;
+    /** Hard ceiling for the stat's `max`; spends that would exceed it are rejected. */
+    maxCap?: number;
+}
+/** Outcome of {@link CompanionRoster.spend}: the updated record + stat, or a rejection reason. */
+export type CompanionSpendResult = {
+    status: "ok";
+    record: CompanionRecord;
+    stat: StatValue;
+} | {
+    status: "rejected";
+    reason: string;
+};
+/** Per-companion configuration shared by every companion the roster mints. */
+export interface CompanionConfig {
+    /** Stat catalog seeded into each new companion's pool (via `entityStats.seedStatValues`). */
+    stats?: StatCatalog;
+    /** Per-stat upgrade rules consulted by {@link CompanionRoster.spend}. */
+    upgrades?: Record<string, CompanionStatUpgrade>;
+    /** Points granted on reaching a given level; default `1` per level. Inject `game/progression` curves here. */
+    pointsPerLevel?: (level: number) => number;
+    /** Level ceiling; `levelUp` past it is a no-op. Default `Infinity`. */
+    maxLevel?: number;
+    /** Level every companion starts at; default `1`. */
+    startLevel?: number;
+    /** Default leash radius for new companions; default `12`. */
+    leash?: number;
+}
+/** Options for {@link CompanionRoster.adopt}. */
+export interface CompanionAdoptOptions {
+    id?: string;
+    /** The {@link RosterEntry.id} this companion springs from — the ownership/catalog tie. */
+    sourceId?: string;
+    command?: CompanionCommand;
+    home?: MobVec3 | null;
+    leash?: number;
+    level?: number;
+    /** Override the config stat catalog for this one companion. */
+    stats?: StatCatalog;
+}
+/**
+ * A set of tamed companions keyed by companion id, scoped to owners. Wraps allegiance/command
+ * state, per-companion levelled stats, and intent resolution behind create/command/level/
+ * snapshot/hydrate — the counterpart of `scene/roster` for creatures that fight beside you.
+ */
+export interface CompanionRoster {
+    /** Mint a companion for an owner (optionally tied to a {@link RosterEntry}). */
+    adopt(ownerId: string, options?: CompanionAdoptOptions): CompanionRecord;
+    release(companionId: string): boolean;
+    get(companionId: string): CompanionRecord | null;
+    ownerOf(companionId: string): string | null;
+    list(ownerId: string): readonly CompanionRecord[];
+    /** Set a companion's standing order; `null` if the id is unknown. */
+    command(companionId: string, command: CompanionCommand): CompanionRecord | null;
+    /** Park/clear a companion's `stay` anchor. */
+    setHome(companionId: string, home: MobVec3 | null): CompanionRecord | null;
+    setLeash(companionId: string, leash: number): CompanionRecord | null;
+    /** Gain `levels` levels (bounded by `maxLevel`), accruing points from `pointsPerLevel`. */
+    levelUp(companionId: string, levels?: number): CompanionRecord | null;
+    /** Spend one earned point into a stat per its {@link CompanionStatUpgrade} rule. */
+    spend(companionId: string, statId: string): CompanionSpendResult;
+    /** Resolve the companion's per-tick {@link CompanionIntent}; `null` if the id is unknown. */
+    resolveIntent(companionId: string, context: CompanionIntentContext): CompanionIntent | null;
+    /** Whole-store serializable copy — the save/replication seam. */
+    snapshot(): Record<string, CompanionRecord>;
+    hydrate(data: Record<string, CompanionRecord>): void;
+}
+/**
+ * Pure command → intent resolver. Maps a companion's standing order plus this tick's owner
+ * position, owner target, and nearby threats into the {@link CompanionIntent} a game feeds into
+ * `ai/mobBrain` (or executes directly). Deterministic and allocation-light — no import of the
+ * `@internal` brain factory; the two interoperate purely by shape.
+ *
+ * @capability companion-intent resolve a companion's command + threat context into a per-tick follow/hold/engage/assist intent
+ */
+export declare function resolveCompanionIntent(record: CompanionRecord, context: CompanionIntentContext): CompanionIntent;
+/**
+ * Build a {@link CompanionRoster}. Composes `scene/roster` ownership (via `ownerId`/`sourceId`),
+ * `scene/entityStats` for the per-companion stat pool, and {@link resolveCompanionIntent} for
+ * `ai/mobBrain`-shaped behavior — turning a captured creature into a loyal, levelling ally.
+ *
+ * @capability companion-roster manage tamed companions — allegiance, commands, per-companion stats/leveling, and mobBrain-shaped intent
+ */
+export declare function createCompanionRoster(config?: CompanionConfig): CompanionRoster;

package/dist/scene/companion.js

@@ -0,0 +1,193 @@
+import { seedStatValues, setStatValue } from "./entityStats.js";
+function dedupePush(out, id) {
+    if (!out.includes(id))
+        out.push(id);
+}
+function candidatesFor(command, ownerTargetId, threats) {
+    switch (command) {
+        case "passive":
+            return [];
+        case "follow":
+        case "stay":
+            return ownerTargetId === null ? [] : [ownerTargetId];
+        case "neutral":
+            return [...threats];
+        case "aggressive": {
+            const out = [];
+            for (const threat of threats)
+                dedupePush(out, threat);
+            if (ownerTargetId !== null)
+                dedupePush(out, ownerTargetId);
+            return out;
+        }
+    }
+}
+/**
+ * Pure command → intent resolver. Maps a companion's standing order plus this tick's owner
+ * position, owner target, and nearby threats into the {@link CompanionIntent} a game feeds into
+ * `ai/mobBrain` (or executes directly). Deterministic and allocation-light — no import of the
+ * `@internal` brain factory; the two interoperate purely by shape.
+ *
+ * @capability companion-intent resolve a companion's command + threat context into a per-tick follow/hold/engage/assist intent
+ */
+export function resolveCompanionIntent(record, context) {
+    const ownerTargetId = context.ownerTargetId ?? null;
+    const threats = context.threats ?? [];
+    const anchor = record.command === "stay" ? "home" : "owner";
+    const leashTo = anchor === "home" ? record.home : (context.ownerPosition ?? null);
+    const candidates = candidatesFor(record.command, ownerTargetId, threats);
+    const targetId = candidates.length > 0 ? candidates[0] : null;
+    let kind;
+    if (targetId === null) {
+        kind = anchor === "home" ? "hold" : "follow";
+    }
+    else if (targetId === ownerTargetId) {
+        kind = "assist";
+    }
+    else {
+        kind = "engage";
+    }
+    return { kind, anchor, leashTo, leashDistance: record.leash, candidates, targetId };
+}
+function cloneStats(stats) {
+    const out = {};
+    for (const [statId, value] of Object.entries(stats))
+        out[statId] = { ...value };
+    return out;
+}
+function cloneRecord(record) {
+    return {
+        id: record.id,
+        ownerId: record.ownerId,
+        sourceId: record.sourceId,
+        command: record.command,
+        home: record.home === null ? null : [record.home[0], record.home[1], record.home[2]],
+        leash: record.leash,
+        level: record.level,
+        unspentPoints: record.unspentPoints,
+        stats: cloneStats(record.stats),
+    };
+}
+/**
+ * Build a {@link CompanionRoster}. Composes `scene/roster` ownership (via `ownerId`/`sourceId`),
+ * `scene/entityStats` for the per-companion stat pool, and {@link resolveCompanionIntent} for
+ * `ai/mobBrain`-shaped behavior — turning a captured creature into a loyal, levelling ally.
+ *
+ * @capability companion-roster manage tamed companions — allegiance, commands, per-companion stats/leveling, and mobBrain-shaped intent
+ */
+export function createCompanionRoster(config = {}) {
+    const records = new Map();
+    const pointsPerLevel = config.pointsPerLevel ?? (() => 1);
+    const maxLevel = config.maxLevel ?? Number.POSITIVE_INFINITY;
+    const startLevel = config.startLevel ?? 1;
+    const defaultLeash = config.leash ?? 12;
+    let counter = 0;
+    const write = (record) => {
+        records.set(record.id, record);
+        return record;
+    };
+    const patch = (companionId, fn) => {
+        const record = records.get(companionId);
+        if (record === undefined)
+            return null;
+        return write(fn(record));
+    };
+    return {
+        adopt(ownerId, options = {}) {
+            counter += 1;
+            const id = options.id ?? `companion_${counter}`;
+            const seed = options.stats ?? config.stats ?? {};
+            const record = {
+                id,
+                ownerId,
+                sourceId: options.sourceId ?? null,
+                command: options.command ?? "follow",
+                home: options.home ?? null,
+                leash: options.leash ?? defaultLeash,
+                level: options.level ?? startLevel,
+                unspentPoints: 0,
+                stats: seedStatValues(seed),
+            };
+            return write(record);
+        },
+        release(companionId) {
+            return records.delete(companionId);
+        },
+        get(companionId) {
+            return records.get(companionId) ?? null;
+        },
+        ownerOf(companionId) {
+            return records.get(companionId)?.ownerId ?? null;
+        },
+        list(ownerId) {
+            const out = [];
+            for (const record of records.values())
+                if (record.ownerId === ownerId)
+                    out.push(record);
+            return out;
+        },
+        command(companionId, command) {
+            return patch(companionId, (record) => ({ ...record, command }));
+        },
+        setHome(companionId, home) {
+            return patch(companionId, (record) => ({
+                ...record,
+                home: home === null ? null : [home[0], home[1], home[2]],
+            }));
+        },
+        setLeash(companionId, leash) {
+            return patch(companionId, (record) => ({ ...record, leash }));
+        },
+        levelUp(companionId, levels = 1) {
+            return patch(companionId, (record) => {
+                let level = record.level;
+                let points = record.unspentPoints;
+                for (let i = 0; i < levels && level < maxLevel; i += 1) {
+                    level += 1;
+                    points += pointsPerLevel(level);
+                }
+                return { ...record, level, unspentPoints: points };
+            });
+        },
+        spend(companionId, statId) {
+            const record = records.get(companionId);
+            if (record === undefined)
+                return { status: "rejected", reason: `unknown companion "${companionId}"` };
+            if (record.unspentPoints <= 0)
+                return { status: "rejected", reason: "no unspent points" };
+            const upgrade = config.upgrades?.[statId];
+            if (upgrade === undefined)
+                return { status: "rejected", reason: `stat "${statId}" is not upgradable` };
+            const existing = record.stats[statId];
+            if (existing === undefined)
+                return { status: "rejected", reason: `unknown stat "${statId}"` };
+            const nextMax = existing.max + upgrade.increment;
+            if (upgrade.maxCap !== undefined && nextMax > upgrade.maxCap) {
+                return { status: "rejected", reason: `stat "${statId}" is at its cap` };
+            }
+            const stats = setStatValue(record.stats, statId, {
+                max: nextMax,
+                current: existing.current + upgrade.increment,
+            });
+            const updated = write({ ...record, unspentPoints: record.unspentPoints - 1, stats });
+            return { status: "ok", record: updated, stat: updated.stats[statId] };
+        },
+        resolveIntent(companionId, context) {
+            const record = records.get(companionId);
+            if (record === undefined)
+                return null;
+            return resolveCompanionIntent(record, context);
+        },
+        snapshot() {
+            const out = {};
+            for (const [id, record] of records)
+                out[id] = cloneRecord(record);
+            return out;
+        },
+        hydrate(data) {
+            records.clear();
+            for (const [id, record] of Object.entries(data))
+                records.set(id, cloneRecord(record));
+        },
+    };
+}

package/dist/scene/entityStats.d.ts

@@ -1,12 +1,9 @@
-export interface StatValue {
-    current: number;
-    max: number;
-    min: number;
+import { type StatPool, type StatPoolAccess, type StatPoolPatch } from "../stats/statPool.js";
+/** Native entity-stat name retained as a compatibility bridge to the portable pool model. */
+export interface StatValue extends StatPool {
 }
-export interface StatValuePatch {
-    current?: number;
-    max?: number;
-    min?: number;
+/** Native entity-stat patch retained as a compatibility bridge. */
+export interface StatValuePatch extends StatPoolPatch {
 }
 export type StatValueMap = Record<string, StatValue>;
 export type StatCatalog = Record<string, {
@@ -24,19 +21,29 @@ 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 {
+/** Native entity-stat adapter over the portable {@link StatPoolAccess} contract. */
+export interface EntityStatsApi extends StatPoolAccess {
     get(instanceId: string, statId: string): StatValue | null;
     set(instanceId: string, statId: string, patch: StatValuePatch): boolean;
     delta(instanceId: string, statId: string, amount: number): null | {
         reason: string;
     };
 }
+/** @internal */
 export declare function createEntityStatsApi(resolve: (instanceId: string) => StatValueMap | undefined): EntityStatsApi;

package/dist/scene/entityStats.js

@@ -1,41 +1,43 @@
-function clamp(value, min, max) {
-    return Math.min(max, Math.max(min, value));
-}
+import { changeStatPool, createStatPool, patchStatPool, } from "../stats/statPool.js";
+/** @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;
-    const min = patch.min ?? existing?.min ?? 0;
-    const current = clamp(patch.current ?? existing?.current ?? max, min, max);
-    return { ...map, [statId]: { current, max, min } };
+    const next = existing === undefined
+        ? createStatPool({ max: patch.max ?? 0, min: patch.min, current: patch.current })
+        : patchStatPool(existing, patch);
+    return { ...map, [statId]: next };
 }
+/** @internal */
 export function applyPoolDelta(map, statId, amount) {
     const existing = map[statId];
     if (existing === undefined) {
         return { status: "rejected", reason: `unknown stat "${statId}"` };
     }
-    const current = clamp(existing.current + amount, existing.min, existing.max);
-    const stat = { ...existing, current };
+    const change = changeStatPool(existing, amount);
+    const stat = change.pool;
     return {
         status: "ok",
         map: { ...map, [statId]: stat },
         stat,
-        hitMin: current === existing.min,
-        hitMax: current === existing.max,
+        hitMin: change.hitMin,
+        hitMax: change.hitMax,
     };
 }
+/** @internal */
 export function seedStatValues(catalogStats) {
     const map = {};
     for (const [statId, declaration] of Object.entries(catalogStats)) {
-        const min = declaration.min ?? 0;
-        const current = clamp(declaration.current ?? declaration.max, min, declaration.max);
-        map[statId] = { current, max: declaration.max, min };
+        map[statId] = createStatPool(declaration);
     }
     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 +48,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 +60,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 };