@jgengine/core 0.10.0 → 0.11.0

package/dist/runtime/runtimeSave.d.ts

@@ -0,0 +1,79 @@
+import { type SaveBackend, type SaveStatus, type SaveTimers } from "../game/saveStore.js";
+import type { WorldSnapshot } from "./worldSnapshot.js";
+/**
+ * The narrow slice of a live `GameContext` a runtime save reads and writes — a
+ * `GameContext` satisfies it directly (`ctx.snapshot`/`ctx.hydrate`/`ctx.subscribe`).
+ * Depending on this instead of the full context keeps the save controller a deep,
+ * decoupled module: it captures and restores the *whole* opted-in world without
+ * knowing any subsystem.
+ */
+export interface RuntimeSaveTarget {
+    snapshot(): WorldSnapshot;
+    hydrate(snapshot: WorldSnapshot): void;
+    subscribe(listener: () => void): () => void;
+}
+/** `"autosave"` writes a fresh capture on a debounce after any world change; `"manual"` writes only on an explicit `save()`/`checkpoint()` — the save-point / quest-trigger model. */
+export type RuntimeSaveMode = "autosave" | "manual";
+/** How {@link createRuntimeSave} is wired — the live world `target`, the `backend` it persists through, and optional mode/slot/versioning/cadence knobs. */
+export interface RuntimeSaveConfig {
+    /** The live world to capture from and restore into — pass the `GameContext`. */
+    target: RuntimeSaveTarget;
+    /** Where the save lives — `localSaveBackend()` (offline) or a cloud/Convex backend; the only thing that changes between offline and cloud. */
+    backend: SaveBackend;
+    /** `"autosave"` (default) persists on world change; `"manual"` only when the game calls `save()`/`checkpoint()`. */
+    mode?: RuntimeSaveMode;
+    /** Storage namespace. Default `"runtime"`. */
+    key?: string;
+    /** Active save slot. Default `"default"`. */
+    slot?: string;
+    /** Save-format version; bump + pass {@link migrate} on a breaking world-shape change. */
+    version?: number;
+    migrate?: (data: unknown, fromVersion: number) => WorldSnapshot;
+    /** Debounce for `autosave` mode. Default `3000`. */
+    autosaveMs?: number;
+    now?: () => number;
+    timers?: SaveTimers;
+    onError?: (error: unknown) => void;
+}
+/** {@link RuntimeSaveConfig} without `target` — what a host (`createGameContext`) accepts to build `ctx.game.save` and bind it to the context itself. */
+export type RuntimeSaveOptions = Omit<RuntimeSaveConfig, "target">;
+/**
+ * Whole-world save/load bound to a live world and a pluggable backend. `save()`
+ * captures `target.snapshot()` and writes it; `load()` reads it back and
+ * `target.hydrate()`s the whole world. In `autosave` mode it also writes on a
+ * debounce after any change. Named slots, versioned migration, and offline↔cloud
+ * (backend swap) all come for free from the underlying save store.
+ */
+export interface RuntimeSave {
+    status(): SaveStatus;
+    slot(): string;
+    /** Capture the live world and persist it now (serialized against any in-flight write). */
+    save(): Promise<void>;
+    /** Semantic alias for `save()` — call it from a save point, a quest-complete or area-enter handler. */
+    checkpoint(): Promise<void>;
+    /** Load the active slot and hydrate the whole world; resolves `true` when a real save was applied, `false` for an empty slot. */
+    load(): Promise<boolean>;
+    /** Whether the active slot holds a saved world — gate a title-screen "Continue" on it. */
+    hasSave(): Promise<boolean>;
+    /** Delete the active slot's save. */
+    clear(): Promise<void>;
+    /** Switch slot and load it, hydrating the world when that slot has a save. */
+    switchSlot(slot: string): Promise<boolean>;
+    /** The slots this game has written — back a load/save menu. */
+    slots(): Promise<string[]>;
+    subscribe(listener: () => void): () => void;
+    /** Stop autosave and release the world subscription. */
+    dispose(): void;
+}
+/**
+ * Bridge a live world to a pluggable save backend: whole-state capture/restore
+ * with autosave, save points, named slots, and versioned migration — the same
+ * call for offline (localStorage) and cloud (Convex), only the `backend`
+ * differs. The game keeps control of *when* it saves (the `mode` plus explicit
+ * `checkpoint()` calls from quests/areas) and *when* it restores (`load()` on
+ * boot), so any save mechanic — continuous autosave, manual save points,
+ * checkpoint triggers — is expressible without new engine code.
+ *
+ * @capability runtime-save save/load the whole game world through a pluggable backend, autosave or save points
+ */
+export declare function createRuntimeSave(config: RuntimeSaveConfig): RuntimeSave;

