@jgengine/core 0.18.0 → 0.19.0

package/dist/editor/environment.d.ts

@@ -3,6 +3,7 @@ import type { AvoidZone } from "../world/geometry.js";
 import { type ClearanceOptions } from "../world/scatterRegion.js";
 import type { TerraformSnapshot } from "../world/terraform.js";
 import type { EditorDocument, EditorEnvironment } from "./types.js";
+import type { LightingConfig } from "../game/playableGame.js";
 /**
  * World-authoring convergence (#1018, epic #1006 Phase 4): derive the **coordinate/placement**
  * content of an `environment()` world from the scene document, so a game with an authored document
@@ -46,6 +47,8 @@ export declare function skyFromDocument(doc: EditorDocument): SkyEnvironmentConf
  * @internal
  */
 export declare function skyConfigFromEnvironment(env: EditorEnvironment): SkyEnvironmentConfig;
+/** Converts authored `light` markers into the runtime lighting contract. */
+export declare function lightingFromDocument(doc: EditorDocument): LightingConfig | undefined;
 /**
  * The origin-centered terrain footprint that covers every authored object in a document, padded and
  * floored to `minBounds`. An empty document yields exactly `minBounds`. Because `environment()`

package/dist/editor/environment.js

@@ -25,9 +25,33 @@ export function skyConfigFromEnvironment(env) {
         ...(env.zenithColor === undefined ? {} : { zenithColor: env.zenithColor }),
         ...(env.sunIntensity === undefined ? {} : { sunIntensity: env.sunIntensity }),
         ...(env.ambientIntensity === undefined ? {} : { ambientIntensity: env.ambientIntensity }),
+        ...(env.sunAzimuth === undefined && env.sunElevation === undefined
+            ? {}
+            : {
+                sun: {
+                    ...(env.sunAzimuth === undefined ? {} : { azimuth: env.sunAzimuth }),
+                    ...(env.sunElevation === undefined ? {} : { elevation: env.sunElevation }),
+                },
+            }),
         ...(env.fog === undefined ? {} : { fog: { ...env.fog } }),
     };
 }
+/** Converts authored `light` markers into the runtime lighting contract. */
+export function lightingFromDocument(doc) {
+    const points = [];
+    const spots = [];
+    for (const marker of doc.markers) {
+        if (marker.kind !== "light" || marker.position === undefined)
+            continue;
+        const meta = marker.meta ?? {};
+        const base = { position: [marker.position.x, marker.position.y, marker.position.z], color: typeof meta.color === "string" ? meta.color : "#ffd6a0", intensity: typeof meta.intensity === "number" ? meta.intensity : 2, distance: typeof meta.range === "number" ? meta.range : 12, castShadow: meta.castShadow === true };
+        if (meta.type === "spot")
+            spots.push({ ...base, angle: typeof meta.angle === "number" ? meta.angle : Math.PI / 6 });
+        else
+            points.push(base);
+    }
+    return points.length === 0 && spots.length === 0 ? undefined : { point: points, spot: spots };
+}
 /**
  * The origin-centered terrain footprint that covers every authored object in a document, padded and
  * floored to `minBounds`. An empty document yields exactly `minBounds`. Because `environment()`

package/dist/editor/index.d.ts

@@ -5,7 +5,9 @@ export type { EditorTerrain } from "./types.js";
 /** A baked top-down minimap (PNG data URI + world bounds) persisted on the scene document. */
 export type { EditorMinimapBake } from "./types.js";
 /** Scene-document sky/fog/lighting bag edited by the lighting workspace. */
-export type { EditorEnvironment, EditorFogConfig, EditorSkyPreset } from "./types.js";
+export type { EditorEnvironment, EditorFogConfig, EditorSkyPreset, PointLightingConfig } from "./types.js";
+/** Declarative HDRI, cube, or gradient environment source used by the shell. */
+export type { EnvironmentSource } from "../render/environment.js";
 /** Per-kind show/hide flags for the editor's layer panel. */
 export type { EditorKindVisibility } from "./types.js";
 /** The four placeable-object collections a prefab fragment or clipboard fragment carries. */
