@jgengine/core 0.18.0 → 0.19.0

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,22 @@
+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 { GamepadFeelConfig } from "../input/gamepadModel.js";
+import type { LocalPlayersConfig } from "../runtime/localPlayers.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";
@@ -16,14 +24,21 @@ import type { SkyEnvironmentConfig } from "../world/features.js";
 import type { VisibilityConfig } from "../visibility/config.js";
 import type { GameDefinition, GameLoop } from "./defineGame.js";
 import type { GameCameraConfig } from "./cameraConfig.js";
+import type { ViewportsConfig } from "./viewports.js";
 import type { LootFilterRule } from "./lootFilter.js";
 import type { RarityStyle } from "./worldItem.js";
-export type { CameraFollowState, CameraKeyframe, CameraProjection, CameraRigKind, CameraShakeConfig, ChaseCameraConfig, ChaseView, CinematicCameraConfig, FirstPersonCameraConfig, GameCameraConfig, InspectionCameraConfig, InspectionZoomAnchor, LockOnCameraConfig, ObserverCameraConfig, PlayerFovConfig, RtsCameraConfig, ShoulderCameraConfig, SideScrollCameraConfig, TopDownCameraConfig, TurntableCameraConfig, } from "./cameraConfig.js";
+export type { CameraFollowState, CameraKeyframe, CameraProjection, CameraRigKind, CameraWeaponView, CameraShakeConfig, ChaseCameraConfig, ChaseView, CinematicCameraConfig, FirstPersonCameraConfig, GameCameraConfig, InspectionCameraConfig, InspectionZoomAnchor, LockOnCameraConfig, ObserverCameraConfig, PlayerFovConfig, RtsCameraConfig, ShoulderCameraConfig, SideScrollCameraConfig, TopDownCameraConfig, TurntableCameraConfig, } from "./cameraConfig.js";
 export { CAMERA_FRUSTUM_DEFAULTS } from "./cameraConfig.js";
