@jgengine/core 0.8.0 → 0.10.0

package/dist/runtime/gameRuntime.d.ts

@@ -5,7 +5,7 @@ import { type GameRuntimeSnapshot, type RuntimeChunkRow, type RuntimePlayerRow,
 export type ServerLoopHooks = {
     onInit?: (ctx: RuntimeInitContext) => void;
     onNewPlayer?: (ctx: RuntimeLoopContext) => void;
-    onTick?: (ctx: RuntimeLoopContext, dtSeconds: number) => void;
+    onTick?: (ctx: RuntimeWorldContext, dtSeconds: number) => void;
 };
 export type RuntimeInitContext = {
     snapshot: GameRuntimeSnapshot;
@@ -17,6 +17,9 @@ export type RuntimeLoopContext = RuntimeInitContext & {
         isNew: boolean;
     };
 };
+export type RuntimeWorldContext = RuntimeInitContext & {
+    playerIds: readonly string[];
+};
 export type GameRuntimeDefinition = {
     gameId: string;
     save: SaveConfig;
@@ -29,6 +32,7 @@ export type HydrateInput = {
     serverRow: RuntimeServerRow;
     playersByUserId: Record<string, RuntimePlayerRow>;
     chunksByKey: Record<string, RuntimeChunkRow>;
+    revision?: number;
 };
 export type GameRuntime = {
     gameId: string;

package/dist/runtime/gameRuntime.js

@@ -13,6 +13,7 @@ export function createGameRuntime(definition) {
                 server: input.serverRow,
                 players: input.playersByUserId,
                 chunks: input.chunksByKey,
+                revision: input.revision,
             });
             if (loop?.onInit && !initialized) {
                 initialized = true;
@@ -34,18 +35,18 @@ export function createGameRuntime(definition) {
             if (!loop?.onTick)
                 return snapshot;
             let current = snapshot;
-            for (const userId of Object.keys(current.players)) {
-                const ctx = {
-                    get snapshot() {
-                        return current;
-                    },
-                    player: { userId, isNew: false },
-                    setSnapshot(next) {
-                        current = next;
-                    },
-                };
-                loop.onTick(ctx, dtSeconds);
-            }
+            const ctx = {
+                get snapshot() {
+                    return current;
+                },
+                get playerIds() {
+                    return Object.keys(current.players);
+                },
+                setSnapshot(next) {
+                    current = next;
+                },
+            };
+            loop.onTick(ctx, dtSeconds);
             return current;
         },
         joinPlayer(snapshot, userId, isNew) {

package/dist/runtime/hostPersistence.d.ts

@@ -63,6 +63,7 @@ export declare function drainPendingLeaderboardIncrements(session: Record<string
     session: Record<string, unknown>;
 };
 export declare const LEADERBOARD_TOP_LIMIT = 100;
+export declare function clampLimit(value: number | undefined, fallback: number, max: number): number;
 export type LeaderboardRow = {
     gameId: string;
     stat: string;
@@ -97,7 +98,12 @@ export type ServerListing = {
     tags?: string[];
     updatedAt: number;
 };
-export declare function toServerListing(record: GameServerRecord): ServerListing;
+export type ToServerListingOptions = {
+    includeJoinCode?: boolean;
+};
+export declare function toServerListing(record: GameServerRecord, options?: ToServerListingOptions): ServerListing;
+export declare const OPEN_SERVER_LISTING_LIMIT = 20;
+export declare const OPEN_SERVER_LISTING_MAX = 100;
 export declare function toOpenServerListings(listings: Iterable<ServerListing>, limit?: number): ServerListing[];
 export type HostPersistence = {
     savePlan?: (plan: ServerPersistPlan) => Promise<void>;
@@ -112,6 +118,7 @@ export type HostPersistence = {
     saveProfile: (record: PlayerProfileRecord) => Promise<void>;
     loadChunks: (serverId: string) => Promise<WorldChunkRecord[]>;
     saveChunks: (serverId: string, chunks: WorldChunkRecord[]) => Promise<void>;
+    deleteChunks: (serverId: string, chunkKeys: string[]) => Promise<void>;
     loadFeed: (args: {
         serverId: string;
         action: string;
@@ -139,6 +146,7 @@ export type ServerPersistPlan = {
     server: GameServerRecord;
     profiles: PlayerProfileRecord[];
     chunks: WorldChunkRecord[];
+    deletedChunks: string[];
     leaderboard: LeaderboardIncrement[];
 };
 export declare function planServerPersist(server: GameServerRecord, snapshot: GameRuntimeSnapshot, save: SaveConfig, now: number): ServerPersistPlan;

package/dist/runtime/hostPersistence.js

@@ -21,6 +21,12 @@ export function drainPendingLeaderboardIncrements(session) {
     return { increments: raw.filter(isLeaderboardIncrement), session: rest };
 }
 export const LEADERBOARD_TOP_LIMIT = 100;
+export function clampLimit(value, fallback, max) {
+    const candidate = value ?? fallback;
+    if (!Number.isFinite(candidate))
+        return fallback;
+    return Math.min(Math.max(Math.floor(candidate), 1), max);
+}
 export function leaderboardRowKey(row) {
     return [row.gameId, row.scope, row.stat, row.serverId ?? "", row.userId].join("|");
 }
@@ -45,7 +51,7 @@ export function applyLeaderboardRows(rows, gameId, entries, now) {
     }
 }
 export function topLeaderboardRows(rows, args) {
-    const limit = Math.min(Math.max(args.limit ?? LEADERBOARD_TOP_LIMIT, 1), LEADERBOARD_TOP_LIMIT);
+    const limit = clampLimit(args.limit, LEADERBOARD_TOP_LIMIT, LEADERBOARD_TOP_LIMIT);
     return [...rows]
         .filter((row) => row.gameId === args.gameId &&
         row.stat === args.stat &&
@@ -79,7 +85,7 @@ export function shouldAutoSave(save, dirtyAt, lastSavedAt, now) {
     const anchor = lastSavedAt ?? 0;
     return now - anchor >= intervalMs;
 }
-export function toServerListing(record) {
+export function toServerListing(record, options = {}) {
     return {
         serverId: record.serverId,
         status: record.status,
@@ -88,16 +94,20 @@ export function toServerListing(record) {
         mode: record.mode,
         label: record.label,
         visibility: record.visibility,
-        joinCode: record.joinCode,
+        ...(options.includeJoinCode === true && record.joinCode !== undefined
+            ? { joinCode: record.joinCode }
+            : {}),
         tags: record.tags,
         updatedAt: record.updatedAt,
     };
 }
-export function toOpenServerListings(listings, limit = 20) {
+export const OPEN_SERVER_LISTING_LIMIT = 20;
+export const OPEN_SERVER_LISTING_MAX = 100;
+export function toOpenServerListings(listings, limit = OPEN_SERVER_LISTING_LIMIT) {
     return [...listings]
         .filter((listing) => listing.status === "running")
         .sort((a, b) => b.updatedAt - a.updatedAt)
-        .slice(0, limit);
+        .slice(0, clampLimit(limit, OPEN_SERVER_LISTING_LIMIT, OPEN_SERVER_LISTING_MAX));
 }
 export function buildHydratePlayers(server, profiles) {
     const players = {};
@@ -146,12 +156,16 @@ export function planServerPersist(server, snapshot, save, now) {
         }
     }
     const chunks = [];
+    const deletedChunks = [];
     if (isSaveEnabled(save) && saveScopeIncludesChunks(save.scope)) {
         for (const chunkKey of snapshot.dirty.chunks) {
             const chunk = snapshot.chunks[chunkKey];
-            if (!chunk)
-                continue;
-            chunks.push({ serverId: server.serverId, chunkKey, snapshot: chunk, updatedAt: now });
+            if (chunk) {
+                chunks.push({ serverId: server.serverId, chunkKey, snapshot: chunk, updatedAt: now });
+            }
+            else {
+                deletedChunks.push(chunkKey);
+            }
         }
     }
     return {
@@ -166,6 +180,7 @@ export function planServerPersist(server, snapshot, save, now) {
         },
         profiles,
         chunks,
+        deletedChunks,
         leaderboard,
     };
 }

package/dist/runtime/hostedGameRunner.d.ts

@@ -0,0 +1,49 @@
+import type { CommandResult } from "../commands/commandRegistry.js";
+import type { GameDefinition, LoopPlayer } from "../game/defineGame.js";
+import type { ModelAssetRef } from "../scene/assetCatalog.js";
+import { type GameContext, type GameContextContent } from "./gameContext.js";
+import { type InputFrame } from "./inputSnapshot.js";
+import { type WorldDiff } from "./worldReplication.js";
+import type { WorldSnapshot } from "./worldSnapshot.js";
+export type { InputFrame };
+/** Reserved command name the authoritative host intercepts on the existing `runCommand` transport to route a client's {@link InputFrame} to `session.input`, so per-tick input needs no separate wire. */
+export declare const INPUT_COMMAND = "engine.input";
+/** Config for {@link createHostedGameRunner}: the game definition, its content lookup, and an optional host identity. */
+export interface HostedGameRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> {
+    definition: GameDefinition<TAssetRef, TMultiplayer>;
+    content: GameContextContent;
+    /** The world's own authoritative identity (`ctx.player` server-side); real players join as members. */
+    host?: LoopPlayer;
+    now?: () => number;
+    /**
+     * Rehydrate a persisted world instead of booting a fresh one — for stateless hosts (Convex) that reconstruct
+     * the runner each invocation. `onInit` still runs (so commands and systems it registers exist), then this
+     * snapshot overlays the world state it seeded. Omit for a long-lived stateful host (ws) that keeps one runner.
+     */
+    restore?: WorldSnapshot;
+}
+/**
+ * The GameContext-loop equivalent of the pure-reducer `createGameHost`: one authoritative `createGameContext`
+ * per world, driven server-side. `onInit` runs once at construction; `onNewPlayer`/`onPlayerLeave` fire per
+ * join/leave; `tick` advances `onTick` then commits a revision. Clients pull a full {@link WorldSnapshot}
+ * baseline once, then per-tick {@link WorldDiff}s from their last revision. Games ship only normal GameContext
+ * code — the runner adds no per-game surface.
+ */
+export interface HostedGameRunner {
+    join(userId: string, isNew: boolean): void;
+    /** Re-attach an already-joined member on a reconstructed runner — restores membership and `ctx.game.players` without re-firing `onNewPlayer`. Stateless hosts call it once per persisted member after `restore`. */
+    resume(userId: string): void;
+    leave(userId: string): void;
+    /** Record a client's latest input frame — stashed for {@link heldInput} and mirrored onto `ctx.game.players` so the movement seam reads each player's intent in `onTick`. */
+    input(userId: string, frame: InputFrame): void;
+    heldInput(userId: string): InputFrame | null;
+    command(userId: string, name: string, input: unknown): CommandResult<GameContext>;
+    tick(dt: number): number;
+    diff(sinceRevision: number): WorldDiff;
+    revision(): number;
+    snapshot(): WorldSnapshot;
+    members(): readonly string[];
+    context(): GameContext;
+}
+/** Build a {@link HostedGameRunner} — one authoritative GameContext world driven server-side from the game's own loop. */
+export declare function createHostedGameRunner<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HostedGameRunnerOptions<TAssetRef, TMultiplayer>): HostedGameRunner;

package/dist/runtime/hostedGameRunner.js

@@ -0,0 +1,62 @@
+import { createGameContext } from "./gameContext.js";
+import {} from "./inputSnapshot.js";
+import { createWorldReplicator } from "./worldReplication.js";
+/** Reserved command name the authoritative host intercepts on the existing `runCommand` transport to route a client's {@link InputFrame} to `session.input`, so per-tick input needs no separate wire. */
+export const INPUT_COMMAND = "engine.input";
+/** Build a {@link HostedGameRunner} — one authoritative GameContext world driven server-side from the game's own loop. */
+export function createHostedGameRunner(options) {
+    const { definition, content, host, now, restore } = options;
+    const ctx = createGameContext({
+        definition,
+        content,
+        player: host ?? { userId: "host", isNew: true },
+        ...(now === undefined ? {} : { now }),
+    });
+    const loop = definition.loop ?? {};
+    const replicator = createWorldReplicator(() => ctx.snapshot());
+    const members = new Map();
+    const inputs = new Map();
+    loop.onInit?.(ctx);
+    if (restore !== undefined)
+        ctx.hydrate(restore);
+    return {
+        join(userId, isNew) {
+            const player = { userId, isNew };
+            members.set(userId, player);
+            ctx.game.players?.join(userId, isNew);
+            loop.onNewPlayer?.(ctx, player);
+        },
+        resume(userId) {
+            members.set(userId, { userId, isNew: false });
+            ctx.game.players?.join(userId, false);
+        },
+        leave(userId) {
+            const player = members.get(userId);
+            if (player === undefined)
+                return;
+            members.delete(userId);
+            inputs.delete(userId);
+            loop.onPlayerLeave?.(ctx, player);
+            ctx.game.players?.leave(userId);
+        },
+        input(userId, frame) {
+            inputs.set(userId, frame);
+            ctx.game.players?.setInput(userId, frame);
+        },
+        heldInput(userId) {
+            return inputs.get(userId) ?? null;
+        },
+        command(userId, name, input) {
+            return ctx.game.commands.runAs(userId, name, input);
+        },
+        tick(dt) {
+            loop.onTick?.(ctx, dt);
+            return replicator.commit();
+        },
+        diff: (sinceRevision) => replicator.diff(sinceRevision),
+        revision: () => replicator.revision(),
+        snapshot: () => ctx.snapshot(),
+        members: () => Array.from(members.keys()),
+        context: () => ctx,
+    };
+}

package/dist/runtime/hostedWorldSession.d.ts

@@ -0,0 +1,65 @@
+import type { CommandResult } from "../commands/commandRegistry.js";
+import type { ModelAssetRef } from "../scene/assetCatalog.js";
+import type { GameContext, GameContextContent } from "./gameContext.js";
+import type { GameDefinition, LoopPlayer } from "../game/defineGame.js";
+import { type HostedGameRunner, type InputFrame } from "./hostedGameRunner.js";
+import type { WorldDiff } from "./worldReplication.js";
+import type { WorldSnapshot } from "./worldSnapshot.js";
+/** One hosted world's persisted authoritative state — the unit a {@link HostedWorldStore} loads and saves. */
+export interface HostedWorldRecord {
+    snapshot: WorldSnapshot;
+    revision: number;
+}
+/**
+ * Narrow persistence seam for a hosted world — the {@link HostedWorldRecord} counterpart of `HostPersistence`.
+ * Backends implement it (memory/file/sql/convex); the session never names one. A stateful host loads once and
+ * saves on a cadence; a stateless host reconstructs from `load()` each invocation.
+ */
+export interface HostedWorldStore {
+    load(): HostedWorldRecord | null;
+    save(record: HostedWorldRecord): void;
+}
+/** In-process {@link HostedWorldStore} for tests, local play, and the browser-tab P2P host. */
+export declare function memoryWorldStore(seed?: HostedWorldRecord): HostedWorldStore;
+/** A client replication pull: a full baseline (first sync / fell behind) or a diff since the client's cursor. */
+export type HostedWorldSync = {
+    kind: "baseline";
+    revision: number;
+    snapshot: WorldSnapshot;
+} | {
+    kind: "diff";
+    diff: WorldDiff;
+};
+/** Config for {@link createHostedWorldSession}: the game, its persistence store, and the auto-save cadence. */
+export interface HostedWorldSessionOptions<TAssetRef extends ModelAssetRef, TMultiplayer> {
+    definition: GameDefinition<TAssetRef, TMultiplayer>;
+    content: GameContextContent;
+    host?: LoopPlayer;
+    now?: () => number;
+    /** Where the authoritative snapshot persists; defaults to {@link memoryWorldStore}. */
+    store?: HostedWorldStore;
+    /** Minimum elapsed `now()` ms between auto-saves on tick. Default `0` — persist on every revision-changing tick. */
+    saveIntervalMs?: number;
+}
+/**
+ * The stateful host substrate a long-lived backend binds (ws server, browser P2P host): a live
+ * {@link HostedGameRunner} loaded from a {@link HostedWorldStore}, auto-persisted on tick, serving each client a
+ * baseline then diffs. The stateless Convex path doesn't use this — it reconstructs a runner from the same store
+ * per invocation and diffs with `diffSnapshots`. Either way the store seam and the game code are identical.
+ */
+export interface HostedWorldSession {
+    join(userId: string, isNew: boolean): void;
+    leave(userId: string): void;
+    input(userId: string, frame: InputFrame): void;
+    command(userId: string, name: string, input: unknown): CommandResult<GameContext>;
+    tick(dt: number): number;
+    /** Replication pull: `null`/`0` cursor → full baseline; a prior revision → a diff since it. */
+    sync(sinceRevision: number | null): HostedWorldSync;
+    revision(): number;
+    members(): readonly string[];
+    /** Force-persist the current world to the store. */
+    save(): void;
+    runner(): HostedGameRunner;
+}
+/** Build a {@link HostedWorldSession} — a live runner loaded from a {@link HostedWorldStore} and auto-persisted on tick. */
+export declare function createHostedWorldSession<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HostedWorldSessionOptions<TAssetRef, TMultiplayer>): HostedWorldSession;

package/dist/runtime/hostedWorldSession.js

@@ -0,0 +1,57 @@
+import { createHostedGameRunner } from "./hostedGameRunner.js";
+/** In-process {@link HostedWorldStore} for tests, local play, and the browser-tab P2P host. */
+export function memoryWorldStore(seed) {
+    let record = seed ?? null;
+    return {
+        load: () => record,
+        save(next) {
+            record = { snapshot: next.snapshot, revision: next.revision };
+        },
+    };
+}
+/** Build a {@link HostedWorldSession} — a live runner loaded from a {@link HostedWorldStore} and auto-persisted on tick. */
+export function createHostedWorldSession(options) {
+    const { definition, content, host, now, saveIntervalMs = 0 } = options;
+    const store = options.store ?? memoryWorldStore();
+    const loaded = store.load();
+    const runner = createHostedGameRunner({
+        definition,
+        content,
+        ...(host === undefined ? {} : { host }),
+        ...(now === undefined ? {} : { now }),
+        ...(loaded === null ? {} : { restore: loaded.snapshot }),
+    });
+    let savedRevision = loaded?.revision ?? 0;
+    let lastSaveAt = now?.() ?? 0;
+    function persist() {
+        savedRevision = runner.revision();
+        store.save({ snapshot: runner.snapshot(), revision: savedRevision });
+    }
+    return {
+        join: (userId, isNew) => runner.join(userId, isNew),
+        leave: (userId) => runner.leave(userId),
+        input: (userId, frame) => runner.input(userId, frame),
+        command: (userId, name, input) => runner.command(userId, name, input),
+        tick(dt) {
+            const revision = runner.tick(dt);
+            if (revision !== savedRevision) {
+                const at = now?.() ?? 0;
+                if (saveIntervalMs <= 0 || at - lastSaveAt >= saveIntervalMs) {
+                    lastSaveAt = at;
+                    persist();
+                }
+            }
+            return revision;
+        },
+        sync(sinceRevision) {
+            if (sinceRevision === null || sinceRevision <= 0) {
+                return { kind: "baseline", revision: runner.revision(), snapshot: runner.snapshot() };
+            }
+            return { kind: "diff", diff: runner.diff(sinceRevision) };
+        },
+        revision: () => runner.revision(),
+        members: () => runner.members(),
+        save: persist,
+        runner: () => runner,
+    };
+}

package/dist/runtime/inputSnapshot.d.ts

@@ -1,7 +1,25 @@
+import type { PointerAxisState } from "../input/pointerAxis.js";
+import { type AxisBinding, type AxisRange } from "../input/axisInput.js";
+/** One client's input for a tick — the semantic held-action set plus pointer state, the serializable, over-the-wire counterpart of {@link InputSnapshot} the host stores per connected player. */
+export interface InputFrame {
+    held: readonly string[];
+    pointer: PointerAxisState | null;
+}
 export interface InputSnapshot {
     /** Replaces the held-action set for this frame. Called by the shell before `onTick` each frame; does not bump `ctx.version()` or notify `ctx.subscribe` listeners — per-frame publishes would storm subscribers. */
     publish(held: readonly string[]): void;
+    /** Replaces the normalized pointer-position state for this frame (#293). Same no-notify contract as `publish`. */
+    publishPointer(state: PointerAxisState | null): void;
     isDown(action: string): boolean;
     held(): readonly string[];
+    /** Pointer position over the play surface, `[-1, 1]` per axis with `+y` down, published by the shell each frame; `null` until the first pointer move. */
+    pointer(): PointerAxisState | null;
+    /**
+     * Instantaneous analog axis sample against the held-action set and current pointer (#533.7) — bind
+     * throttle/steer/handbrake (or any axes) to *action names*, not raw key codes, since the held set is
+     * semantic actions. Feed the result into an `AxisChannel` for smoothing; unlisted ranges default to
+     * bipolar `[-1, 1]`, so pass `{ min: 0, max: 1 }` for one-directional pedals.
+     */
+    axis<TAxes extends string>(bindings: Record<TAxes, AxisBinding>, ranges?: Partial<Record<TAxes, AxisRange>>): Record<TAxes, number>;
 }
 export declare function createInputSnapshot(): InputSnapshot;

package/dist/runtime/inputSnapshot.js

@@ -1,12 +1,19 @@
+import { sampleAxisBindings } from "../input/axisInput.js";
 export function createInputSnapshot() {
     let heldSet = new Set();
     let heldList = [];
+    let pointerState = null;
     return {
         publish(held) {
             heldList = held;
             heldSet = new Set(held);
         },
+        publishPointer(state) {
+            pointerState = state;
+        },
         isDown: (action) => heldSet.has(action),
         held: () => heldList,
+        pointer: () => pointerState,
+        axis: (bindings, ranges) => sampleAxisBindings(bindings, (action) => heldSet.has(action), pointerState, ranges),
     };
 }

package/dist/runtime/motionIntents.d.ts

@@ -1,11 +1,14 @@
 /**
- * Seam for game code to reach the vertical motion the shell's FrameDriver
+ * Seam for game code to reach the motion the shell's FrameDriver
  * otherwise owns privately (#162.4). Game code calls `impulse`,
- * `setVerticalVelocity`, and/or `setY` from `onTick` or commands; the shell
- * calls `takePending()` once per frame, before integrating gravity, to drain
- * what accumulated. `setY` wins over physics for that frame; impulses add to
- * the vertical velocity the driver is about to integrate; a later
- * `setVerticalVelocity` replaces that velocity outright.
+ * `pushHorizontal`, `setVerticalVelocity`, and/or `setY` from `onTick` or
+ * commands; the shell calls `takePending()` once per frame, before
+ * integrating gravity, to drain what accumulated. `setY` wins over physics
+ * for that frame; impulses add to the velocity the driver is about to
+ * integrate; a later `setVerticalVelocity` replaces that velocity outright.
+ * Horizontal pushes compose with the walk controller (#282.4): they add to
+ * its horizontal velocity and decay naturally as it re-blends toward input —
+ * knockback, dashes, explosion shoves without raw `setPose` offsets.
  *
  * Intentionally not `ctx.version()`/`ctx.subscribe` wired: these fire at
  * most once per frame and would otherwise storm subscribers with per-frame
@@ -13,13 +16,20 @@
  */
 export interface MotionIntents {
     impulse(velocityY: number): void;
+    /** Adds a horizontal velocity kick (world units/s) that the walk controller integrates and decays. */
+    pushHorizontal(velocityX: number, velocityZ: number): void;
     setVerticalVelocity(velocityY: number): void;
     setY(y: number): void;
     takePending(): MotionIntentBatch | null;
 }
 export interface MotionIntentBatch {
     impulses: readonly number[];
+    horizontalImpulses: readonly (readonly [number, number])[];
     verticalVelocity: number | null;
     y: number | null;
 }
 export declare function createMotionIntents(): MotionIntents;
+/** Fold a batch's vertical impulses into a controller's velocity, then apply an outright `setVerticalVelocity` override — the vertical counterpart of {@link applyHorizontalImpulses}. */
+export declare function applyMotionImpulses(currentVelocity: number, batch: MotionIntentBatch | null): number;
+/** Fold a batch's horizontal pushes into a controller's velocity pair — shared by the walk and voxel drivers. */
+export declare function applyHorizontalImpulses(velocityX: number, velocityZ: number, batch: MotionIntentBatch | null): readonly [number, number];

package/dist/runtime/motionIntents.js

@@ -1,11 +1,15 @@
 export function createMotionIntents() {
     let impulses = [];
+    let horizontalImpulses = [];
     let verticalVelocity = null;
     let y = null;
     return {
         impulse(velocityY) {
             impulses.push(velocityY);
         },
+        pushHorizontal(velocityX, velocityZ) {
+            horizontalImpulses.push([velocityX, velocityZ]);
+        },
         setVerticalVelocity(velocityY) {
             verticalVelocity = velocityY;
         },
@@ -13,13 +17,38 @@ export function createMotionIntents() {
             y = nextY;
         },
         takePending() {
-            if (impulses.length === 0 && verticalVelocity === null && y === null)
+            if (impulses.length === 0 && horizontalImpulses.length === 0 && verticalVelocity === null && y === null) {
                 return null;
-            const batch = { impulses, verticalVelocity, y };
+            }
+            const batch = { impulses, horizontalImpulses, verticalVelocity, y };
             impulses = [];
+            horizontalImpulses = [];
             verticalVelocity = null;
             y = null;
             return batch;
         },
     };
 }
+/** Fold a batch's vertical impulses into a controller's velocity, then apply an outright `setVerticalVelocity` override — the vertical counterpart of {@link applyHorizontalImpulses}. */
+export function applyMotionImpulses(currentVelocity, batch) {
+    if (batch === null)
+        return currentVelocity;
+    let velocity = currentVelocity;
+    for (const impulse of batch.impulses)
+        velocity += impulse;
+    if (batch.verticalVelocity !== null)
+        velocity = batch.verticalVelocity;
+    return velocity;
+}
+/** Fold a batch's horizontal pushes into a controller's velocity pair — shared by the walk and voxel drivers. */
+export function applyHorizontalImpulses(velocityX, velocityZ, batch) {
+    if (batch === null || batch.horizontalImpulses.length === 0)
+        return [velocityX, velocityZ];
+    let x = velocityX;
+    let z = velocityZ;
+    for (const [ix, iz] of batch.horizontalImpulses) {
+        x += ix;
+        z += iz;
+    }
+    return [x, z];
+}

package/dist/runtime/snapshot.d.ts

@@ -77,6 +77,7 @@ export declare function createRuntimeSnapshot(args: {
     server?: RuntimeServerRow;
     players?: Record<string, RuntimePlayerRow>;
     chunks?: Record<string, RuntimeChunkRow>;
+    revision?: number;
 }): GameRuntimeSnapshot;
 export declare function markServerDirty(snapshot: GameRuntimeSnapshot): GameRuntimeSnapshot;
 export declare function markPlayerDirty(snapshot: GameRuntimeSnapshot, userId: string): GameRuntimeSnapshot;

package/dist/runtime/snapshot.js

@@ -24,7 +24,7 @@ export function createRuntimeSnapshot(args) {
         server: args.server ?? createEmptyServerRow(),
         players: args.players ?? {},
         chunks: args.chunks ?? {},
-        revision: 0,
+        revision: args.revision ?? 0,
         dirty: {
             server: false,
             players: [],

package/dist/runtime/visibility.d.ts

@@ -0,0 +1,74 @@
+/** Stable identifier for a visibility-tracked object or camera. */
+export type VisibilityId = string | number;
+/** World-space point; `z` is optional for 2D adapters. */
+export interface VisibilityPoint {
+    x: number;
+    y: number;
+    z?: number;
+}
+/** Sphere bounds used for visibility/streaming distance checks. */
+export interface VisibilityBounds {
+    center: VisibilityPoint;
+    radius: number;
+}
+/** A camera's position and reach, as seen by the visibility system. */
+export interface CameraVisibilityContext {
+    id: VisibilityId;
+    position: VisibilityPoint;
+    /** Approximate visible radius in world units. Adapters may derive this from a frustum. */
+    visibleRadius: number;
+    /** Extra distance used to request assets before an object becomes visible. */
+    preloadMargin?: number;
+    /** Cameras such as editor thumbnails can opt out of influencing streaming. */
+    influencesStreaming?: boolean;
+}
+/** Per-object escape hatches that bypass or tune the default visibility policy. */
+export interface VisibilityOverrides {
+    alwaysVisible?: boolean;
+    neverUnload?: boolean;
+    cullingDisabled?: boolean;
+    streamingDisabled?: boolean;
+    minRenderDistance?: number;
+    maxRenderDistance?: number;
+    preloadMargin?: number;
+}
+/** An entity/asset tracked by `VisibilitySystem.evaluate`. */
+export interface VisibilityObject {
+    id: VisibilityId;
+    bounds: VisibilityBounds;
+    overrides?: VisibilityOverrides;
+}
+/** Baseline policy settings a `VisibilitySystem` is constructed with. */
+export interface VisibilityDefaults {
+    enabled: boolean;
+    streamingEnabled: boolean;
+    minRenderDistance: number;
+    maxRenderDistance: number;
+    preloadMargin: number;
+    unloadGraceMs: number;
+    hysteresis: number;
+}
+/** Default `VisibilityDefaults` a `VisibilitySystem` falls back to when unspecified. */
+export declare const DEFAULT_VISIBILITY_SETTINGS: Readonly<VisibilityDefaults>;
+/** Result of evaluating one object against the active cameras this tick. */
+export interface VisibilityDecision {
+    render: boolean;
+    load: boolean;
+    unload: boolean;
+    reason: "always-visible" | "culling-disabled" | "visible" | "preload" | "distance-culled" | "outside-view" | "grace-period" | "streaming-disabled";
+}
+/**
+ * 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 declare class VisibilitySystem {
+    #private;
+    readonly settings: VisibilityDefaults;
+    constructor(settings?: Partial<VisibilityDefaults>);
+    evaluate(object: VisibilityObject, cameras: readonly CameraVisibilityContext[], now?: number): VisibilityDecision;
+    setLoaded(id: VisibilityId, loaded: boolean, now?: number): void;
+    forget(id: VisibilityId): void;
+    clear(): void;
+}