@jgengine/core 0.10.0 → 0.11.0

package/dist/game/objectives.js

@@ -0,0 +1,36 @@
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+/**
+ * Evaluate a single live-metric objective: is `value` at least (or at most) the target, and how far along.
+ * Unlike an event counter, this reads a continuously-changing metric — population, approval, pollution —
+ * the objective shape city-builders and management sims track every tick.
+ *
+ * @capability objectives check progress of a threshold objective against a live metric
+ */
+export function evaluateObjective(objective, value) {
+    const direction = objective.direction ?? "atLeast";
+    const target = objective.target;
+    let met;
+    let progress;
+    if (direction === "atMost") {
+        met = value <= target;
+        progress = met ? 1 : target <= 0 ? 0 : clamp01(target / value);
+    }
+    else {
+        met = value >= target;
+        progress = met ? 1 : target <= 0 ? 1 : clamp01(value / target);
+    }
+    return { id: objective.id, value, target, direction, met, progress };
+}
+/**
+ * Evaluate every objective against current metric values (a lookup map or function) and roll them up into
+ * a met-count, completion flag, and mean progress — the brief/charter panel every sim renders.
+ */
+export function evaluateObjectives(objectives, values) {
+    const lookup = typeof values === "function" ? values : (id) => values[id] ?? 0;
+    const statuses = objectives.map((objective) => evaluateObjective(objective, lookup(objective.id)));
+    const met = statuses.filter((status) => status.met).length;
+    const progress = statuses.length === 0 ? 1 : statuses.reduce((sum, s) => sum + s.progress, 0) / statuses.length;
+    return { statuses, met, total: statuses.length, complete: met === statuses.length, progress };
+}

