@jgengine/core 0.17.0 → 0.18.1

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
@@ -269,6 +275,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/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;

package/dist/game/pixelPerfect.js

@@ -0,0 +1,29 @@
+/**
+ * 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 function pixelPerfectFrustum(viewport, pixelsPerUnit, integerScale = false) {
+    const width = Math.max(1, viewport.width);
+    const height = Math.max(1, viewport.height);
+    const density = Math.max(1e-6, pixelsPerUnit);
+    const scale = integerScale ? Math.max(1, Math.floor(Math.min(width, height) / density)) : 1;
+    const zoom = density * scale;
+    return {
+        left: -width / (2 * zoom),
+        right: width / (2 * zoom),
+        top: height / (2 * zoom),
+        bottom: -height / (2 * zoom),
+        zoom,
+        scale,
+    };
+}
+/** Snaps a camera position to the authored pixel grid without changing its orientation. */
+export function snapPixelPerfectPosition(position, pixelsPerUnit) {
+    const density = Math.max(1e-6, pixelsPerUnit);
+    return {
+        ...position,
+        x: Math.round(position.x * density) / density,
+        y: Math.round(position.y * density) / density,
+        z: Math.round(position.z * density) / density,
+    };
+}

package/dist/game/playableGame.d.ts

@@ -1,14 +1,20 @@
+import type { AnimGraph } from "../anim/animGraph.js";
 import type { AudioBusDef, SoundDef } from "../audio/audioFalloff.js";
 import type { MusicTheme } from "../audio/music.js";
 import type { EditorCatalogDefinition, EditorDocument } from "../editor/types.js";
 import type { PostProcessingConfig } from "../render/postProcessing.js";
+import type { EnvironmentSource } from "../render/environment.js";
+import type { SpriteAtlas } from "../assets/spriteAtlas.js";
 import type { LookPreset } from "../render/lookPreset.js";
 import type { TouchControlsConfig } from "../input/touchScheme.js";
 import type { GameSettingsConfig } from "../settings/settingsModel.js";
+import type { GraphicsProfile } from "../settings/graphicsProfile.js";
 import type { GameOrientation } from "../ui/orientation.js";
 import type { HudPlatform, HudViewportConfig } from "../ui/hudScale.js";
 import type { PositionedPrompt } from "../interaction/proximityPrompt.js";
+import type { ChaseCameraTuning } from "../runtime/cameraDirector.js";
 import type { CatalogEntityRole, GameContext, GameContextContent } from "../runtime/gameContext.js";
+import type { FreeFlightBindings } from "../movement/freeFlight.js";
 import type { ModelDims } from "../scene/assetCatalog.js";
 import type { PartMotionParams, PartRole } from "./partAnimation.js";
 import type { CollisionMeshData } from "../scene/collisionMesh.js";
