@jgengine/core 0.9.0 → 0.11.0

package/dist/scene/behaviorRuntime.js

@@ -0,0 +1,217 @@
+import { seededRng } from "../random/rng.js";
+import { advancePathFollow, createPathFollow, pathFollowSeek, } from "../nav/pathFollow.js";
+import { perContext } from "../runtime/perContext.js";
+const DEFAULT_WANDER_SPEED = 1.5;
+const WANDER_ARRIVAL = 0.6;
+function patrolOf(entity) {
+    return entity.behaviors.find((b) => b.kind === "patrol") ?? null;
+}
+function wanderOf(entity) {
+    return entity.behaviors.find((b) => b.kind === "wander") ?? null;
+}
+const runtimeOf = perContext((ctx) => {
+    const nav = new Map();
+    const refresh = () => {
+        const live = new Set();
+        for (const entity of ctx.scene.entity.list()) {
+            live.add(entity.id);
+            if (nav.has(entity.id))
+                continue;
+            const patrol = patrolOf(entity);
+            if (patrol !== null) {
+                const config = { waypoints: patrol.waypoints, speed: patrol.speed, loop: patrol.loop };
+                nav.set(entity.id, {
+                    kind: "patrol",
+                    config,
+                    state: patrol.startProgress !== undefined ? pathFollowSeek(config, patrol.startProgress) : createPathFollow(config),
+                    groundClamp: patrol.groundClamp ?? false,
+                    status: "active",
+                    reason: null,
+                    pausedElapsed: 0,
+                });
+                continue;
+            }
+            const wander = wanderOf(entity);
+            if (wander !== null) {
+                nav.set(entity.id, {
+                    kind: "wander",
+                    radius: wander.radius,
+                    origin: entity.position,
+                    target: null,
+                    roll: seededRng(`wander:${entity.id}`),
+                    status: "active",
+                    reason: null,
+                    pausedElapsed: 0,
+                });
+            }
+        }
+        for (const id of nav.keys())
+            if (!live.has(id))
+                nav.delete(id);
+    };
+    ctx.scene.entity.subscribeMembership(refresh);
+    refresh();
+    return { nav };
+});
+function stepWander(ctx, id, nav, dt) {
+    const entity = ctx.scene.entity.get(id);
+    if (entity === null)
+        return;
+    const [px, , pz] = entity.position;
+    if (nav.target === null || Math.hypot(px - nav.target[0], pz - nav.target[2]) < WANDER_ARRIVAL) {
+        const angle = nav.roll() * Math.PI * 2;
+        const distance = Math.sqrt(nav.roll()) * nav.radius;
+        const tx = nav.origin[0] + Math.cos(angle) * distance;
+        const tz = nav.origin[2] + Math.sin(angle) * distance;
+        nav.target = [tx, ctx.world.groundHeightAt(tx, tz), tz];
+    }
+    const speed = entity.movement.walkSpeed ?? DEFAULT_WANDER_SPEED;
+    const dx = nav.target[0] - px;
+    const dz = nav.target[2] - pz;
+    const dist = Math.hypot(dx, dz);
+    if (dist < 1e-6)
+        return;
+    const step = Math.min(dist, speed * dt);
+    const nx = px + (dx / dist) * step;
+    const nz = pz + (dz / dist) * step;
+    ctx.scene.entity.setPose(id, {
+        position: [nx, ctx.world.groundHeightAt(nx, nz), nz],
+        rotationY: Math.atan2(dx, dz),
+        dt,
+    });
+}
+function posePatrol(ctx, id, nav, dt) {
+    const [x, y, z] = nav.state.position;
+    ctx.scene.entity.setPose(id, {
+        position: nav.groundClamp ? [x, ctx.world.groundHeightAt(x, z), z] : [x, y, z],
+        rotationY: nav.state.heading,
+        dt,
+    });
+}
+/**
+ * Advance every spawned entity carrying a `patrol` or `wander` {@link BehaviorDescriptor} one tick — the
+ * engine reads the descriptor, keeps the per-entity nav state itself, and poses the entity, so ambient
+ * traffic and idle NPC routes are register-once (attach the behavior at spawn) instead of a per-game
+ * per-frame `advancePathFollow` + `setPose` loop. Instances that are paused or disabled through
+ * {@link behaviorControl} retain their state and are skipped. The shell/host call this each frame; a game never does.
+ *
+ * @capability behavior-tick auto-advance patrol/wander behaviors on spawned entities, no per-game route loop
+ */
+export function advanceBehaviors(ctx, dt) {
+    if (dt <= 0)
+        return;
+    const { nav } = runtimeOf(ctx);
+    if (nav.size === 0)
+        return;
+    for (const [id, entry] of nav) {
+        if (entry.status !== "active") {
+            if (entry.status === "paused")
+                entry.pausedElapsed += dt;
+            continue;
+        }
+        if (entry.kind === "patrol") {
+            entry.state = advancePathFollow(entry.config, entry.state, dt);
+            posePatrol(ctx, id, entry, dt);
+        }
+        else {
+            stepWander(ctx, id, entry, dt);
+        }
+    }
+}
+/**
+ * Obtain the per-context {@link BehaviorControl} surface for suspending, resuming, seeking, serializing,
+ * and inspecting behavior instances by entity id — the lifecycle contract games use to hand pose
+ * ownership to possession/streaming/staggering code instead of bypassing the behavior runtime.
+ *
+ * @capability behavior-control pause/disable/resume/seek/inspect behavior instances per entity
+ */
+export function behaviorControl(ctx) {
+    const { nav } = runtimeOf(ctx);
+    const setStatus = (id, status, reason) => {
+        const entry = nav.get(id);
+        if (entry === undefined)
+            return false;
+        entry.status = status;
+        entry.reason = reason;
+        return true;
+    };
+    return {
+        status: (id) => nav.get(id)?.status ?? null,
+        reason: (id) => nav.get(id)?.reason ?? null,
+        pause: (id, reason) => {
+            const entry = nav.get(id);
+            if (entry === undefined || entry.status !== "active")
+                return false;
+            entry.status = "paused";
+            entry.reason = reason ?? null;
+            entry.pausedElapsed = 0;
+            return true;
+        },
+        resume: (id, policy = "freeze") => {
+            const entry = nav.get(id);
+            if (entry === undefined || entry.status !== "paused")
+                return false;
+            if (policy === "advance" && entry.kind === "patrol" && entry.pausedElapsed > 0) {
+                entry.state = advancePathFollow(entry.config, entry.state, entry.pausedElapsed);
+                // Emit a single final pose at the caught-up position (no intermediate writes).
+                posePatrol(ctx, id, entry, entry.pausedElapsed);
+            }
+            entry.status = "active";
+            entry.reason = null;
+            entry.pausedElapsed = 0;
+            return true;
+        },
+        disable: (id, reason) => setStatus(id, "disabled", reason ?? null),
+        enable: (id) => {
+            const entry = nav.get(id);
+            if (entry === undefined || entry.status !== "disabled")
+                return false;
+            entry.status = "active";
+            entry.reason = null;
+            entry.pausedElapsed = 0;
+            return true;
+        },
+        seek: (id, progress) => {
+            const entry = nav.get(id);
+            if (entry === undefined || entry.kind !== "patrol")
+                return false;
+            entry.state = pathFollowSeek(entry.config, progress);
+            return true;
+        },
+        serialize: (id) => {
+            const entry = nav.get(id);
+            if (entry === undefined)
+                return null;
+            if (entry.kind === "patrol")
+                return { kind: "patrol", state: { ...entry.state } };
+            return { kind: "wander", origin: [...entry.origin], target: entry.target === null ? null : [...entry.target] };
+        },
+        restore: (id, snapshot) => {
+            const entry = nav.get(id);
+            if (entry === undefined || entry.kind !== snapshot.kind)
+                return false;
+            if (entry.kind === "patrol" && snapshot.kind === "patrol") {
+                entry.state = { ...snapshot.state };
+                return true;
+            }
+            if (entry.kind === "wander" && snapshot.kind === "wander") {
+                entry.origin = [...snapshot.origin];
+                entry.target = snapshot.target === null ? null : [...snapshot.target];
+                return true;
+            }
+            return false;
+        },
+        inspect: (id) => {
+            const entry = nav.get(id);
+            if (entry === undefined)
+                return null;
+            return { id, kind: entry.kind, status: entry.status, reason: entry.reason };
+        },
+        list: () => {
+            const out = [];
+            for (const [id, entry] of nav)
+                out.push({ id, kind: entry.kind, status: entry.status, reason: entry.reason });
+            return out;
+        },
+    };
+}

