@jgengine/core 0.18.0 → 0.18.1

package/dist/runtime/prediction.js

@@ -0,0 +1,62 @@
+/**
+ * Keeps local input predictions ahead of the last server confirmation. Reconciliation replaces the
+ * confirmed state and deterministically replays unconfirmed inputs through the supplied step function.
+ * `maxTicks` bounds retained work and memory; dropped inputs are folded into the confirmed baseline.
+ * @capability client-side input prediction with replay reconciliation
+ */
+export function createPredictionBuffer(config) {
+    const maxTicks = Math.max(1, Math.floor(config.maxTicks));
+    const step = config.step;
+    let confirmedTick = config.startTick ?? 0;
+    let confirmed = config.initial;
+    let predicted = config.initial;
+    let records = [];
+    const defaultDt = config.dt ?? 1 / 60;
+    const snapThreshold = Math.max(0, config.snapThreshold ?? 0.1);
+    const replay = (base, pending) => {
+        let next = base;
+        for (const record of pending)
+            next = step(next, record.input, record.dt);
+        return next;
+    };
+    return {
+        record(input, dt = defaultDt, observedState) {
+            const tick = confirmedTick + records.length + 1;
+            const state = observedState === undefined ? step(predicted, input, dt) : observedState;
+            records.push({ tick, input, state, dt });
+            predicted = state;
+            if (records.length > maxTicks) {
+                const oldest = records.shift();
+                confirmedTick = oldest.tick;
+                confirmed = oldest.state;
+            }
+            return predicted;
+        },
+        reconcile(tick, authoritative) {
+            const predictedAtTick = records.find((record) => record.tick === tick)?.state ?? confirmed;
+            const distance = (a, b) => {
+                if (typeof a === "number" && typeof b === "number")
+                    return Math.abs(a - b);
+                if (Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((v) => typeof v === "number") && b.every((v) => typeof v === "number")) {
+                    return Math.sqrt(a.reduce((sum, value, index) => sum + (Number(value) - Number(b[index])) ** 2, 0));
+                }
+                return JSON.stringify(a) === JSON.stringify(b) ? 0 : 1;
+            };
+            const dx = distance(predictedAtTick, authoritative);
+            const pending = records.filter((record) => record.tick > tick);
+            confirmedTick = tick;
+            confirmed = authoritative;
+            records = pending;
+            predicted = replay(confirmed, records);
+            return { error: dx, replayed: records.length, snapped: dx > snapThreshold, state: predicted };
+        },
+        state: () => predicted,
+        snapshot: () => ({ confirmedTick, confirmed, predicted, records: records.map((record) => ({ ...record })) }),
+        restore(next) {
+            confirmedTick = next.confirmedTick;
+            confirmed = next.confirmed;
+            predicted = next.predicted;
+            records = next.records.map((record) => ({ ...record }));
+        },
+    };
+}

package/dist/runtime/simContext.d.ts

@@ -0,0 +1,45 @@
+import type { EntityStore } from "../scene/entityStore.js";
+import { type PoseHistory, type RenderPose } from "./poseInterpolation.js";
+import { type SimAdvanceResult, type SimLoop, type SimulationConfig } from "./simLoop.js";
+/** Where a registered stage runs inside one simulation step. */
+export type SimStagePhase = "beforeMovement" | "afterMovement" | "afterTick";
+/** Extra work a game or engine seam (a physics backend, a netcode buffer) runs inside every simulation step. */
+export interface SimStage {
+    id: string;
+    phase: SimStagePhase;
+    run(dt: number, tick: number): void;
+}
+/** Serializable `ctx.sim` state: loop position plus the interpolation pose history. */
+export interface SimContextState {
+    loop: ReturnType<SimLoop["snapshot"]>;
+    poses: ReturnType<PoseHistory["snapshot"]>;
+}
+/**
+ * `ctx.sim`: the simulation stepper shared by every driver plus the render-side interpolation it enables.
+ * Drivers call {@link advance} with real elapsed seconds and do their per-step work inside the callback;
+ * renderers call {@link renderPose} each frame.
+ */
+export interface SimContext {
+    readonly loop: SimLoop;
+    /** Advance the loop; `body` runs once per simulation step with that step's dt. Pose history is captured before each step. */
+    advance(realDt: number, body: (dt: number, tick: number) => void): SimAdvanceResult;
+    tick(): number;
+    /** Interpolation fraction for the current frame, 1 on a variable loop. */
+    alpha(): number;
+    /** Interpolated pose for rendering; live pose on a variable loop. `false` when the entity does not exist. */
+    renderPose(id: string, out: RenderPose): boolean;
+    /** Forget an entity's interpolation history so it renders at its live pose next frame. */
+    snapPose(id: string): void;
+    /** Register a stage; returns an unregister handle. Stages run in registration order within a phase. */
+    addStage(stage: SimStage): () => void;
+    /** Run every stage registered for `phase`; drivers call this from inside {@link advance}'s body. */
+    runStages(phase: SimStagePhase, dt: number): void;
+    retune(config: SimulationConfig): void;
+    snapshot(): SimContextState;
+    restore(state: SimContextState): void;
+}
+/** Build `ctx.sim` for a context; `createGameContext` calls this from `definition.simulation`. */
+export declare function createSimContext(options: {
+    config?: SimulationConfig;
+    entities: EntityStore;
+}): SimContext;