+/**
+ * Mouse/touch pointer bindings for `defineGame({ pointer })`.
+ *
+ * @capability pointer-commands click an entity or the ground to run a command (click-to-target, click-to-move, grab loot, marquee select)
+ */
 export interface PointerConfig {
     /**
-     * Left-click on open ground runs this command with `{ point, entity, object }`
-     * (click-to-move / ground-target). Suppresses the default left-click hotbar fire.
+     * Left-click runs this command with `{ point, entity, object }`; `entity` is the clicked entity id or
+     * null, so the same command covers click-to-move, ground-target and click-to-target
+     * (`ctx.scene.entity.setTarget`). Suppresses the default left-click hotbar fire.
      */
     moveCommand?: string;
     /** Enable left-drag marquee + single-click box-select of entities (RTS unit command). */
@@ -52,6 +67,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 +139,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 +158,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 +234,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 +245,14 @@ export interface ModelConfig {
      * rig's bind pose.
      */
     animation?: ModelAnimationConfig | "auto" | "none";
+    /**
+     * Runtime inverse kinematics for a rigged model, applied after the animation mixer each frame.
+     * Feet follow slopes and steps while keeping each clip's swing lift, soles never sink below the
+     * ground, the pelvis drops so the lower leg can reach, and the correction fades out while airborne.
+     * `"auto"` finds the legs by bone name (`UpLeg`, `UpperLeg`, `Thigh`); bone names resolve on the
+     * loaded scene.
+     */
+    ik?: "auto" | ModelIkConfig;
     /** 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. */
@@ -219,6 +260,25 @@ export interface ModelConfig {
     /** Tuning for the procedural part-motion driver when any part carries a `role`; omit for defaults. */
     partMotion?: PartMotionParams;
 }
+/** Bone names and limits for {@link ModelConfig.ik}. */
+export interface ModelIkConfig {
+    /** Thigh → shin → foot chains; omit to find them by bone name. `[]` turns foot IK off. */
+    feet?: readonly {
+        root: string;
+        mid: string;
+        tip: string;
+    }[];
+    /** Bone shifted down when a foot has to reach lower ground; defaults to the first thigh's parent. */
+    pelvis?: string;
+    /** Largest foot or pelvis correction, as a fraction of leg length. Default `0.4`. */
+    maxAdjust?: number;
+    /** Tilt planted feet to the ground normal, `0..1`. Default `1`. */
+    alignToGround?: number;
+    /** Turns this bone toward the camera. */
+    lookAt?: {
+        bone: string;
+    };
+}
 export interface ObjectStyle {
     color?: string;
     opacity?: number;
@@ -255,10 +315,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 +353,62 @@ 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 and rockets use `physics/aircraftDynamics`. */
+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;
+}
+/** Feel knobs for the built-in walk controller; see {@link PlayerMovementConfig.feel}. */
+export interface MovementFeelConfig {
+    /** Ground velocity response, 1/s (default 26). Lower drifts into and out of motion; higher is snappy. */
+    groundAcceleration?: number;
+    /** Air velocity response, 1/s (default 12). `0` commits to the jump arc; high values steer freely in the air. */
+    airAcceleration?: number;
+    /** Stopping response on the ground with no input, 1/s (default 18). Lower slides like ice. */
+    groundFriction?: number;
+    /** Sprint speed as a multiple of walk speed (default 2.25). */
+    runMultiplier?: number;
+    /** Crouch speed as a multiple of walk speed (default 0.45). */
+    crouchMultiplier?: number;
+    /** A jump pressed up to this many ms before landing fires on landing (default 0). */
+    jumpBufferMs?: number;
+    /** A jump pressed up to this many ms after walking off a ledge still fires (default 0). */
+    coyoteMs?: number;
+    /** Rising speed kept when jump is released early, 0..1 (default 1: no cut). Lower makes a tap a hop. */
+    jumpCutFactor?: number;
+    /** Gravity multiplier near the peak, while vertical speed is under `apexSpeed` (default 1). Below 1 hangs. */
+    apexGravityScale?: number;
+    /** Vertical speed under which `apexGravityScale` applies, m/s (default 1.5). */
+    apexSpeed?: number;
+    /** Gravity multiplier while falling (default 1). Above 1 drops faster than it rose. */
+    fallGravityScale?: number;
+    /** After landing, jumps wait and walk speed ramps back from `landingSpeedScale` over this many ms (default 0). */
+    landingRecoveryMs?: number;
+    /** Walk speed share right after landing when `landingRecoveryMs` is set (default 0.5). */
+    landingSpeedScale?: number;
+}
 /** 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. */
@@ -298,6 +433,13 @@ export interface PlayerMovementConfig {
     canSprint?: (ctx: GameContext) => boolean;
     /** Fraction of walk speed while backpedalling (holding `moveBack`). Overrides the engine default (0.65). */
     backpedalMult?: number;
+    /**
+     * Walk-controller feel. Acceleration and friction are exponential response rates (1/s): higher reaches
+     * the target velocity or stops sooner. Omitted fields keep the engine defaults, so nothing changes until a
+     * game sets one. The jump fields apply to the kinematic walk; a `physics.backend` capsule or `collision.voxel`
+     * body jumps on the press frame with plain gravity. Tune against `measureMovement` (`@jgengine/core/movement/movementProbe`).
+     */
+    feel?: MovementFeelConfig;
     /** Radians/second the rendered body rotates toward its movement heading (shortest arc), so strafing/backpedalling read as a turn rather than an instant flip; also the rate the internally-integrated `turnLeft`/`turnRight` heading turns when the shell doesn't own yaw. Unset = body facing snaps instantly (no change to existing feel). */
     turnSpeed?: number;
     /** On-foot swimming when the terrain declares a `waterLevel` and the player is submerged: caps speed and floats them at the surface. `true` uses defaults; default off. */
@@ -308,6 +450,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 and rockets
+     * use `physics/aircraftDynamics`. 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 +563,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,10 +592,18 @@ 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. */
     touch?: TouchControlsConfig | false;
+    /** Gamepad stick deadzone, response curve and trigger deadzone the shell's pad poll applies before publishing analog values. Unset keeps the shell defaults (axial `0.12`/`0.95`, linear). */
+    gamepad?: GamepadFeelConfig;
+    /** Local seats on this screen for couch co-op. With `maxSlots > 1` each extra pad hot-joins its own seat on its first button press, the shell calls `loop.onNewPlayer(ctx, { userId, isNew: true })` for it, and its input lands on `localPlayers(ctx).local(slotId).input` instead of `ctx.input`. Unset keeps one seat: every device drives `ctx.player`. */
+    localPlayers?: LocalPlayersConfig;
+    /** Split-screen for local seats (`localPlayers`): one viewport per joined seat, each following its own entity. The primary seat keeps the main camera rig; post-processing is skipped while more than one viewport is drawn. */
+    viewports?: ViewportsConfig;
     /** Phone orientation contract. Legacy `"landscape"`/`"portrait"` stays advisory (a dismissible rotate hint). The object form `{ mobile: "landscape-required" }` is strict — the shell shows an engine-owned rotate screen and blocks gameplay until the device is turned. See `GameOrientation`. */
     orientation?: GameOrientation;
     /** Where the game is meant to be played. Default `["web", "mobile"]` — design-resolution HUD fit is on for every game: `HudCanvas` auto-scales from `hudFit.designSize` down to the live viewport, so the desktop layout shrinks to fit a phone instead of overflowing it. Declare `["web"]` to opt a desktop-only game out (compact displays fall back to the legacy fixed 0.85 zoom). */
@@ -499,10 +658,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/game/toasts.d.ts

@@ -15,6 +15,11 @@ export interface Toast<T = string> {
 export declare function appendToast<T>(toasts: readonly Toast<T>[], toast: Toast<T>, cap: number): readonly Toast<T>[];
 /** Drop every toast whose `expiresAt` is at or before `now`. Returns the same array when nothing expired. */
 export declare function pruneToasts<T>(toasts: readonly Toast<T>[], now: number): readonly Toast<T>[];
+/** Plain JSON state of a {@link ToastQueue}: live toasts plus the id counter. */
+export interface ToastQueueState<T = string> {
+    toasts: Toast<T>[];
+    counter: number;
+}
 /** Stateful transient-toast list with a size cap and time-to-live eviction. */
 export interface ToastQueue<T = string> {
     /** Raise a toast at `now` living `ttlSeconds` (falling back to the queue default); returns it. */
@@ -25,6 +30,9 @@ export interface ToastQueue<T = string> {
     list(): readonly Toast<T>[];
     /** Remove all toasts. */
     clear(): void;
+    /** Copies the queue; each toast's `body` is shared, since the queue never mutates it. */
+    snapshot(): ToastQueueState<T>;
+    restore(next: ToastQueueState<T>): void;
 }
 /** Options for {@link createToastQueue}. */
 export interface ToastQueueOptions {

package/dist/game/toasts.js

@@ -40,5 +40,12 @@ export function createToastQueue(options = {}) {
         clear() {
             toasts = [];
         },
+        snapshot() {
+            return { toasts: toasts.map((toast) => ({ ...toast })), counter };
+        },
+        restore(next) {
+            toasts = next.toasts.map((toast) => ({ ...toast }));
+            counter = next.counter;
+        },
     };
 }

package/dist/game/vfxInstance.d.ts

@@ -115,6 +115,15 @@ export interface VfxInstanceStore {
     tick(nowMs?: number): number;
     /** Dispose every instance (scene change / reset), emitting a `stop` op for each. */
     clear(): void;
+    /** Plain JSON copy of every live instance plus the id counter. */
+    snapshot(): VfxInstanceStoreState;
+    /** Replaces the live set: emits `stop` for each current instance, then `upsert` for each restored one. */
+    restore(next: VfxInstanceStoreState): void;
+}
+/** Plain JSON state of a {@link VfxInstanceStore}. */
+export interface VfxInstanceStoreState {
+    instances: VfxInstanceState[];
+    seq: number;
 }
 /** Options for {@link createVfxInstanceStore}. */
 export interface VfxInstanceStoreOptions {

package/dist/game/vfxInstance.js

@@ -92,5 +92,16 @@ export function createVfxInstanceStore(options = {}) {
         for (const id of [...instances.keys()])
             stop(id);
     }
-    return { upsert, update, stop, get, list, count, tick, clear };
+    function snapshot() {
+        return { instances: structuredClone([...instances.values()]), seq };
+    }
+    function restore(next) {
+        clear();
+        seq = next.seq;
+        for (const state of structuredClone(next.instances)) {
+            instances.set(state.id, state);
+            emit({ op: "upsert", id: state.id, instance: state });
+        }
+    }
+    return { upsert, update, stop, get, list, count, tick, clear, snapshot, restore };
 }

package/dist/game/viewports.d.ts

@@ -0,0 +1,43 @@
+import type { ChaseCameraConfig, TopDownCameraConfig } from "./cameraConfig.js";
+/** A screen region as fractions of the canvas, `[x, y, width, height]` in `0..1` with the origin at the top left. */
+export type ViewportRect = readonly [number, number, number, number];
+/** The follow camera an extra viewport runs; the primary seat keeps the game's main camera rig. */
+export interface ViewportCameraConfig {
+    /** Default: `"topDown"` when the game's main rig is top-down, otherwise `"chase"`. */
+    rig?: "chase" | "topDown";
+    chase?: ChaseCameraConfig;
+    topDown?: TopDownCameraConfig;
+}
+/** One viewport: which local seat it shows and where. */
+export interface ViewportDef {
+    /** Local seat id (`"slot:0"`, `"slot:1"`, …) from `localPlayers(ctx)`. */
+    slot: string;
+    rect: ViewportRect;
+    camera?: ViewportCameraConfig;
+}
+/** `defineGame({ viewports })`: split-screen layout for local seats. */
+export interface ViewportsConfig {
+    /** `"auto"` (default) splits the screen evenly across the seats currently joined; a list pins explicit rects. */
+    layout?: "auto" | readonly ViewportDef[];
+    /** Two-seat split: `"vertical"` puts them side by side (default), `"horizontal"` stacks them. */
+    split?: "vertical" | "horizontal";
+    /** Follow camera for seats whose viewport has none. */
+    camera?: ViewportCameraConfig;
+}
+/** A viewport in canvas pixels with a bottom-left origin, ready for `gl.setViewport`/`setScissor`. */
+export interface ViewportPixels {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Even split-screen rects for seats in order: one fills the screen, two split side by side (or stacked),
+ * three put the first on a full-width top half, four make a 2×2 grid, more fill a grid row by row.
+ * @capability split-screen Split the screen into one viewport per local seat, each with its own follow camera.
+ */
+export declare function splitViewports(slots: readonly string[], split?: "vertical" | "horizontal"): ViewportDef[];
+/** The viewports to draw for the seats currently joined: the explicit layout filtered to joined seats, or an even split. */
+export declare function resolveViewports(config: ViewportsConfig | undefined, slots: readonly string[]): ViewportDef[];
+/** Convert a top-left fractional rect into whole canvas pixels with a bottom-left origin; neighbours share edges exactly. */
+export declare function viewportPixels(rect: ViewportRect, width: number, height: number): ViewportPixels;

package/dist/game/viewports.js

@@ -0,0 +1,46 @@
+function gridRects(count) {
+    const columns = Math.ceil(Math.sqrt(count));
+    const rows = Math.ceil(count / columns);
+    const rects = [];
+    for (let index = 0; index < count; index += 1) {
+        const row = Math.floor(index / columns);
+        const inRow = row === rows - 1 ? count - row * columns : columns;
+        const column = index - row * columns;
+        rects.push([column / inRow, row / rows, 1 / inRow, 1 / rows]);
+    }
+    return rects;
+}
+/**
+ * Even split-screen rects for seats in order: one fills the screen, two split side by side (or stacked),
+ * three put the first on a full-width top half, four make a 2×2 grid, more fill a grid row by row.
+ * @capability split-screen Split the screen into one viewport per local seat, each with its own follow camera.
+ */
+export function splitViewports(slots, split = "vertical") {
+    const count = slots.length;
+    let rects;
+    if (count <= 1)
+        rects = [[0, 0, 1, 1]];
+    else if (count === 2) {
+        rects = split === "vertical" ? [[0, 0, 0.5, 1], [0.5, 0, 0.5, 1]] : [[0, 0, 1, 0.5], [0, 0.5, 1, 0.5]];
+    }
+    else if (count === 3)
+        rects = [[0, 0, 1, 0.5], [0, 0.5, 0.5, 0.5], [0.5, 0.5, 0.5, 0.5]];
+    else
+        rects = gridRects(count);
+    return slots.map((slot, index) => ({ slot, rect: rects[index] }));
+}
+/** The viewports to draw for the seats currently joined: the explicit layout filtered to joined seats, or an even split. */
+export function resolveViewports(config, slots) {
+    const layout = config?.layout ?? "auto";
+    if (layout === "auto")
+        return splitViewports(slots, config?.split);
+    return layout.filter((def) => slots.includes(def.slot));
+}
+/** Convert a top-left fractional rect into whole canvas pixels with a bottom-left origin; neighbours share edges exactly. */
+export function viewportPixels(rect, width, height) {
+    const left = Math.round(rect[0] * width);
+    const right = Math.round((rect[0] + rect[2]) * width);
+    const top = Math.round(rect[1] * height);
+    const bottom = Math.round((rect[1] + rect[3]) * height);
+    return { x: left, y: height - bottom, width: Math.max(1, right - left), height: Math.max(1, bottom - top) };
+}

package/dist/game/worldItem.d.ts

@@ -62,7 +62,6 @@ export declare function selectNearestWorldItem(candidates: readonly {
 /**
  * Spawn and track pickup-able items scattered in the world, including drops that scatter on death.
  *
- * @capability world-drops spawn pickup-able items in the world, including death drops
   * @internal
   */
 export declare function createWorldItemStore(deps: WorldItemStoreDeps): WorldItemStore;
@@ -87,6 +86,11 @@ export interface ResolvedDeathDrops {
   * @internal
   */
 export declare function resolveDeathDrops(drops: readonly Drop[], options: ResolveDeathDropsOptions): ResolvedDeathDrops;
+/**
+ * Per-rarity look of a dropped item: beam, color and label. Set via `defineGame({ worldItem: { rarityStyle } })`.
+ *
+ * @capability loot-beams rarity-colored loot beams and labels on dropped items via defineGame({ worldItem: { rarityStyle, beamHeight } })
+ */
 export interface RarityStyle {
     color?: string;
     beam?: boolean;

package/dist/game/worldItem.js

@@ -39,7 +39,6 @@ export function selectNearestWorldItem(candidates, from, radius) {
 /**
  * Spawn and track pickup-able items scattered in the world, including drops that scatter on death.
  *
- * @capability world-drops spawn pickup-able items in the world, including death drops
   * @internal
   */
 export function createWorldItemStore(deps) {

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
@@ -33,7 +34,13 @@ export type ActionCodes<TCode extends string = string> = readonly TCode[] | {
     toggle?: readonly TCode[];
     repeatMs?: number;
 };
-/** Maps each game action name to the input codes (hold/toggle keys, repeat rate) that trigger it. */
+/**
+ * Maps each game action name to the input codes (hold/toggle keys, repeat rate) that trigger it. In a
+ * `defineGame({ input })`, pressing an action runs the same-named command with `{ yaw, pitch, aim }`;
+ * `repeatMs` re-fires it while held (automatic weapons).
+ *
+ * @capability fire-input bind a key or mouse button to a named action that runs the same-named command with the aim; repeatMs auto-fires while held
+ */
 export type ActionCodesMap<TAction extends string = string, TCode extends string = string> = Record<TAction, ActionCodes<TCode>>;
 /** @internal */
 export declare function actionRepeatMs(codes: ActionCodes | undefined): number | undefined;
@@ -69,7 +76,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
  */
@@ -81,6 +88,14 @@ export interface ActionStateTracker<TAction extends string> {
     wasPressed(action: TAction): boolean;
     endFrame(): void;
     reset(): void;
+    /**
+     * Swap the binding map without dropping what is physically held: a key still down counts toward
+     * whatever action it maps to now, with no fresh press edge. Toggle state survives for actions that
+     * come back later.
+     */
+    rebind(map: ActionStateBindingMap<TAction, string>): void;
+    /** The action names in the current binding map. */
+    actions(): readonly TAction[];
 }
 /** @internal */
 export declare function createActionStateTracker<TAction extends string, TCode extends string = string>(map: ActionStateBindingMap<TAction, TCode>): ActionStateTracker<TAction>;

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;
@@ -177,9 +179,9 @@ function resolveActionBindingModes(config) {
 }
 /** @internal */
 export function createActionStateTracker(map) {
-    const actions = Object.keys(map);
-    const modesByAction = new Map(actions.map((action) => [action, resolveActionBindingModes(map[action])]));
-    const heldCodesByAction = new Map(actions.map((action) => [action, new Set()]));
+    let actions = Object.keys(map);
+    let modesByAction = new Map(actions.map((action) => [action, resolveActionBindingModes(map[action])]));
+    let heldCodesByAction = new Map(actions.map((action) => [action, new Set()]));
     const toggledActions = new Set();
     const pressedThisFrame = new Set();
     const activeCodes = new Set();
@@ -238,5 +240,16 @@ export function createActionStateTracker(map) {
             pressedThisFrame.clear();
             activeCodes.clear();
         },
+        rebind(next) {
+            actions = Object.keys(next);
+            modesByAction = new Map(actions.map((action) => [action, resolveActionBindingModes(next[action])]));
+            heldCodesByAction = new Map(actions.map((action) => [action, new Set()]));
+            for (const code of activeCodes) {
+                const holdAction = findAction(code, (modes) => modes.hold);
+                if (holdAction !== null)
+                    heldCodesByAction.get(holdAction).add(code);
+            }
+        },
+        actions: () => actions,
     };
 }