@jgengine/core 0.18.0 → 0.18.1

package/dist/render/lookPreset.d.ts

@@ -2,8 +2,8 @@ import type { BackdropConfig, LightingConfig } from "../game/playableGame.js";
 import type { SkyEnvironmentConfig } from "../world/features.js";
 import type { PostProcessingConfig } from "./postProcessing.js";
 /**
- * Named default-look preset composing the existing lighting/sky/fog/post knobs into one field.
- * `"cinematic"` (the default when unset) draws a scene lit like a shipped game — a real day sky
+ * Named look preset composing the existing lighting/sky/fog/post knobs into one field.
+ * `"neutral"` (the default when unset) keeps presentation unstyled; `"cinematic"` draws a scene lit like a shipped game — a real day sky
  * with a view-following shadow-casting sun + hemisphere fill, a network-free image-based-lighting
  * environment so PBR surfaces catch soft reflections, and a tuned tone-map/bloom/AO/vignette post
  * stack. `"flat"` opts out of the sky/IBL/post rig to the bare ambient+directional default (pre-#773).
@@ -11,7 +11,7 @@ import type { PostProcessingConfig } from "./postProcessing.js";
  * detail so un-modeled boxes/capsules stop reading as flat plastic — apply under both presets.
  * @capability default-look one field that lights a scene like a shipped game (opt out with "flat")
  */
