@jgengine/core 0.7.0 → 0.9.0

package/dist/game/gamePhase.d.ts

@@ -0,0 +1,20 @@
+import type { GameContext } from "../runtime/gameContext.js";
+/**
+ * Canonical run phase every game moves through. `menu` (title/main menu),
+ * `playing` (live), `paused` (mid-run pause), `ended` (win/lose/results).
+ * Touch controls are shown only while `playing`; menus and results never paint
+ * the touch dock over themselves.
+ */
+export type GamePhase = "menu" | "playing" | "paused" | "ended";
+export declare const GAME_PHASE_STORE_KEY = "jg.phase";
+/**
+ * Set the current phase. Publishes it to `ctx.game.store` (React reads it via
+ * `useGamePhase`) and gates the shell's on-screen touch controls in one call —
+ * `playing` shows them, every other phase hides them. This is the whole
+ * "main menu shouldn't show touch controls" wiring: call it once per phase
+ * transition and the dock follows.
+ */
+export declare function setGamePhase(ctx: GameContext, phase: GamePhase): void;
+/** Current phase; defaults to `playing` when unset so always-live games need no wiring. */
+export declare function gamePhase(ctx: GameContext): GamePhase;
+export declare function isPlaying(ctx: GameContext): boolean;

package/dist/game/gamePhase.js

@@ -0,0 +1,21 @@
+import { setPlayControlsActive } from "./controlGate.js";
+export const GAME_PHASE_STORE_KEY = "jg.phase";
+/**
+ * Set the current phase. Publishes it to `ctx.game.store` (React reads it via
+ * `useGamePhase`) and gates the shell's on-screen touch controls in one call —
+ * `playing` shows them, every other phase hides them. This is the whole
+ * "main menu shouldn't show touch controls" wiring: call it once per phase
+ * transition and the dock follows.
+ */
+export function setGamePhase(ctx, phase) {
+    ctx.game.store.set(GAME_PHASE_STORE_KEY, phase);
+    setPlayControlsActive(ctx, phase === "playing");
+}
+/** Current phase; defaults to `playing` when unset so always-live games need no wiring. */
+export function gamePhase(ctx) {
+    const value = ctx.game.store.get(GAME_PHASE_STORE_KEY);
+    return value === "menu" || value === "paused" || value === "ended" ? value : "playing";
+}
+export function isPlaying(ctx) {
+    return gamePhase(ctx) === "playing";
+}

package/dist/game/levelSequence.d.ts

@@ -0,0 +1,44 @@
+export interface LevelDescriptor<TLevelConfig> {
+    id: string;
+    config: TLevelConfig;
+}
+export interface LevelSequenceConfig<TLevelConfig> {
+    levels: readonly LevelDescriptor<TLevelConfig>[];
+    /** Extra attempts granted after the first per level. Defaults to 0 (a single attempt, no retries). */
+    retriesPerLevel?: number;
+}
+export type LevelSequenceStatus = "idle" | "playing" | "cleared" | "failed" | "complete";
+export interface CurrentLevel<TLevelConfig> {
+    id: string;
+    index: number;
+    config: TLevelConfig;
+    attempt: number;
+}
+export interface LevelSequenceProgress {
+    index: number;
+    total: number;
+    cleared: readonly string[];
+}
+export interface LevelSequence<TLevelConfig> {
+    current(): CurrentLevel<TLevelConfig> | null;
+    status(): LevelSequenceStatus;
+    /** Enters level 0. A no-op on an empty level list, which leaves `status()` at "idle" forever. */
+    start(): void;
+    /** Marks the current level cleared; call `advance()` to move to the next one. */
+    clear(): void;
+    /** Consumes an attempt on the current level. Returns "retry" while attempts remain, else "failed". */
+    fail(): "retry" | "failed";
+    /** Restarts the current level after a "retry"-eligible failure. Returns false if there was nothing to retry. */
+    retry(): boolean;
+    /** Moves past a cleared level, or to "complete" if it was the last one. Returns false unless status is "cleared". */
+    advance(): boolean;
+    reset(): void;
+    progress(): LevelSequenceProgress;
+}
+/**
+ * A pure, deterministic level campaign: an ordered list of levels, each with its own opaque config, played
+ * through a `start` → (`clear` → `advance`)* → `complete` happy path, with `fail`/`retry` handling per-level
+ * attempts. Mirrors the reducer style of `game/race.ts` and `ai/spawnDirector.ts` — no I/O, no timers, just
+ * state transitions driven by the caller.
+ */
+export declare function createLevelSequence<TLevelConfig>(config: LevelSequenceConfig<TLevelConfig>): LevelSequence<TLevelConfig>;