package/dist/runtime/runtimeSave.js

@@ -0,0 +1,105 @@
+import { createSaveStore, } from "../game/saveStore.js";
+function defaultTimers() {
+    return {
+        set: (handler, ms) => globalThis.setTimeout(handler, ms),
+        clear: (handle) => globalThis.clearTimeout(handle),
+    };
+}
+function hasContent(snapshot) {
+    for (const _key in snapshot)
+        return true;
+    return false;
+}
+/**
+ * Bridge a live world to a pluggable save backend: whole-state capture/restore
+ * with autosave, save points, named slots, and versioned migration — the same
+ * call for offline (localStorage) and cloud (Convex), only the `backend`
+ * differs. The game keeps control of *when* it saves (the `mode` plus explicit
+ * `checkpoint()` calls from quests/areas) and *when* it restores (`load()` on
+ * boot), so any save mechanic — continuous autosave, manual save points,
+ * checkpoint triggers — is expressible without new engine code.
+ *
+ * @capability runtime-save save/load the whole game world through a pluggable backend, autosave or save points
+ */
+export function createRuntimeSave(config) {
+    const mode = config.mode ?? "autosave";
+    const autosaveMs = config.autosaveMs ?? 3000;
+    const timers = config.timers ?? defaultTimers();
+    const store = createSaveStore({
+        backend: config.backend,
+        initial: {},
+        key: config.key ?? "runtime",
+        slot: config.slot,
+        version: config.version,
+        migrate: config.migrate,
+        autosave: false,
+        now: config.now,
+        onError: config.onError,
+    });
+    let pendingTimer = null;
+    let unsubscribe = null;
+    let disposed = false;
+    let restoring = false;
+    function clearTimer() {
+        if (pendingTimer !== null) {
+            timers.clear(pendingTimer);
+            pendingTimer = null;
+        }
+    }
+    function persist() {
+        clearTimer();
+        store.set(config.target.snapshot());
+        return store.save();
+    }
+    function scheduleAutosave() {
+        if (disposed || restoring)
+            return;
+        clearTimer();
+        pendingTimer = timers.set(() => {
+            pendingTimer = null;
+            void persist();
+        }, autosaveMs);
+    }
+    if (mode === "autosave") {
+        unsubscribe = config.target.subscribe(scheduleAutosave);
+    }
+    function applyLoaded(snapshot) {
+        if (!hasContent(snapshot))
+            return false;
+        restoring = true;
+        try {
+            config.target.hydrate(snapshot);
+        }
+        finally {
+            restoring = false;
+        }
+        return true;
+    }
+    const save = () => persist();
+    return {
+        status: () => store.status(),
+        slot: () => store.slot(),
+        save,
+        checkpoint: save,
+        async load() {
+            return applyLoaded(await store.load());
+        },
+        async hasSave() {
+            return hasContent(await store.load());
+        },
+        clear: () => store.clear(),
+        async switchSlot(slot) {
+            clearTimer();
+            return applyLoaded(await store.switchSlot(slot));
+        },
+        slots: () => store.slots(),
+        subscribe: (listener) => store.subscribe(listener),
+        dispose() {
+            disposed = true;
+            clearTimer();
+            if (unsubscribe !== null)
+                unsubscribe();
+            store.dispose();
+        },
+    };
+}

package/dist/runtime/save.d.ts

@@ -3,7 +3,11 @@ export type SaveConfig = "none" | {
     auto: string;
     scope: SaveScope;
 };
+/** @internal */
 export declare function parseSaveAutoMs(auto: string): number;
+/** @internal */
 export declare function saveScopeIncludesPlayer(scope: SaveScope): boolean;
+/** @internal */
 export declare function saveScopeIncludesChunks(scope: SaveScope): boolean;
