@jgengine/core 0.8.0 → 0.10.0

package/dist/runtime/visibility.js

@@ -0,0 +1,127 @@
+/** Default `VisibilityDefaults` a `VisibilitySystem` falls back to when unspecified. */
+export const DEFAULT_VISIBILITY_SETTINGS = Object.freeze({
+    enabled: true,
+    streamingEnabled: true,
+    minRenderDistance: 0,
+    maxRenderDistance: Number.POSITIVE_INFINITY,
+    preloadMargin: 24,
+    unloadGraceMs: 5_000,
+    hysteresis: 8,
+});
+function squaredDistance(a, b) {
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+    const dz = (a.z ?? 0) - (b.z ?? 0);
+    return dx * dx + dy * dy + dz * dz;
+}
+function intersectsRadius(camera, bounds, extraMargin) {
+    const radius = Math.max(0, camera.visibleRadius + extraMargin + bounds.radius);
+    return squaredDistance(camera.position, bounds.center) <= radius * radius;
+}
+/**
+ * Engine-level visibility and asset-residency policy.
+ *
+ * Render culling and asset streaming are intentionally separate. This class never
+ * destroys entities or throttles simulation; adapters decide how to apply results.
+ */
+export class VisibilitySystem {
+    settings;
+    #states = new Map();
+    constructor(settings = {}) {
+        this.settings = { ...DEFAULT_VISIBILITY_SETTINGS, ...settings };
+    }
+    evaluate(object, cameras, now = Date.now()) {
+        const overrides = object.overrides ?? {};
+        const state = this.#states.get(object.id) ?? { loaded: false, lastNeededAt: now };
+        if (overrides.alwaysVisible) {
+            this.#markNeeded(object.id, state, now);
+            return { render: true, load: true, unload: false, reason: "always-visible" };
+        }
+        if (!this.settings.enabled || overrides.cullingDisabled) {
+            this.#markNeeded(object.id, state, now);
+            return { render: true, load: true, unload: false, reason: "culling-disabled" };
+        }
+        const minDistance = Math.max(0, overrides.minRenderDistance ?? this.settings.minRenderDistance);
+        const maxDistance = Math.max(minDistance, overrides.maxRenderDistance ?? this.settings.maxRenderDistance);
+        const minDistanceSq = minDistance * minDistance;
+        const maxDistanceWithRadius = maxDistance + object.bounds.radius;
+        const maxDistanceSq = maxDistanceWithRadius * maxDistanceWithRadius;
+        let insideDistance = false;
+        let visible = false;
+        let preload = false;
+        for (const camera of cameras) {
+            const distanceSq = squaredDistance(camera.position, object.bounds.center);
+            if (distanceSq < minDistanceSq || distanceSq > maxDistanceSq)
+                continue;
+            insideDistance = true;
+            if (intersectsRadius(camera, object.bounds, this.settings.hysteresis)) {
+                visible = true;
+            }
+            if (camera.influencesStreaming !== false) {
+                const margin = overrides.preloadMargin ?? camera.preloadMargin ?? this.settings.preloadMargin;
+                if (intersectsRadius(camera, object.bounds, margin + this.settings.hysteresis)) {
+                    preload = true;
+                }
+            }
+        }
+        if (visible) {
+            this.#markNeeded(object.id, state, now);
+            return { render: true, load: true, unload: false, reason: "visible" };
+        }
+        if (overrides.streamingDisabled || !this.settings.streamingEnabled) {
+            state.loaded = true;
+            this.#states.set(object.id, state);
+            return {
+                render: false,
+                load: true,
+                unload: false,
+                reason: "streaming-disabled",
+            };
+        }
+        if (preload) {
+            this.#markNeeded(object.id, state, now);
+            return { render: false, load: true, unload: false, reason: "preload" };
+        }
+        if (overrides.neverUnload) {
+            state.loaded = true;
+            this.#states.set(object.id, state);
+            return {
+                render: false,
+                load: true,
+                unload: false,
+                reason: insideDistance ? "outside-view" : "distance-culled",
+            };
+        }
+        const graceActive = state.loaded && now - state.lastNeededAt < this.settings.unloadGraceMs;
+        if (graceActive) {
+            this.#states.set(object.id, state);
+            return { render: false, load: true, unload: false, reason: "grace-period" };
+        }
+        state.loaded = false;
+        this.#states.set(object.id, state);
+        return {
+            render: false,
+            load: false,
+            unload: true,
+            reason: insideDistance ? "outside-view" : "distance-culled",
+        };
+    }
+    setLoaded(id, loaded, now = Date.now()) {
+        const previous = this.#states.get(id);
+        this.#states.set(id, {
+            loaded,
+            lastNeededAt: loaded ? now : previous?.lastNeededAt ?? now,
+        });
+    }
+    forget(id) {
+        this.#states.delete(id);
+    }
+    clear() {
+        this.#states.clear();
+    }
+    #markNeeded(id, state, now) {
+        state.loaded = true;
+        state.lastNeededAt = now;
+        this.#states.set(id, state);
+    }
+}

