@jgengine/core 0.18.1 → 0.19.0

package/dist/combat/weaponPresentation.d.ts

@@ -0,0 +1,115 @@
+import type { WeaponHandlingFrame } from "./weaponHandling.js";
+/** Camera-space position `[x, y, z]` in metres: `+x` right, `+y` up, `-z` forward. */
+export type ViewmodelOffset = readonly [number, number, number];
+/**
+ * How one weapon sits in first person. Offsets are camera-space metres, angles are radians, FOVs are
+ * degrees. Every field is optional; two weapons differ by the ones they set.
+ */
+export interface WeaponPresentationTuning {
+    /** Viewmodel anchor at the hip (default `[0.34, -0.26, -0.72]`). */
+    hip?: ViewmodelOffset;
+    /** Viewmodel anchor fully aimed; put the sight on the camera axis (default `[0, -0.07, -0.55]`). */
+    ads?: ViewmodelOffset;
+    /** Viewmodel FOV in degrees, independent of the world FOV; omit to draw the viewmodel at the world FOV. */
+    viewmodelFov?: {
+        hip?: number;
+        ads?: number;
+    };
+    /** World FOV multiplier at full ADS, e.g. `0.8` for a light zoom (default `1`). */
+    adsZoom?: number;
+    /** Viewmodel lag behind look motion. */
+    sway?: {
+        /** Radians of lag per rad/s of look speed (default `0.02`). */
+        perRadPerSec?: number;
+        /** Largest lag, rad (default `0.08`). */
+        max?: number;
+        /** How fast lag follows its target, 1/s (default `12`). */
+        response?: number;
+        /** Lag multiplier at full ADS (default `0.3`). */
+        adsScale?: number;
+    };
+    /** Walk bob driven by the movement probe's speed and `bobPhase`. */
+    bob?: {
+        /** Side and vertical amplitude in metres at `fullSpeed` (default `[0.012, 0.01]`). */
+        amplitude?: readonly [number, number];
+        /** Ground speed that gives the full amplitude, m/s (default `4`). */
+        fullSpeed?: number;
+        /** Bob multiplier at full ADS (default `0.25`). */
+        adsScale?: number;
+    };
+    /** Viewmodel reaction to the handling's recoil offset. */
+    kick?: {
+        /** Metres pushed back per radian of recoil (default `1.2`). */
+        back?: number;
+        /** Viewmodel muzzle rise per radian of recoil (default `1.5`). */
+        rise?: number;
+    };
+}
+/** One frame of inputs: look motion, the movement probe, and the weapon's handling readout. */
+export interface WeaponPresentationInput {
+    /** Look yaw speed, rad/s, positive turning left (the same sign as a camera yaw that grows left). */
+    lookYawRate: number;
+    /** Look pitch speed, rad/s, positive looking up. */
+    lookPitchRate: number;
+    /** Horizontal ground speed, m/s (e.g. `EntityRenderCues.speed`). */
+    speed: number;
+    /** `0..1` walk-cycle phase (e.g. `EntityRenderCues.bobPhase`). */
+    bobPhase: number;
+    handling: WeaponHandlingFrame;
+}
+/**
+ * Where the viewmodel and camera go this frame. First person applies all of it; third person and
+ * over-the-shoulder read `lookPitch`/`lookYaw`, `aimPitch`/`aimYaw` and `adsProgress` from the same frame.
+ */
+export interface WeaponPose {
+    /** Viewmodel anchor, camera-space metres. */
+    offset: [number, number, number];
+    /** Viewmodel rotation about its anchor, rad: `pitch > 0` muzzle up, `yaw > 0` muzzle left, `roll > 0` tilts left. */
+    pitch: number;
+    yaw: number;
+    roll: number;
+    /** Viewmodel FOV in degrees, or `null` to use the world FOV. */
+    viewmodelFov: number | null;
+    /** Multiplier for the world FOV (ADS zoom). */
+    fovScale: number;
+    /** Offset to add to the camera look, rad: aim kick plus view punch. `lookYaw > 0` pulls right. */
+    lookPitch: number;
+    lookYaw: number;
+    /** Offset shots follow, rad; a third-person rig or upper-body aim reads this. */
+    aimPitch: number;
+    aimYaw: number;
+    /** `0` hip … `1` fully aimed. */
+    adsProgress: number;
+}
+/** Serializable presentation state: the current sway lag. */
+export interface WeaponPresentationState {
+    swayPitch: number;
+    swayYaw: number;
+}
+/** Turns a {@link WeaponHandlingFrame} plus look and movement into a viewmodel and camera pose. */
+export interface WeaponPresentation {
+    /** Advance sway by `dt` and return the pose. The returned object is reused between calls. */
+    update(dt: number, input: WeaponPresentationInput): WeaponPose;
+    pose(): WeaponPose;
+    retune(next: WeaponPresentationTuning): void;
+    snapshot(): WeaponPresentationState;
+    restore(state: WeaponPresentationState): void;
+    reset(): void;
+}
+/** Default hip anchor, matching the shell's built-in viewmodel. */
+export declare const DEFAULT_VIEWMODEL_HIP: ViewmodelOffset;
+/** Default ADS anchor: the built-in viewmodel's top rail on the camera axis. */
+export declare const DEFAULT_VIEWMODEL_ADS: ViewmodelOffset;
+/**
+ * Creates a {@link WeaponPresentation}: per-weapon viewmodel offset, ADS pose and viewmodel FOV, sway
+ * and inertia from look speed, bob from the movement probe, and a recoil kick, all driven by the same
+ * handling frame third-person and over-the-shoulder rigs read. Deterministic and allocation-free per update.
+ * @capability weapon-presentation per-weapon viewmodel offset, ADS pose, viewmodel FOV, sway, bob and recoil kick from a weapon handling frame
+ */
+export declare function createWeaponPresentation(initial?: WeaponPresentationTuning): WeaponPresentation;
+/**
+ * Scale for a viewmodel drawn at `viewmodelFov` through a camera at `worldFov` (both degrees): multiply
+ * the viewmodel's camera-space x and y by this and it projects as if rendered with its own FOV, without
+ * a second camera or render pass.
+ */
+export declare function viewmodelFovScale(worldFov: number, viewmodelFov: number): number;