package/dist/game/levelSequence.js

@@ -0,0 +1,78 @@
+/**
+ * A pure, deterministic level campaign: an ordered list of levels, each with its own opaque config, played
+ * through a `start` → (`clear` → `advance`)* → `complete` happy path, with `fail`/`retry` handling per-level
+ * attempts. Mirrors the reducer style of `game/race.ts` and `ai/spawnDirector.ts` — no I/O, no timers, just
+ * state transitions driven by the caller.
+ */
+export function createLevelSequence(config) {
+    const levels = config.levels;
+    const maxAttempts = 1 + Math.max(0, Math.floor(config.retriesPerLevel ?? 0));
+    let index = 0;
+    let attempt = 1;
+    let status = "idle";
+    const clearedIds = [];
+    function current() {
+        if (status === "idle" || status === "complete")
+            return null;
+        const level = levels[index];
+        if (level === undefined)
+            return null;
+        return { id: level.id, index, config: level.config, attempt };
+    }
+    return {
+        current,
+        status: () => status,
+        start() {
+            if (levels.length === 0)
+                return;
+            index = 0;
+            attempt = 1;
+            clearedIds.length = 0;
+            status = "playing";
+        },
+        clear() {
+            if (status !== "playing" || current() === null)
+                return;
+            clearedIds.push(levels[index].id);
+            status = "cleared";
+        },
+        fail() {
+            if (status !== "playing" || current() === null)
+                return "failed";
+            status = "failed";
+            return attempt < maxAttempts ? "retry" : "failed";
+        },
+        retry() {
+            if (status !== "failed" || attempt >= maxAttempts)
+                return false;
+            attempt += 1;
+            status = "playing";
+            return true;
+        },
+        advance() {
+            if (status !== "cleared")
+                return false;
+            if (index >= levels.length - 1) {
+                status = "complete";
+                return true;
+            }
+            index += 1;
+            attempt = 1;
+            status = "playing";
+            return true;
+        },
+        reset() {
+            index = 0;
+            attempt = 1;
+            clearedIds.length = 0;
+            status = "idle";
+        },
+        progress() {
+            return {
+                index: status === "complete" ? levels.length : index,
+                total: levels.length,
+                cleared: [...clearedIds],
+            };
+        },
+    };
+}

package/dist/game/lootTable.d.ts