package/dist/runtime/worldChannel.d.ts

@@ -0,0 +1,58 @@
+import type { GameContext } from "./gameContext.js";
+import type { InputFrame } from "./hostedGameRunner.js";
+import type { HostedWorldSession } from "./hostedWorldSession.js";
+import type { WorldDiff } from "./worldReplication.js";
+import type { WorldSnapshot } from "./worldSnapshot.js";
+/** Host→client frame: the full baseline a joiner needs, then per-tick diffs. What a transport marshals downstream. */
+export type WorldServerFrame = {
+    t: "baseline";
+    revision: number;
+    snapshot: WorldSnapshot;
+} | {
+    t: "diff";
+    diff: WorldDiff;
+};
+/** Client→host frame: a player's session verbs. What a transport marshals upstream. */
+export type WorldClientFrame = {
+    t: "join";
+    isNew: boolean;
+} | {
+    t: "leave";
+} | {
+    t: "command";
+    name: string;
+    input: unknown;
+} | {
+    t: "input";
+    frame: InputFrame;
+};
+/** One client's link on the host side: routes its upstream frames into the shared session, pushes it sync frames. */
+export interface WorldHostConnection {
+    receive(frame: WorldClientFrame): void;
+    push(): void;
+    close(): void;
+}
+/**
+ * The transport-agnostic host: fans one {@link HostedWorldSession} out to many connections, each tracking its own
+ * revision cursor so a joiner gets a baseline and everyone else gets diffs. A ws server, a Convex function, or an
+ * in-process loopback all drive the same shape — decode a frame → `connection.receive`; after `session.tick` →
+ * `broadcast`. No wire format is assumed; frames are plain data a transport serializes however it likes.
+ */
+export interface WorldHost {
+    connect(userId: string, send: (frame: WorldServerFrame) => void): WorldHostConnection;
+    broadcast(): void;
+    session(): HostedWorldSession;
+}
+/** Build a {@link WorldHost} fanning one {@link HostedWorldSession} out to many cursor-tracked connections. */
+export declare function createWorldHost(session: HostedWorldSession): WorldHost;
+/** The client end of a {@link WorldHost} connection: applies server frames to a local `ctx`, sends session verbs upstream. */
+export interface WorldClientLink {
+    receive(frame: WorldServerFrame): void;
+    join(isNew: boolean): void;
+    leave(): void;
+    command(name: string, input: unknown): void;
+    input(frame: InputFrame): void;
+    revision(): number;
+}
+/** Build a {@link WorldClientLink} — the client end that mirrors host frames into `ctx` and sends session verbs upstream. */
+export declare function createWorldClientLink(ctx: Pick<GameContext, "hydrate">, send: (frame: WorldClientFrame) => void): WorldClientLink;

package/dist/runtime/worldChannel.js