package/dist/game/paramLayers.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Layered numeric parameter modifiers over a caller-owned schema.
+ *
+ * A {@link ParamLayer} is a named, serializable bundle of transforms ({@link ParamOp}) keyed by
+ * parameter name. {@link resolveParams} folds an ordered stack of layers over a base value map and
+ * returns a deterministic {@link ParamSnapshot} — the effective values plus a full provenance trace
+ * of every op that touched each parameter. Layers order by ascending `priority` (ties broken by
+ * active-list index, a stable sort), and within a layer a parameter's ops fold left-to-right, so the
+ * stacking order is fully well-defined and reproducible.
+ *
+ * The primitive is genre-agnostic: difficulty tiers, game modes, mutators, accessibility presets,
+ * events, NG+, server rules, and challenge runs are all just ordered layers over different schemas.
+ * Save files store a {@link LayerSelection} (ordered layer ids); a {@link LayerRegistry} resolves
+ * those ids back to layers and reports unknown ids so migration and unknown saved content degrade
+ * gracefully rather than throwing.
+ */
+import { type Curve } from "./progression.js";
+/**
+ * A single transform applied to one numeric parameter. `set` overrides, `add`/`multiply` accumulate,
+ * `clamp` bounds, and `curve` remaps the running value through a {@link Curve} (the same curve
+ * primitive progression tracks use), so a caller can reshape a value non-linearly mid-stack.
+ */
+export type ParamOp = {
+    readonly kind: "set";
+    readonly value: number;
+} | {
+    readonly kind: "add";
+    readonly value: number;
+} | {
+    readonly kind: "multiply";
+    readonly value: number;
+} | {
+    readonly kind: "clamp";
+    readonly min?: number;
+    readonly max?: number;
+} | {
+    readonly kind: "curve";
+    readonly curve: Curve;
+};
+/** Per-parameter ops contributed by one layer — a single op or an ordered list folded in sequence. */
+export type LayerOps = Readonly<Record<string, ParamOp | readonly ParamOp[]>>;
+/**
+ * A named, serializable bundle of parameter transforms with a stable id and precedence. `label` is an
+ * optional display name that may intentionally differ from the applied ops (e.g. a tier shown as
+ * "Mayhem 4" whose real multipliers are data). Higher `priority` applies later — on top — and ties
+ * break by the layer's index in the active list, so ordering is deterministic.
+ */
+export interface ParamLayer {
+    readonly id: string;
+    readonly label?: string;
+    /** Higher applies later (stacks on top). Ties break by active-list index. Default `0`. */
+    readonly priority?: number;
+    readonly ops: LayerOps;
+}
+/** One recorded fold step — which layer's op ran and the value before/after. Contribution provenance. */
+export interface ParamContribution {
+    readonly layerId: string;
+    readonly op: ParamOp;
+    readonly from: number;
+    readonly to: number;
+}
+/** A resolved effective-parameter snapshot: final `values` plus the ordered op trace per parameter. */
+export interface ParamSnapshot {
+    readonly values: Readonly<Record<string, number>>;
+    readonly contributions: Readonly<Record<string, readonly ParamContribution[]>>;
+}
+/** A serializable, ordered reference to layers by stable id — what a save file or session setup stores. */
+export type LayerSelection = readonly string[];
+/** A single conflict surfaced by {@link validateLayers}. */
+export interface LayerConflict {
+    readonly kind: "duplicate-id" | "set-conflict";
+    /** The affected parameter, for `set-conflict`. */
+    readonly param?: string;
+    readonly layerIds: readonly string[];
+}
+/** One parameter's change between two value maps, for preview/diff surfaces. */
+export interface ParamDelta {
+    readonly param: string;
+    readonly from: number;
+    readonly to: number;
+    readonly delta: number;
+}
+/**
+ * Order layers into their well-defined application sequence: ascending `priority`, ties broken by the
+ * layer's index in `layers` (a stable sort). Same input, same order, on every platform.
+ *
+ * @capability param-layers order active parameter layers into their deterministic application sequence
+ */
+export declare function orderLayers(layers: readonly ParamLayer[]): readonly ParamLayer[];
+/**
+ * Fold an ordered stack of layers over `base` and return the effective {@link ParamSnapshot}. Layers
+ * apply in {@link orderLayers} sequence; within a layer each parameter's ops fold left-to-right. Every
+ * op is recorded in `contributions` for provenance/preview. Parameters a layer introduces but `base`
+ * omits start from `0`. Pure and deterministic — no ambient randomness or time.
+ *
+ * @capability param-layers resolve base values plus ordered layers into an effective parameter snapshot
+ */
+export declare function resolveParams(base: Readonly<Record<string, number>>, layers: readonly ParamLayer[]): ParamSnapshot;
+/**
+ * Detect design conflicts in a layer set before resolving: duplicate ids, and competing `set` ops on
+ * the same parameter at the same priority (order-dependent, so worth surfacing). Returns an empty
+ * array when the set is clean, so callers can gate a difficulty/session build on it.
+ *
+ * @capability param-layers validate a layer set for duplicate ids and competing set-op conflicts
+ */
+export declare function validateLayers(layers: readonly ParamLayer[]): readonly LayerConflict[];
+/**
+ * Compute the per-parameter deltas between two value maps — the preview/diff of applying a change,
+ * for showing a player what a difficulty tier or mutator will do before they commit.
+ *
+ * @capability param-layers diff two parameter value maps into per-parameter deltas for preview
+ */
+export declare function diffParams(before: Readonly<Record<string, number>>, after: Readonly<Record<string, number>>): readonly ParamDelta[];
+/** Registered lookup of {@link ParamLayer}s by stable id, resolving serialized selections and unknowns. */
+export interface LayerRegistry {
+    register(layer: ParamLayer): void;
+    has(id: string): boolean;
+    get(id: string): ParamLayer | undefined;
+    all(): readonly ParamLayer[];
+    /**
+     * Resolve a saved {@link LayerSelection} to concrete layers in the given order, collecting any ids
+     * with no registered layer into `unknown` (dropped, never thrown) so migration and stale saves
+     * degrade gracefully.
+     */
+    resolve(ids: LayerSelection): {
+        readonly layers: readonly ParamLayer[];
+        readonly unknown: readonly string[];
+    };
+}
+/**
+ * Create a {@link LayerRegistry} — the registration seam difficulty tiers, mutators, and presets
+ * install into. Duplicate ids throw at registration; unknown ids at resolve time are reported, not
+ * fatal, which is what keeps saved sessions reproducible across content/version drift.
+ *
+ * @capability param-layers register parameter layers by stable id and resolve serialized selections
+ */
+export declare function createLayerRegistry(initial?: readonly ParamLayer[]): LayerRegistry;
+/**
+ * Reproducible session setup in one call: resolve a saved {@link LayerSelection} through a registry,
+ * fold the found layers over `base`, and return the snapshot alongside any unknown ids. The same
+ * base + registry + selection always yields the same snapshot.
+ *
+ * @capability param-layers resolve a saved layer selection into an effective snapshot with unknown-id report
+ */
+export declare function resolveSelection(base: Readonly<Record<string, number>>, registry: LayerRegistry, ids: LayerSelection): {
+    readonly snapshot: ParamSnapshot;
+    readonly unknown: readonly string[];
+};