package/dist/combat/weaponPresentation.js

@@ -0,0 +1,96 @@
+/** Default hip anchor, matching the shell's built-in viewmodel. */
+export const DEFAULT_VIEWMODEL_HIP = [0.34, -0.26, -0.72];
+/** Default ADS anchor: the built-in viewmodel's top rail on the camera axis. */
+export const DEFAULT_VIEWMODEL_ADS = [0, -0.07, -0.55];
+const TAU = Math.PI * 2;
+const DEFAULT_BOB = [0.012, 0.01];
+function lerp(hip, aimed, ads) {
+    return hip * (1 - ads) + aimed * ads;
+}
+function clamp(value, limit) {
+    return Math.max(-limit, Math.min(limit, value));
+}
+/**
+ * Creates a {@link WeaponPresentation}: per-weapon viewmodel offset, ADS pose and viewmodel FOV, sway
+ * and inertia from look speed, bob from the movement probe, and a recoil kick, all driven by the same
+ * handling frame third-person and over-the-shoulder rigs read. Deterministic and allocation-free per update.
+ * @capability weapon-presentation per-weapon viewmodel offset, ADS pose, viewmodel FOV, sway, bob and recoil kick from a weapon handling frame
+ */
+export function createWeaponPresentation(initial = {}) {
+    let tuning = initial;
+    const state = { swayPitch: 0, swayYaw: 0 };
+    const out = {
+        offset: [...(tuning.hip ?? DEFAULT_VIEWMODEL_HIP)],
+        pitch: 0,
+        yaw: 0,
+        roll: 0,
+        viewmodelFov: tuning.viewmodelFov?.hip ?? null,
+        fovScale: 1,
+        lookPitch: 0,
+        lookYaw: 0,
+        aimPitch: 0,
+        aimYaw: 0,
+        adsProgress: 0,
+    };
+    return {
+        update(dt, input) {
+            const step = Math.max(0, dt);
+            const handling = input.handling;
+            const ads = Math.max(0, Math.min(1, handling.adsProgress));
+            const sway = tuning.sway;
+            const swayMax = sway?.max ?? 0.08;
+            const swayScale = lerp(1, sway?.adsScale ?? 0.3, ads);
+            const per = sway?.perRadPerSec ?? 0.02;
+            const targetYaw = clamp(-input.lookYawRate * per, swayMax) * swayScale;
+            const targetPitch = clamp(-input.lookPitchRate * per, swayMax) * swayScale;
+            const follow = 1 - Math.exp(-(sway?.response ?? 12) * step);
+            state.swayYaw += (targetYaw - state.swayYaw) * follow;
+            state.swayPitch += (targetPitch - state.swayPitch) * follow;
+            const bob = tuning.bob;
+            const [bobX, bobY] = bob?.amplitude ?? DEFAULT_BOB;
+            const bobScale = Math.min(1, Math.max(0, input.speed) / Math.max(1e-6, bob?.fullSpeed ?? 4)) * lerp(1, bob?.adsScale ?? 0.25, ads);
+            const phase = input.bobPhase * TAU;
+            const recoil = Math.hypot(handling.aimPitch + handling.cameraPitch, handling.aimYaw + handling.cameraYaw);
+            const hip = tuning.hip ?? DEFAULT_VIEWMODEL_HIP;
+            const aimed = tuning.ads ?? DEFAULT_VIEWMODEL_ADS;
+            out.offset[0] = lerp(hip[0], aimed[0], ads) + Math.sin(phase) * bobX * bobScale;
+            out.offset[1] = lerp(hip[1], aimed[1], ads) - Math.abs(Math.sin(phase)) * bobY * bobScale;
+            out.offset[2] = lerp(hip[2], aimed[2], ads) + recoil * (tuning.kick?.back ?? 1.2);
+            out.pitch = state.swayPitch + recoil * (tuning.kick?.rise ?? 1.5);
+            out.yaw = state.swayYaw;
+            out.roll = state.swayYaw * 0.5;
+            const hipFov = tuning.viewmodelFov?.hip ?? tuning.viewmodelFov?.ads;
+            const adsFov = tuning.viewmodelFov?.ads ?? hipFov;
+            out.viewmodelFov = hipFov === undefined || adsFov === undefined ? null : lerp(hipFov, adsFov, ads);
+            out.fovScale = lerp(1, tuning.adsZoom ?? 1, ads);
+            out.lookPitch = handling.aimPitch + handling.cameraPitch;
+            out.lookYaw = handling.aimYaw + handling.cameraYaw;
+            out.aimPitch = handling.aimPitch;
+            out.aimYaw = handling.aimYaw;
+            out.adsProgress = ads;
+            return out;
+        },
+        pose: () => out,
+        retune(next) {
+            tuning = next;
+        },
+        snapshot: () => ({ ...state }),
+        restore(next) {
+            state.swayPitch = next.swayPitch;
+            state.swayYaw = next.swayYaw;
+        },
+        reset() {
+            state.swayPitch = 0;
+            state.swayYaw = 0;
+        },
+    };
+}
+/**
+ * Scale for a viewmodel drawn at `viewmodelFov` through a camera at `worldFov` (both degrees): multiply
+ * the viewmodel's camera-space x and y by this and it projects as if rendered with its own FOV, without
+ * a second camera or render pass.
+ */
+export function viewmodelFovScale(worldFov, viewmodelFov) {
+    const toHalf = (deg) => Math.tan((Math.max(1, Math.min(179, deg)) * Math.PI) / 360);
+    return toHalf(worldFov) / toHalf(viewmodelFov);
+}