@@ -0,0 +1,69 @@
+import { createWorldMirror } from "./worldMirror.js";
+/** Build a {@link WorldHost} fanning one {@link HostedWorldSession} out to many cursor-tracked connections. */
+export function createWorldHost(session) {
+    const connections = new Set();
+    function connect(userId, send) {
+        let cursor = 0;
+        const connection = {
+            receive(frame) {
+                switch (frame.t) {
+                    case "join":
+                        session.join(userId, frame.isNew);
+                        break;
+                    case "leave":
+                        session.leave(userId);
+                        break;
+                    case "command":
+                        session.command(userId, frame.name, frame.input);
+                        break;
+                    case "input":
+                        session.input(userId, frame.frame);
+                        break;
+                }
+            },
+            push() {
+                if (cursor !== 0 && cursor === session.revision())
+                    return;
+                const sync = session.sync(cursor === 0 ? null : cursor);
+                if (sync.kind === "baseline") {
+                    cursor = sync.revision;
+                    send({ t: "baseline", revision: sync.revision, snapshot: sync.snapshot });
+                }
+                else {
+                    cursor = sync.diff.revision;
+                    send({ t: "diff", diff: sync.diff });
+                }
+            },
+            close() {
+                connections.delete(connection);
+            },
+        };
+        connections.add(connection);
+        return connection;
+    }
+    return {
+        connect,
+        broadcast() {
+            for (const connection of connections)
+                connection.push();
+        },
+        session: () => session,
+    };
+}
+/** Build a {@link WorldClientLink} — the client end that mirrors host frames into `ctx` and sends session verbs upstream. */
+export function createWorldClientLink(ctx, send) {
+    const mirror = createWorldMirror(ctx);
+    return {
+        receive(frame) {
+            if (frame.t === "baseline")
+                mirror.applyBaseline(frame.revision, frame.snapshot);
+            else
+                mirror.applyDiff(frame.diff);
+        },
+        join: (isNew) => send({ t: "join", isNew }),
+        leave: () => send({ t: "leave" }),
+        command: (name, input) => send({ t: "command", name, input }),
+        input: (frame) => send({ t: "input", frame }),
+        revision: () => mirror.revision(),
+    };
+}

package/dist/runtime/worldMirror.d.ts

@@ -0,0 +1,24 @@
+import type { GameContext } from "./gameContext.js";
+import type { HostedWorldSession } from "./hostedWorldSession.js";
+import { type WorldDiff } from "./worldReplication.js";
+import type { WorldSnapshot } from "./worldSnapshot.js";
+/**
+ * The client end of host-authoritative replication: folds a host's baseline + {@link WorldDiff} stream onto a
+ * local {@link GameContext}. It keeps the last full {@link WorldSnapshot}, advances it with each diff, and pushes
+ * the result through `ctx.hydrate` — so the client mirrors exactly the subsystems its own game opted into and
+ * silently ignores host modules it lacks. This is the inverse of a {@link HostedWorldSession}; the transport in
+ * between (loopback, ws, Convex) is irrelevant.
+ */
+export interface WorldMirror {
+    applyBaseline(revision: number, snapshot: WorldSnapshot): void;
+    applyDiff(diff: WorldDiff): void;
+    revision(): number;
+}
+/** Build a {@link WorldMirror} that replicates a host's baseline + diff stream onto `ctx` via `ctx.hydrate`. */
+export declare function createWorldMirror(ctx: Pick<GameContext, "hydrate">): WorldMirror;
+/**
+ * Pull one replication step from a co-located {@link HostedWorldSession} into a {@link WorldMirror} — the
+ * no-network local path (host and client in one process). A fresh mirror pulls a baseline; thereafter it pulls
+ * a diff since its own revision. The same `sync(sinceRevision)` call is what a networked transport marshals.
+ */
+export declare function pullWorld(session: HostedWorldSession, mirror: WorldMirror): void;

package/dist/runtime/worldMirror.js