package/dist/scene/behaviors.d.ts

@@ -1,5 +1,5 @@
 import { type ProximityPrompt } from "../interaction/proximityPrompt.js";
-import type { Waypoint } from "../nav/pathFollow.js";
+import type { PathProgress, Waypoint } from "../nav/pathFollow.js";
 export interface WanderBehavior {
     kind: "wander";
     radius: number;
@@ -9,6 +9,16 @@ export interface PatrolBehavior {
     waypoints: readonly Waypoint[];
     speed: number;
     loop: boolean;
+    /**
+     * Optional initial progress the follower is seeded at instead of waypoint zero — lets a fleet of
+     * route followers start at distributed phases. Round-trips through the behavior lifecycle seek/serialize.
+     */
+    startProgress?: PathProgress;
+    /**
+     * Sample world ground height for the pose Y each tick, so a route authored in the XZ plane rides
+     * uneven terrain. Default false (waypoint Y is used verbatim).
+     */
+    groundClamp?: boolean;
 }
 export interface PromptableBehavior {
     kind: "promptable";
@@ -21,10 +31,12 @@ export type BehaviorDescriptor = WanderBehavior | PatrolBehavior | PromptableBeh
 export declare function wander({ radius }: {
     radius: number;
 }): WanderBehavior;
-export declare function patrol({ waypoints, speed, loop, }: {
+export declare function patrol({ waypoints, speed, loop, startProgress, groundClamp, }: {
     waypoints: readonly Waypoint[];
     speed: number;
     loop?: boolean;
+    startProgress?: PathProgress;
+    groundClamp?: boolean;
 }): PatrolBehavior;
 export declare function promptable(prompt: ProximityPrompt): PromptableBehavior;
 export declare function talkable(dialogueId: string): PromptableBehavior;

package/dist/scene/behaviors.js

@@ -2,8 +2,13 @@ import { command, keybind, proximityPrompt, } from "../interaction/proximityProm
 export function wander({ radius }) {
     return { kind: "wander", radius };
 }
-export function patrol({ waypoints, speed, loop = true, }) {
-    return { kind: "patrol", waypoints, speed, loop };
+export function patrol({ waypoints, speed, loop = true, startProgress, groundClamp, }) {
+    const behavior = { kind: "patrol", waypoints, speed, loop };
+    if (startProgress !== undefined)
+        behavior.startProgress = startProgress;
+    if (groundClamp !== undefined)
+        behavior.groundClamp = groundClamp;
+    return behavior;
 }
 export function promptable(prompt) {
     return { kind: "promptable", prompt };

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

@@ -33,11 +33,29 @@ export interface ResolvedCollider {
 }
 export declare const DEFAULT_ENTITY_HIT_RADIUS = 0.5;
 export declare const DEFAULT_OBJECT_HALF_EXTENTS: EntityPosition;
+/** Matches the shell's fallback actor capsule (~0.7m wide, feet at y=0 to head at ~1.8m). */
+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).
+ * @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

@@ -1,18 +1,56 @@
 export const DEFAULT_ENTITY_HIT_RADIUS = 0.5;
 export const DEFAULT_OBJECT_HALF_EXTENTS = [0.5, 0.5, 0.5];
+/** Matches the shell's fallback actor capsule (~0.7m wide, feet at y=0 to head at ~1.8m). */
+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: [
             {
                 name: "body",
                 purpose: "damage",
-                shape: { kind: "sphere", radius: DEFAULT_ENTITY_HIT_RADIUS },
+                shape: {
+                    kind: "aabb",
+                    halfExtents: DEFAULT_ENTITY_BODY_HALF_EXTENTS,
+                    offset: DEFAULT_ENTITY_BODY_OFFSET,
+                },
                 damageEligible: true,
                 blocks: false,
             },
         ],
     };
 }
+/** 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: {
@@ -24,6 +62,25 @@ 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).
+ * @internal
+ */
+export function scaledObjectColliders(scale) {
+    return {
+        body: {
+            name: "body",
+            purpose: "physical",
+            shape: {
+                kind: "aabb",
+                halfExtents: [scale[0] / 2, scale[1] / 2, scale[2] / 2],
+                offset: [0, scale[1] / 2, 0],
+            },
+            damageEligible: false,
+            blocks: true,
+        },
+    };
+}
+/** @internal */
 export function resolveColliders(set) {
     if (set === null || set === undefined)
         return [];
@@ -47,6 +104,7 @@ function resolveOne(def) {
         blocks,
     };
 }
+/** @internal */
 export function worldOffset(local, position, rotationY) {
     if (local === undefined)
         return position;
@@ -57,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,10 +24,22 @@ 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}.
+ * @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.
+ * @internal
+ */
+export declare function hydrateEntityStats(store: Map<string, StatValueMap>, data: Record<string, StatValueMap>): void;
 export interface EntityStatsApi {
     get(instanceId: string, statId: string): StatValue | null;
     set(instanceId: string, statId: string, patch: StatValuePatch): boolean;
@@ -35,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,6 +39,32 @@ export function seedStatValues(catalogStats) {
     }
     return map;
 }
+/** 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) {
+        const copy = {};
+        for (const [statId, value] of Object.entries(map))
+            copy[statId] = { ...value };
+        out[instanceId] = copy;
+    }
+    return out;
+}
+/** 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)) {
+        const copy = {};
+        for (const [statId, value] of Object.entries(map))
+            copy[statId] = { ...value };
+        store.set(instanceId, copy);
+    }
+}
+/** @internal */
 export function createEntityStatsApi(resolve) {
     return {
         get(instanceId, statId) {