@@ -52,6 +58,11 @@ export interface EntitySpriteConfig {
     width: number;
     height: number;
     y: number;
+    /** Optional atlas-backed animation. The atlas image supersedes `url` when present. */
+    clip?: {
+        atlas: SpriteAtlas;
+        animation: string;
+    };
 }
 export interface WorldItemRenderConfig {
     /** Baseline rarity→color/beam/label render binding (#32); the game's rarity palette. */
@@ -119,6 +130,14 @@ export interface ModelAnimationConfig {
      * `string[]` picks a random variant per trigger. `death` clamps on its final frame instead of returning.
      */
     oneShots?: Record<string, string | readonly string[]>;
+    /**
+     * A full animation graph (`@jgengine/core/anim/animGraph`) — layered state machine with blend trees, data
+     * transitions, triggers, and clip events. Takes over from `states`/`oneShots` when set: the shell feeds the
+     * entity's smoothed ground speed as the `speed` parameter plus anything under the entity blackboard key
+     * `ANIM_PARAMS_KEY`, arms triggers from `entity.animation` (`hit` and `death` from their combat events), and
+     * emits `animation.event` for clip events. `locomotionGraph()` builds the default idle/walk/run graph.
+     */
+    graph?: AnimGraph;
 }
 /**
  * Real PBR map URLs (e.g. `buildMaterialCatalog(...).resolve(id)!.maps` from `@jgengine/assets`)
@@ -130,8 +149,11 @@ export interface ModelMaterialMaps {
     normal?: string;
     roughness?: string;
     ao?: string;
+    metalness?: string;
+    emissive?: string;
+    height?: string;
 }
-/** Per-entity PBR material override (#151.3) applied to every `MeshStandardMaterial` in the model's cloned scene graph. */
+/** Per-entity PBR material override (#151.3) applied to every standard or physical material in the model's cloned scene graph. */
 export interface ModelMaterialOverride {
     color?: string;
     metalness?: number;
@@ -203,6 +225,8 @@ export interface ModelConfig {
     collisionMesh?: CollisionMeshData;
     /** Per-entity PBR tint/finish override (#151.3); cloned onto each `MeshStandardMaterial` in the model so shared GLTF caches stay untouched. */
     material?: ModelMaterialOverride;
+    /** Shadow participation of every mesh in the model. Default `"both"` (casts and receives); `"none"` for foliage cards, decals, or viewmodels that must never shadow the world. */
+    shadows?: "cast" | "receive" | "both" | "none";
     /**
      * Plays a GLTF animation clip on the model when the source has any (skinned or not).
      * A model resolved from a catalog id whose index carries `clips` animates automatically —
@@ -212,6 +236,17 @@ export interface ModelConfig {
      * rig's bind pose.
      */
     animation?: ModelAnimationConfig | "auto" | "none";
+    /** Optional runtime inverse-kinematics targets for a rigged model. Bone names are resolved on the loaded scene. */
+    ik?: {
+        feet: readonly {
+            root: string;
+            mid: string;
+            tip: string;
+        }[];
+        lookAt?: {
+            bone: string;
+        };
+    };
     /** Props/weapons parented to named bones on this model's rig; each follows its bone through animation. */
     attachments?: readonly ModelAttachment[];
     /** Static kit-of-parts pieces stacked at fixed local offsets — no bone/rig involved. Use this for a compound entity assembled from several modular meshes (a castle keep from base + mid + roof pieces); use `attachments` for props parented to an animated rig's bones. Tag parts with a `role` to procedurally animate a rig-less character composition. */
@@ -255,10 +290,29 @@ export interface HemisphereLightingConfig {
     groundColor?: string;
     intensity?: number;
 }
+/** A bounded dynamic point light in world space. */
+export interface PointLightingConfig {
+    color?: string;
+    intensity?: number;
+    position: readonly [number, number, number];
+    distance?: number;
+    decay?: number;
+    castShadow?: boolean;
+}
+/** A bounded dynamic spot light in world space. */
+export interface SpotLightingConfig extends PointLightingConfig {
+    target?: readonly [number, number, number];
+    angle?: number;
+    penumbra?: number;
+}
 /** Declarative lighting replacing the shell's hardcoded ambient/directional default (#207.5); mounts regardless of world kind, only when supplied. */
 export interface LightingConfig {
     ambient?: AmbientLightingConfig;
     directional?: readonly DirectionalLightingConfig[];
+    point?: readonly PointLightingConfig[];
+    spot?: readonly SpotLightingConfig[];
+    /** Maximum dynamic point + spot lights mounted by the shell. Default 8. */
+    maxDynamicLights?: number;
     hemisphere?: HemisphereLightingConfig;
 }
 export interface BackdropFogConfig {
@@ -274,6 +328,33 @@ export interface BackdropConfig {
     sky?: SkyEnvironmentConfig;
     fog?: BackdropFogConfig;
 }
+/** Free-flight families moved into the walk controller so one seam covers ground + air — creative/spectator/noclip/hover are weightless, aircraft/rotorcraft stay on `flightDynamics`. */
+export interface FlightConfig {
+    /** Which free-flight family to use when flight is active. Default "creative". */
+    mode?: "creative" | "spectator" | "noclip" | "hover";
+    /** Horizontal base speed (units/s). Default 8. */
+    speed?: number;
+    /** Vertical base speed for ascend/descend. Default = `speed`. */
+    verticalSpeed?: number;
+    /** Sprint multiplier while shift is held. Default 1.8. */
+    sprintMultiplier?: number;
+    /** Lerp rate toward target velocity. Default 20. */
+    acceleration?: number;
+    /** Downward acceleration for hover mode. Default 0 (weightless). */
+    gravity?: number;
+    /** Upward thrust while ascending in hover. Default 32. */
+    thrust?: number;
+    /** When true, W moves along the look pitch (6DOF spectator). Default false. */
+    alignWithLook?: boolean;
+    /** Whether flight slides against world solids. Default true for creative/hover, false for spectator/noclip. */
+    collide?: boolean;
+    /** Axis bindings for this flight — which actions drive each axis. Unlisted axes keep the defaults above. */
+    bindings?: FreeFlightBindings;
+    /** Camera POV while this flight is active — chase tuning overlay applied on mount, cleared on dismount. */
+    camera?: ChaseCameraTuning | null;
+    /** Gate flight behind live game state — creative toggle, stamina check, etc. `false` stays walking. Default true when `flight` is present. */
+    canFly?: (ctx: GameContext) => boolean;
+}
 /** Movement-control levers for the shell-driven local player walk controller. */
 export interface PlayerMovementConfig {
     /** "free" (default) moves camera-relative across the plane; "axis" locks travel to one world axis; "grid" snaps each committed position to cell centers. */
@@ -308,6 +389,15 @@ export interface PlayerMovementConfig {
     slopeSlide?: {
         maxClimbSlope?: number;
     } | boolean;
+    /**
+     * Free-flight — creative/spectator/noclip/hover — folded into the same walk controller so a game
+     * doesn't hand-roll a second movement loop to get Minecraft-like flight. `true` uses creative defaults;
+     * an object tunes speed/vertical/sprint/collide/canFly. Horizontal is always yaw-relative strafe
+     * (A = left, D = right — never roll/bank), vertical is Space/Ctrl, and aircraft/rotorcraft remain
+     * on `physics/flightDynamics`. The shell drives this automatically when present; `canFly` toggles
+     * between walking and flying per tick without rebuilding the config.
+     */
+    flight?: FlightConfig | boolean;
 }
 /** One frame's movement resolution handed to `PlayerMovementConfig.beforeCommit`. */
 export interface MovementCommitFrame {
@@ -412,7 +502,7 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     /** Optional canvas-layer VFX component (e.g. traveling projectiles); receives `{ ctx }` (#542) so overlay VFX read live engine state without a separate hook or a module-global workaround. */
     WorldOverlay?: TOverlay;
     /** Replaces the default demo backdrop (ground + grid + rocks) with the game's own scene — ground, sky, structures. Camera, input, HUD, entity rendering, and the loop stay shell-provided; supply your world without forking the shell. When unset and `game.world` is an `environment()` descriptor, the shell auto-renders that world here — no manual wiring needed. */
-    environment?: TWorldOverlay;
+    environment?: TWorldOverlay | EnvironmentSource;
     /** The game's authored scene document (`editor.scene.json`, normalized). When set, `defineGame` always mounts `AuthoredScene` over it (draped paths, scatter, studios, placed catalog props) — any `WorldOverlay` renders alongside it as VFX only — and the embedded editor opens it as its default layers: the zero-wiring path from document to play and edit modes. */
     editorLayers?: EditorDocument;
     /** Game-exported gameplay catalog definitions (schemas + defaults). `GameHost` forwards them to the summoned editor's Data panel; no per-game editor bootstrap needed. */
@@ -441,6 +531,8 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     capture?: GameCaptureConfig;
     /** Cast/receive shadows across the scene (R3F Canvas shadow pass). Default true. */
     shadows?: boolean;
+    /** Per-quality renderer budgets; omitted tiers use {@link DEFAULT_GRAPHICS_PROFILES}. */
+    graphics?: Partial<Record<"low" | "medium" | "high", Partial<GraphicsProfile>>>;
     /** Pointer-driven input: click-to-move, box-select, right-click verbs, cursor aim (#22/#30/#31). */
     pointer?: PointerConfig;
     /** Touch controls on coarse-pointer devices. Unset derives a scheme from `input` (virtual joystick for movement actions, on-screen buttons for the rest); a config refines it with gestures and curated buttons; `false` opts out. */
@@ -499,10 +591,12 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     collision?: VoxelCollisionConfig;
     /** Movement-control levers (axis/grid constraints, object collision, pre-commit hook) for the shell-driven walk controller. */
     movement?: PlayerMovementConfig;
-    /** Default-look preset (#773). Unset/`"cinematic"` composes a real sky, a shadow-casting sun+hemisphere rig, a network-free image-based-lighting environment (soft PBR reflections), and a tuned tone-map/bloom/AO/vignette post stack, so a scene reads lit-like-a-game out of the box; `"flat"` opts out to the bare ambient+directional default. Upgraded default primitive materials (tuned PBR + subtle procedural surface detail) apply under both presets. Any explicit `lighting`/`backdrop`/`postProcessing` always wins. */
+    /** Graphics look profile (#1680). Unset/`"neutral"` keeps the output unstyled; `"photoreal"` and `"toon"` select authored presentation profiles, while `"cinematic"` and `"flat"` remain compatibility aliases. Explicit `lighting`/`backdrop`/`postProcessing` always wins. */
     look?: LookPreset;
     /** Declarative ambient/directional/hemisphere lighting (#207.5); replaces the shell's hardcoded default lights when present, regardless of world kind. */
     lighting?: LightingConfig;
+    /** Image-based environment source; omit to use the procedural gradient probe. */
+    environmentSource?: EnvironmentSource;
     /** Generic background/sky/fog (#207.6), applied for any world kind including a custom `environment` component. */
     backdrop?: BackdropConfig;
     /** Declarative post-processing chain (AO/bloom/tone-map/grade). When set, the shell mounts an EffectComposer and owns the render; absent leaves the renderer drawing directly (unchanged). */

package/dist/game/systemRuntime.js

@@ -1,4 +1,5 @@
 import { compileSystemSchedule, } from "./systemSchedule.js";
+const MAX_FIXED_SUBSTEPS = 8;
 function resolveModule(spec, ctx) {
     if (spec === undefined)
         return undefined;
@@ -56,10 +57,14 @@ export function installSystems(ctx, systems, options) {
         for (const group of schedule.fixed) {
             const step = 1 / group.rate;
             let acc = (fixedAcc.get(group.rate) ?? 0) + dt;
-            while (acc >= step) {
+            let substeps = 0;
+            while (acc >= step && substeps < MAX_FIXED_SUBSTEPS) {
                 runIds(ctx, group.order, step);
                 acc -= step;
+                substeps += 1;
             }
+            if (acc >= step)
+                acc %= step;
             fixedAcc.set(group.rate, acc);
         }
         runIds(ctx, schedule.frameOrder, dt);

package/dist/input/actionBindings.d.ts

@@ -1,3 +1,4 @@
+import { type GamepadGlyphName, type GamepadGlyphSet } from "./gamepadModel.js";
 /**
  * Action-binding model: games bind semantic actions ("jump", "interact") to
  * physical control codes; capture layers resolve raw events through this map
@@ -69,7 +70,7 @@ export declare function resolveActionCommand(action: string, has: (command: stri
 /** Short display label for a raw key/button code (e.g. `"KeyW"` → `"W"`).
  * @internal
  */
-export declare function bindingLabel(code: string): string;
+export declare function bindingLabel(code: string, glyphSet?: GamepadGlyphName | GamepadGlyphSet): string;
 /** Short display label for an action's first bound code, or null when unbound.
  * @internal
  */

package/dist/input/actionBindings.js

@@ -1,10 +1,4 @@
-/**
- * Action-binding model: games bind semantic actions ("jump", "interact") to
- * physical control codes; capture layers resolve raw events through this map
- * so gameplay code never sees keycodes. Control codes are plain strings, so
- * the same model serves keyboard codes, mouse buttons, touch controls, or
- * gamepad inputs.
- */
+import { GAMEPAD_GLYPH_SETS } from "./gamepadModel.js";
 /** @internal */
 export function bindingMatches(code, binding) {
     return code === binding.primary || code === binding.secondary;
@@ -142,7 +136,15 @@ const CODE_LABELS = {
 /** Short display label for a raw key/button code (e.g. `"KeyW"` → `"W"`).
  * @internal
  */
-export function bindingLabel(code) {
+export function bindingLabel(code, glyphSet = "generic") {
+    const padButton = /^pad:(\d+)$/.exec(code);
+    if (padButton !== null) {
+        const set = typeof glyphSet === "string" ? GAMEPAD_GLYPH_SETS[glyphSet] : glyphSet;
+        return set.buttons[Number(padButton[1])] ?? `Button ${padButton[1]}`;
+    }
+    const padAxis = /^padaxis:(\d+)([+-])$/.exec(code);
+    if (padAxis !== null)
+        return `Axis ${padAxis[1]}${padAxis[2]}`;
     const direct = CODE_LABELS[code];
     if (direct !== undefined)
         return direct;

package/dist/input/actionContexts.d.ts

@@ -0,0 +1,21 @@
+import type { ActionCodesMap } from "./actionBindings.js";
+/** Named action-binding layer that may optionally expose lower layers. */
+export interface ActionContext {
+    id: string;
+    codes: ActionCodesMap;
+    passthrough: boolean;
+}
+/** Serializable state for an action-context stack. */
+export interface ActionContextStackSnapshot {
+    contexts: ActionContext[];
+}
+/** Mutable layered action-map stack with snapshot and restore support. */
+export interface ActionContextStack {
+    push(context: ActionContext): void;
+    pop(id: string): boolean;
+    active(): ActionCodesMap;
+    snapshot(): ActionContextStackSnapshot;
+    restore(snapshot: ActionContextStackSnapshot): void;
+}
+/** Creates a serializable stack of layered action maps for menus and gameplay modes. */
+export declare function createActionContextStack(): ActionContextStack;

package/dist/input/actionContexts.js

@@ -0,0 +1,56 @@
+function cloneCodes(codes) {
+    const result = {};
+    for (const [action, value] of Object.entries(codes)) {
+        const modes = value;
+        result[action] = Array.isArray(value)
+            ? [...value]
+            : {
+                ...(modes.hold === undefined ? {} : { hold: [...modes.hold] }),
+                ...(modes.toggle === undefined ? {} : { toggle: [...modes.toggle] }),
+                ...(modes.repeatMs === undefined ? {} : { repeatMs: modes.repeatMs }),
+            };
+    }
+    return result;
+}
+/** Creates a serializable stack of layered action maps for menus and gameplay modes. */
+export function createActionContextStack() {
+    let contexts = [];
+    return {
+        push(context) {
+            contexts = [...contexts.filter((current) => current.id !== context.id), {
+                    id: context.id,
+                    codes: cloneCodes(context.codes),
+                    passthrough: context.passthrough,
+                }];
+        },
+        pop(id) {
+            const next = contexts.filter((context) => context.id !== id);
+            const changed = next.length !== contexts.length;
+            contexts = next;
+            return changed;
+        },
+        active() {
+            const merged = {};
+            for (let index = contexts.length - 1; index >= 0; index -= 1) {
+                const context = contexts[index];
+                for (const [action, codes] of Object.entries(context.codes)) {
+                    if (merged[action] === undefined)
+                        merged[action] = codes;
+                }
+                if (!context.passthrough)
+                    break;
+            }
+            return merged;
+        },
+        snapshot() {
+            return { contexts: contexts.map((context) => ({ ...context, codes: cloneCodes(context.codes) })) };
+        },
+        restore(snapshot) {
+            contexts = snapshot.contexts.map((context) => ({
+                id: context.id,
+                codes: cloneCodes(context.codes),
+                passthrough: context.passthrough,
+            }));
+        },
+    };
+}