@@ -0,0 +1,31 @@
+import { applyWorldDiff } from "./worldReplication.js";
+/** Build a {@link WorldMirror} that replicates a host's baseline + diff stream onto `ctx` via `ctx.hydrate`. */
+export function createWorldMirror(ctx) {
+    let mirror = {};
+    let revision = 0;
+    return {
+        applyBaseline(nextRevision, snapshot) {
+            mirror = snapshot;
+            revision = nextRevision;
+            ctx.hydrate(snapshot);
+        },
+        applyDiff(diff) {
+            mirror = applyWorldDiff(mirror, diff);
+            revision = diff.revision;
+            ctx.hydrate(mirror);
+        },
+        revision: () => revision,
+    };
+}
+/**
+ * Pull one replication step from a co-located {@link HostedWorldSession} into a {@link WorldMirror} — the
+ * no-network local path (host and client in one process). A fresh mirror pulls a baseline; thereafter it pulls
+ * a diff since its own revision. The same `sync(sinceRevision)` call is what a networked transport marshals.
+ */
+export function pullWorld(session, mirror) {
+    const sync = session.sync(mirror.revision() === 0 ? null : mirror.revision());
+    if (sync.kind === "baseline")
+        mirror.applyBaseline(sync.revision, sync.snapshot);
+    else
+        mirror.applyDiff(sync.diff);
+}

package/dist/runtime/worldReplication.d.ts

@@ -0,0 +1,46 @@
+import type { SceneEntity } from "../scene/entityStore.js";
+import type { StatValueMap } from "../scene/entityStats.js";
+import type { WorldSnapshot } from "./worldSnapshot.js";
+/**
+ * A revision-stamped delta over a {@link WorldSnapshot}. The host sends one per tick to each client, carrying
+ * only what changed since that client's last acknowledged revision — entity/stat/store deltas plus whole
+ * snapshots of any other opted-in module (feed, leaderboard, chat, …) that changed. Fold it onto a prior
+ * baseline with {@link applyWorldDiff}.
+ */
+export interface WorldDiff {
+    revision: number;
+    entities: readonly SceneEntity[];
+    removedEntities: readonly string[];
+    stats: Record<string, StatValueMap>;
+    removedStats: readonly string[];
+    store: readonly (readonly [string, unknown])[];
+    removedStore: readonly string[];
+    /** Changed whole-module snapshots keyed by module name — everything a client can't reconstruct from deltas. */
+    modules: WorldSnapshot;
+}
+/**
+ * Turns successive full {@link WorldSnapshot}s into per-client {@link WorldDiff}s. Each `commit()` re-reads the
+ * world, stamps every item that changed with the new revision, and remembers removals; `diff(sinceRevision)`
+ * then replays exactly the items stamped after that revision. Everything the tracker holds is JSON — the same
+ * shape that rides the wire — so a diff is inherently serializable. Change-detection is a full re-serialize per
+ * commit; dirty-hint acceleration is a later optimization behind the same seam.
+ */
+export declare function createWorldReplicator(takeSnapshot: () => WorldSnapshot): {
+    commit: () => number;
+    diff: (sinceRevision: number) => WorldDiff;
+    revision: () => number;
+};
+/** The stateful diff tracker returned by {@link createWorldReplicator}: `commit()`, `diff(sinceRevision)`, `revision()`. */
+export type WorldReplicator = ReturnType<typeof createWorldReplicator>;
+/**
+ * Diff two full {@link WorldSnapshot}s directly, stamping the result at `revision` — the stateless counterpart of
+ * {@link createWorldReplicator} for hosts that persist snapshots rather than keep a live tracker (Convex reconstructs
+ * per invocation). `applyWorldDiff(prev, diffSnapshots(prev, next, r))` reproduces `next`.
+ */
+export declare function diffSnapshots(prev: WorldSnapshot, next: WorldSnapshot, revision: number): WorldDiff;
+/**
+ * Fold a {@link WorldDiff} onto a prior {@link WorldSnapshot} baseline, returning the next full snapshot — the
+ * client-side inverse of {@link createWorldReplicator}. Pure data in, pure data out: upserts changed entities,
+ * stats and store keys, drops the removed ones, and replaces changed module snapshots wholesale.
+ */
+export declare function applyWorldDiff(baseline: WorldSnapshot, diff: WorldDiff): WorldSnapshot;