+/** @internal */
 export declare function isSaveEnabled(config: SaveConfig): config is Exclude<SaveConfig, "none">;

package/dist/runtime/save.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function parseSaveAutoMs(auto) {
     const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/.exec(auto.trim());
     if (!match) {
@@ -18,12 +19,15 @@ export function parseSaveAutoMs(auto) {
             throw new Error(`Invalid save.auto unit: ${unit}`);
     }
 }
+/** @internal */
 export function saveScopeIncludesPlayer(scope) {
     return scope === "player" || scope === "player+chunks";
 }
+/** @internal */
 export function saveScopeIncludesChunks(scope) {
     return scope === "chunks" || scope === "player+chunks";
 }
+/** @internal */
 export function isSaveEnabled(config) {
     return config !== "none";
 }

package/dist/runtime/snapshot.d.ts

@@ -69,8 +69,11 @@ export type GameRuntimeSnapshot = {
         chunks: string[];
     };
 };
+/** @internal */
 export declare function createEmptyServerRow(): RuntimeServerRow;
+/** @internal */
 export declare function createEmptyPlayerRow(userId: string): RuntimePlayerRow;
+/** @internal */
 export declare function createRuntimeSnapshot(args: {
     gameId: string;
     serverId: string;
@@ -79,9 +82,13 @@ export declare function createRuntimeSnapshot(args: {
     chunks?: Record<string, RuntimeChunkRow>;
     revision?: number;
 }): GameRuntimeSnapshot;
+/** @internal */
 export declare function markServerDirty(snapshot: GameRuntimeSnapshot): GameRuntimeSnapshot;
+/** @internal */
 export declare function markPlayerDirty(snapshot: GameRuntimeSnapshot, userId: string): GameRuntimeSnapshot;
+/** @internal */
 export declare function clearDirtyFlags(snapshot: GameRuntimeSnapshot): GameRuntimeSnapshot;
+/** @internal */
 export declare function splitProfilePlayer(player: RuntimePlayerRow): {
     persistent: RuntimePlayerRow;
     session: Record<string, unknown>;

package/dist/runtime/snapshot.js

@@ -1,4 +1,5 @@
 export const RUNTIME_SNAPSHOT_VERSION = 1;
+/** @internal */
 export function createEmptyServerRow() {
     return {
         entities: [],
@@ -7,6 +8,7 @@ export function createEmptyServerRow() {
         feeds: {},
     };
 }
+/** @internal */
 export function createEmptyPlayerRow(userId) {
     return {
         userId,
@@ -16,6 +18,7 @@ export function createEmptyPlayerRow(userId) {
         session: {},
     };
 }
+/** @internal */
 export function createRuntimeSnapshot(args) {
     return {
         version: RUNTIME_SNAPSHOT_VERSION,
@@ -32,6 +35,7 @@ export function createRuntimeSnapshot(args) {
         },
     };
 }
+/** @internal */
 export function markServerDirty(snapshot) {
     return {
         ...snapshot,
@@ -39,6 +43,7 @@ export function markServerDirty(snapshot) {
         dirty: { ...snapshot.dirty, server: true },
     };
 }
+/** @internal */
 export function markPlayerDirty(snapshot, userId) {
     if (snapshot.dirty.players.includes(userId)) {
         return markServerDirty(snapshot);
@@ -53,6 +58,7 @@ export function markPlayerDirty(snapshot, userId) {
         },
     };
 }
+/** @internal */
 export function clearDirtyFlags(snapshot) {
     return {
         ...snapshot,
@@ -63,6 +69,7 @@ export function clearDirtyFlags(snapshot) {
         },
     };
 }
+/** @internal */
 export function splitProfilePlayer(player) {
     const { session = {}, ...persistentFields } = player;
     return {

package/dist/runtime/visibility.d.ts

@@ -62,7 +62,8 @@ export interface VisibilityDecision {
  *
  * Render culling and asset streaming are intentionally separate. This class never
  * destroys entities or throttles simulation; adapters decide how to apply results.
- */
+  * @internal
+  */
 export declare class VisibilitySystem {
     #private;
     readonly settings: VisibilityDefaults;

package/dist/runtime/visibility.js

@@ -23,7 +23,8 @@ function intersectsRadius(camera, bounds, extraMargin) {
  *
  * Render culling and asset streaming are intentionally separate. This class never
  * destroys entities or throttles simulation; adapters decide how to apply results.
- */
+  * @internal
+  */
 export class VisibilitySystem {
     settings;
     #states = new Map();

package/dist/runtime/worldChannel.d.ts

@@ -1,7 +1,7 @@
 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 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 = {
@@ -43,7 +43,9 @@ export interface WorldHost {
     broadcast(): void;
     session(): HostedWorldSession;
 }
-/** Build a {@link WorldHost} fanning one {@link HostedWorldSession} out to many cursor-tracked connections. */
+/** Build a {@link WorldHost} fanning one {@link HostedWorldSession} out to many cursor-tracked connections.
+ * @internal
+ */
 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 {
@@ -54,5 +56,7 @@ export interface WorldClientLink {
     input(frame: InputFrame): void;
     revision(): number;
 }
-/** Build a {@link WorldClientLink} — the client end that mirrors host frames into `ctx` and sends session verbs upstream. */
+/** Build a {@link WorldClientLink} — the client end that mirrors host frames into `ctx` and sends session verbs upstream.
+ * @internal
+ */
 export declare function createWorldClientLink(ctx: Pick<GameContext, "hydrate">, send: (frame: WorldClientFrame) => void): WorldClientLink;

package/dist/runtime/worldChannel.js

@@ -1,9 +1,31 @@
 import { createWorldMirror } from "./worldMirror.js";
-/** Build a {@link WorldHost} fanning one {@link HostedWorldSession} out to many cursor-tracked connections. */
+import { diffSnapshots } from "./worldReplication.js";
+/** Build a {@link WorldHost} fanning one {@link HostedWorldSession} out to many cursor-tracked connections.
+ * @internal
+ */
 export function createWorldHost(session) {
     const connections = new Set();
+    const connectionsByUser = new Map();
+    const perViewer = session.projectsViewers();
     function connect(userId, send) {
         let cursor = 0;
+        let released = false;
+        let viewerSnapshot = null;
+        let viewerRevision = 0;
+        function release() {
+            if (released)
+                return;
+            released = true;
+            connections.delete(connection);
+            const peers = connectionsByUser.get(userId);
+            if (peers === undefined)
+                return;
+            peers.delete(connection);
+            if (peers.size === 0) {
+                connectionsByUser.delete(userId);
+                session.leave(userId);
+            }
+        }
         const connection = {
             receive(frame) {
                 switch (frame.t) {
@@ -11,7 +33,7 @@ export function createWorldHost(session) {
                         session.join(userId, frame.isNew);
                         break;
                     case "leave":
-                        session.leave(userId);
+                        release();
                         break;
                     case "command":
                         session.command(userId, frame.name, frame.input);
@@ -22,6 +44,23 @@ export function createWorldHost(session) {
                 }
             },
             push() {
+                if (released)
+                    return;
+                if (perViewer) {
+                    const revision = session.revision();
+                    if (viewerSnapshot !== null && revision === viewerRevision)
+                        return;
+                    const snapshot = session.snapshotFor({ userId });
+                    if (viewerSnapshot === null) {
+                        send({ t: "baseline", revision, snapshot });
+                    }
+                    else {
+                        send({ t: "diff", diff: diffSnapshots(viewerSnapshot, snapshot, revision, viewerRevision) });
+                    }
+                    viewerSnapshot = snapshot;
+                    viewerRevision = revision;
+                    return;
+                }
                 if (cursor !== 0 && cursor === session.revision())
                     return;
                 const sync = session.sync(cursor === 0 ? null : cursor);
@@ -34,11 +73,15 @@ export function createWorldHost(session) {
                     send({ t: "diff", diff: sync.diff });
                 }
             },
-            close() {
-                connections.delete(connection);
-            },
+            close: release,
         };
         connections.add(connection);
+        let peers = connectionsByUser.get(userId);
+        if (peers === undefined) {
+            peers = new Set();
+            connectionsByUser.set(userId, peers);
+        }
+        peers.add(connection);
         return connection;
     }
     return {
@@ -50,7 +93,9 @@ export function createWorldHost(session) {
         session: () => session,
     };
 }
-/** Build a {@link WorldClientLink} — the client end that mirrors host frames into `ctx` and sends session verbs upstream. */
+/** Build a {@link WorldClientLink} — the client end that mirrors host frames into `ctx` and sends session verbs upstream.
+ * @internal
+ */
 export function createWorldClientLink(ctx, send) {
     const mirror = createWorldMirror(ctx);
     return {

package/dist/runtime/worldMirror.d.ts

@@ -11,14 +11,26 @@ import type { WorldSnapshot } from "./worldSnapshot.js";
  */
 export interface WorldMirror {
     applyBaseline(revision: number, snapshot: WorldSnapshot): void;
+    /**
+     * Fold one {@link WorldDiff} onto the mirror. A diff whose `revision` doesn't advance past the mirror's own
+     * (stale or a duplicate resend) is ignored. A diff carrying `baseRevision` that doesn't match the mirror's
+     * current revision means frames were skipped in transit — the diff is ignored and {@link needsResync} flips
+     * true until the next {@link applyBaseline} instead of folding a gap onto local state. A diff without
+     * `baseRevision` (legacy producer) always applies, matching the pre-revision-checking behavior.
+     */
     applyDiff(diff: WorldDiff): void;
     revision(): number;
+    /** True after `applyDiff` detected a skipped revision; the caller should fetch a fresh baseline instead of more diffs. */
+    needsResync(): boolean;
 }
-/** Build a {@link WorldMirror} that replicates a host's baseline + diff stream onto `ctx` via `ctx.hydrate`. */
+/** Build a {@link WorldMirror} that replicates a host's baseline + diff stream onto `ctx` via `ctx.hydrate`.
+ * @internal
+ */
 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.
- */
+  * @internal
+  */
 export declare function pullWorld(session: HostedWorldSession, mirror: WorldMirror): void;

package/dist/runtime/worldMirror.js

@@ -1,27 +1,40 @@
 import { applyWorldDiff } from "./worldReplication.js";
-/** Build a {@link WorldMirror} that replicates a host's baseline + diff stream onto `ctx` via `ctx.hydrate`. */
+/** Build a {@link WorldMirror} that replicates a host's baseline + diff stream onto `ctx` via `ctx.hydrate`.
+ * @internal
+ */
 export function createWorldMirror(ctx) {
     let mirror = {};
     let revision = 0;
+    let resyncNeeded = false;
     return {
         applyBaseline(nextRevision, snapshot) {
             mirror = snapshot;
             revision = nextRevision;
+            resyncNeeded = false;
             ctx.hydrate(snapshot);
         },
         applyDiff(diff) {
+            if (diff.revision <= revision)
+                return;
+            if (diff.baseRevision !== undefined && diff.baseRevision !== revision) {
+                resyncNeeded = true;
+                return;
+            }
+            resyncNeeded = false;
             mirror = applyWorldDiff(mirror, diff);
             revision = diff.revision;
             ctx.hydrate(mirror);
         },
         revision: () => revision,
+        needsResync: () => resyncNeeded,
     };
 }
 /**
  * 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.
- */
+  * @internal
+  */
 export function pullWorld(session, mirror) {
     const sync = session.sync(mirror.revision() === 0 ? null : mirror.revision());
     if (sync.kind === "baseline")

package/dist/runtime/worldProjection.d.ts

@@ -0,0 +1,47 @@
+import type { SceneEntity } from "../scene/entityStore.js";
+import type { SnapshotViewer } from "./worldSnapshot.js";
+/**
+ * Host-side interest/privacy policy — how the authoritative world projects to each viewer over the
+ * wire. Unset (the default) means every client receives the whole world, exactly as before. Enabling a
+ * field changes only what each client *sees*, never how the host simulates: the game plays identically.
+ * The core replication modules read this to attach a {@link SnapshotModule.project} without the engine
+ * growing a per-feature branch.
+ */
+export interface ReplicationPolicy {
+    /**
+     * Replicate each player's private per-user state (inventory) only to that player — other viewers
+     * receive none of it. Off by default so existing games keep broadcasting every player's state.
+     */
+    privatePerUser?: boolean;
+    /**
+     * Area-of-interest radius in world units: an entity replicates to a viewer only when within this
+     * distance of the viewer's own entity (the entity whose `id` equals the viewer's `userId`). A viewer
+     * always receives its own entity. Omit for no distance culling — every entity to every viewer.
+     */
+    aoiRadius?: number;
+}
+/** True when at least one field of the policy would change the wire payload. A no-op policy needs no projection.
+ * @internal host projection plumbing — games set ReplicationPolicy; the runtime applies it.
+ */
+export declare function policyProjectsViewers(policy: ReplicationPolicy | undefined): boolean;
+/**
+ * Cull an entity list to a viewer's area of interest: keep the viewer's own entity plus every entity
+ * within `radius` of it. When the viewer has no locatable entity the full list is returned (fail-open —
+ * a spectator or not-yet-spawned player still sees the world rather than an empty one).
+ * @internal host projection plumbing
+ */
+export declare function projectEntitiesForViewer(entities: readonly SceneEntity[], viewer: SnapshotViewer, radius: number): readonly SceneEntity[];
+/** The set of entity ids a viewer can see under an area-of-interest radius — the visibility set entity-keyed modules cull against.
+ * @internal host projection plumbing
+ */
+export declare function visibleEntityIds(entities: readonly SceneEntity[], viewer: SnapshotViewer, radius: number): Set<string>;
+/** Keep only the entries of an entity-id-keyed record whose id is in `visible` — the projection for entity stats under area-of-interest.
+ * @internal host projection plumbing
+ */
+export declare function projectByVisibleIds<T>(byId: Record<string, T>, visible: Set<string>): Record<string, T>;
+/**
+ * Narrow a `userId → state` record to only the viewer's own entry — the projection for private
+ * per-user state (inventory, wallets) so one client never receives another player's private data.
+ * @internal host projection plumbing
+ */
+export declare function projectPerUserForViewer<T>(byUser: Record<string, T>, viewer: SnapshotViewer): Record<string, T>;

package/dist/runtime/worldProjection.js

@@ -0,0 +1,52 @@
+/** True when at least one field of the policy would change the wire payload. A no-op policy needs no projection.
+ * @internal host projection plumbing — games set ReplicationPolicy; the runtime applies it.
+ */
+export function policyProjectsViewers(policy) {
+    if (policy === undefined)
+        return false;
+    return policy.privatePerUser === true || policy.aoiRadius !== undefined;
+}
+function distanceSquared(a, b) {
+    const dx = a[0] - b[0];
+    const dy = a[1] - b[1];
+    const dz = a[2] - b[2];
+    return dx * dx + dy * dy + dz * dz;
+}
+/**
+ * Cull an entity list to a viewer's area of interest: keep the viewer's own entity plus every entity
+ * within `radius` of it. When the viewer has no locatable entity the full list is returned (fail-open —
+ * a spectator or not-yet-spawned player still sees the world rather than an empty one).
+ * @internal host projection plumbing
+ */
+export function projectEntitiesForViewer(entities, viewer, radius) {
+    const self = entities.find((entity) => entity.id === viewer.userId);
+    if (self === undefined)
+        return entities;
+    const radiusSquared = radius * radius;
+    return entities.filter((entity) => entity.id === viewer.userId || distanceSquared(entity.position, self.position) <= radiusSquared);
+}
+/** The set of entity ids a viewer can see under an area-of-interest radius — the visibility set entity-keyed modules cull against.
+ * @internal host projection plumbing
+ */
+export function visibleEntityIds(entities, viewer, radius) {
+    return new Set(projectEntitiesForViewer(entities, viewer, radius).map((entity) => entity.id));
+}
+/** Keep only the entries of an entity-id-keyed record whose id is in `visible` — the projection for entity stats under area-of-interest.
+ * @internal host projection plumbing
+ */
+export function projectByVisibleIds(byId, visible) {
+    const out = {};
+    for (const [id, value] of Object.entries(byId))
+        if (visible.has(id))
+            out[id] = value;
+    return out;
+}
+/**
+ * Narrow a `userId → state` record to only the viewer's own entry — the projection for private
+ * per-user state (inventory, wallets) so one client never receives another player's private data.
+ * @internal host projection plumbing
+ */
+export function projectPerUserForViewer(byUser, viewer) {
+    const own = byUser[viewer.userId];
+    return own === undefined ? {} : { [viewer.userId]: own };
+}