@jgengine/core 0.18.0 → 0.19.0

package/dist/runtime/adapter.d.ts

@@ -122,9 +122,28 @@ export declare function offline(): MultiplayerAdapterConfig;
 export declare function adapterOf(multiplayer: unknown): MultiplayerAdapterConfig | null;
 export declare function multiplayerAdapterKind(multiplayer: unknown): string | null;
 export type ServersPoolConfig = {
+    minPlayersToStart?: number;
+    adapter: MultiplayerAdapterConfig;
+} & ({
+    topology: "shared";
+    maxServers?: number;
+    slotsPerServer?: number;
+} | {
+    topology?: "rooms";
+    maxServers: number;
+    slotsPerServer: number;
+});
+/** Resolve the shared-world pool to one unbounded world; room pools keep explicit capacities. */
+export declare function servers(config: ServersPoolConfig): {
+    minPlayersToStart?: number;
+    adapter: MultiplayerAdapterConfig;
+    topology: "rooms" | "shared";
     maxServers: number;
     slotsPerServer: number;
+} | {
     minPlayersToStart?: number;
     adapter: MultiplayerAdapterConfig;
+    topology: "rooms" | "shared";
+    maxServers: number;
+    slotsPerServer: number;
 };
-export declare function servers(config: ServersPoolConfig): ServersPoolConfig;

package/dist/runtime/adapter.js