-export type LookPreset = "cinematic" | "flat";
+export type LookPreset = "neutral" | "photoreal" | "toon" | "cinematic" | "flat";
 /** Explicit graphics knobs a game may set; the preset only fills the ones left undefined. */
 export interface GameLookInput {
     look?: LookPreset;
@@ -31,9 +31,15 @@ export interface ResolvedGameLook {
 export declare const CINEMATIC_SKY: SkyEnvironmentConfig;
 /** Tuned tone-map + bloom + gentle SSAO + vignette/grade stack — the shipped-game post look. */
 export declare const CINEMATIC_POST_PROCESSING: PostProcessingConfig;
+/** Unstyled baseline: a stable linear presentation with no genre-specific grading. */
+export declare const NEUTRAL_POST_PROCESSING: PostProcessingConfig;
+/** High-contrast physically based presentation for authored HDR environments. */
+export declare const PHOTOREAL_POST_PROCESSING: PostProcessingConfig;
+/** Clean graphic presentation; toon materials remain game-owned while this sets the grade. */
+export declare const TOON_POST_PROCESSING: PostProcessingConfig;
 /**
- * Expand a game's `look` into concrete lighting/backdrop/post. The default is `"cinematic"`, so a
- * scene reads lit-like-a-game out of the box; `"flat"` passes the explicit knobs through untouched.
+ * Expand a game's `look` into concrete lighting/backdrop/post. The default is `"neutral"`;
+ * `"flat"` passes the explicit knobs through untouched.
  * Anything the game authored wins — the preset only fills unset knobs, and it never adds a sky when
  * the world already owns one (so the sky's tuned sun/hemisphere serve as the lighting rig).
  * @capability resolve-game-look expand a look preset into concrete lighting/backdrop/post knobs

package/dist/render/lookPreset.js

@@ -7,23 +7,48 @@ export const CINEMATIC_POST_PROCESSING = {
     ao: { intensity: 1.4 },
     grade: {},
 };
+/** Unstyled baseline: a stable linear presentation with no genre-specific grading. */
+export const NEUTRAL_POST_PROCESSING = {
+    toneMapping: "agx",
+    bloom: false,
+    ao: false,
+    grade: false,
+};
+/** High-contrast physically based presentation for authored HDR environments. */
+export const PHOTOREAL_POST_PROCESSING = {
+    toneMapping: "aces",
+    bloom: { strength: 0.28, radius: 0.58, threshold: 0.9 },
+    ao: { intensity: 1.25, radius: 1.6 },
+    grade: { saturation: 1.04, vignette: 0.08, grain: 0.004 },
+};
+/** Clean graphic presentation; toon materials remain game-owned while this sets the grade. */
+export const TOON_POST_PROCESSING = {
+    toneMapping: "linear",
+    bloom: { strength: 0.08, radius: 0.35, threshold: 1.1 },
+    ao: { intensity: 0.8, radius: 1.2 },
+    grade: { saturation: 1.18, gamma: 1, vignette: 0, grain: 0 },
+};
 /**
- * Expand a game's `look` into concrete lighting/backdrop/post. The default is `"cinematic"`, so a
- * scene reads lit-like-a-game out of the box; `"flat"` passes the explicit knobs through untouched.
+ * Expand a game's `look` into concrete lighting/backdrop/post. The default is `"neutral"`;
+ * `"flat"` passes the explicit knobs through untouched.
  * Anything the game authored wins — the preset only fills unset knobs, and it never adds a sky when
  * the world already owns one (so the sky's tuned sun/hemisphere serve as the lighting rig).
  * @capability resolve-game-look expand a look preset into concrete lighting/backdrop/post knobs
  */
 export function resolveGameLook(input) {
-    const look = input.look ?? "cinematic";
+    const look = input.look ?? "neutral";
     if (look === "flat") {
         return { lighting: input.lighting, backdrop: input.backdrop, postProcessing: input.postProcessing };
     }
+    if (look === "neutral") {
+        return { lighting: input.lighting, backdrop: input.backdrop, postProcessing: input.postProcessing ?? NEUTRAL_POST_PROCESSING };
+    }
     const sky = input.backdrop?.sky ?? (input.hasWorldSky === true ? undefined : CINEMATIC_SKY);
     const backdrop = sky === input.backdrop?.sky ? input.backdrop : { ...input.backdrop, sky };
     return {
         lighting: input.lighting,
         backdrop,
-        postProcessing: input.postProcessing ?? CINEMATIC_POST_PROCESSING,
+        postProcessing: input.postProcessing ??
+            (look === "toon" ? TOON_POST_PROCESSING : look === "photoreal" ? PHOTOREAL_POST_PROCESSING : CINEMATIC_POST_PROCESSING),
     };
 }

package/dist/render/postProcessing.d.ts

@@ -6,7 +6,11 @@ export interface BloomConfig {
     strength?: number;
     /** Glow spread radius, 0..1. Default 0.55. */
     radius?: number;
-    /** Luminance above which a pixel blooms, 0..1. Default 0.85. */
+    /**
+     * Luminance above which a pixel blooms. Default 0.85. Measured on raw HDR
+     * before the tone-map/exposure stage, so lowering `exposure` does not change
+     * which pixels bloom — push past 1.0 to select only emissives.
+     */
     threshold?: number;
 }
 /** Ground-truth ambient occlusion stage — darkens contact creases and cavities for depth. */
@@ -22,6 +26,11 @@ export interface AoConfig {
 }
 /** Final colour-grade stage: lift/gain/gamma, saturation, vignette, film grain — applied in display space after tone mapping. */
 export interface GradeConfig {
+    /** Optional 2D strip LUT URL. The strip contains size square tiles, one tile per blue slice. */
+    lut?: {
+        url: string;
+        size?: number;
+    };
     /** Additive shadow tint (RGB, ~0..0.1). Default cool [0.012, 0.010, 0.018]. */
     lift?: readonly [number, number, number];
     /** Multiplicative highlight tint (RGB, ~1). Default warm [1.05, 1.02, 0.98]. */

package/dist/render/sprite2d.d.ts

@@ -0,0 +1,38 @@
+import type { SpriteAtlas } from "../assets/spriteAtlas.js";
+/** Serializable playback position for a named sprite animation. */
+export interface SpriteClipState {
+    animation: string;
+    frameIndex: number;
+    elapsed: number;
+    done: boolean;
+}
+/** Create a renderer-independent sprite animation player.
+ * @capability sprite-2d animate a sprite atlas clip from headless or rendered game code
+ */
+export declare function createSpriteClipPlayer(atlas: SpriteAtlas): {
+    play(name: string): void;
+    advance(dt: number): void;
+    frame: () => {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        pivot?: [number, number];
+    } | undefined;
+    snapshot: () => {
+        animation: string;
+        frameIndex: number;
+        elapsed: number;
+        done: boolean;
+    };
+    restore(next: SpriteClipState): void;
+    retune(next: {
+        speed: number;
+    }): void;
+};
+/** Canonical layers used by 2D presentations. */
+export declare const SortingLayers: readonly ["background", "world", "actors", "effects", "foreground", "ui"];
+/** Resolve a layer name and local offset into a stable render order.
+ * @capability sprite-2d order sprites by named presentation layers
+ */
+export declare function sortingOrder(layers: readonly string[], layer: string, offset?: number): number;

package/dist/render/sprite2d.js

@@ -0,0 +1,40 @@
+/** Create a renderer-independent sprite animation player.
+ * @capability sprite-2d animate a sprite atlas clip from headless or rendered game code
+ */
+export function createSpriteClipPlayer(atlas) {
+    let state = { animation: Object.keys(atlas.animations)[0] ?? "", frameIndex: 0, elapsed: 0, done: false };
+    let speed = 1;
+    const current = () => { const animation = atlas.animations[state.animation]; if (!animation)
+        return undefined; return atlas.frames[animation.frames[state.frameIndex]]; };
+    return {
+        play(name) { if (!atlas.animations[name])
+            throw new Error(`Unknown sprite animation: ${name}.`); state = { animation: name, frameIndex: 0, elapsed: 0, done: false }; },
+        advance(dt) { if (!Number.isFinite(dt) || dt < 0)
+            throw new Error("dt must be non-negative."); const animation = atlas.animations[state.animation]; if (!animation || state.done)
+            return; state.elapsed += dt * speed; const duration = 1 / animation.fps; while (state.elapsed >= duration && !state.done) {
+            state.elapsed -= duration;
+            if (state.frameIndex + 1 < animation.frames.length)
+                state.frameIndex += 1;
+            else if (animation.loop === false) {
+                state.frameIndex = animation.frames.length - 1;
+                state.done = true;
+            }
+            else
+                state.frameIndex = 0;
+        } },
+        frame: current,
+        snapshot: () => ({ ...state }),
+        restore(next) { if (!atlas.animations[next.animation])
+            throw new Error(`Unknown sprite animation: ${next.animation}.`); state = { ...next }; },
+        retune(next) { if (!Number.isFinite(next.speed) || next.speed < 0)
+            throw new Error("speed must be non-negative."); speed = next.speed; },
+    };
+}
+/** Canonical layers used by 2D presentations. */
+export const SortingLayers = ["background", "world", "actors", "effects", "foreground", "ui"];
+/** Resolve a layer name and local offset into a stable render order.
+ * @capability sprite-2d order sprites by named presentation layers
+ */
+export function sortingOrder(layers, layer, offset = 0) { const index = layers.indexOf(layer); if (index < 0)
+    throw new Error(`Unknown sorting layer: ${layer}.`); if (!Number.isFinite(offset))
+    throw new Error("offset must be finite."); return index + offset; }

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/commandInput.d.ts

@@ -0,0 +1,15 @@
+/** 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;

package/dist/runtime/commandInput.js

@@ -0,0 +1,13 @@
+/** 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" };
+}

package/dist/runtime/commandRunner.d.ts

@@ -12,23 +12,28 @@ 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";
+};
 export type CommandDef<TInput = unknown> = {
     /**
      * 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 +54,4 @@ 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;

package/dist/runtime/commandRunner.js

@@ -1,10 +1,12 @@
 /**
- * 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 scope = commands[commandName]?.scope?.(input, actorUserId) ?? { 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 +37,16 @@ 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);
+    const validationError = command.validate(snapshot, input, actorUserId, nowMs);
     if (validationError) {
         return { ok: false, reason: validationError.reason };
     }
-    const next = command.apply(snapshot, input, actorUserId);
+    const next = command.apply(snapshot, input, actorUserId, nowMs);
     return {
         ok: true,
         snapshot: {

package/dist/runtime/gameContext.js

@@ -19,8 +19,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";
@@ -220,6 +222,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 +292,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) => {
@@ -405,6 +408,7 @@ export function createGameContext(options) {
             groundHeightAt: ground.sampleHeight,
         },
         game: {
+            territory: options.territory,
             commands: {
                 define: commandRegistry.define,
                 has: commandRegistry.has,
@@ -496,7 +500,9 @@ export function createGameContext(options) {
             weapon,
         },
         time,
+        sim: createSimContext({ config: definition.simulation, entities }),
         camera,
+        particles,
         input,
         subscribe: signal.subscribe,
         version: signal.version,
@@ -510,6 +516,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";
@@ -52,9 +54,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 +115,7 @@ export interface GameContextOptions<TAssetRef extends ModelAssetRef = ModelAsset
         userId: string;
         isNew: boolean;
     };
+    territory?: Territory;
     now?: () => number;
     occluder?: (from: EntityPosition, to: EntityPosition) => boolean;
     /**
@@ -367,14 +372,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;
@@ -446,6 +451,7 @@ export interface GameContext {
      */
     rng: () => number;
     game: {
+        territory?: Territory;
         commands: GameContextCommands;
         events: GameEvents;
         audio: GameAudio;
@@ -523,8 +529,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;

package/dist/runtime/gameRuntime.d.ts

@@ -16,6 +16,13 @@ export type ServerLoopHooks = {
 export type RuntimeInitContext = {
     snapshot: GameRuntimeSnapshot;
     setSnapshot: (snapshot: GameRuntimeSnapshot) => void;
+    /**
+     * Host wall clock at the start of this call, in ms. The host already knows it, so anything keyed to
+     * real time — a UTC date rollover, a `lastTickAt` anchor other code paths read, a seed or a
+     * `createdAt` stamp — reads it here instead of re-deriving one by accumulating `dtSeconds` against a
+     * persisted epoch. It is authoritative: unlike a `now` carried in command input, no client supplied it.
+     */
+    nowMs: number;
 };
 export type RuntimeLoopContext = RuntimeInitContext & {
     player: {
@@ -28,6 +35,7 @@ export type RuntimeWorldContext = RuntimeInitContext & {
 };
 export type GameRuntimeDefinition = {
     gameId: string;
+    topology?: "shared" | "rooms";
     save: SaveConfig;
     commands: Record<string, CommandDef>;
     loop?: ServerLoopHooks;
@@ -39,9 +47,12 @@ export type HydrateInput = {
     playersByUserId: Record<string, RuntimePlayerRow>;
     chunksByKey: Record<string, RuntimeChunkRow>;
     revision?: number;
+    /** Host wall clock for `onInit`, in ms. Defaults to `Date.now()`. */
+    nowMs?: number;
 };
 export type GameRuntime = {
     gameId: string;
+    topology?: "shared" | "rooms";
     save: SaveConfig;
     /**
      * Whether this runtime declares `loop.onTick`. A host's tick cron reads it to skip hydrating and
@@ -50,17 +61,22 @@ export type GameRuntime = {
      */
     hasTick: boolean;
     hydrate: (input: HydrateInput) => GameRuntimeSnapshot;
-    runCommand: (snapshot: GameRuntimeSnapshot, actorUserId: string, commandName: string, input: unknown) => ReturnType<typeof runCommand>;
+    runCommand: (snapshot: GameRuntimeSnapshot, actorUserId: string, commandName: string, input: unknown, 
+    /** Host wall clock handed to `validate`/`apply`, in ms. Defaults to `Date.now()`. */
+    nowMs?: number) => ReturnType<typeof runCommand>;
     /**
      * What a command declares it will touch, evaluated before hydration so a host can load that slice
-     * and nothing else. `undefined` means the command declared no scope — hydrate everything.
+     * and nothing else. Missing scopes load only the actor and no chunks; `{}` explicitly requests all state.
      */
     commandScope: (commandName: string, input: unknown, actorUserId: string) => CommandScope | undefined;
     /** What a join has to hydrate. `undefined` means the whole world, as when `onNewPlayer` is unscoped. */
     joinScope: (userId: string, isNew: boolean) => CommandScope | undefined;
-    tick: (snapshot: GameRuntimeSnapshot, dtSeconds: number) => GameRuntimeSnapshot;
-    joinPlayer: (snapshot: GameRuntimeSnapshot, userId: string, isNew: boolean) => GameRuntimeSnapshot;
+    /** `nowMs` is the host wall clock at the start of the tick, in ms; defaults to `Date.now()`. */
+    tick: (snapshot: GameRuntimeSnapshot, dtSeconds: number, nowMs?: number) => GameRuntimeSnapshot;
+    joinPlayer: (snapshot: GameRuntimeSnapshot, userId: string, isNew: boolean, nowMs?: number) => GameRuntimeSnapshot;
     toProfileRow: (snapshot: GameRuntimeSnapshot, userId: string) => RuntimeProfileRow | null;
 };
 /** @internal */
 export declare function createGameRuntime(definition: GameRuntimeDefinition): GameRuntime;
+/** Seed a fresh player through the same onNewPlayer hook as joining, without hydrating or modifying a world. */
+export declare function initialPlayerState(runtime: GameRuntime, userId: string, nowMs?: number): RuntimePlayerRow;

package/dist/runtime/gameRuntime.js

@@ -6,6 +6,7 @@ export function createGameRuntime(definition) {
     let initialized = false;
     return {
         gameId: definition.gameId,
+        topology: definition.topology,
         save: definition.save,
         hasTick: loop?.onTick !== undefined,
         hydrate(input) {
@@ -23,6 +24,7 @@ export function createGameRuntime(definition) {
                     get snapshot() {
                         return current;
                     },
+                    nowMs: input.nowMs ?? Date.now(),
                     setSnapshot(next) {
                         current = next;
                     },
@@ -30,8 +32,8 @@ export function createGameRuntime(definition) {
             }
             return current;
         },
-        runCommand(snapshot, actorUserId, commandName, input) {
-            return runCommand(snapshot, definition.commands, commandName, input, actorUserId);
+        runCommand(snapshot, actorUserId, commandName, input, nowMs) {
+            return runCommand(snapshot, definition.commands, commandName, input, actorUserId, nowMs ?? Date.now());
         },
         commandScope(commandName, input, actorUserId) {
             return resolveCommandScope(definition.commands, commandName, input, actorUserId);
@@ -41,7 +43,7 @@ export function createGameRuntime(definition) {
                 return { players: [userId], chunkKeys: [] };
             return loop.joinScope?.(userId, isNew);
         },
-        tick(snapshot, dtSeconds) {
+        tick(snapshot, dtSeconds, nowMs) {
             if (!loop?.onTick)
                 return snapshot;
             let current = snapshot;
@@ -52,6 +54,7 @@ export function createGameRuntime(definition) {
                 get playerIds() {
                     return Object.keys(current.players);
                 },
+                nowMs: nowMs ?? Date.now(),
                 setSnapshot(next) {
                     current = next;
                 },
@@ -59,7 +62,7 @@ export function createGameRuntime(definition) {
             loop.onTick(ctx, dtSeconds);
             return current;
         },
-        joinPlayer(snapshot, userId, isNew) {
+        joinPlayer(snapshot, userId, isNew, nowMs) {
             const players = { ...snapshot.players };
             if (!players[userId]) {
                 players[userId] = createEmptyPlayerRow(userId);
@@ -84,6 +87,7 @@ export function createGameRuntime(definition) {
                     return next;
                 },
                 player: { userId, isNew },
+                nowMs: nowMs ?? Date.now(),
                 setSnapshot(updated) {
                     next = updated;
                 },
@@ -104,3 +108,12 @@ export function createGameRuntime(definition) {
         },
     };
 }
+/** Seed a fresh player through the same onNewPlayer hook as joining, without hydrating or modifying a world. */
+export function initialPlayerState(runtime, userId, nowMs = Date.now()) {
+    const snapshot = createRuntimeSnapshot({ gameId: runtime.gameId, serverId: "" });
+    const initialized = runtime.joinPlayer(snapshot, userId, true, nowMs);
+    const player = initialized.players[userId];
+    if (!player)
+        throw new Error(`onNewPlayer removed player "${userId}"`);
+    return structuredClone(player);
+}

package/dist/runtime/headlessRunner.d.ts

@@ -3,6 +3,7 @@ import type { PointerAxisState } from "../input/pointerAxis.js";
 import type { ModelAssetRef } from "../scene/assetCatalog.js";
 import { type GameContext, type GameContextContent, type GameContextModels } from "./gameContext.js";
 import type { InputSnapshot } from "./inputSnapshot.js";
+import { type SimSnapshot } from "./simSnapshot.js";
 /** One step's worth of player intent handed to {@link HeadlessRunner.step} — the held-action set and pointer state the shell would otherwise publish from the browser each frame. */
 export interface HeadlessInput {
     /** Replaces the held-action set for this step; edge detection (`justPressed`/`justReleased`) rolls the previous set forward. Omit to keep the last published set. */
@@ -31,8 +32,12 @@ export interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultipl
      * `onTick` and don't need it.
      */
     playerMovement?: boolean;
+    /** Movement tuning — when `playerMovement` is on, the shell resolves from `definition.world`/`physics`; pass a direct config to test flight or other movement overrides headlessly. */
+    movement?: import("../game/playableGame.js").PlayerMovementConfig;
     /** Yaw heading (radians) fed to the movement controller when `playerMovement` is on; the shell supplies its camera yaw. */
     heading?: number;
+    /** Pitch (radians) fed alongside yaw for 6DOF spectator flight when `alignWithLook` is set. */
+    pitch?: number;
     /** Render-model lookup for collider auto-fit — pass what the shell would derive from `entityModels`/`objectModels` so headless raycasts hit the same boxes as play. */
     models?: GameContextModels;
 }
@@ -71,5 +76,10 @@ export interface HeadlessRunner {
     publishInput(input: HeadlessInput): void;
     /** Drive the game's own UI commands / intents headlessly — the same registry `ctx.game.commands` and the shell's command sink dispatch into. No renderer, no pointer simulation: dispatch an intent, then read reactive state off `ctx`. */
     readonly ui: HeadlessCommandInterface;
+    /** Capture the whole simulation (world, clock, loop, rng cursor) for {@link restore}; with a fixed `simulation.hz` and recorded input, replaying from it reproduces the run exactly. */
+    snapshot(): SimSnapshot;
+    restore(snapshot: SimSnapshot): void;
+    /** Current simulation tick (`ctx.sim.tick()`). */
+    tick(): number;
 }
 export declare function createHeadlessRunner<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HeadlessRunnerOptions<TAssetRef, TMultiplayer>): HeadlessRunner;