package/dist/runtime/simContext.js

@@ -0,0 +1,65 @@
+import { createPoseHistory } from "./poseInterpolation.js";
+import { createSimLoop } from "./simLoop.js";
+/** Build `ctx.sim` for a context; `createGameContext` calls this from `definition.simulation`. */
+export function createSimContext(options) {
+    const { entities } = options;
+    const loop = createSimLoop(options.config);
+    const poses = createPoseHistory({ snapDistance: loop.config().snapDistance });
+    const stages = new Map();
+    let advancing = false;
+    return {
+        loop,
+        advance(realDt, body) {
+            if (advancing)
+                throw new Error("ctx.sim.advance is not reentrant");
+            advancing = true;
+            try {
+                return loop.advance(realDt, (dt, tick) => {
+                    if (loop.isFixed())
+                        poses.beginStep(entities);
+                    body(dt, tick);
+                });
+            }
+            finally {
+                advancing = false;
+            }
+        },
+        tick: () => loop.tick(),
+        alpha: () => loop.alpha(),
+        renderPose(id, out) {
+            return poses.sample(entities, id, loop.isFixed() ? loop.alpha() : 1, out);
+        },
+        snapPose: (id) => poses.snap(id),
+        addStage(stage) {
+            const list = stages.get(stage.phase) ?? [];
+            list.push(stage);
+            stages.set(stage.phase, list);
+            return () => {
+                const current = stages.get(stage.phase);
+                if (current === undefined)
+                    return;
+                const index = current.indexOf(stage);
+                if (index >= 0)
+                    current.splice(index, 1);
+            };
+        },
+        runStages(phase, dt) {
+            const list = stages.get(phase);
+            if (list === undefined)
+                return;
+            const tick = loop.tick();
+            for (const stage of list)
+                stage.run(dt, tick);
+        },
+        retune(config) {
+            loop.retune(config);
+            if (config.snapDistance !== undefined)
+                poses.retune({ snapDistance: config.snapDistance });
+        },
+        snapshot: () => ({ loop: loop.snapshot(), poses: poses.snapshot() }),
+        restore(state) {
+            loop.restore(state.loop);
+            poses.restore(state.poses);
+        },
+    };
+}

package/dist/runtime/simLoop.d.ts