package/dist/runtime/worldReplication.js

@@ -0,0 +1,185 @@
+const CORE_KEYS = new Set(["entities", "stats", "store"]);
+/**
+ * Turns successive full {@link WorldSnapshot}s into per-client {@link WorldDiff}s. Each `commit()` re-reads the
+ * world, stamps every item that changed with the new revision, and remembers removals; `diff(sinceRevision)`
+ * then replays exactly the items stamped after that revision. Everything the tracker holds is JSON — the same
+ * shape that rides the wire — so a diff is inherently serializable. Change-detection is a full re-serialize per
+ * commit; dirty-hint acceleration is a later optimization behind the same seam.
+ */
+export function createWorldReplicator(takeSnapshot) {
+    let revision = 0;
+    const entities = new Map();
+    const removedEntities = new Map();
+    const stats = new Map();
+    const removedStats = new Map();
+    const store = new Map();
+    const removedStore = new Map();
+    const modules = new Map();
+    function diffMap(live, tracked, removed, nextRevision) {
+        let changed = false;
+        for (const [key, json] of live) {
+            const prev = tracked.get(key);
+            if (prev === undefined || prev.json !== json) {
+                tracked.set(key, { json, revision: nextRevision });
+                removed.delete(key);
+                changed = true;
+            }
+        }
+        for (const key of tracked.keys()) {
+            if (!live.has(key)) {
+                tracked.delete(key);
+                removed.set(key, nextRevision);
+                changed = true;
+            }
+        }
+        return changed;
+    }
+    function commit() {
+        const snapshot = takeSnapshot();
+        const nextRevision = revision + 1;
+        const liveEntities = new Map();
+        for (const entity of (snapshot["entities"] ?? [])) {
+            liveEntities.set(entity.id, JSON.stringify(entity));
+        }
+        const liveStats = new Map();
+        for (const [id, value] of Object.entries((snapshot["stats"] ?? {}))) {
+            liveStats.set(id, JSON.stringify(value));
+        }
+        const liveStore = new Map();
+        for (const [key, value] of (snapshot["store"] ?? [])) {
+            liveStore.set(key, JSON.stringify(value ?? null));
+        }
+        const liveModules = new Map();
+        for (const [key, value] of Object.entries(snapshot)) {
+            if (CORE_KEYS.has(key))
+                continue;
+            liveModules.set(key, JSON.stringify(value ?? null));
+        }
+        let changed = diffMap(liveEntities, entities, removedEntities, nextRevision);
+        changed = diffMap(liveStats, stats, removedStats, nextRevision) || changed;
+        changed = diffMap(liveStore, store, removedStore, nextRevision) || changed;
+        changed = diffMap(liveModules, modules, new Map(), nextRevision) || changed;
+        if (changed)
+            revision = nextRevision;
+        return revision;
+    }
+    function diff(sinceRevision) {
+        const changedEntities = [];
+        for (const [, tracked] of entities) {
+            if (tracked.revision > sinceRevision)
+                changedEntities.push(JSON.parse(tracked.json));
+        }
+        const changedStats = {};
+        for (const [id, tracked] of stats) {
+            if (tracked.revision > sinceRevision)
+                changedStats[id] = JSON.parse(tracked.json);
+        }
+        const changedStore = [];
+        for (const [key, tracked] of store) {
+            if (tracked.revision > sinceRevision)
+                changedStore.push([key, JSON.parse(tracked.json)]);
+        }
+        const changedModules = {};
+        for (const [key, tracked] of modules) {
+            if (tracked.revision > sinceRevision)
+                changedModules[key] = JSON.parse(tracked.json);
+        }
+        return {
+            revision,
+            entities: changedEntities,
+            removedEntities: keysAfter(removedEntities, sinceRevision),
+            stats: changedStats,
+            removedStats: keysAfter(removedStats, sinceRevision),
+            store: changedStore,
+            removedStore: keysAfter(removedStore, sinceRevision),
+            modules: changedModules,
+        };
+    }
+    return { commit, diff, revision: () => revision };
+}
+function keysAfter(map, sinceRevision) {
+    const out = [];
+    for (const [key, revision] of map) {
+        if (revision > sinceRevision)
+            out.push(key);
+    }
+    return out;
+}
+/**
+ * Diff two full {@link WorldSnapshot}s directly, stamping the result at `revision` — the stateless counterpart of
+ * {@link createWorldReplicator} for hosts that persist snapshots rather than keep a live tracker (Convex reconstructs
+ * per invocation). `applyWorldDiff(prev, diffSnapshots(prev, next, r))` reproduces `next`.
+ */
+export function diffSnapshots(prev, next, revision) {
+    const prevEntities = new Map();
+    for (const entity of (prev["entities"] ?? [])) {
+        prevEntities.set(entity.id, JSON.stringify(entity));
+    }
+    const entities = [];
+    const nextEntityIds = new Set();
+    for (const entity of (next["entities"] ?? [])) {
+        nextEntityIds.add(entity.id);
+        const json = JSON.stringify(entity);
+        if (prevEntities.get(entity.id) !== json)
+            entities.push(JSON.parse(json));
+    }
+    const removedEntities = [...prevEntities.keys()].filter((id) => !nextEntityIds.has(id));
+    const prevStats = (prev["stats"] ?? {});
+    const nextStats = (next["stats"] ?? {});
+    const stats = {};
+    for (const [id, value] of Object.entries(nextStats)) {
+        const json = JSON.stringify(value);
+        if (JSON.stringify(prevStats[id]) !== json)
+            stats[id] = JSON.parse(json);
+    }
+    const removedStats = Object.keys(prevStats).filter((id) => !(id in nextStats));
+    const prevStore = new Map((prev["store"] ?? []));
+    const nextStore = new Map((next["store"] ?? []));
+    const store = [];
+    for (const [key, value] of nextStore) {
+        const json = JSON.stringify(value ?? null);
+        if (JSON.stringify(prevStore.get(key) ?? null) !== json)
+            store.push([key, JSON.parse(json)]);
+    }
+    const removedStore = [...prevStore.keys()].filter((key) => !nextStore.has(key));
+    const modules = {};
+    for (const [key, value] of Object.entries(next)) {
+        if (CORE_KEYS.has(key))
+            continue;
+        const json = JSON.stringify(value ?? null);
+        if (JSON.stringify(prev[key] ?? null) !== json)
+            modules[key] = JSON.parse(json);
+    }
+    return { revision, entities, removedEntities, stats, removedStats, store, removedStore, modules };
+}
+/**
+ * Fold a {@link WorldDiff} onto a prior {@link WorldSnapshot} baseline, returning the next full snapshot — the
+ * client-side inverse of {@link createWorldReplicator}. Pure data in, pure data out: upserts changed entities,
+ * stats and store keys, drops the removed ones, and replaces changed module snapshots wholesale.
+ */
+export function applyWorldDiff(baseline, diff) {
+    const next = { ...baseline };
+    const entityById = new Map();
+    for (const entity of (baseline["entities"] ?? []))
+        entityById.set(entity.id, entity);
+    for (const entity of diff.entities)
+        entityById.set(entity.id, entity);
+    for (const id of diff.removedEntities)
+        entityById.delete(id);
+    next["entities"] = Array.from(entityById.values());
+    const statsById = { ...(baseline["stats"] ?? {}) };
+    for (const [id, value] of Object.entries(diff.stats))
+        statsById[id] = value;
+    for (const id of diff.removedStats)
+        delete statsById[id];
+    next["stats"] = statsById;
+    const storeByKey = new Map((baseline["store"] ?? []));
+    for (const [key, value] of diff.store)
+        storeByKey.set(key, value);
+    for (const key of diff.removedStore)
+        storeByKey.delete(key);
+    next["store"] = Array.from(storeByKey.entries());
+    for (const [key, value] of Object.entries(diff.modules))
+        next[key] = value;
+    return next;
+}