package/dist/devtools/warnOnce.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Logs a dev-mode `console.warn` once per `site`, and never in a production build. Reach for it
+ * where a permissive config would otherwise fail silently — a clipped sky dome, an ignored tint.
+ * @capability warn-once emit a dev-only warning a single time per call site
+ */
+export declare function warnOnce(site: string, message: string): void;
+/** Clears the once-per-site record so a test can observe the warning again. @internal */
+export declare function resetWarnOnce(): void;

package/dist/devtools/warnOnce.js

@@ -0,0 +1,18 @@
+import { isProductionEnvironment } from "./saveEndpoint.js";
+const warned = new Set();
+/**
+ * Logs a dev-mode `console.warn` once per `site`, and never in a production build. Reach for it
+ * where a permissive config would otherwise fail silently — a clipped sky dome, an ignored tint.
+ * @capability warn-once emit a dev-only warning a single time per call site
+ */
+export function warnOnce(site, message) {
+    if (warned.has(site) || isProductionEnvironment())
+        return;
+    warned.add(site);
+    const host = globalThis;
+    host.console?.warn?.(message);
+}
+/** Clears the once-per-site record so a test can observe the warning again. @internal */
+export function resetWarnOnce() {
+    warned.clear();
+}

package/dist/editor/document.js

@@ -19,6 +19,8 @@ function cloneEnvironment(environment) {
         ...(environment.zenithColor === undefined ? {} : { zenithColor: environment.zenithColor }),
         ...(environment.sunIntensity === undefined ? {} : { sunIntensity: environment.sunIntensity }),
         ...(environment.ambientIntensity === undefined ? {} : { ambientIntensity: environment.ambientIntensity }),
+        ...(environment.sunAzimuth === undefined ? {} : { sunAzimuth: environment.sunAzimuth }),
+        ...(environment.sunElevation === undefined ? {} : { sunElevation: environment.sunElevation }),
         ...(environment.fog === undefined ? {} : { fog: { ...environment.fog } }),
     };
 }
@@ -1082,7 +1084,7 @@ function decodeEnvironment(value, path, errors) {
             failed = true;
         }
     }
-    for (const key of ["sunIntensity", "ambientIntensity"]) {
+    for (const key of ["sunIntensity", "ambientIntensity", "sunAzimuth", "sunElevation"]) {
         if (value[key] === undefined)
             continue;
         if (typeof value[key] === "number" && Number.isFinite(value[key]))

package/dist/editor/environment.js

@@ -25,6 +25,14 @@ 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 } }),
     };
 }

package/dist/editor/types.d.ts

@@ -219,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. */

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;
@@ -170,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;
@@ -446,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/events.d.ts

@@ -236,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 {

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

@@ -6,6 +6,8 @@ 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";
@@ -22,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). */
@@ -236,17 +245,14 @@ 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;
-        };
-    };
+    /**
+     * 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. */
@@ -254,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;
@@ -328,7 +353,7 @@ 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`. */
+/** 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";
@@ -355,6 +380,35 @@ export interface FlightConfig {
     /** 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. */
@@ -379,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. */
@@ -393,8 +454,8 @@ export interface PlayerMovementConfig {
      * 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
+     * (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;
@@ -537,6 +598,12 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     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). */

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 {