@@ -2,11 +2,20 @@ export interface LootEntry {
     item?: string;
     currency?: string;
     count: number | [number, number];
-    weight: number;
+    /** Relative pick weight — required in `"weighted"` mode, forbidden in `"independent"` mode. */
+    weight?: number;
+    /** Per-entry drop probability in `(0, 1]` — required in `"independent"` mode, forbidden in `"weighted"` mode. */
+    chance?: number;
 }
 export interface LootTableDef {
     id: string;
     rolls?: number;
+    /**
+     * `"weighted"` (default): each roll picks exactly one entry by relative `weight`.
+     * `"independent"`: each roll gives every entry its own `chance` — classic drop lists
+     * where a kill can yield several items (or nothing) without filler entries.
+     */
+    mode?: "weighted" | "independent";
     entries: LootEntry[];
 }
 export interface Drop {

package/dist/game/lootTable.js

@@ -1,11 +1,23 @@
-function assertValidEntry(entry) {
+function assertValidEntry(entry, mode) {
     const hasItem = entry.item !== undefined;
     const hasCurrency = entry.currency !== undefined;
     if (hasItem === hasCurrency) {
         throw new Error("loot entry must have exactly one of item or currency");
     }
-    if (!(entry.weight > 0)) {
-        throw new Error(`loot entry weight must be positive, got ${entry.weight}`);
+    if (mode === "weighted") {
+        if (entry.chance !== undefined) {
+            throw new Error("loot entry chance is only valid in independent mode");
+        }
+        if (entry.weight === undefined || !(entry.weight > 0)) {
+            throw new Error(`loot entry weight must be positive, got ${entry.weight}`);
+        }
+        return;
+    }
+    if (entry.weight !== undefined) {
+        throw new Error("loot entry weight is only valid in weighted mode");
+    }
+    if (entry.chance === undefined || !(entry.chance > 0) || entry.chance > 1) {
+        throw new Error(`loot entry chance must be in (0, 1], got ${entry.chance}`);
     }
 }
 function assertValidDef(def) {
@@ -13,7 +25,7 @@ function assertValidDef(def) {
         throw new Error(`loot table "${def.id}" must have at least one entry`);
     }
     for (const entry of def.entries)
-        assertValidEntry(entry);
+        assertValidEntry(entry, def.mode ?? "weighted");
 }
 function resolveCount(count, rng) {
     if (typeof count === "number")
@@ -22,10 +34,10 @@ function resolveCount(count, rng) {
     return min + Math.floor(rng() * (max - min + 1));
 }
 function pickEntry(entries, rng) {
-    const total = entries.reduce((sum, entry) => sum + entry.weight, 0);
+    const total = entries.reduce((sum, entry) => sum + (entry.weight ?? 0), 0);
     let roll = rng() * total;
     for (const entry of entries) {
-        roll -= entry.weight;
+        roll -= entry.weight ?? 0;
         if (roll < 0)
             return entry;
     }
@@ -56,7 +68,15 @@ export function createLootRegistry() {
             const rolls = table.rolls ?? 1;
             const drops = [];
             for (let i = 0; i < rolls; i++) {
-                drops.push(rollEntry(pickEntry(table.entries, rng), rng));
+                if (table.mode === "independent") {
+                    for (const entry of table.entries) {
+                        if (rng() < (entry.chance ?? 0))
+                            drops.push(rollEntry(entry, rng));
+                    }
+                }
+                else {
+                    drops.push(rollEntry(pickEntry(table.entries, rng), rng));
+                }
             }
             return drops;
         },

package/dist/game/playableGame.d.ts

@@ -1,7 +1,12 @@
 import type { AudioBusDef, SoundDef } from "../audio/audioFalloff.js";
+import type { TouchControlsConfig } from "../input/touchScheme.js";
+import type { GameSettingsConfig } from "../settings/settingsModel.js";
+import type { HudPlatform, HudViewportConfig } from "../ui/hudScale.js";
 import type { PositionedPrompt } from "../interaction/proximityPrompt.js";
-import type { GameContext, GameContextContent } from "../runtime/gameContext.js";
+import type { CatalogEntityRole, GameContext, GameContextContent } from "../runtime/gameContext.js";
 import type { ModelDims } from "../scene/assetCatalog.js";
+import type { SkyEnvironmentConfig } from "../world/features.js";
+import type { VisibilityConfig } from "../visibility/config.js";
 import type { GameDefinition, GameLoop } from "./defineGame.js";
 import type { LootFilterRule } from "./lootFilter.js";
 import type { RarityStyle } from "./worldItem.js";
@@ -25,6 +30,8 @@ export interface PointerConfig {
     grabWorldItems?: boolean;
     /** Press the bound `ping` action → `worldHit()` → run this command with `{ point, entity, object, normal }` (contextual ping, #94). */
     pingCommand?: string;
+    /** Right-click runs this command with `{ point, entity, object, aim }` when neither `orderCommand` nor `contextMenu` claims the click (#164.4). */
+    secondaryCommand?: string;
 }
 export interface CameraFollowState {
     entityId: string;
@@ -65,13 +72,33 @@ export interface FirstPersonCameraConfig {
  * - `lockOn` — yaw bound to the player→target vector; move axis becomes strafe.
  * - `chase` — speed-reactive vehicle chase (speed→FOV, spring arm, shake) + cockpit/hood/rear views.
  * - `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.
+ * - `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";
+export type CameraRigKind = "orbit" | "first" | "topDown" | "rts" | "shoulder" | "lockOn" | "chase" | "observer" | "turntable" | "sideScroll" | "inspection" | "none";
+/** Canvas camera projection. "orthographic" renders a flat 2D-style view (side-scrollers, falling-block puzzles) — pair with `rig: "sideScroll"`; default "perspective". */
+export type CameraProjection = "perspective" | "orthographic";
+/** Fixed lateral 2.5D follow (side-on platformer cam): the camera sits perpendicular to the travel axis, tracks the followed entity, and never reads player look input. */
+export interface SideScrollCameraConfig {
+    /** World axis the action travels along; the camera watches from the perpendicular side. Default "x". */
+    axis?: "x" | "z";
+    /** Camera distance from the followed entity along the perpendicular axis. Default 10. */
+    distance?: number;
+    /** Camera height above the followed entity. Default 3. */
+    height?: number;
+    /** Height of the look point above the entity. Default 1. */
+    lookHeight?: number;
+    /** Per-second smoothing factor for the follow (0 hard-locks). Default 8. */
+    followSmoothing?: number;
+    fov?: number;
+}
 /** Fixed top-down / isometric rig (#23) — height/pitch/yaw + decoupled follow. */
 export interface TopDownCameraConfig {
     /** Camera height above the follow point. Default 18. */
     height?: number;
-    /** Look-down angle in radians (0 = straight down, PI/2 = level). Default ~1.02 (~58°, ARPG iso). */
+    /** Elevation of the camera above the ground plane in radians (PI/2 = straight down, near 0 = grazing; values below 0.05 clamp to 0.05). Default ~1.02 (~58°, ARPG iso). */
     pitch?: number;
     /** Fixed azimuth in radians; ~PI/4 reads as isometric, 0 as straight top-down. Default PI/4. */
     yaw?: number;
@@ -113,6 +140,8 @@ export interface RtsCameraConfig extends TopDownCameraConfig {
         x?: number;
         z?: number;
     };
+    /** Read WASD/arrow pan, edge-scroll, Q/E rotate, and wheel zoom. `false` sits static at the start/bounds position — a backdrop camera, no input at all. Default true. */
+    pan?: boolean;
 }
 /** Over-the-shoulder combat rig (#25) — offset, ADS, shoulder swap, decoupled reticle. */
 export interface ShoulderCameraConfig {
@@ -178,6 +207,17 @@ export interface ChaseCameraConfig {
     };
     /** Procedural shake amplitude per unit of speed (adds to the trauma channel). Default 0.0. */
     shakePerSpeed?: number;
+    /** Velocity-lead / predictive follow (#286.9): the rig aims `time` seconds ahead of the target along its velocity, clamped to `max` world units (default 4). */
+    lead?: {
+        time: number;
+        max?: number;
+    };
+    /** Roll into turns (#286.10): radians of camera roll per rad/s of the target's yaw rate, clamped to `max` (default 0.35), exponentially smoothed by `damping` (default 8). */
+    bank?: {
+        perYawRate: number;
+        max?: number;
+        damping?: number;
+    };
     /** Which view to mount. Default "chase". */
     view?: ChaseView;
     /** Local offset for cockpit/hood/rear seats (relative to the vehicle, +z forward). */
@@ -225,6 +265,70 @@ export interface ObserverCameraConfig {
     startAngle?: number;
     fov?: number;
 }
+/**
+ * Turntable / showcase rig — slowly auto-orbits a fixed world point (no player
+ * input), the way a museum turntable rotates an object on display. A flat,
+ * self-describing spelling of `observer`'s point-orbit mode: `target` names the
+ * point directly instead of `bind: { kind: "point", position }`. Set
+ * `camera.turntable` and the rig is inferred — you don't also write `rig`.
+ */
+export interface TurntableCameraConfig {
+    /** World point the camera circles. Default the world origin. */
+    target?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Orbit radius from the target. Default 8. */
+    distance?: number;
+    /** Camera height above the target. Default 3. */
+    height?: number;
+    /** Height of the look point above the target. Default 1.2. */
+    lookHeight?: number;
+    /** Radians/second of rotation; 0 holds a fixed angle. Default 0.2. */
+    orbitSpeed?: number;
+    /** Starting angle in radians. Default 0. */
+    startAngle?: number;
+    fov?: number;
+}
+/**
+ * How scroll-zoom re-anchors the view for the inspection rig (#207.7):
+ * - `target` — dolly toward the orbit target (classic OrbitControls behavior).
+ * - `cursor` — dolly toward the point under the pointer.
+ * - `center` — dolly toward the viewport center; equivalent to `target` for an
+ *   OrbitControls-driven rig, since the camera always faces `target` and that
+ *   point already projects to the exact center of the viewport.
+ */
+export type InspectionZoomAnchor = "target" | "cursor" | "center";
+/** Model-viewer / inspection rig (#207.7) — orbit + pan + anchored zoom around a fixed point, never reads player input. */
+export interface InspectionCameraConfig {
+    /** Where scroll-zoom re-anchors the view. Default "target". */
+    anchor?: InspectionZoomAnchor;
+    /** Orbit target (the point orbited/panned around). Default origin. */
+    target?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    /** Camera distance from `target` used to seed the initial camera position when `initialPosition` is unset. Default 6. */
+    initialDistance?: number;
+    /** Explicit starting camera world position; overrides `initialDistance` when set. */
+    initialPosition?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    minDistance?: number;
+    maxDistance?: number;
+    /** 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. */
+    pan?: boolean;
+    rotateSpeed?: number;
+    zoomSpeed?: number;
+    dampingFactor?: number;
+}
 /** One stop on a scripted camera path (#29). */
 export interface CameraKeyframe {
     position: {
@@ -262,9 +366,39 @@ export interface CameraShakeConfig {
     /** Noise frequency (Hz) of the shake oscillation. Default 24. */
     frequency?: number;
 }
+export declare const CAMERA_FRUSTUM_DEFAULTS: {
+    readonly fov: 55;
+    readonly near: 0.1;
+    readonly far: 300;
+    readonly zoom: 50;
+};
+/** Player-facing FOV preference applied across every perspective camera rig. Orthographic projections ignore it. */
+export interface PlayerFovConfig {
+    /** Inclusive lower bound for the slider and persisted values. Default 40. */
+    min?: number;
+    /** Inclusive upper bound for the slider and persisted values. Default 120. */
+    max?: number;
+    /** Initial FOV when nothing is persisted. Defaults to `frustum.fov` or 55. */
+    default?: number;
+    /** Persist the preference in localStorage across reloads. Default true. */
+    persist?: boolean;
+    /** Show the shell FOV slider. Default true for perspective cameras; forced off for orthographic. */
+    control?: boolean;
+}
 export interface GameCameraConfig {
     /** Selects the rig. Overrides `perspective`; leave unset to fall back to `perspective`. */
     rig?: CameraRigKind;
+    /** Canvas camera projection. "orthographic" renders a flat 2D-style view (side-scrollers, falling-block puzzles) — pair with `rig: "sideScroll"`; default perspective. */
+    projection?: CameraProjection;
+    /** Render frustum overrides applied to the canvas camera. `far` defaults to 300 — raise it for worlds whose content spans more than a few hundred units, or distant scenery silently clips. `zoom` is the orthographic zoom in canvas pixels per world unit, read only when `projection` is "orthographic"; default 50. */
+    frustum?: {
+        fov?: number;
+        near?: number;
+        far?: number;
+        zoom?: number;
+    };
+    /** Universal player FOV preference (slider + persistence) for perspective rigs. Ignored when `projection` is `"orthographic"`. */
+    playerFov?: PlayerFovConfig;
     /** "third" mounts the orbit camera (default); "first" mounts pointer-lock mouse-look. Shorthand for `rig: "orbit" | "first"`. */
     perspective?: "third" | "first";
     /** First-person tuning; only read when the rig resolves to "first". */
@@ -281,6 +415,12 @@ export interface GameCameraConfig {
     chase?: ChaseCameraConfig;
     /** Detached spectator/photo cam tuning (#120); read when `rig: "observer"`. */
     observer?: ObserverCameraConfig;
+    /** Turntable / showcase tuning; setting this selects the `turntable` rig on its own. */
+    turntable?: TurntableCameraConfig;
+    /** Fixed side-on follow tuning; read when `rig: "sideScroll"`. */
+    sideScroll?: SideScrollCameraConfig;
+    /** Model-viewer / inspection tuning (#207.7); read when `rig: "inspection"`. */
+    inspection?: InspectionCameraConfig;
     /** Camera-shake / trauma channel defaults (#28); read by every rig. */
     shake?: CameraShakeConfig;
     /** Scripted keyframe path (#29); when set, plays over the active rig. */
@@ -331,6 +471,47 @@ export interface WorldItemRenderConfig {
     pickupRadius?: number;
     /** Beam height above the item's ground position. Default 2.5. */
     beamHeight?: number;
+    /** Walk-over collection: the shell grants the nearest dropped item within this radius of the local player each frame (Minecraft-style pickup). `true` uses `pickupRadius`. Omitted/false leaves pickup to `pointer.grabWorldItems` clicks. */
+    autoPickup?: boolean | {
+        radius?: number;
+    };
+}
+/**
+ * Player-vs-world collision for the first-person controller. Without this the
+ * shell keeps the player on flat ground at y=0. With `voxel: true` the shell
+ * resolves the player as a box against placed scene objects (each treated as a
+ * solid unit cell), so they stand on blocks, fall into holes, and are stopped by
+ * walls — the controller a block-building/mining game needs.
+ */
+export interface VoxelCollisionConfig {
+    voxel: true;
+    /** Half the player box width on each horizontal axis. Default 0.3. */
+    halfWidth?: number;
+    /** Player box height from the feet. Default 1.8. */
+    height?: number;
+    /** Tallest ledge walked up without jumping. Default 0.6. */
+    stepHeight?: number;
+}
+/** Rig playback for a `ModelConfig`'s GLTF animation clips — looping idles, one-shots, and held poses. */
+export interface ModelAnimationConfig {
+    /** Clip name to play; defaults to the GLB's first clip. */
+    clip?: string;
+    /** Loop the clip. Default true. */
+    loop?: boolean;
+    /** Playback rate multiplier. Default 1. */
+    timeScale?: number;
+    /** Hold the rig on a fixed frame instead of advancing it each tick. */
+    paused?: boolean;
+    /** Seek the clip to this time in seconds; combine with `paused: true` to hold a specific pose ("pose library" usage). */
+    time?: number;
+}
+/** Per-entity PBR material override (#151.3) applied to every `MeshStandardMaterial` in the model's cloned scene graph. */
+export interface ModelMaterialOverride {
+    color?: string;
+    metalness?: number;
+    roughness?: number;
+    emissive?: string;
+    emissiveIntensity?: number;
 }
 export interface ModelConfig {
     url: string;
@@ -340,35 +521,119 @@ export interface ModelConfig {
     anchor?: "center" | "origin";
     /** Measured footprint/center/minY; supplied automatically when the model resolves through an `@jgengine/assets` catalog. Required for `anchor: "center"` to take effect. */
     dims?: ModelDims;
+    /** Per-entity PBR tint/finish override (#151.3); cloned onto each `MeshStandardMaterial` in the model so shared GLTF caches stay untouched. */
+    material?: ModelMaterialOverride;
+    /** Plays a GLTF animation clip on the model when the source has any (skinned or not); omit to render the rig's bind pose. */
+    animation?: ModelAnimationConfig;
+}
+export interface ObjectStyle {
+    color?: string;
+    opacity?: number;
+    hidden?: boolean;
+}
+export interface AmbientLightingConfig {
+    color?: string;
+    intensity?: number;
+}
+export interface DirectionalLightingConfig {
+    color?: string;
+    intensity?: number;
+    position: readonly [number, number, number];
+    castShadow?: boolean;
+}
+export interface HemisphereLightingConfig {
+    skyColor?: string;
+    groundColor?: string;
+    intensity?: 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[];
+    hemisphere?: HemisphereLightingConfig;
+}
+export interface BackdropFogConfig {
+    color?: string;
+    near?: number;
+    far?: number;
+    /** Exponential (`FogExp2`) falloff instead of linear near/far; when set, `near`/`far` are ignored. */
+    density?: number;
+}
+/** Generic sky/background/fog for ANY world kind, including a custom `environment` component (#207.6). */
+export interface BackdropConfig {
+    background?: string;
+    sky?: SkyEnvironmentConfig;
+    fog?: BackdropFogConfig;
+}
+/** 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. */
+    mode?: "free" | "axis" | "grid";
+    /** World axis for mode "axis". Default "x". */
+    axis?: "x" | "z";
+    /** Cell size for mode "grid". Default 1. */
+    cellSize?: number;
+    /** Collide the walking player against placed scene objects (unit-box AABBs) even without `collision.voxel`. Default false. */
+    collideObjects?: boolean;
+    /** Intercepts each frame's resolved position before the pose commits (and before onTick): return a replacement [x,y,z] to constrain or redirect the step, or nothing to accept it. */
+    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;
+}
+/** One frame's movement resolution handed to `PlayerMovementConfig.beforeCommit`. */
+export interface MovementCommitFrame {
+    entityId: string;
+    current: readonly [number, number, number];
+    next: readonly [number, number, number];
+    dt: number;
+    /** 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> {
+export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEntity = never, TRenderObject = never> {
     game: GameDefinition;
     content: GameContextContent;
     loop: Required<GameLoop<GameContext>>;
     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;
-    /** 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. */
+    /** 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;
     /** 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. */
+    renderObject?: TRenderObject;
     /** Billboard sprites keyed by entity kind name; unmatched entities get primitive markers. */
     entitySprites?: Record<string, EntitySpriteConfig>;
     /** GLB models keyed by entity kind name; a string resolves as an asset-catalog key via game.assets, a ModelConfig renders directly. Takes priority over sprites, then primitives. */
     entityModels?: Record<string, string | ModelConfig>;
     /** GLB models keyed by object catalog id; a string resolves via game.assets, a ModelConfig renders directly. Replaces the colored box when present. */
     objectModels?: Record<string, string | ModelConfig>;
+    /** Styling for the default colored-box object render, keyed by catalog id: color override, opacity (< 1 sets transparent), hidden (skips the mesh but keeps the positioning group + picking). */
+    objectStyles?: Record<string, ObjectStyle>;
     /** Optional scroll-selected hotbar index for primary ability (mouse0). */
     hotbarSelection?: () => number;
     /** Positioned proximity prompts for the interact key + HUD; single source shared with useActivePrompt. */
     prompts?: (ctx: GameContext) => readonly PositionedPrompt[];
     /** Camera tuning (perspective, orbit, first-person) for the dev game player shell. */
     camera?: GameCameraConfig;
+    /** 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). */
     pointer?: PointerConfig;
-    /** Opt in to world-space health bars floating over non-local entities that carry the stat. */
+    /** 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;
+    /** Preferred phone orientation. When a coarse-pointer device is held the other way the shell shows a dismissible rotate hint; purely advisory, never blocks play. */
+    orientation?: "landscape" | "portrait";
+    /** 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). */
+    platforms?: readonly HudPlatform[];
+    /** HUD design resolution + scale clamps (default 1600×900, scale 0.4–1). `mobile` overrides tune the phone fit separately — the same resolution system drives desktop UI-scale and phone shrink. */
+    hudFit?: HudViewportConfig;
+    /** Opt in to world-space health bars floating over non-local entities that carry the stat. `roles` restricts bars to entities whose catalog entry declares one of the given roles. */
     worldHealthBars?: boolean | {
         statId?: string;
+        roles?: readonly CatalogEntityRole[];
     };
     /** Sound catalog + mix buses (music/sfx/ambient/…) the shell's Web Audio glue plays from. Catalog-first — no per-game audio wiring. */
     audio?: {
@@ -381,4 +646,19 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     objectSounds?: Record<string, string>;
     /** Rarity render binding + loot filter for dropped-item ground presentation (#32/#33). */
     worldItem?: WorldItemRenderConfig;
+    /** Player-vs-world collision for the first-person controller (block/voxel worlds). Off by default (flat ground). */
+    collision?: VoxelCollisionConfig;
+    /** Movement-control levers (axis/grid constraints, object collision, pre-commit hook) for the shell-driven walk controller. */
+    movement?: PlayerMovementConfig;
+    /** 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;
+    /** F2 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;
+    /** Automatic camera frustum + distance culling and asset streaming. On by default with conservative margins; unset uses engine defaults, `{ enabled: false }` opts out. Override bounds/distance/pins per entity kind or object catalog id. */
+    visibility?: VisibilityConfig;
 }
+export declare function worldHealthBarAllowsRole(roles: readonly CatalogEntityRole[] | undefined, role: CatalogEntityRole | undefined): boolean;

package/dist/game/playableGame.js

@@ -1 +1,6 @@
-export {};
+export const CAMERA_FRUSTUM_DEFAULTS = { fov: 55, near: 0.1, far: 300, zoom: 50 };
+export function worldHealthBarAllowsRole(roles, role) {
+    if (roles === undefined)
+        return true;
+    return role !== undefined && roles.includes(role);
+}