package/dist/runtime/worldSnapshot.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The replication seam for host-authoritative shared worlds: the opt-in feature manifest *is* the
+ * replication schema. Each live subsystem a game opts into registers a {@link SnapshotModule} keyed
+ * by name; the host serializes exactly the registered set into a {@link WorldSnapshot} and a client
+ * hydrates the same keys back. Adding a replicated subsystem is a registration, never a new branch.
+ */
+export interface SnapshotModule<T = unknown> {
+    readonly key: string;
+    snapshot(): T;
+    hydrate(data: T): void;
+}
+/** Full world baseline keyed by {@link SnapshotModule.key} — one entry per opted-in subsystem. */
+export type WorldSnapshot = Record<string, unknown>;
+/** Serialize every registered module into one keyed baseline — the host→client full-world send. */
+export declare function composeWorldSnapshot(modules: readonly SnapshotModule[]): WorldSnapshot;
+/** Hydrate every registered module whose key is present in `snapshot`; keys absent from it are left untouched. */
+export declare function applyWorldSnapshot(modules: readonly SnapshotModule[], snapshot: WorldSnapshot): void;

package/dist/runtime/worldSnapshot.js

@@ -0,0 +1,15 @@
+/** Serialize every registered module into one keyed baseline — the host→client full-world send. */
+export function composeWorldSnapshot(modules) {
+    const snapshot = {};
+    for (const module of modules)
+        snapshot[module.key] = module.snapshot();
+    return snapshot;
+}
+/** Hydrate every registered module whose key is present in `snapshot`; keys absent from it are left untouched. */
+export function applyWorldSnapshot(modules, snapshot) {
+    for (const module of modules) {
+        if (Object.prototype.hasOwnProperty.call(snapshot, module.key)) {
+            module.hydrate(snapshot[module.key]);
+        }
+    }
+}