package/dist/game/paramLayers.js

@@ -0,0 +1,185 @@
+/**
+ * Layered numeric parameter modifiers over a caller-owned schema.
+ *
+ * A {@link ParamLayer} is a named, serializable bundle of transforms ({@link ParamOp}) keyed by
+ * parameter name. {@link resolveParams} folds an ordered stack of layers over a base value map and
+ * returns a deterministic {@link ParamSnapshot} — the effective values plus a full provenance trace
+ * of every op that touched each parameter. Layers order by ascending `priority` (ties broken by
+ * active-list index, a stable sort), and within a layer a parameter's ops fold left-to-right, so the
+ * stacking order is fully well-defined and reproducible.
+ *
+ * The primitive is genre-agnostic: difficulty tiers, game modes, mutators, accessibility presets,
+ * events, NG+, server rules, and challenge runs are all just ordered layers over different schemas.
+ * Save files store a {@link LayerSelection} (ordered layer ids); a {@link LayerRegistry} resolves
+ * those ids back to layers and reports unknown ids so migration and unknown saved content degrade
+ * gracefully rather than throwing.
+ */
+import { evalCurve } from "./progression.js";
+function applyOp(value, op) {
+    switch (op.kind) {
+        case "set":
+            return op.value;
+        case "add":
+            return value + op.value;
+        case "multiply":
+            return value * op.value;
+        case "clamp": {
+            let next = value;
+            if (op.min !== undefined)
+                next = Math.max(op.min, next);
+            if (op.max !== undefined)
+                next = Math.min(op.max, next);
+            return next;
+        }
+        case "curve":
+            return evalCurve(op.curve, value);
+    }
+}
+/**
+ * Order layers into their well-defined application sequence: ascending `priority`, ties broken by the
+ * layer's index in `layers` (a stable sort). Same input, same order, on every platform.
+ *
+ * @capability param-layers order active parameter layers into their deterministic application sequence
+ */
+export function orderLayers(layers) {
+    return layers
+        .map((layer, index) => ({ layer, index }))
+        .sort((a, b) => (a.layer.priority ?? 0) - (b.layer.priority ?? 0) || a.index - b.index)
+        .map((entry) => entry.layer);
+}
+/**
+ * Fold an ordered stack of layers over `base` and return the effective {@link ParamSnapshot}. Layers
+ * apply in {@link orderLayers} sequence; within a layer each parameter's ops fold left-to-right. Every
+ * op is recorded in `contributions` for provenance/preview. Parameters a layer introduces but `base`
+ * omits start from `0`. Pure and deterministic — no ambient randomness or time.
+ *
+ * @capability param-layers resolve base values plus ordered layers into an effective parameter snapshot
+ */
+export function resolveParams(base, layers) {
+    const values = { ...base };
+    const contributions = {};
+    for (const layer of orderLayers(layers)) {
+        for (const [param, opOrList] of Object.entries(layer.ops)) {
+            const ops = Array.isArray(opOrList) ? opOrList : [opOrList];
+            let current = values[param] ?? 0;
+            const trace = (contributions[param] ??= []);
+            for (const op of ops) {
+                const next = applyOp(current, op);
+                trace.push({ layerId: layer.id, op, from: current, to: next });
+                current = next;
+            }
+            values[param] = current;
+        }
+    }
+    return { values, contributions };
+}
+/**
+ * Detect design conflicts in a layer set before resolving: duplicate ids, and competing `set` ops on
+ * the same parameter at the same priority (order-dependent, so worth surfacing). Returns an empty
+ * array when the set is clean, so callers can gate a difficulty/session build on it.
+ *
+ * @capability param-layers validate a layer set for duplicate ids and competing set-op conflicts
+ */
+export function validateLayers(layers) {
+    const conflicts = [];
+    const counts = new Map();
+    for (const layer of layers)
+        counts.set(layer.id, (counts.get(layer.id) ?? 0) + 1);
+    for (const [id, count] of counts) {
+        if (count > 1)
+            conflicts.push({ kind: "duplicate-id", layerIds: [id] });
+    }
+    const setters = new Map();
+    for (const layer of layers) {
+        const priority = layer.priority ?? 0;
+        for (const [param, opOrList] of Object.entries(layer.ops)) {
+            const ops = Array.isArray(opOrList) ? opOrList : [opOrList];
+            if (!ops.some((op) => op.kind === "set"))
+                continue;
+            const existing = setters.get(param);
+            if (existing)
+                existing.push({ layerId: layer.id, priority });
+            else
+                setters.set(param, [{ layerId: layer.id, priority }]);
+        }
+    }
+    for (const [param, entries] of setters) {
+        const byPriority = new Map();
+        for (const entry of entries) {
+            const bucket = byPriority.get(entry.priority);
+            if (bucket)
+                bucket.add(entry.layerId);
+            else
+                byPriority.set(entry.priority, new Set([entry.layerId]));
+        }
+        for (const ids of byPriority.values()) {
+            if (ids.size > 1)
+                conflicts.push({ kind: "set-conflict", param, layerIds: [...ids] });
+        }
+    }
+    return conflicts;
+}
+/**
+ * Compute the per-parameter deltas between two value maps — the preview/diff of applying a change,
+ * for showing a player what a difficulty tier or mutator will do before they commit.
+ *
+ * @capability param-layers diff two parameter value maps into per-parameter deltas for preview
+ */
+export function diffParams(before, after) {
+    const params = new Set([...Object.keys(before), ...Object.keys(after)]);
+    const deltas = [];
+    for (const param of [...params].sort()) {
+        const from = before[param] ?? 0;
+        const to = after[param] ?? 0;
+        if (from !== to)
+            deltas.push({ param, from, to, delta: to - from });
+    }
+    return deltas;
+}
+/**
+ * Create a {@link LayerRegistry} — the registration seam difficulty tiers, mutators, and presets
+ * install into. Duplicate ids throw at registration; unknown ids at resolve time are reported, not
+ * fatal, which is what keeps saved sessions reproducible across content/version drift.
+ *
+ * @capability param-layers register parameter layers by stable id and resolve serialized selections
+ */
+export function createLayerRegistry(initial) {
+    const layers = new Map();
+    const register = (layer) => {
+        if (layers.has(layer.id))
+            throw new Error(`param layer "${layer.id}" is already registered`);
+        layers.set(layer.id, layer);
+    };
+    if (initial)
+        for (const layer of initial)
+            register(layer);
+    return {
+        register,
+        has: (id) => layers.has(id),
+        get: (id) => layers.get(id),
+        all: () => [...layers.values()],
+        resolve(ids) {
+            const resolved = [];
+            const unknown = [];
+            for (const id of ids) {
+                const layer = layers.get(id);
+                if (layer)
+                    resolved.push(layer);
+                else
+                    unknown.push(id);
+            }
+            return { layers: resolved, unknown };
+        },
+    };
+}
+/**
+ * Reproducible session setup in one call: resolve a saved {@link LayerSelection} through a registry,
+ * fold the found layers over `base`, and return the snapshot alongside any unknown ids. The same
+ * base + registry + selection always yields the same snapshot.
+ *
+ * @capability param-layers resolve a saved layer selection into an effective snapshot with unknown-id report
+ */
+export function resolveSelection(base, registry, ids) {
+    const { layers, unknown } = registry.resolve(ids);
+    return { snapshot: resolveParams(base, layers), unknown };
+}