@@ -0,0 +1,52 @@
+/** How the simulation is stepped: a fixed rate with a catch-up cap, or once per frame with the frame's dt. */
+export interface SimulationConfig {
+    /**
+     * Fixed simulation rate in steps per second, or `"variable"` to run one step per frame with the frame's
+     * clamped dt. Default `"variable"` (the historical behavior). A fixed rate makes every step's dt identical,
+     * which is what determinism, replay, rollback, and a stable physics solver need; renderers read
+     * `ctx.sim.renderPose` to interpolate between steps.
+     */
+    hz?: number | "variable";
+    /** Fixed steps run per advance before the loop drops the remaining time instead of spiralling. Default 5. */
+    maxCatchUpSteps?: number;
+    /** Entities that move farther than this in one step snap instead of interpolating (teleports, respawns). Default 8 world units. */
+    snapDistance?: number;
+}
+/** Serializable loop position: the tick count and the real seconds accumulated toward the next fixed step. */
+export interface SimLoopState {
+    tick: number;
+    accumulator: number;
+}
+/** What one {@link SimLoop.advance} did. */
+export interface SimAdvanceResult {
+    /** Steps run this advance. */
+    steps: number;
+    /** Fraction of a step accumulated but not yet simulated, 0..1; always 1 on a variable loop. */
+    alpha: number;
+    /** Tick count after this advance. */
+    tick: number;
+    /** Steps discarded because the catch-up cap was hit. */
+    dropped: number;
+}
+/** The stepper handle: advance with real time, read the tick and interpolation alpha, retune the rate, snapshot and restore. */
+export interface SimLoop {
+    /** Feed real elapsed seconds; runs `step(dt, tick)` zero or more times and returns what happened. */
+    advance(realDt: number, step: (dt: number, tick: number) => void): SimAdvanceResult;
+    tick(): number;
+    alpha(): number;
+    /** Seconds per fixed step, `null` on a variable loop. */
+    stepSeconds(): number | null;
+    isFixed(): boolean;
+    retune(config: SimulationConfig): void;
+    config(): Readonly<Required<SimulationConfig>>;
+    snapshot(): SimLoopState;
+    restore(state: SimLoopState): void;
+}
+/**
+ * The simulation stepper every driver (shell frame, headless runner, authoritative host) advances through, so
+ * the sim sees the same dt sequence regardless of who drives it. Fixed mode accumulates real time and steps in
+ * equal slices with a catch-up cap; variable mode steps once per advance.
+ *
+ * @capability sim-loop fixed-step or variable simulation stepping with tick count, catch-up cap, and interpolation alpha
+ */
+export declare function createSimLoop(initial?: SimulationConfig): SimLoop;

package/dist/runtime/simLoop.js

@@ -0,0 +1,72 @@
+const DEFAULT_MAX_CATCH_UP = 5;
+const DEFAULT_SNAP_DISTANCE = 8;
+function resolveConfig(config) {
+    const hz = config?.hz;
+    return {
+        hz: typeof hz === "number" && Number.isFinite(hz) && hz > 0 ? hz : "variable",
+        maxCatchUpSteps: Math.max(1, Math.floor(config?.maxCatchUpSteps ?? DEFAULT_MAX_CATCH_UP)),
+        snapDistance: config?.snapDistance ?? DEFAULT_SNAP_DISTANCE,
+    };
+}
+/**
+ * The simulation stepper every driver (shell frame, headless runner, authoritative host) advances through, so
+ * the sim sees the same dt sequence regardless of who drives it. Fixed mode accumulates real time and steps in
+ * equal slices with a catch-up cap; variable mode steps once per advance.
+ *
+ * @capability sim-loop fixed-step or variable simulation stepping with tick count, catch-up cap, and interpolation alpha
+ */
+export function createSimLoop(initial) {
+    let config = resolveConfig(initial);
+    let tick = 0;
+    let accumulator = 0;
+    let alpha = 1;
+    function stepSeconds() {
+        return config.hz === "variable" ? null : 1 / config.hz;
+    }
+    return {
+        advance(realDt, step) {
+            if (!(realDt > 0))
+                return { steps: 0, alpha, tick, dropped: 0 };
+            const stepDt = stepSeconds();
+            if (stepDt === null) {
+                tick += 1;
+                alpha = 1;
+                step(realDt, tick);
+                return { steps: 1, alpha, tick, dropped: 0 };
+            }
+            accumulator += realDt;
+            let steps = 0;
+            while (accumulator >= stepDt && steps < config.maxCatchUpSteps) {
+                tick += 1;
+                step(stepDt, tick);
+                accumulator -= stepDt;
+                steps += 1;
+            }
+            let dropped = 0;
+            if (accumulator >= stepDt) {
+                dropped = Math.floor(accumulator / stepDt);
+                accumulator -= dropped * stepDt;
+            }
+            alpha = accumulator / stepDt;
+            return { steps, alpha, tick, dropped };
+        },
+        tick: () => tick,
+        alpha: () => alpha,
+        stepSeconds,
+        isFixed: () => config.hz !== "variable",
+        retune(next) {
+            config = resolveConfig({ ...config, ...next });
+            if (config.hz === "variable") {
+                accumulator = 0;
+                alpha = 1;
+            }
+        },
+        config: () => config,
+        snapshot: () => ({ tick, accumulator }),
+        restore(state) {
+            tick = state.tick;
+            accumulator = state.accumulator;
+            alpha = config.hz === "variable" ? 1 : accumulator * config.hz;
+        },
+    };
+}