@@ -105,6 +105,13 @@ export function adapterOf(multiplayer) {
 export function multiplayerAdapterKind(multiplayer) {
     return adapterOf(multiplayer)?.kind ?? null;
 }
+/** Resolve the shared-world pool to one unbounded world; room pools keep explicit capacities. */
 export function servers(config) {
-    return config;
+    const shared = config.topology === "shared";
+    const maxServers = shared ? 1 : config.maxServers;
+    const slotsPerServer = shared ? Number.MAX_SAFE_INTEGER : config.slotsPerServer;
+    if (!Number.isSafeInteger(maxServers) || maxServers < 1 || !Number.isSafeInteger(slotsPerServer) || slotsPerServer < 1) {
+        throw new RangeError("Server pool capacities must be positive safe integers");
+    }
+    return { ...config, topology: config.topology ?? "rooms", maxServers, slotsPerServer };
 }

package/dist/runtime/cameraDirector.d.ts

@@ -1,6 +1,16 @@
-import type { ChaseCameraConfig, CinematicCameraConfig } from "../game/playableGame.js";
-/** Runtime patch over the static `camera.chase` config — distance/height/fov retuning from gameplay events (#286.11), or a whole driving-feel overlay (speed→FOV, lead, bank, speed shake, drift-lag) applied only while a vehicle is piloted (#1299). */
-export type ChaseCameraTuning = Partial<Pick<ChaseCameraConfig, "distance" | "height" | "lookHeight" | "springDamping" | "fov" | "lead" | "bank" | "shakePerSpeed" | "velocityYaw" | "yawResponse">>;
+import type { ChaseCameraConfig, ChaseView, CinematicCameraConfig } from "../game/playableGame.js";
+/** Runtime patch over the static `camera.chase` config — distance/height/fov retuning from gameplay events (#286.11), a whole driving-feel overlay applied only while a vehicle is piloted (#1299), or a `view` switch between chase and seat cameras. */
+export type ChaseCameraTuning = Partial<Pick<ChaseCameraConfig, "distance" | "height" | "lookHeight" | "springDamping" | "fov" | "lead" | "bank" | "shakePerSpeed" | "velocityYaw" | "yawResponse" | "distanceBySpeed" | "pitchFollow" | "fovKick" | "lookBackAction" | "collision" | "view">>;
+/** Default order {@link nextChaseView} cycles through. */
+export declare const CHASE_VIEWS: readonly ChaseView[];
+/**
+ * The view after `current` in `views`, wrapping at the end; a view missing from the list starts the cycle over.
+ * Pair with `setChaseTuning` to bind a "change camera" key:
+ * `ctx.camera.setChaseTuning({ ...ctx.camera.chaseTuning(), view: nextChaseView(view) })`.
+ *
+ * @capability chase-view-cycle cycle a vehicle camera between chase, hood and cockpit views at runtime
+ */
+export declare function nextChaseView(current: ChaseView, views?: readonly ChaseView[]): ChaseView;
 export interface CameraDirector {
     follow(entityId: string | null): void;
     /** `undefined` means no runtime override — the shell falls back to the static `playable.camera.followEntityId`. `null` means explicitly follow nothing. */
@@ -10,6 +20,10 @@ export interface CameraDirector {
     /** Overlay a runtime patch on the chase rig's config — a boss-intro pull-back, drift zoom-out; `null` restores the static config. */
     setChaseTuning(tuning: ChaseCameraTuning | null): void;
     chaseTuning(): ChaseCameraTuning | null;
+    /** Add a transient FOV impulse in degrees (a landing, a hit, a boost) that the chase rig layers on and decays per `camera.chase.fovKick`. Kicks from one frame sum. */
+    kickFov(degrees: number): void;
+    /** Drain the FOV impulses queued since the last call; the shell's chase rig calls this once per frame. */
+    takeFovKick(): number;
     subscribe(listener: () => void): () => void;
 }
 /** @internal */

package/dist/runtime/cameraDirector.js

@@ -1,9 +1,25 @@
+/** Default order {@link nextChaseView} cycles through. */
+export const CHASE_VIEWS = ["chase", "hood", "cockpit"];
+/**
+ * The view after `current` in `views`, wrapping at the end; a view missing from the list starts the cycle over.
+ * Pair with `setChaseTuning` to bind a "change camera" key:
+ * `ctx.camera.setChaseTuning({ ...ctx.camera.chaseTuning(), view: nextChaseView(view) })`.
+ *
+ * @capability chase-view-cycle cycle a vehicle camera between chase, hood and cockpit views at runtime
+ */
+export function nextChaseView(current, views = CHASE_VIEWS) {
+    if (views.length === 0)
+        return current;
+    const index = views.indexOf(current);
+    return views[(index + 1) % views.length];
+}
 /** @internal */
 export function createCameraDirector() {
     const listeners = new Set();
     let followEntity = undefined;
     let cinematicConfig = null;
     let chaseTuningPatch = null;
+    let pendingFovKick = 0;
     function notify() {
         for (const listener of listeners)
             listener();
@@ -24,6 +40,15 @@ export function createCameraDirector() {
             notify();
         },
         chaseTuning: () => chaseTuningPatch,
+        kickFov(degrees) {
+            if (Number.isFinite(degrees))
+                pendingFovKick += degrees;
+        },
+        takeFovKick() {
+            const kick = pendingFovKick;
+            pendingFovKick = 0;
+            return kick;
+        },
         subscribe(listener) {
             listeners.add(listener);
             return () => listeners.delete(listener);

package/dist/runtime/commandInput.d.ts

@@ -0,0 +1,52 @@
+/** Validated integer quantity or a stable input rejection. */
+export type QuantityResult = {
+    ok: true;
+    quantity: number;
+} | {
+    ok: false;
+    reason: "invalid-quantity";
+};
+/** Read an untrusted whole-item quantity without coercion, truncation, or clamping.
+ * @capability command-quantity validate bounded whole-item counts at command boundaries
+ */
+export declare function readQuantity(value: unknown, options?: {
+    min?: number;
+    max?: number;
+}): QuantityResult;
+/** Narrow an untrusted value to a plain object, rejecting arrays and null. */
+export declare function isInputRecord(value: unknown): value is Record<string, unknown>;
+/** Read a non-empty string of at most `maxLength` characters, or `null`. */
+export declare function readInputString(value: unknown, options?: {
+    maxLength?: number;
+}): string | null;
+/**
+ * Read a finite number inside `[min, max]`, or `null`. `NaN` and `±Infinity` are always rejected, so a
+ * coordinate can never drive an unbounded loop; `integer` also rejects fractions instead of flooring them.
+ * @capability command-number validate finite, bounded numbers and integers at command boundaries
+ */
+export declare function readInputNumber(value: unknown, options?: {
+    min?: number;
+    max?: number;
+    integer?: boolean;
+}): number | null;
+/** Read one of a fixed set of values, or `null`. */
+export declare function readInputOneOf<const T extends string | number>(value: unknown, allowed: readonly T[]): T | null;
+/** Read an `{ x, y, z }` point whose axes are finite and within `maxAbs`, or `null`. */
+export declare function readInputPoint3(value: unknown, options?: {
+    maxAbs?: number;
+}): {
+    x: number;
+    y: number;
+    z: number;
+} | null;
+/** Read an `{ x, z }` ground point whose axes are finite and within `maxAbs`, or `null`. */
+export declare function readInputPoint2(value: unknown, options?: {
+    maxAbs?: number;
+}): {
+    x: number;
+    z: number;
+} | null;
+/** Read an array of at most `maxItems` entries, each accepted by `readItem`; any rejected entry rejects the whole array. */
+export declare function readInputArray<T>(value: unknown, readItem: (item: unknown) => T | null, options?: {
+    maxItems?: number;
+}): T[] | null;

package/dist/runtime/commandInput.js

@@ -0,0 +1,71 @@
+/** Read an untrusted whole-item quantity without coercion, truncation, or clamping.
+ * @capability command-quantity validate bounded whole-item counts at command boundaries
+ */
+export function readQuantity(value, options = {}) {
+    const min = options.min ?? 1;
+    const max = options.max ?? Number.MAX_SAFE_INTEGER;
+    if (!Number.isSafeInteger(min) || !Number.isSafeInteger(max) || min < 0 || max < min) {
+        throw new RangeError("Quantity bounds must be nonnegative safe integers in order");
+    }
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= min && value <= max
+        ? { ok: true, quantity: value }
+        : { ok: false, reason: "invalid-quantity" };
+}
+/** Narrow an untrusted value to a plain object, rejecting arrays and null. */
+export function isInputRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Read a non-empty string of at most `maxLength` characters, or `null`. */
+export function readInputString(value, options = {}) {
+    return typeof value === "string" && value.length > 0 && value.length <= (options.maxLength ?? 256) ? value : null;
+}
+/**
+ * Read a finite number inside `[min, max]`, or `null`. `NaN` and `±Infinity` are always rejected, so a
+ * coordinate can never drive an unbounded loop; `integer` also rejects fractions instead of flooring them.
+ * @capability command-number validate finite, bounded numbers and integers at command boundaries
+ */
+export function readInputNumber(value, options = {}) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return null;
+    if (options.integer === true && !Number.isSafeInteger(value))
+        return null;
+    if (value < (options.min ?? -Number.MAX_VALUE) || value > (options.max ?? Number.MAX_VALUE))
+        return null;
+    return value;
+}
+/** Read one of a fixed set of values, or `null`. */
+export function readInputOneOf(value, allowed) {
+    return allowed.includes(value) ? value : null;
+}
+/** Read an `{ x, y, z }` point whose axes are finite and within `maxAbs`, or `null`. */
+export function readInputPoint3(value, options = {}) {
+    if (!isInputRecord(value))
+        return null;
+    const bound = { min: -(options.maxAbs ?? Number.MAX_VALUE), max: options.maxAbs ?? Number.MAX_VALUE };
+    const x = readInputNumber(value.x, bound);
+    const y = readInputNumber(value.y, bound);
+    const z = readInputNumber(value.z, bound);
+    return x === null || y === null || z === null ? null : { x, y, z };
+}
+/** Read an `{ x, z }` ground point whose axes are finite and within `maxAbs`, or `null`. */
+export function readInputPoint2(value, options = {}) {
+    if (!isInputRecord(value))
+        return null;
+    const bound = { min: -(options.maxAbs ?? Number.MAX_VALUE), max: options.maxAbs ?? Number.MAX_VALUE };
+    const x = readInputNumber(value.x, bound);
+    const z = readInputNumber(value.z, bound);
+    return x === null || z === null ? null : { x, z };
+}
+/** Read an array of at most `maxItems` entries, each accepted by `readItem`; any rejected entry rejects the whole array. */
+export function readInputArray(value, readItem, options = {}) {
+    if (!Array.isArray(value) || value.length > (options.maxItems ?? 256))
+        return null;
+    const items = [];
+    for (const entry of value) {
+        const item = readItem(entry);
+        if (item === null)
+            return null;
+        items.push(item);
+    }
+    return items;
+}

package/dist/runtime/commandRunner.d.ts

@@ -12,23 +12,47 @@ export type CommandScope = {
     /** Chunk keys to hydrate; omit for every chunk of the server, `[]` for none. */
     chunkKeys?: readonly string[];
 };
+/** Declarative read scope; actor is resolved before host hydration. */
+export type CommandScopeDefinition = Omit<CommandScope, "players"> & {
+    players?: readonly string[] | "actor";
+};
+/** Who may send a command: any client through the public transport, or only trusted host code. */
+export type CommandAccess = "client" | "server";
+/** Reason every host returns when a command's `parse` rejects its input. */
+export declare const MALFORMED_COMMAND_INPUT_REASON = "Malformed command input";
+/** Reason a public transport returns for a {@link CommandDef} marked `access: "server"`. */
+export declare const SERVER_ONLY_COMMAND_REASON = "Command is server-only";
 export type CommandDef<TInput = unknown> = {
+    /**
+     * `"server"` when `input` carries facts only the host may decide (unlock state, prices, multipliers):
+     * public transports then refuse it and only trusted host calls such as `helpers.runCommand` run it.
+     * Defaults to `"client"`, so every field of `input` must be validated as untrusted.
+     */
+    access?: CommandAccess;
+    /**
+     * Turns the untrusted wire value into the command's input, or `null` to refuse it with
+     * {@link MALFORMED_COMMAND_INPUT_REASON} before `scope`, `validate` or `apply` run. Those then only ever see
+     * parsed input, so a field checked here can't be skipped in one of them. Build it from the readers in
+     * `runtime/commandInput`; declare typed commands with {@link defineCommand}.
+     */
+    parse?: (input: unknown) => TInput | null;
     /**
      * What this command reads and writes, derived from its own input. A host that hydrates through a
      * scope loads only this slice instead of the whole world, and refuses the command if `apply` then
      * dirties a player or chunk the scope did not name — writing an unhydrated chunk would overwrite
-     * the stored one with a blank. Omit it to keep the whole-world default.
+     * the stored one with a blank. Omit it to load only the actor and no chunks; return `{}` to request the whole world.
      */
-    scope?: (input: TInput, actorUserId: string) => CommandScope;
-    validate: (snapshot: import("./snapshot.js").GameRuntimeSnapshot, input: TInput, actorUserId: string) => CommandValidationError | null;
-    apply: (snapshot: import("./snapshot.js").GameRuntimeSnapshot, input: TInput, actorUserId: string) => import("./snapshot.js").GameRuntimeSnapshot;
+    scope?: (input: TInput, actorUserId: string) => CommandScopeDefinition;
+    /** `nowMs` is the host wall clock, in ms — read it rather than a `now` the client put in `input`. */
+    validate: (snapshot: import("./snapshot.js").GameRuntimeSnapshot, input: TInput, actorUserId: string, nowMs: number) => CommandValidationError | null;
+    apply: (snapshot: import("./snapshot.js").GameRuntimeSnapshot, input: TInput, actorUserId: string, nowMs: number) => import("./snapshot.js").GameRuntimeSnapshot;
 };
 /**
- * The scope a command declares for this input, or `undefined` when it declares none (hydrate everything).
+ * The resolved scope, defaulting to the actor and no chunks.
  * Evaluate it before hydration: the actor and the command's own input are both known by then.
  * @internal
  */
-export declare function resolveCommandScope<TInput>(commands: Record<string, CommandDef<TInput>>, commandName: string, input: TInput, actorUserId: string): CommandScope | undefined;
+export declare function resolveCommandScope<TInput>(commands: Record<string, CommandDef<TInput>>, commandName: string, input: TInput, actorUserId: string): CommandScope;
 /**
  * Widen a scope so the actor is always hydrated. A command's own player row is dirtied by
  * {@link runCommand} whatever the command did, and an unhydrated player is dropped from the persist.
@@ -49,4 +73,12 @@ export type RunCommandResult = {
     reason: string;
 };
 /** @internal */
-export declare function runCommand<TInput>(snapshot: import("./snapshot.js").GameRuntimeSnapshot, commands: Record<string, CommandDef<TInput>>, commandName: string, input: TInput, actorUserId: string): RunCommandResult;
+export declare function runCommand<TInput>(snapshot: import("./snapshot.js").GameRuntimeSnapshot, commands: Record<string, CommandDef<TInput>>, commandName: string, input: TInput, actorUserId: string, nowMs?: number): RunCommandResult;
+/**
+ * Declare a command with a typed input: `parse` narrows the wire value once, and `scope`, `validate` and
+ * `apply` receive the parsed type. Returns the untyped {@link CommandDef} a runtime's command table holds.
+ * @capability command-parse parse untrusted command input once so every command stage sees typed, bounded values
+ */
+export declare function defineCommand<TInput>(definition: CommandDef<TInput> & {
+    parse: (input: unknown) => TInput | null;
+}): CommandDef;

package/dist/runtime/commandRunner.js

@@ -1,10 +1,25 @@
+/** Reason every host returns when a command's `parse` rejects its input. */
+export const MALFORMED_COMMAND_INPUT_REASON = "Malformed command input";
+/** Reason a public transport returns for a {@link CommandDef} marked `access: "server"`. */
+export const SERVER_ONLY_COMMAND_REASON = "Command is server-only";
 /**
- * The scope a command declares for this input, or `undefined` when it declares none (hydrate everything).
+ * The resolved scope, defaulting to the actor and no chunks.
  * Evaluate it before hydration: the actor and the command's own input are both known by then.
  * @internal
  */
 export function resolveCommandScope(commands, commandName, input, actorUserId) {
-    return commands[commandName]?.scope?.(input, actorUserId);
+    const command = commands[commandName];
+    let declared;
+    if (command?.parse === undefined) {
+        declared = command?.scope?.(input, actorUserId);
+    }
+    else {
+        const parsed = command.parse(input);
+        declared = parsed === null ? undefined : command.scope?.(parsed, actorUserId);
+    }
+    const scope = declared ?? { players: "actor", chunkKeys: [] };
+    const { players, ...rest } = scope;
+    return players === undefined ? rest : { ...rest, players: players === "actor" ? [actorUserId] : players };
 }
 /**
  * Widen a scope so the actor is always hydrated. A command's own player row is dirtied by
@@ -35,16 +50,23 @@ export function commandScopeEscape(scope, dirty, commandName) {
     return `Command "${commandName}" wrote outside its declared scope: ${parts.join("; ")}`;
 }
 /** @internal */
-export function runCommand(snapshot, commands, commandName, input, actorUserId) {
+export function runCommand(snapshot, commands, commandName, input, actorUserId, nowMs = Date.now()) {
     const command = commands[commandName];
     if (!command) {
         return { ok: false, reason: `Unknown command: ${commandName}` };
     }
-    const validationError = command.validate(snapshot, input, actorUserId);
+    let parsed = input;
+    if (command.parse !== undefined) {
+        const result = command.parse(input);
+        if (result === null)
+            return { ok: false, reason: MALFORMED_COMMAND_INPUT_REASON };
+        parsed = result;
+    }
+    const validationError = command.validate(snapshot, parsed, actorUserId, nowMs);
     if (validationError) {
         return { ok: false, reason: validationError.reason };
     }
-    const next = command.apply(snapshot, input, actorUserId);
+    const next = command.apply(snapshot, parsed, actorUserId, nowMs);
     return {
         ok: true,
         snapshot: {
@@ -60,3 +82,11 @@ export function runCommand(snapshot, commands, commandName, input, actorUserId)
         },
     };
 }
+/**
+ * Declare a command with a typed input: `parse` narrows the wire value once, and `scope`, `validate` and
+ * `apply` receive the parsed type. Returns the untyped {@link CommandDef} a runtime's command table holds.
+ * @capability command-parse parse untrusted command input once so every command stage sees typed, bounded values
+ */
+export function defineCommand(definition) {
+    return definition;
+}

package/dist/runtime/context/combat.d.ts

@@ -36,6 +36,7 @@ export interface CombatSubsystemDeps {
     despawnEntity: (instanceId: string) => boolean;
     runCommand: (name: string, args: unknown) => void;
     localUserId: string;
+    rng: () => number;
     physics?: PhysicsConfig;
 }
 /** @internal Effects, projectiles, death, and combat presentation surface. */

package/dist/runtime/context/combat.js

@@ -8,7 +8,7 @@ import { createCombatFx } from "./combatFx.js";
 import { applyLethalLoot, isLocalPlayerKill } from "./deathLoot.js";
 /** @internal */
 export function createCombatSubsystem(d) {
-    const { content, signalNotify, now, events, time, entities, objects, combatSpatial, sceneRaycast, entityCollidersOf, objectCollidersOf, catalogEntry, statsByInstance, weapon, loot, lootRegistry, spawnWorldItem, despawnEntity, runCommand, localUserId, } = d;
+    const { content, signalNotify, now, events, time, entities, objects, combatSpatial, sceneRaycast, entityCollidersOf, objectCollidersOf, catalogEntry, statsByInstance, weapon, loot, lootRegistry, spawnWorldItem, despawnEntity, runCommand, localUserId, rng, } = d;
     const death = createDeathSystem({
         resolveOnDeath: (instanceId) => catalogEntry(instanceId)?.onDeath,
         resolveIdentity(instanceId) {
@@ -64,6 +64,7 @@ export function createCombatSubsystem(d) {
                 spawnWorldItem,
                 grantToPlayer: loot.grantToPlayer,
                 localUserId,
+                rng,
             });
         },
     }), ["applyEffect"], signalNotify);

package/dist/runtime/context/deathLoot.d.ts

@@ -18,6 +18,8 @@ export interface LethalLootInput {
     spawnWorldItem: (input: WorldItemSpawnInput) => void;
     grantToPlayer: (userId: string, drops: Drop[], source?: string) => void;
     localUserId: string;
+    /** The world's seeded stream — scatter positions must replay with the rest of the simulation. */
+    rng: () => number;
 }
 /**
  * Pure death→loot policy: when a kill yields drops for the local player, either scatter them as

package/dist/runtime/context/deathLoot.js

@@ -14,6 +14,7 @@ export function applyLethalLoot(input) {
         const resolved = resolveDeathDrops([...input.drops], {
             mode: "world",
             origin: input.position,
+            rng: input.rng,
             resolveRarity: (itemId) => input.content.itemById?.(itemId)?.rarity ?? DEFAULT_RARITY,
             resolveBaseType: (itemId) => input.content.itemById?.(itemId)?.baseType ?? itemId,
             scatter: normalizedOnDeath.scatter,

package/dist/runtime/gameContext.js

@@ -1,6 +1,7 @@
 import { createCommandRegistry } from "../commands/commandRegistry.js";
 import {} from "../game/cosmetics.js";
 import { groundFieldFor } from "../world/terrain.js";
+import { createWorldSolids, structureSolids } from "../world/worldSolids.js";
 import { createGameEvents } from "../game/events.js";
 import { createGameFeed } from "../game/feed.js";
 import { setGamePhase } from "../game/gamePhase.js";
@@ -19,8 +20,10 @@ import { createRuntimeSave } from "./runtimeSave.js";
 import { isOffline } from "./adapter.js";
 import { localSaveBackend, memorySaveBackend } from "../game/saveStore.js";
 import { createSimClock } from "../time/simClock.js";
+import { createSimContext } from "./simContext.js";
 import { seededRng } from "../random/rng.js";
 import { createCameraDirector } from "./cameraDirector.js";
+import { createParticleDirector } from "../vfx/particleDirector.js";
 import { createInputSnapshot } from "./inputSnapshot.js";
 import { baselineDescriptors } from "./descriptors/baseline.js";
 import { featureDescriptors } from "./descriptors/features.js";
@@ -41,6 +44,10 @@ export function createGameContext(options) {
     const activeUserId = () => actingUserId ?? player.userId;
     const time = createSimClock({ config: definition.time, onChange: signal.notify });
     const ground = groundFieldFor(definition.world);
+    const solids = createWorldSolids();
+    if (definition.world?.kind === "environment") {
+        solids.set("environment:structures", structureSolids(definition.world, ground.sampleHeight));
+    }
     const rawEvents = createGameEvents();
     const events = {
         on: rawEvents.on,
@@ -213,6 +220,7 @@ export function createGameContext(options) {
             commandRegistry.run(ctxRef, name, args);
         },
         localUserId: player.userId,
+        rng,
         ...(definition.physics !== undefined ? { physics: definition.physics } : {}),
     });
     scene.setOnAfterSpawn((instanceId) => combat.death.revive(instanceId));
@@ -220,6 +228,7 @@ export function createGameContext(options) {
     const store = notifyAfter(createObservableKeyedStore(), ["set", "delete", "hydrate"], signal.notify);
     const { pile, loop, raceState, cardPiles, turnLoops } = createContextRegistries(signal.notify);
     const camera = notifyAfter(createCameraDirector(), ["follow", "setCinematic", "setChaseTuning"], signal.notify);
+    const particles = createParticleDirector();
     const input = createInputSnapshot();
     // --- Descriptor install (single feature enable path) ---
     const featureDeps = {
@@ -289,7 +298,7 @@ export function createGameContext(options) {
         ...featureReplicateModules,
     ];
     const replication = options.replication;
-    const projectsViewers = policyProjectsViewers(replication);
+    const projectsViewers = policyProjectsViewers(replication) || snapshotModules.some((module) => module.priority !== undefined);
     const aoiRadius = replication?.aoiRadius;
     const typedProject = (project) => (data, viewer, world) => project(data, viewer, world);
     const projectorFor = (key) => {
@@ -403,8 +412,10 @@ export function createGameContext(options) {
         world: {
             ground,
             groundHeightAt: ground.sampleHeight,
+            solids,
         },
         game: {
+            territory: options.territory,
             commands: {
                 define: commandRegistry.define,
                 has: commandRegistry.has,
@@ -496,7 +507,9 @@ export function createGameContext(options) {
             weapon,
         },
         time,
+        sim: createSimContext({ config: definition.simulation, entities }),
         camera,
+        particles,
         input,
         subscribe: signal.subscribe,
         version: signal.version,
@@ -510,6 +523,10 @@ export function createGameContext(options) {
         replicatesPerViewer: () => projectsViewers,
     };
     ctxRef = ctx;
+    const physicsBackend = definition.physics?.backend;
+    if (physicsBackend !== undefined) {
+        ctx.sim.addStage({ id: "physics", phase: "afterMovement", run: (dt) => physicsBackend.step(dt) });
+    }
     const saveOptions = resolveSaveOptions(definition, options);
     if (saveOptions !== undefined) {
         const saveTarget = {

package/dist/runtime/gameContextTypes.d.ts

@@ -1,3 +1,5 @@
+import type { Territory } from "../world/territory.js";
+import type { CurrencyDefinition } from "../economy/currency.js";
 import type { CardPile, CardPileConfig } from "../cards/cardPile.js";
 import type { EffectInput, EffectResult, EffectVia, ReceiveMap, SingleTargetEffectInput } from "../combat/effects.js";
 import type { ProjectileSystem } from "../combat/projectiles.js";
@@ -9,6 +11,7 @@ import type { ChargeOptions as WalletChargeOptions } from "../economy/wallet.js"
 import type { Cosmetics } from "../game/cosmetics.js";
 import type { GameDefinition } from "../game/defineGame.js";
 import type { TerrainField } from "../world/terrain.js";
+import type { WorldSolids } from "../world/worldSolids.js";
 import type { GameEventMap, GameEvents, VfxKind } from "../game/events.js";
 import type { VfxInstanceStore } from "../game/vfxInstance.js";
 import type { GameFeed } from "../game/feed.js";
@@ -52,9 +55,11 @@ import type { SnapshotModule, SnapshotViewer, WorldSnapshot } from "./worldSnaps
 import type { ReplicationPolicy } from "./worldProjection.js";
 import type { RuntimeSave, RuntimeSaveOptions } from "./runtimeSave.js";
 import type { SimClock } from "../time/simClock.js";
+import type { SimContext } from "./simContext.js";
 import type { TurnLoop, TurnLoopConfig } from "../turn/turnLoop.js";
 import type { RaceState, RaceStateConfig } from "../game/race.js";
 import type { CameraDirector } from "./cameraDirector.js";
+import type { ParticleDirector } from "../vfx/particleDirector.js";
 import type { InputSnapshot } from "./inputSnapshot.js";
 import type { MotionIntents } from "./motionIntents.js";
 import type { OnDeathSpec } from "../combat/death.js";
@@ -111,6 +116,7 @@ export interface GameContextOptions<TAssetRef extends ModelAssetRef = ModelAsset
         userId: string;
         isNew: boolean;
     };
+    territory?: Territory;
     now?: () => number;
     occluder?: (from: EntityPosition, to: EntityPosition) => boolean;
     /**
@@ -339,6 +345,11 @@ export type WorldItemPickupResult = {
     status: "rejected";
     reason: string;
 };
+/**
+ * `ctx.scene.worldItem`: items lying in the world — spawn, list, find the nearest, and pick up into a player's bag.
+ *
+ * @capability world-item-pickup pick up dropped items: ctx.scene.worldItem nearestInRadius → pickup into the player's inventory
+ */
 export interface SceneWorldItemContext {
     spawn(input: WorldItemSpawnInput): WorldItemRecord;
     get(instanceId: string): WorldItemRecord | null;
@@ -367,14 +378,14 @@ export interface GameContextLoot {
     grantToPlayer(userId: string, drops: Drop[], source?: string): void;
 }
 export interface GameContextEconomy {
-    balance(userId: string, currencyId: string): number;
-    grant(userId: string, currencyId: string, amount: number): void;
+    balance(userId: string, currencyId: string | CurrencyDefinition): number;
+    grant(userId: string, currencyId: string | CurrencyDefinition, amount: number): void;
     /** `options.overdraft` opts this charge into carrying a negative balance (`true` unlimited, `{ max }` capped) — omitted keeps the strict no-debt default. */
-    charge(userId: string, currencyId: string, amount: number, options?: WalletChargeOptions): {
+    charge(userId: string, currencyId: string | CurrencyDefinition, amount: number, options?: WalletChargeOptions): {
         reason: string;
     } | null;
     /** True once `balance(userId, currencyId)` has gone negative under an overdraft-enabled charge. */
-    isOverdrawn(userId: string, currencyId: string): boolean;
+    isOverdrawn(userId: string, currencyId: string | CurrencyDefinition): boolean;
 }
 export interface GameContextItemUse {
     register(handlers: Record<string, ItemUseHandler<GameContext>>): void;
@@ -385,6 +396,11 @@ export interface GameContextItemUse {
 export interface GameContextWorld {
     ground: TerrainField;
     groundHeightAt(x: number, z: number): number;
+    /**
+     * Static collision for world geometry that is not a scene object. `environment({ structures })`
+     * fills the `environment:structures` layer; `syncAuthoredSolids` fills one layer per studio object.
+     */
+    solids: WorldSolids;
 }
 export interface GameContextCards {
     /** Lazily creates (on first call, `config` required) or returns the existing notify-wrapped pile for `id`. */
@@ -415,14 +431,19 @@ export interface GameAudio {
     }): void;
     /**
      * Live-update retained loop `id` via `audio.loopSet`: `rate` re-pitches it (1 = authored pitch, clamped
-     * 0.25–4 by the shell), `gain` rescales volume (0–1), `at` repositions its emitter. Cheap to call every
-     * tick (~60 Hz) — the shell ramps rate/gain over ~20 ms to avoid zipper noise. A no-op when `id` is not a
-     * live loop (an update may race a stop) (#1051).
+     * 0.25–4 by the shell), `gain` rescales volume (0–1), `at` repositions its emitter. `lowpass`/`highpass`
+     * set filter cutoffs in Hz (muffle an engine off-throttle or behind a wall); `velocity` is the emitter's
+     * world velocity, which pitches the loop by doppler when its sound declares `doppler`. Cheap to call every
+     * tick (~60 Hz) — the shell ramps rate/gain/cutoffs over ~20 ms to avoid zipper noise. A no-op when `id`
+     * is not a live loop (an update may race a stop) (#1051).
      */
     setLoop(id: string, params: {
         rate?: number;
         gain?: number;
         at?: readonly [number, number, number];
+        velocity?: readonly [number, number, number];
+        lowpass?: number;
+        highpass?: number;
     }): void;
     /** Stop and dispose retained loop `id` (emits `audio.loopStop`); an unknown `id` is ignored (#1051). */
     stopLoop(id: string): void;
@@ -446,6 +467,7 @@ export interface GameContext {
      */
     rng: () => number;
     game: {
+        territory?: Territory;
         commands: GameContextCommands;
         events: GameEvents;
         audio: GameAudio;
@@ -523,8 +545,12 @@ export interface GameContext {
         weapon: WeaponStats;
     };
     time: SimClock;
+    /** The simulation stepper (fixed or variable) every driver advances through, plus render-side pose interpolation and per-step stages. */
+    sim: SimContext;
     /** Runtime camera-follow/cinematic override (#196.2); the shell reads `followedEntityId()` each frame. */
     camera: CameraDirector;
+    /** Particle VFX seam (#1659): queue bursts / standing emitters as data; the shell renders them quality-capped. */
+    particles: ParticleDirector;
     /** Held-input snapshot published by the shell each frame before `onTick` (#164.1). */
     input: InputSnapshot;
     subscribe(listener: () => void): () => void;