package/dist/game/ping.d.ts

@@ -64,4 +64,9 @@ export interface PingSystem {
     /** Classify → build → broadcast in one call; the ping verb. */
     ping(from: string, hit: PointerHit, category?: PingCategory): PingPayload;
 }
+/**
+ * Contextual ping/marker communication between teammates, classified by what was pinged.
+ *
+ * @capability ping-wheel contextual ping/marker communication between teammates
+ */
 export declare function createPingSystem(deps: PingSystemDeps): PingSystem;

package/dist/game/ping.js

@@ -33,6 +33,11 @@ export function classifyPing(hit, deps = {}, options = {}) {
 function categoryDef(categories, category) {
     return categories[category] ?? { id: category, markerKind: category, label: category, callout: category };
 }
+/**
+ * Contextual ping/marker communication between teammates, classified by what was pinged.
+ *
+ * @capability ping-wheel contextual ping/marker communication between teammates
+ */
 export function createPingSystem(deps) {
     const now = deps.now ?? Date.now;
     const categories = deps.categories ?? DEFAULT_PING_CATEGORIES;

package/dist/game/playableGame.d.ts

@@ -1,6 +1,7 @@
 import type { AudioBusDef, SoundDef } from "../audio/audioFalloff.js";
 import type { MusicTheme } from "../audio/music.js";
 import type { PostProcessingConfig } from "../render/postProcessing.js";
+import type { LookPreset } from "../render/lookPreset.js";
 import type { TouchControlsConfig } from "../input/touchScheme.js";
 import type { GameSettingsConfig } from "../settings/settingsModel.js";
 import type { GameOrientation } from "../ui/orientation.js";
@@ -50,6 +51,10 @@ export interface CameraFollowState {
     };
     distance: number;
 }
+/** Props handed to a `WorldOverlay` component (#542): explicit `ctx` access so canvas-layer VFX read live engine state directly, without an extra hook or a module-global workaround. */
+export interface WorldOverlayProps {
+    ctx: GameContext;
+}
 export interface FirstPersonCameraConfig {
     /** Camera height above the followed entity's origin. Default 1.6. */
     eyeHeight?: number;
@@ -59,7 +64,7 @@ export interface FirstPersonCameraConfig {
     maxPitch?: number;
     /** Show the centered crosshair overlay. Default true. */
     reticle?: boolean;
-    /** Render a simple first-person weapon in view. Default true. */
+    /** Render a viewmodel in view: the built-in three-mesh gun, or `PlayableGame.viewmodel` when set (#542). `false` renders no viewmodel regardless of `PlayableGame.viewmodel`. Default true. */
     viewmodel?: boolean;
 }
 /**
@@ -77,7 +82,7 @@ export interface FirstPersonCameraConfig {
  * - `observer` — detached spectator/photo cam bound to any entity or fixed point; never reads player input.
  * - `turntable` — slow auto-orbit of a fixed point: a rotating display stand for a scene. The friendly, flat spelling of `observer`'s point-orbit mode; providing `camera.turntable` selects it without an explicit `rig`.
  * - `sideScroll` — fixed lateral follow (2.5D platformer/beat-'em-up side view); reads no player input.
- * - `inspection` — model-viewer rig (#207.7): left-drag orbit, middle/right-drag pan, scroll zoom toward a configurable anchor; orbits a fixed point, reads no player/entity input.
+ * - `inspection` — model-viewer / editor rig (#207.7, #866): middle-drag pan, right-drag orbit, scroll zoom toward a configurable anchor; orbits a fixed point, reads no player/entity input.
  * - `none` — no camera rig is mounted; use for HUD-only presentations or a game that manages its own camera.
  */
 export type CameraRigKind = "orbit" | "first" | "topDown" | "rts" | "shoulder" | "lockOn" | "chase" | "observer" | "turntable" | "sideScroll" | "inspection" | "none";
@@ -326,7 +331,7 @@ export interface InspectionCameraConfig {
     /** Vertical orbit clamp (radians). Unset allows a full pole-to-pole orbit, unlike the tighter default on the classic orbit rig. */
     minPolarAngle?: number;
     maxPolarAngle?: number;
-    /** Middle-mouse/right-drag pan. Default true for this rig. */
+    /** Middle-mouse pan. Default true for this rig. */
     pan?: boolean;
     rotateSpeed?: number;
     zoomSpeed?: number;
@@ -441,6 +446,10 @@ export interface GameCameraConfig {
     };
     initialDistance?: number;
     initialHeight?: number;
+    /** Initial horizontal boom facing (radians): 0 = camera behind on -Z, PI = camera on +Z. Seeds the orbit rig; unset keeps the legacy -Z placement. */
+    initialYaw?: number;
+    /** Initial boom elevation (radians): 0 = level, positive = camera above the target looking down. Seeds the orbit rig; unset derives elevation from `initialHeight`/`initialDistance`. */
+    initialPitch?: number;
     /** Lock orbit radius while the follow target moves (default true in shell). */
     followLock?: boolean;
     /** When false, orbit target stays fixed (cinematic / debug). Default true. */
@@ -458,6 +467,8 @@ export interface GameCameraConfig {
     /** Vertical look clamp (three.js polar angle, radians): 0 = top-down over the head, PI/2 = level, >PI/2 = look up from below. Widen for top-down or vertical aim; unset keeps the standard chase feel. */
     minPolarAngle?: number;
     maxPolarAngle?: number;
+    /** Signed boom-elevation clamp `[min, max]` (radians): min < 0 dips the camera below the target, max > 0 rises overhead. Maps onto `minPolarAngle`/`maxPolarAngle` (polar = PI/2 − pitch); explicit polar fields win. */
+    pitchClamp?: readonly [number, number];
     /** Spring-arm occlusion for the orbit rig: pull the camera in past walls/terrain so it never clips inside geometry. Off unless `enabled`. */
     collision?: {
         enabled?: boolean;
@@ -538,6 +549,17 @@ export interface ModelAnimationConfig {
      */
     oneShots?: Record<string, string | readonly string[]>;
 }
+/**
+ * Real PBR map URLs (e.g. `buildMaterialCatalog(...).resolve(id)!.maps` from `@jgengine/assets`)
+ * layered onto a model's material — the seam for texturing an otherwise-flat/untextured GLB. Any
+ * role may be omitted to keep the model's own map.
+ */
+export interface ModelMaterialMaps {
+    color?: string;
+    normal?: string;
+    roughness?: string;
+    ao?: string;
+}
 /** Per-entity PBR material override (#151.3) applied to every `MeshStandardMaterial` in the model's cloned scene graph. */
 export interface ModelMaterialOverride {
     color?: string;
@@ -545,6 +567,8 @@ export interface ModelMaterialOverride {
     roughness?: number;
     emissive?: string;
     emissiveIntensity?: number;
+    /** Real PBR texture maps applied over the model's material — see {@link ModelMaterialMaps}. */
+    maps?: ModelMaterialMaps;
 }
 /** Parents a prop/weapon model to a named bone or node on the host model's rig — a sword on `handslot.r`, a spellbook offhand — following the bone's animated transform each frame. */
 export interface ModelAttachment {
@@ -559,6 +583,17 @@ export interface ModelAttachment {
     /** Uniform scale of the attached model at the bone. Default 1. */
     scale?: number;
 }
+/** Static child model stacked at a fixed local offset under its parent's transform — no bone/rig resolution, unlike `ModelAttachment`. Assembles a compound entity (e.g. a modular castle wall + tower + roof) from several single-mesh kit pieces. */
+export interface ModelPart {
+    /** The child model — a catalog asset id or an inline `ModelConfig`; resolves through the catalog exactly like the top-level model and gets its own `dims`/anchor centering. */
+    model: string | ModelConfig;
+    /** Local position offset under the parent's transform. */
+    position?: [number, number, number];
+    /** Local Euler rotation (radians) under the parent's transform. */
+    rotation?: [number, number, number];
+    /** Uniform scale of the part under the parent's transform. Default 1. */
+    scale?: number;
+}
 export interface ModelConfig {
     url: string;
     scale?: number;
@@ -575,6 +610,8 @@ export interface ModelConfig {
     animation?: ModelAnimationConfig;
     /** 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. */
+    parts?: readonly ModelPart[];
 }
 export interface ObjectStyle {
     color?: string;
@@ -637,6 +674,18 @@ export interface PlayerMovementConfig {
     beforeCommit?: (frame: MovementCommitFrame) => readonly [number, number, number] | undefined | void;
     /** Gates the built-in sprint (`runSpeedMultiplier`) behind live game state — a stamina stat, an encumbrance check (#282.3). Called each frame while sprint is held; `false` walks. */
     canSprint?: (ctx: GameContext) => boolean;
+    /** Fraction of walk speed while backpedalling (holding `moveBack`). Overrides the engine default (0.65). */
+    backpedalMult?: number;
+    /** 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. */
+    swim?: {
+        speedMultiplier?: number;
+    } | boolean;
+    /** Slide the player downhill on terrain steeper than they can stand on (heightfield worlds only). `true` uses defaults; default off. */
+    slopeSlide?: {
+        maxClimbSlope?: number;
+    } | boolean;
 }
 /** One frame's movement resolution handed to `PlayerMovementConfig.beforeCommit`. */
 export interface MovementCommitFrame {
@@ -647,17 +696,36 @@ export interface MovementCommitFrame {
     /** The live game context (#282.2) — movement rules read stores/stats directly instead of module-level bridge objects. */
     ctx: GameContext;
 }
-export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEntity = never, TRenderObject = never> {
+/** How a screenshot host reaches live gameplay in this game — the data behind `shoot --mode play`. */
+export interface GameCaptureConfig {
+    /** Commands run (in order, via `ctx.game.commands.run`) right after boot when a capture host requests the play screen — the same commands the start-menu buttons dispatch. A bare string runs with a default input; the object form carries the input a command needs (e.g. `[{ name: "class.select", input: { classId: "siren" } }, "startRun"]`). A name the game never registers fails the capture loudly instead of shipping a menu screenshot. */
+    play?: readonly (string | {
+        name: string;
+        input?: unknown;
+    })[];
+    /** Named capture states beyond live gameplay — any screen worth screenshotting on demand (`lobby`, `store`, `game_over`), each mapping to the command sequence that reaches it from boot. `shoot <game> --state <name>` runs that sequence and captures whatever is on screen — menus included, no live-play guard. An unknown state name fails the capture with the declared list. */
+    states?: Record<string, readonly (string | {
+        name: string;
+        input?: unknown;
+    })[]>;
+    /** Extra milliseconds the capture host waits after `play` commands before taking the play-mode screenshot — cover an intro cinematic or spawn-in fade. Default 2500. */
+    settleMs?: number;
+    /** Bot-playtest read hook: maps live game state to a flat vector of numeric progress metrics the `drive --playtest` harness samples over time (e.g. `{ x, z, score, phase }`). Genre-agnostic — "progress" is whatever the game reports; the engine stays neutral. The harness watches these numbers move under scripted input: any metric changing beyond an epsilon counts as forward progress, all metrics flat past the softlock threshold under active input flags a softlock. Return every value that should count as advancing; omit to opt the game out of the playtest rung. */
+    probe?: (ctx: GameContext) => Record<string, number>;
+}
+export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEntity = never, TRenderObject = never, TViewmodel = unknown, TOverlay = TWorldOverlay> {
     game: GameDefinition;
     content: GameContextContent;
     loop: Required<Omit<GameLoop<GameContext>, "onPlayerLeave">> & Pick<GameLoop<GameContext>, "onPlayerLeave">;
     GameUI: TUi;
     /** Which shell mount to use. Default `"3d"` (canvas, camera rig, pointer, world rendering). `"hud"` mounts no 3D canvas, camera rig, or pointer — the game is `GameUI` plus the command/input loop, for board/card/menu games. */
     presentation?: "3d" | "hud";
-    /** Optional canvas-layer VFX component (e.g. traveling projectiles). */
-    WorldOverlay?: TWorldOverlay;
+    /** 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;
+    /** Custom first-person viewmodel (#542), read when the active rig is first-person. Rendered inside the shell's camera-locked, muzzle-tracked anchor in place of the built-in three-mesh gun; receives a live `cuesRef` (velocity/bob/firing/reloading/recoil) driven from the followed entity — see `@jgengine/shell/camera`'s `ViewmodelProps`. Set `camera.firstPerson.viewmodel: false` to render no viewmodel at all regardless of this field. */
+    viewmodel?: TViewmodel;
     /** Per-entity visual override: return your own mesh for an entity and the shell still positions it and drives selection/targeting. Return null/undefined to fall back to model → sprite → primitive. */
     renderEntity?: TRenderEntity;
     /** Per-object visual override: return your own mesh for a placed scene object and the shell still positions it and drives picking. Return null/undefined to fall back to objectModels → styled box. */
@@ -676,6 +744,8 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     prompts?: (ctx: GameContext) => readonly PositionedPrompt[];
     /** Camera tuning (perspective, orbit, first-person) for the dev game player shell. */
     camera?: GameCameraConfig;
+    /** Screenshot-host recipe for reaching live gameplay past a start menu (`shoot --mode play` runs `capture.play` automatically). Any game with a start/title screen declares this. */
+    capture?: GameCaptureConfig;
     /** Cast/receive shadows across the scene (R3F Canvas shadow pass). Default true. */
     shadows?: boolean;
     /** Pointer-driven input: click-to-move, box-select, right-click verbs, cursor aim (#22/#30/#31). */
@@ -694,6 +764,19 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
         roles?: readonly CatalogEntityRole[];
         maxDistance?: number;
     };
+    /**
+     * Opt in to billboarded nameplates (name + optional HP bar) floating over non-local entities — the
+     * MMO "who's this and how hurt are they" readout. `roles` restricts to entities whose catalog entry
+     * declares one of the given roles (default: all); `maxDistance` hides nameplates beyond this many
+     * world units from the player (default 40). Headless: skin every part via `className`/`data-*` hooks
+     * on `WorldNameplates` (`@jgengine/shell/world/WorldHud`) — this flag only turns the readout on and
+     * scopes which entities it covers.
+     */
+    nameplates?: boolean | {
+        statId?: string;
+        roles?: readonly CatalogEntityRole[];
+        maxDistance?: number;
+    };
     /** Sound catalog + mix buses (music/sfx/ambient/…) the shell's Web Audio glue plays from. Catalog-first — no per-game audio wiring. `sounds` may be sample (`url`) or procedural (`synth`); `music` holds procedural themes crossfaded via `ctx.game.audio.music(id)`. */
     audio?: {
         sounds: Record<string, SoundDef>;
@@ -711,13 +794,15 @@ 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. */
+    look?: LookPreset;
     /** Declarative ambient/directional/hemisphere lighting (#207.5); replaces the shell's hardcoded default lights when present, regardless of world kind. */
     lighting?: LightingConfig;
     /** 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). */
     postProcessing?: PostProcessingConfig;
-    /** F2 debug overlay (frame/sim timing, logs, backend latency, keybinds, live tunables). On for every game by default; `false` disables the toggle. */
+    /** F2+D debug overlay (frame/sim timing, logs, backend latency, keybinds, live tunables). On for every game by default; `false` disables the toggle. */
     devtools?: boolean;
     /** Player settings menu. Auto-mounted for every game (Sound / Graphics / Gameplay / Controls); unset uses the defaults, `false` opts out. Add game-specific rows via `extra`, switch overlay/full-page via `mode`, or swap the gear for compact on-screen buttons via `surface: "quick"`. */
     settings?: GameSettingsConfig | false;

package/dist/game/quest.d.ts

@@ -89,7 +89,15 @@ export interface QuestJournal {
     bind(action: "entity.died" | "inventory.added"): () => void;
     snapshot(userId: string): QuestSnapshotEntry[];
     hydrate(userId: string, data: QuestSnapshotEntry[]): void;
+    /** Whole-store capture across every user — the world-save/replication seam (per-user `snapshot` can't enumerate users). */
+    snapshotAll(): Record<string, QuestSnapshotEntry[]>;
+    hydrateAll(data: Record<string, QuestSnapshotEntry[]>): void;
 }
+/**
+ * Track accepted quests and their per-objective progress, granting rewards on completion.
+ *
+ * @capability quest-log track accepted quests and their per-objective progress
+ */
 export declare function createQuestJournal(deps: QuestJournalDeps): QuestJournal;
 export interface QuestAcceptOptions {
     hasUnlock?(id: string): boolean;