package/dist/runtime/simSnapshot.d.ts

@@ -0,0 +1,32 @@
+import type { GameContext } from "./gameContext.js";
+/** One piece of simulation state that can be captured and restored by id. */
+export interface SimSnapshotContributor<T = unknown> {
+    id: string;
+    capture(): T;
+    restore(data: T): void;
+}
+/** Captured contributor data keyed by contributor id. */
+export type SimSnapshot = Record<string, unknown>;
+/** Registry of {@link SimSnapshotContributor}s that captures and restores them together. */
+export interface SimSnapshotRegistry {
+    register<T>(contributor: SimSnapshotContributor<T>): () => void;
+    capture(): SimSnapshot;
+    /** Alias of {@link capture}, matching the engine's snapshot/restore naming. */
+    snapshot(): SimSnapshot;
+    /** Restore every contributor present in `snapshot`; contributors missing from it are left untouched. */
+    restore(snapshot: SimSnapshot): void;
+    ids(): string[];
+}
+/**
+ * A registry of everything that must round-trip for a simulation to resume bit-for-bit: world state, the
+ * clock, the rng cursor, the loop accumulator, and whatever a physics backend or game adds. Pair with
+ * {@link createInputRecorder} for replay.
+ *
+ * @capability sim-snapshot capture and restore whole-simulation state for replay, rollback, and regression tests
+ */
+export declare function createSimSnapshotRegistry(): SimSnapshotRegistry;
+/**
+ * The engine's own contributors for a context: replicated world state, the sim clock, the loop and pose
+ * history, and the rng cursor when `ctx.rng` is a seeded stream. Games register theirs on the same registry.
+ */
+export declare function createContextSimSnapshot(ctx: GameContext): SimSnapshotRegistry;

package/dist/runtime/simSnapshot.js

@@ -0,0 +1,60 @@
+import { rngStateOf, restoreRng } from "../random/rng.js";
+/**
+ * A registry of everything that must round-trip for a simulation to resume bit-for-bit: world state, the
+ * clock, the rng cursor, the loop accumulator, and whatever a physics backend or game adds. Pair with
+ * {@link createInputRecorder} for replay.
+ *
+ * @capability sim-snapshot capture and restore whole-simulation state for replay, rollback, and regression tests
+ */
+export function createSimSnapshotRegistry() {
+    const contributors = new Map();
+    function capture() {
+        const out = {};
+        for (const [id, contributor] of contributors)
+            out[id] = contributor.capture();
+        return out;
+    }
+    return {
+        register(contributor) {
+            if (contributors.has(contributor.id)) {
+                throw new Error(`sim snapshot contributor "${contributor.id}" is already registered`);
+            }
+            contributors.set(contributor.id, contributor);
+            return () => {
+                contributors.delete(contributor.id);
+            };
+        },
+        capture,
+        snapshot: capture,
+        restore(snapshot) {
+            for (const [id, contributor] of contributors) {
+                if (id in snapshot)
+                    contributor.restore(snapshot[id]);
+            }
+        },
+        ids: () => Array.from(contributors.keys()),
+    };
+}
+/**
+ * The engine's own contributors for a context: replicated world state, the sim clock, the loop and pose
+ * history, and the rng cursor when `ctx.rng` is a seeded stream. Games register theirs on the same registry.
+ */
+export function createContextSimSnapshot(ctx) {
+    const registry = createSimSnapshotRegistry();
+    // ctx.snapshot() hands back live rows; clone both ways so a captured snapshot stays frozen while the sim keeps running.
+    registry.register({
+        id: "world",
+        capture: () => structuredClone(ctx.snapshot()),
+        restore: (data) => ctx.hydrate(structuredClone(data)),
+    });
+    registry.register({ id: "clock", capture: () => ctx.time.snapshot(), restore: (data) => ctx.time.hydrate(data) });
+    registry.register({ id: "sim", capture: () => ctx.sim.snapshot(), restore: (data) => ctx.sim.restore(data) });
+    if (rngStateOf(ctx.rng) !== null) {
+        registry.register({
+            id: "rng",
+            capture: () => rngStateOf(ctx.rng) ?? 0,
+            restore: (cursor) => restoreRng(ctx.rng, cursor),
+        });
+    }
+    return registry;
+}