package/dist/scene/assetCatalog.d.ts

@@ -1,3 +1,4 @@
+/** Measured horizontal footprint, footprint center, and lowest Y of a model in model space. */
 export interface ModelDims {
     footprint: {
         w: number;

package/dist/scene/colliders.d.ts

@@ -0,0 +1,50 @@
+import type { EntityPosition } from "./entityStore.js";
+export type ColliderPurpose = "physical" | "damage";
+export type ColliderShape = {
+    kind: "sphere";
+    radius: number;
+    offset?: EntityPosition;
+} | {
+    kind: "aabb";
+    halfExtents: EntityPosition;
+    offset?: EntityPosition;
+};
+export interface ColliderDef {
+    name: string;
+    purpose: ColliderPurpose;
+    shape: ColliderShape;
+    /** Defaults true for `purpose: "damage"`, false for `purpose: "physical"`. */
+    damageEligible?: boolean;
+    /** Defaults true — a blocking collider stops a ray at first impact. */
+    blocks?: boolean;
+}
+export interface EntityColliderSet {
+    /** Single physical collision body (push / obstruction). */
+    body?: ColliderDef;
+    /** Named damage hitboxes (zero or more). */
+    hitboxes?: readonly ColliderDef[];
+}
+export interface ResolvedCollider {
+    name: string;
+    purpose: ColliderPurpose;
+    shape: ColliderShape;
+    damageEligible: boolean;
+    blocks: boolean;
+}
+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;
+export declare function defaultEntityColliders(): EntityColliderSet;
+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). */
+export declare function scaledObjectColliders(scale: readonly [number, number, number]): EntityColliderSet;
+export declare function resolveColliders(set: EntityColliderSet | null | undefined): ResolvedCollider[];
+export declare function worldOffset(local: EntityPosition | undefined, position: EntityPosition, rotationY: number): EntityPosition;
+export declare function colliderWorldCenter(collider: ResolvedCollider, position: EntityPosition, rotationY: number): EntityPosition;
+export declare function colliderBounds(collider: ResolvedCollider, position: EntityPosition, rotationY: number): {
+    min: EntityPosition;
+    max: EntityPosition;
+};