@@ -62,7 +64,7 @@ export { WORLD_BASE_SHARD_ID, WORLD_MANIFEST_KIND, decodeWorldManifest, exportWo
 export type { DecodeWorldManifestResult, SplitWorldOptions, SplitWorldResult, WorldGrid, WorldManifest, WorldManifestShard, WorldQuery, WorldShardBounds, WorldShardResidency, WorldShardResolver, WorldStreamingConfig, } from "./world.js";
 /** Result of {@link decodeEditorDocument}: a typed document, or every diagnostic collected while decoding it. */
 export type { DecodeEditorDocumentResult } from "./document.js";
-export { environmentContentFromDocument, skyConfigFromEnvironment, skyFromDocument, terrainBoundsFromDocument, } from "./environment.js";
+export { environmentContentFromDocument, lightingFromDocument, skyConfigFromEnvironment, skyFromDocument, terrainBoundsFromDocument, } from "./environment.js";
 /** Coordinate/placement content of an `environment()` world derived from the scene document. */
 export type { EnvironmentContent, EnvironmentContentOptions } from "./environment.js";
 export { bakeMinimapFromDocument, documentBakeZones } from "./minimap.js";

package/dist/editor/index.js

@@ -3,7 +3,7 @@ export { ENTITY_CATALOG_ID, entityDefinitionSchema, entityEntryFromCatalog, reso
 export { WELL_KNOWN_MARKER_KINDS, WELL_KNOWN_PATH_KINDS, WELL_KNOWN_VOLUME_KINDS, } from "./types.js";
 export { applyEditorDocumentOverlay, cloneEditorDocument, collectDescendants, createEmptyEditorDocument, createPrefabFragment, decodeEditorDocument, editorChildren, editorDocumentBounds, editorDocumentExtras, editorDocumentSize, editorMarkerPosition, editorMarkerXZ, editorParentOf, editorRoots, exportEditorDocumentJson, extractEditorFragment, findEditorCatalog, findEditorCatalogEntry, findEditorCollection, findEditorMarker, findEditorNote, findEditorPath, findEditorPrefab, findEditorVolume, importEditorDocumentJson, isEditorObjectCollectionLocked, isEditorObjectHidden, isEditorObjectLocked, isEditorObjectSelfLocked, listEditorKinds, mergeEditorDocuments, normalizeEditorLayers, requireEditorMarker, seedEditorCatalogs, wouldCreateCycle, } from "./document.js";
 export { WORLD_BASE_SHARD_ID, WORLD_MANIFEST_KIND, decodeWorldManifest, exportWorldManifestJson, loadWorldDocument, selectWorldShards, shardMatchesQuery, singleShardWorldManifest, splitEditorDocumentIntoShards, } from "./world.js";
-export { environmentContentFromDocument, skyConfigFromEnvironment, skyFromDocument, terrainBoundsFromDocument, } from "./environment.js";
+export { environmentContentFromDocument, lightingFromDocument, skyConfigFromEnvironment, skyFromDocument, terrainBoundsFromDocument, } from "./environment.js";
 export { bakeMinimapFromDocument, documentBakeZones } from "./minimap.js";
 export { createWorldStreamer, shardDistance } from "./streamer.js";
 export { applyDirectiveOverlay, materializeDirective, materializeDirectives, materializePopulationDirective, materializeScatterDirective, resolveDirectiveFootprint, } from "./directives.js";

package/dist/editor/types.d.ts

@@ -3,6 +3,10 @@ import type { EditorUiDocument } from "../ui/hudDocument.js";
 import type { MinimapBakeBounds } from "../world/minimapBake.js";
 import type { TerraformSnapshot } from "../world/terraform.js";
 import type { EditorGridLayer } from "./grid.js";
+import type { EnvironmentSource } from "../render/environment.js";
+import type { PointLightingConfig } from "../game/playableGame.js";
+/** Runtime point-light shape reused by authored editor light markers. */
+export type { PointLightingConfig } from "../game/playableGame.js";
 export type { EditorUiDocument, EditorUiPanelLayout, HudResizeAxes, HudPanelTypeDef } from "../ui/hudDocument.js";
 /** A world-space point used across editor markers, volumes, and paths. */
 export type EditorVec3 = {
@@ -177,6 +181,12 @@ export interface EditorMinimapBake {
     /** World-space rectangle the baked image spans. */
     bounds: MinimapBakeBounds;
 }
+/** A named baked artifact produced by an editor or build tool. */
+export interface EditorBake {
+    kind: "nav" | "minimap";
+    id: string;
+    data: unknown;
+}
 /** Named sky look stored on the scene document; matches runtime `SkyEnvironmentConfig.preset`. */
 export type EditorSkyPreset = "day" | "dusk" | "night";
 /**
@@ -197,6 +207,10 @@ export interface EditorFogConfig {
  * @capability editor-environment persist sky/fog/lighting knobs on the scene document
  */
 export interface EditorEnvironment {
+    /** Optional runtime environment map source; absent keeps the procedural gradient. */
+    source?: EnvironmentSource;
+    /** Authored local point lights; the runtime clamps these to its bounded light budget. */
+    pointLights?: readonly PointLightingConfig[];
     /** Fixed sky look when `timeOfDay` is off (or no clock is available). */
     preset?: EditorSkyPreset;
     /** Drive sun/sky from the world clock's day fraction instead of the fixed `preset`. */
@@ -205,6 +219,10 @@ export interface EditorEnvironment {
     zenithColor?: string;
     sunIntensity?: number;
     ambientIntensity?: number;
+    /** Sun compass bearing in degrees (0 = -Z, 90 = +X); runtime `SkySunConfig.azimuth`. */
+    sunAzimuth?: number;
+    /** Sun height above the horizon in degrees; runtime `SkySunConfig.elevation`. */
+    sunElevation?: number;
     fog?: EditorFogConfig;
 }
 /** The full authored scene: every marker, volume, path, note, and sculpted terrain for a game. */
@@ -246,6 +264,8 @@ export interface EditorDocument {
      * until baked, so old docs and unbaked games load unchanged.
      */
     minimap?: EditorMinimapBake;
+    /** Named baked artifacts; `minimap` remains as a compatible legacy alias. */
+    bakes?: EditorBake[];
     /**
      * Scene-document sky/fog/lighting (#1110). Absent until authored in the lighting workspace or
      * seeded via `editorLayers`, so old docs load unchanged and world.ts can keep a fallback sky.

package/dist/faction/reputation.d.ts

@@ -17,6 +17,10 @@ export interface ReputationLedgerConfig {
     min?: number;
     max?: number;
 }
+/** Plain JSON standings of a {@link ReputationLedger}: stored values only, `initial` stays config. */
+export interface ReputationLedgerState {
+    records: Record<string, Record<string, number>>;
+}
 export interface ReputationLedger {
     standing(actorId: string, factionId: string): number;
     hasStanding(actorId: string, factionId: string): boolean;
@@ -26,6 +30,8 @@ export interface ReputationLedger {
     relation(actorId: string, factionId: string): FactionRelation;
     standings(actorId: string): Record<string, number>;
     reset(actorId: string, factionId?: string): void;
+    snapshot(): ReputationLedgerState;
+    restore(next: ReputationLedgerState): void;
 }
 export declare function createReputationLedger(config?: ReputationLedgerConfig): ReputationLedger;
 export interface EffectiveRelationInput {

package/dist/faction/reputation.js

@@ -77,6 +77,17 @@ export function createReputationLedger(config = {}) {
             else
                 records.get(actorId)?.delete(factionId);
         },
+        snapshot() {
+            const out = {};
+            for (const [actorId, row] of records)
+                out[actorId] = Object.fromEntries(row);
+            return { records: out };
+        },
+        restore(next) {
+            records.clear();
+            for (const [actorId, row] of Object.entries(next.records))
+                records.set(actorId, new Map(Object.entries(row)));
+        },
     };
 }
 export function effectiveRelation(input) {

package/dist/game/cameraConfig.d.ts

@@ -1,3 +1,5 @@
+import type { WeaponHandlingFrame } from "../combat/weaponHandling.js";
+import type { WeaponPresentationTuning } from "../combat/weaponPresentation.js";
 export interface CameraFollowState {
     entityId: string;
     target: {
@@ -12,6 +14,11 @@ export interface CameraFollowState {
     };
     distance: number;
 }
+/** What a camera rig reads about the held weapon each frame; see `GameCameraConfig.weapon`. */
+export interface CameraWeaponView {
+    handling: WeaponHandlingFrame;
+    presentation?: WeaponPresentationTuning;
+}
 export interface FirstPersonCameraConfig {
     /** Camera height above the followed entity's origin. Default 1.6. */
     eyeHeight?: number;
@@ -45,6 +52,12 @@ export interface FirstPersonCameraConfig {
 export type CameraRigKind = "orbit" | "first" | "topDown" | "rts" | "shoulder" | "lockOn" | "chase" | "observer" | "turntable" | "sideScroll" | "inspection" | "none";
 /** Canvas camera projection. "orthographic" renders a flat 2D-style view (side-scrollers, falling-block puzzles) — pair with `rig: "sideScroll"`; default "perspective". */
 export type CameraProjection = "perspective" | "orthographic";
+/** Pixel-art orthographic camera tuning. `pixelsPerUnit` is the authored pixel density. */
+export interface PixelPerfectCameraConfig {
+    pixelsPerUnit: number;
+    /** Increase density in whole-number steps to use the largest scale that fits the viewport. */
+    integerScale?: boolean;
+}
 /** Fixed lateral 2.5D follow (side-on platformer cam): the camera sits perpendicular to the travel axis, tracks the followed entity, and never reads player look input. */
 export interface SideScrollCameraConfig {
     /** World axis the action travels along; the camera watches from the perpendicular side. Default "x". */
@@ -164,11 +177,47 @@ export interface ChaseCameraConfig {
     lookHeight?: number;
     /** Spring-arm damping (higher = stiffer, less lag). Default 6. */
     springDamping?: number;
-    /** Speed→FOV curve: FOV lerps from `base` to `max` as speed climbs to `speedForMax`. */
+    /**
+     * Speed→FOV curve: FOV lerps from `base` to `max` as speed climbs to `speedForMax`. Speed is the
+     * followed entity's sim `velocity` when it publishes one. `response` (default 6) eases the FOV
+     * toward the curve with `1-exp(-response*dt)`; `Infinity` applies it unsmoothed.
+     */
     fov?: {
         base?: number;
         max?: number;
         speedForMax?: number;
+        response?: number;
+    };
+    /** Pull the boom back by up to `extra` world units as speed climbs to `speedForMax` (default the FOV curve's `speedForMax`). */
+    distanceBySpeed?: {
+        extra: number;
+        speedForMax?: number;
+    };
+    /**
+     * Tilt the boom with the target's body pitch (`rotationX`) so the camera stays behind it on
+     * slopes and ramps. `blend` (default 1) is the fraction of the pitch followed, clamped to `max`
+     * radians (default 0.6) and eased by `response` (default 5). Omit the block to keep a level boom.
+     */
+    pitchFollow?: {
+        blend?: number;
+        max?: number;
+        response?: number;
+    };
+    /** How `ctx.camera.kickFov(degrees)` impulses feel: the kick decays at `decay` per second (default 7) and the summed kick is clamped to `max` degrees (default 20). */
+    fovKick?: {
+        decay?: number;
+        max?: number;
+    };
+    /** Input action that, while held, swings the chase view to look back at what is behind the target. */
+    lookBackAction?: string;
+    /**
+     * Pull the boom in past scene colliders, objects, terrain and walls via `ctx.scene.raycast`
+     * (entities never block). `radius` (default 0.3) keeps the lens off the surface; `minDistance`
+     * (default 0.8) is the closest the camera gets to the look pivot. Default on; `false` disables.
+     */
+    collision?: boolean | {
+        radius?: number;
+        minDistance?: number;
     };
     /** Procedural shake amplitude per unit of speed (adds to the trauma channel). Default 0.0. */
     shakePerSpeed?: number;
@@ -378,6 +427,8 @@ export interface GameCameraConfig {
     rig?: CameraRigKind;
     /** Canvas camera projection. "orthographic" renders a flat 2D-style view (side-scrollers, falling-block puzzles) — pair with `rig: "sideScroll"`; default perspective. */
     projection?: CameraProjection;
+    /** Pixel-perfect orthographic rendering; ignored for perspective cameras. */
+    pixelPerfect?: PixelPerfectCameraConfig;
     /** Render frustum overrides applied to the canvas camera. `far` defaults to 300 — raise it for worlds whose content spans more than a few hundred units, or distant scenery silently clips. `zoom` is the orthographic zoom in canvas pixels per world unit, read only when `projection` is "orthographic"; default 50. */
     frustum?: {
         fov?: number;
@@ -438,6 +489,13 @@ export interface GameCameraConfig {
     followEntityId?: string | null;
     /** Fired each frame after cameraFollow lock is applied. */
     onCameraFollow?: (state: CameraFollowState) => void;
+    /**
+     * The followed entity's held weapon, read every frame by the `first` and `shoulder` rigs. Return the
+     * weapon's `createWeaponHandling` frame and its presentation tuning, or `null` for none. First person
+     * poses the viewmodel from it (offset, ADS pose, viewmodel FOV, sway, bob, kick) and adds the recoil to
+     * the look; over-the-shoulder takes its ADS blend from `adsProgress` and adds the same recoil.
+     */
+    weapon?: (entityId: string) => CameraWeaponView | null;
     rotateSpeed?: number;
     zoomSpeed?: number;
     dampingFactor?: number;

package/dist/game/chat.d.ts

@@ -30,11 +30,18 @@ export type ChatSendResult = {
 export interface ChatSnapshot {
     messages: Record<string, ChatMessage[]>;
     counter: number;
+    rateWindows?: Record<string, Record<string, number[]>>;
 }
 export interface Chat {
     register(def: ChatChannelDef): void;
     channels(): ChatChannelDef[];
+    send(fromUserId: string, body: string): ChatSendResult;
     send(fromUserId: string, channelId: string, body: string): ChatSendResult;
+    recent(options?: {
+        limit?: number;
+        channelId?: string;
+        viewerUserId?: string;
+    }): ChatMessage[];
     whisper(fromUserId: string, toUserId: string, body: string): ChatSendResult;
     history(channelId: string, options?: {
         limit?: number;
@@ -57,12 +64,26 @@ export interface ChatDeps {
 }
 export declare const DEFAULT_CHAT_RATE_LIMIT: ChatRateLimit;
 export declare const DEFAULT_CHAT_HISTORY_LIMIT = 100;
-export declare const DEFAULT_CHAT_BODY_LENGTH = 500;
+export declare const DEFAULT_CHAT_BODY_LENGTH = 240;
 export declare const DEFAULT_PROXIMITY_CHAT_RADIUS = 20;
 export declare const WHISPER_CHANNEL_PREFIX = "whisper:";
 export declare function whisperChannelId(a: string, b: string): string;
 export interface ChatRateLimiter {
     allow(key: string, atMs: number): boolean;
+    snapshot(): Record<string, number[]>;
+    restore(state: Record<string, number[]>): void;
 }
 export declare function createChatRateLimiter(limit: ChatRateLimit): ChatRateLimiter;
 export declare function createChat(deps: ChatDeps): Chat;
+/** Sanitized chat text or a displayable validation failure. */
+export type ChatValidation = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Strip control characters and enforce the shared chat message policy before storage or broadcast. */
+export declare function validateChatMessage(value: unknown, options?: {
+    maxLength?: number;
+}): ChatValidation;

package/dist/game/chat.js

@@ -1,6 +1,7 @@
-export const DEFAULT_CHAT_RATE_LIMIT = { count: 10, perMs: 10_000 };
+import { decideRateWindow } from "../time/rateWindow.js";
+export const DEFAULT_CHAT_RATE_LIMIT = { count: 1, perMs: 2_000 };
 export const DEFAULT_CHAT_HISTORY_LIMIT = 100;
-export const DEFAULT_CHAT_BODY_LENGTH = 500;
+export const DEFAULT_CHAT_BODY_LENGTH = 240;
 export const DEFAULT_PROXIMITY_CHAT_RADIUS = 20;
 export const WHISPER_CHANNEL_PREFIX = "whisper:";
 export function whisperChannelId(a, b) {
@@ -11,15 +12,17 @@ export function createChatRateLimiter(limit) {
     const windows = new Map();
     return {
         allow(key, atMs) {
-            const cutoff = atMs - limit.perMs;
-            const stamps = (windows.get(key) ?? []).filter((stamp) => stamp > cutoff);
-            if (stamps.length >= limit.count) {
-                windows.set(key, stamps);
-                return false;
-            }
-            stamps.push(atMs);
-            windows.set(key, stamps);
-            return true;
+            const result = decideRateWindow(windows.get(key) ?? [], atMs, { windowMs: limit.perMs, max: limit.count });
+            windows.set(key, result.timestamps);
+            return result.allowed;
+        },
+        snapshot() {
+            return Object.fromEntries(Array.from(windows, ([key, stamps]) => [key, [...stamps]]));
+        },
+        restore(state) {
+            windows.clear();
+            for (const [key, stamps] of Object.entries(state))
+                windows.set(key, [...stamps]);
         },
     };
 }
@@ -93,11 +96,10 @@ export function createChat(deps) {
         messagesByChannel.set(channelId, ring);
     }
     function sendResolved(fromUserId, channelId, body, def) {
-        const trimmed = body.trim();
-        if (trimmed.length === 0)
-            return { reason: "empty message" };
-        if (trimmed.length > maxBodyLength)
-            return { reason: "message too long" };
+        const validation = validateChatMessage(body, { maxLength: maxBodyLength });
+        if (!validation.ok)
+            return { reason: validation.reason };
+        const trimmed = validation.text;
         let filteredBody = trimmed;
         if (filter !== undefined) {
             const filtered = filter.apply(trimmed);
@@ -136,10 +138,18 @@ export function createChat(deps) {
         channels() {
             return Array.from(channelDefs.values(), (def) => ({ ...def }));
         },
-        send(fromUserId, channelId, body) {
+        send(fromUserId, channelOrBody, suppliedBody) {
+            const channelId = suppliedBody === undefined ? "global" : channelOrBody;
+            const body = suppliedBody ?? channelOrBody;
             const def = channelDefs.get(channelId) ?? null;
             return sendResolved(fromUserId, channelId, body, def);
         },
+        recent(options) {
+            return this.history(options?.channelId ?? "global", {
+                limit: Math.max(0, Math.min(100, Math.floor(options?.limit ?? 50) || 0)),
+                viewerUserId: options?.viewerUserId,
+            });
+        },
         whisper(fromUserId, toUserId, body) {
             if (fromUserId === toUserId)
                 return { reason: "cannot whisper yourself" };
@@ -153,14 +163,15 @@ export function createChat(deps) {
                 ? ring
                 : ring.filter((message) => !hasBlocked(viewerUserId, message.fromUserId));
             const limit = options?.limit;
-            return limit === undefined ? visible.slice() : visible.slice(-limit);
+            return limit === undefined ? visible.slice() : limit <= 0 ? [] : visible.slice(-limit);
         },
         snapshot() {
             const messages = {};
             for (const [channelId, ring] of messagesByChannel) {
                 messages[channelId] = ring.map((message) => ({ ...message }));
             }
-            return { messages, counter };
+            const rateWindows = Object.fromEntries(Array.from(limiters, ([id, limiter]) => [id, limiter.snapshot()]));
+            return { messages, counter, rateWindows };
         },
         hydrate(data) {
             messagesByChannel.clear();
@@ -168,6 +179,24 @@ export function createChat(deps) {
                 messagesByChannel.set(channelId, ring.map((message) => ({ ...message })));
             }
             counter = data.counter;
+            limiters.clear();
+            for (const [channelId, state] of Object.entries(data.rateWindows ?? {})) {
+                limiterFor(channelId, channelDefs.get(channelId)?.rateLimit ?? defaultRateLimit).restore(state);
+            }
         },
     };
 }
+/** Strip control characters and enforce the shared chat message policy before storage or broadcast. */
+export function validateChatMessage(value, options = {}) {
+    const maxLength = options.maxLength ?? DEFAULT_CHAT_BODY_LENGTH;
+    if (!Number.isSafeInteger(maxLength) || maxLength < 1)
+        throw new RangeError("Invalid chat length limit");
+    if (typeof value !== "string")
+        return { ok: false, reason: "invalid message" };
+    const text = value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").trim();
+    if (!text.length)
+        return { ok: false, reason: "empty message" };
+    if (text.length > maxLength)
+        return { ok: false, reason: "message too long" };
+    return { ok: true, text };
+}

package/dist/game/controlGate.d.ts

@@ -1,4 +1,10 @@
 import type { GameContext } from "../runtime/gameContext.js";
+import { type ActionContextStack } from "../input/actionContexts.js";
+import type { ActionCodesMap } from "../input/actionBindings.js";
 export declare const PLAY_CONTROLS_STORE_KEY = "jg.playControls";
+/** Returns the context stack associated with a game context. */
+export declare function actionContextStack(ctx: GameContext): ActionContextStack;
+/** Applies active contexts to a base action map for shell input tracking. */
+export declare function activeActionCodes(ctx: GameContext, base: ActionCodesMap): ActionCodesMap;
 export declare function setPlayControlsActive(ctx: GameContext, active: boolean): void;
 export declare function playControlsActive(ctx: GameContext): boolean;

package/dist/game/controlGate.js

@@ -1,7 +1,36 @@
+import { createActionContextStack } from "../input/actionContexts.js";
 export const PLAY_CONTROLS_STORE_KEY = "jg.playControls";
+const ACTION_CONTEXTS = new WeakMap();
+function contextsFor(ctx) {
+    let stack = ACTION_CONTEXTS.get(ctx);
+    if (stack === undefined) {
+        stack = createActionContextStack();
+        ACTION_CONTEXTS.set(ctx, stack);
+    }
+    return stack;
+}
+/** Returns the context stack associated with a game context. */
+export function actionContextStack(ctx) {
+    return contextsFor(ctx);
+}
+/** Applies active contexts to a base action map for shell input tracking. */
+export function activeActionCodes(ctx, base) {
+    const stack = contextsFor(ctx);
+    const layered = createActionContextStack();
+    layered.push({ id: "__jg_base_actions", codes: base, passthrough: true });
+    for (const context of stack.snapshot().contexts)
+        layered.push(context);
+    return layered.active();
+}
 export function setPlayControlsActive(ctx, active) {
+    const stack = contextsFor(ctx);
+    if (active)
+        stack.pop("menu");
+    else
+        stack.push({ id: "menu", codes: {}, passthrough: false });
     ctx.game.store.set(PLAY_CONTROLS_STORE_KEY, active);
 }
 export function playControlsActive(ctx) {
-    return ctx.game.store.get(PLAY_CONTROLS_STORE_KEY) !== false;
+    return ctx.game.store.get(PLAY_CONTROLS_STORE_KEY) !== false &&
+        !actionContextStack(ctx).snapshot().contexts.some((context) => context.id === "menu");
 }

package/dist/game/defineGame.d.ts

@@ -12,7 +12,10 @@ import { type AssetCatalog, type ModelAssetRef } from "../scene/assetCatalog.js"
 import { type EntityStore } from "../scene/entityStore.js";
 import type { StoreHandle } from "../store/defineStore.js";
 import type { TimeConfig } from "../time/simClock.js";
+import type { SimulationConfig } from "../runtime/simLoop.js";
 import type { WorldFeature } from "../world/features.js";
+import type { PhysicsBackend } from "../physics/physicsBackend.js";
+import type { CharacterControllerConfig } from "../movement/characterController.js";
 /** Tunes offline whole-world save (`defineGameDefinition({ persist })`). Offline games already autosave to `localStorage` by default — pass this only to tune it (or `persist: false` to opt out). Defaults: continuous `autosave` to `localStorage`, one slot, no version. */
 export interface PersistConfig {
     /** `"autosave"` (default) writes on a trailing timer while the world changes — at most once per `autosaveMs`, so a never-idle world (AI, physics, day/night) still persists; `"manual"` writes only on `ctx.game.save.checkpoint()` (save points / quest triggers). */
@@ -24,10 +27,14 @@ export interface PersistConfig {
     /** Autosave debounce in ms (autosave mode). Default 3000. */
     autosaveMs?: number;
 }
-/** World gravity and jump tuning, plus scene-object collision opt-ins, for the game's physics step. */
+/** World gravity and jump tuning, plus the optional rigid-body backend and character capsule. */
 export interface PhysicsConfig {
     gravity?: number;
     jumpVelocity?: number;
+    /** Physics solver used by the shell movement controller and the context's physics stage. */
+    backend?: PhysicsBackend;
+    /** Capsule dimensions for players using the configured physics backend. */
+    controller?: CharacterControllerConfig;
     /** Opt placed scene objects into projectile raycasts as blocking cover AABBs. Default false — enabling changes where shots land. */
     projectileObstacles?: boolean;
 }
@@ -180,6 +187,8 @@ export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef,
     physics?: PhysicsConfig;
     /** Simulation clock: real→game time scale, selectable speeds, calendar. Exposed as `ctx.time`; the shell feeds its scaled dt to `loop.onTick`. */
     time?: TimeConfig;
+    /** How the simulation is stepped — a fixed `hz` with render interpolation, or `"variable"` (default) once per frame. Exposed as `ctx.sim`. */
+    simulation?: SimulationConfig;
     /** Per-action ring-buffer capacity for `ctx.game.feed`. Default 20. */
     feed?: GameFeedOptions;
     inventories?: Record<string, InventoryDeclaration>;

package/dist/game/events.d.ts

@@ -12,11 +12,17 @@ export interface EntityDiedEvent {
     position: [number, number, number];
     serverId?: string;
 }
-/** Request that an entity's rig play a one-shot animation clip bound to `event` in its `animation.oneShots` (e.g. an "attack" swing); the shell resolves the clip and plays it once over the locomotion state. */
+/** Request that an entity's rig play a one-shot animation clip bound to `event` in its `animation.oneShots` (e.g. an "attack" swing); the shell resolves the clip and plays it once over the locomotion state. With an `animation.graph`, `event` arms the trigger of that name. */
 export interface EntityAnimationEvent {
     instanceId: string;
     event: string;
 }
+/** A named clip moment (`AnimGraph.events`) the rig just crossed — foot plant, hit frame, reload point. Audio and combat listen by `name`. */
+export interface AnimationClipEvent {
+    instanceId: string;
+    name: string;
+    clip: string;
+}
 /**
  * One granted reward: an inventory `item` id or a `currency` id, plus how many. Named because every
  * consumer of `loot.granted` needs it — a toast renderer, a loot log, a session summary — and each
@@ -230,6 +236,12 @@ export interface AudioLoopSetEvent {
     rate?: number;
     gain?: number;
     at?: readonly [number, number, number];
+    /** Emitter velocity (world units/s) for doppler on sounds that declare `doppler`. */
+    velocity?: readonly [number, number, number];
+    /** Lowpass cutoff in Hz. */
+    lowpass?: number;
+    /** Highpass cutoff in Hz. */
+    highpass?: number;
 }
 /** Stop and dispose the retained loop `id`; an unknown `id` is ignored (#1051). */
 export interface AudioLoopStopEvent {
@@ -269,6 +281,7 @@ export interface GameEventMap {
     "audio.loopSet": AudioLoopSetEvent;
     "audio.loopStop": AudioLoopStopEvent;
     "entity.animation": EntityAnimationEvent;
+    "animation.event": AnimationClipEvent;
 }
 export type GameEventHandler<TPayload> = (payload: TPayload) => void;
 export interface GameEvents<TMap extends GameEventMap = GameEventMap> {

package/dist/game/lootTable.d.ts

@@ -38,6 +38,10 @@ export interface LootRegistry {
     register(def: LootTableDef): void;
     has(id: string): boolean;
     roll(id: string, rng?: () => number): Drop[];
+    /** Registered tables in registration order; plain JSON unless an entry uses `generate`. */
+    snapshot(): LootTableDef[];
+    /** Replaces every registered table with `next`, validating each. */
+    restore(next: readonly LootTableDef[]): void;
 }
 /** Options for {@link createLootRegistry} — inject a default RNG so bare `roll(id)` uses the world stream. */
 export interface LootRegistryOptions {

package/dist/game/lootTable.js

@@ -1,4 +1,10 @@
 import { resolveRng } from "../random/resolveRng.js";
+function copyDef(def) {
+    return {
+        ...def,
+        entries: def.entries.map((entry) => ({ ...entry, count: typeof entry.count === "number" ? entry.count : [entry.count[0], entry.count[1]] })),
+    };
+}
 function assertValidEntry(entry, mode) {
     const kinds = [entry.item !== undefined, entry.currency !== undefined, entry.generate !== undefined].filter(Boolean).length;
     if (kinds !== 1) {
@@ -88,6 +94,16 @@ export function createLootRegistry(options = {}) {
             }
             return drops;
         },
+        snapshot() {
+            return [...tables.values()].map(copyDef);
+        },
+        restore(next) {
+            for (const def of next)
+                assertValidDef(def);
+            tables.clear();
+            for (const def of next)
+                tables.set(def.id, copyDef(def));
+        },
     };
 }
 /**

package/dist/game/pixelPerfect.d.ts

@@ -0,0 +1,25 @@
+/** Viewport dimensions in device-independent canvas pixels. */
+export interface PixelPerfectViewport {
+    width: number;
+    height: number;
+}
+/** The orthographic bounds and scale derived from a pixel-perfect camera config. */
+export interface PixelPerfectFrustum {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    zoom: number;
+    scale: number;
+}
+/**
+ * Computes an orthographic frustum whose world units map to the requested pixel density.
+ * Integer scaling chooses the largest whole-number density multiplier available in the viewport.
+ */
+export declare function pixelPerfectFrustum(viewport: PixelPerfectViewport, pixelsPerUnit: number, integerScale?: boolean): PixelPerfectFrustum;
+/** Snaps a camera position to the authored pixel grid without changing its orientation. */
+export declare function snapPixelPerfectPosition<T extends {
+    x: number;
+    y: number;
+    z: number;
+}>(position: T, pixelsPerUnit: number): T;