package/dist/runtime/snapshot.d.ts

@@ -36,6 +36,8 @@ export type RuntimeInventorySlot = {
     slot?: number;
 };
 export type RuntimePlayerRow = {
+    territoryOwnedCount?: number;
+    ownedTerritoryChunkKeys?: string[];
     userId: string;
     inventories: Record<string, RuntimeInventorySlot[]>;
     economy: Record<string, number>;
@@ -46,6 +48,12 @@ export type RuntimePlayerRow = {
     session?: Record<string, unknown>;
 };
 export type RuntimeChunkRow = {
+    /** Cell key to owner id, persisted with its spatial chunk. */
+    territory?: Record<string, string>;
+    territoryReceipts?: Record<string, {
+        claimedAt: number;
+        costPaid: number;
+    }>;
     chunkKey: string;
     objects: RuntimeObjectRow[];
     entities: RuntimeEntityRow[];

package/dist/runtime/snapshotBuffer.d.ts

@@ -0,0 +1,33 @@
+/** A sampled pair of snapshots and interpolation factor. */
+export type SnapshotBufferSample<T> = {
+    before: T;
+    after: T;
+    alpha: number;
+};
+/** Serializable snapshot-buffer state. */
+export type SnapshotBufferState<T> = {
+    delayMs: number;
+    capacity: number;
+    entries: Array<{
+        atMs: number;
+        value: T;
+    }>;
+};
+/** Handle for a timestamped delayed snapshot buffer. */
+export type SnapshotBuffer<T> = {
+    push(atMs: number, value: T): void;
+    sampleAt(nowMs: number): SnapshotBufferSample<T> | null;
+    snapshot(): SnapshotBufferState<T>;
+    restore(next: SnapshotBufferState<T>): void;
+    retune(config: {
+        delayMs?: number;
+        capacity?: number;
+    }): void;
+};
+/** Stores timestamped snapshots and samples a delayed, interpolatable pair.
+ * @capability runtime snapshot interpolation
+ */
+export declare function createSnapshotBuffer<T>(config: {
+    delayMs: number;
+    capacity: number;
+}): SnapshotBuffer<T>;

package/dist/runtime/snapshotBuffer.js

@@ -0,0 +1,58 @@
+/** Stores timestamped snapshots and samples a delayed, interpolatable pair.
+ * @capability runtime snapshot interpolation
+ */
+export function createSnapshotBuffer(config) {
+    let delayMs = Math.max(0, config.delayMs);
+    let capacity = Math.max(1, Math.floor(config.capacity));
+    let entries = [];
+    const trim = () => {
+        if (entries.length > capacity)
+            entries = entries.slice(-capacity);
+    };
+    return {
+        push(atMs, value) {
+            const entry = { atMs, value };
+            const index = entries.findIndex((item) => item.atMs > atMs);
+            if (index < 0)
+                entries.push(entry);
+            else
+                entries.splice(index, 0, entry);
+            trim();
+        },
+        sampleAt(nowMs) {
+            if (entries.length === 0)
+                return null;
+            const target = nowMs - delayMs;
+            if (target <= entries[0].atMs)
+                return { before: entries[0].value, after: entries[0].value, alpha: 0 };
+            const last = entries[entries.length - 1];
+            if (target >= last.atMs)
+                return { before: last.value, after: last.value, alpha: 1 };
+            for (let i = 1; i < entries.length; i += 1) {
+                const after = entries[i];
+                if (target <= after.atMs) {
+                    const before = entries[i - 1];
+                    const span = after.atMs - before.atMs;
+                    return { before: before.value, after: after.value, alpha: span === 0 ? 1 : (target - before.atMs) / span };
+                }
+            }
+            return null;
+        },
+        snapshot() {
+            return { delayMs, capacity, entries: entries.map((entry) => ({ ...entry })) };
+        },
+        restore(next) {
+            delayMs = Math.max(0, next.delayMs);
+            capacity = Math.max(1, Math.floor(next.capacity));
+            entries = next.entries.map((entry) => ({ ...entry })).sort((a, b) => a.atMs - b.atMs);
+            trim();
+        },
+        retune(config) {
+            if (config.delayMs !== undefined)
+                delayMs = Math.max(0, config.delayMs);
+            if (config.capacity !== undefined)
+                capacity = Math.max(1, Math.floor(config.capacity));
+            trim();
+        },
+    };
+}

package/dist/runtime/transport.d.ts

@@ -1,10 +1,38 @@
 import type { ChatSync } from "../multiplayer/chatContract.js";
 import type { PlayerPose } from "../multiplayer/poseSyncGate.js";
 import type { PresenceTransport } from "../multiplayer/presenceContract.js";
+import type { WorldDiff } from "./worldReplication.js";
+import type { WorldSnapshot } from "./worldSnapshot.js";
+/** A revision-stamped world baseline or compact diff sent to a server-authoritative client. */
+export type WorldSyncFrame = {
+    kind: "baseline";
+    revision: number;
+    snapshot: WorldSnapshot;
+} | {
+    kind: "diff";
+    revision: number;
+    diff: WorldDiff;
+};
+/** A short-lived credential allowing a disconnected client to reclaim one server membership. */
+export type ResumeTicket = {
+    userId: string;
+    serverId: string;
+    token: string;
+};
 export type JoinServerResult = {
     serverId: string;
     isNew: boolean;
+    resumeTicket?: ResumeTicket;
+};
+/** Join failures are returned to the caller so the triggering surface can offer retry. */
+export type JoinServerOutcome = (JoinServerResult & {
+    ok: true;
+}) | {
+    ok: false;
+    reason: "full" | "closed" | "unauthorized";
 };
+/** Connection role used for authoritative world access; spectators are read-only. */
+export type MultiplayerRole = "player" | "spectator";
 export type RunCommandArgs = {
     serverId: string;
     command: string;
@@ -21,7 +49,7 @@ export type GameRuntimeServerView = {
     gameId: string;
     revision: number;
     memberUserIds: string[];
-    serverState: unknown;
+    serverState: unknown | WorldSyncFrame;
     updatedAt: number;
 };
 export type GameRuntimePlayerView = {
@@ -38,7 +66,8 @@ export type GameRuntimeTransport = {
     joinServer: (args: {
         gameId: string;
         serverId?: string;
-    }) => Promise<JoinServerResult>;
+        role?: MultiplayerRole;
+    }) => Promise<JoinServerOutcome>;
     leaveServer: (args: {
         serverId: string;
     }) => Promise<void>;
@@ -54,6 +83,7 @@ export type GameRuntimeFeeds = {
         serverId: string;
         action: string;
     }, onChange: (view: GameRuntimeFeedView) => void) => FeedUnsubscribe;
+    requestServerBaseline?: (serverId: string) => void;
 };
 export type GameBackend<TPresenceRow = unknown, TPresenceLocation = unknown, TGameId extends string = string> = {
     transport: GameRuntimeTransport;

package/dist/runtime/worldChunks.d.ts

@@ -37,3 +37,5 @@ export declare function setChunk(snapshot: GameRuntimeSnapshot, chunkKey: string
 export declare function updateChunk(snapshot: GameRuntimeSnapshot, chunkKey: string, update: (chunk: RuntimeChunkRow) => RuntimeChunkRow): GameRuntimeSnapshot;
 /** Drop a chunk from a snapshot and mark the key dirty so the host deletes its stored row. */
 export declare function deleteChunk(snapshot: GameRuntimeSnapshot, chunkKey: string): GameRuntimeSnapshot;
+/** Square chunk neighborhood around a world position, including its own chunk. */
+export declare function chunkKeysAround(position: readonly [number, number, number], rings?: number, size?: number): string[];

package/dist/runtime/worldChunks.js

@@ -81,3 +81,17 @@ export function deleteChunk(snapshot, chunkKey) {
         dirty: { ...snapshot.dirty, server: true, chunks: withChunkDirty(snapshot, chunkKey) },
     };
 }
+/** Square chunk neighborhood around a world position, including its own chunk. */
+export function chunkKeysAround(position, rings = 1, size = DEFAULT_CHUNK_SIZE) {
+    if (!Number.isSafeInteger(rings) || rings < 0 || rings > 128)
+        throw new RangeError("rings must be an integer from 0 to 128");
+    if (!Number.isFinite(size) || size <= 0 || !position.every(Number.isFinite))
+        throw new RangeError("Invalid chunk position or size");
+    const center = chunkCoordAt(position, size);
+    const keys = [];
+    for (let cx = center.cx - rings; cx <= center.cx + rings; cx++) {
+        for (let cz = center.cz - rings; cz <= center.cz + rings; cz++)
+            keys.push(chunkKeyOf({ cx, cz }));
+    }
+    return keys;
+}

package/dist/runtime/worldProjection.d.ts

@@ -8,6 +8,11 @@ import type { SnapshotViewer, WorldSnapshot } from "./worldSnapshot.js";
  * growing a per-feature branch.
  */
 export interface ReplicationPolicy {
+    /** Decimal places used for replicated positions and angles. */
+    quantize?: {
+        position?: number;
+        angle?: number;
+    };
     /**
      * 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.
@@ -24,6 +29,10 @@ export interface ReplicationPolicy {
  * @internal host projection plumbing — games set ReplicationPolicy; the runtime applies it.
  */
 export declare function policyProjectsViewers(policy: ReplicationPolicy | undefined): boolean;
+/** Quantize replicated entity poses according to a host projection policy.
+ * @internal host projection plumbing
+ */
+export declare function quantizeWorldForReplication(world: WorldSnapshot, policy: ReplicationPolicy | undefined): WorldSnapshot;
 /**
  * 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 —

package/dist/runtime/worldProjection.js

@@ -4,7 +4,23 @@
 export function policyProjectsViewers(policy) {
     if (policy === undefined)
         return false;
-    return policy.privatePerUser === true || policy.aoiRadius !== undefined;
+    return policy.privatePerUser === true || policy.aoiRadius !== undefined || policy.quantize !== undefined;
+}
+/** Quantize replicated entity poses according to a host projection policy.
+ * @internal host projection plumbing
+ */
+export function quantizeWorldForReplication(world, policy) {
+    if (policy?.quantize?.position === undefined && policy?.quantize?.angle === undefined)
+        return world;
+    const digits = (value, places) => places === undefined ? value : Number(value.toFixed(Math.max(0, places)));
+    const entities = world["entities"]?.map((entity) => ({
+        ...entity,
+        position: entity.position.map((value) => digits(value, policy.quantize?.position)),
+        rotationY: digits(entity.rotationY, policy.quantize?.angle),
+        rotationX: digits(entity.rotationX, policy.quantize?.angle),
+        rotationZ: digits(entity.rotationZ, policy.quantize?.angle),
+    }));
+    return entities === undefined ? world : { ...world, entities };
 }
 function distanceSquared(a, b) {
     const dx = a[0] - b[0];

package/dist/runtime/worldSnapshot.d.ts

@@ -1,6 +1,10 @@
 /** Who a host→client snapshot is being projected for — the identity a {@link SnapshotModule.project} filters against. */
 export interface SnapshotViewer {
     readonly userId: string;
+    /** A read-only connection role; spectators receive snapshots but cannot mutate the world. */
+    readonly role?: "player" | "spectator";
+    /** Host tick used by {@link SnapshotModule.priority} to throttle low-priority modules. */
+    readonly tick?: number;
 }
 /**
  * The replication seam for host-authoritative shared worlds: the opt-in feature manifest *is* the
@@ -37,6 +41,8 @@ export interface SnapshotModule<T = unknown> {
     project?(data: T, viewer: SnapshotViewer, world: WorldSnapshot): T;
     /** Monotone change counter; unchanged between host commits means this module didn't mutate and need not re-serialize. */
     version?(): number;
+    /** Return the host tick interval for this module; values greater than one omit it on intervening ticks. */
+    priority?(data: T, viewer: SnapshotViewer): number;
 }
 /** Full world baseline keyed by {@link SnapshotModule.key} — one entry per opted-in subsystem. */
 export type WorldSnapshot = Record<string, unknown>;