@jgengine/core 0.18.1 → 0.21.0

package/dist/game/playableGame.d.ts

@@ -1,11 +1,14 @@
 import type { AnimGraph } from "../anim/animGraph.js";
 import type { AudioBusDef, SoundDef } from "../audio/audioFalloff.js";
 import type { MusicTheme } from "../audio/music.js";
+import type { MaterialAsset, MaterialAssignment, MaterialSurfaceParameters, MaterialTextureRole } from "../material/materialAsset.js";
 import type { EditorCatalogDefinition, EditorDocument } from "../editor/types.js";
 import type { PostProcessingConfig } from "../render/postProcessing.js";
 import type { EnvironmentSource } from "../render/environment.js";
 import type { SpriteAtlas } from "../assets/spriteAtlas.js";
 import type { LookPreset } from "../render/lookPreset.js";
+import type { GamepadFeelConfig } from "../input/gamepadModel.js";
+import type { LocalPlayersConfig } from "../runtime/localPlayers.js";
 import type { TouchControlsConfig } from "../input/touchScheme.js";
 import type { GameSettingsConfig } from "../settings/settingsModel.js";
 import type { GraphicsProfile } from "../settings/graphicsProfile.js";
@@ -15,6 +18,7 @@ import type { PositionedPrompt } from "../interaction/proximityPrompt.js";
 import type { ChaseCameraTuning } from "../runtime/cameraDirector.js";
 import type { CatalogEntityRole, GameContext, GameContextContent } from "../runtime/gameContext.js";
 import type { FreeFlightBindings } from "../movement/freeFlight.js";
+import type { SceneEntity } from "../scene/entityStore.js";
 import type { ModelDims } from "../scene/assetCatalog.js";
 import type { PartMotionParams, PartRole } from "./partAnimation.js";
 import type { CollisionMeshData } from "../scene/collisionMesh.js";
@@ -22,14 +26,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). */
@@ -111,6 +122,10 @@ export interface ModelAnimationStates {
 }
 /** Rig playback for a `ModelConfig`'s GLTF animation clips — looping idles, one-shots, and held poses. */
 export interface ModelAnimationConfig {
+    /** Infer defaults from the loaded rig's actual clip roles, then replace fields with explicit overrides. Requires an identifiable idle clip. */
+    auto?: true;
+    /** Playback clock: real seconds (default), or entity-bound locally accepted clock progress after speed/timescale and before calendar scale. Requires an advancing accepted-progress clock; unbound previews use real seconds. */
+    clock?: "real" | "game";
     /** Clip name to play; defaults to the GLB's first clip. */
     clip?: string;
     /** Loop the clip. Default true. */
@@ -142,24 +157,13 @@ export interface ModelAnimationConfig {
 /**
  * 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.
+ * supported MaterialTextureRole may be omitted to keep the model's own map. Physical roles use the
+ * renderer's physical material; map URLs and response parameters remain caller-owned.
  */
-export interface ModelMaterialMaps {
-    color?: string;
-    normal?: string;
-    roughness?: string;
-    ao?: string;
-    metalness?: string;
-    emissive?: string;
-    height?: string;
+export interface ModelMaterialMaps extends Partial<Record<MaterialTextureRole, string>> {
 }
 /** Per-entity PBR material override (#151.3) applied to every standard or physical material in the model's cloned scene graph. */
-export interface ModelMaterialOverride {
-    color?: string;
-    metalness?: number;
-    roughness?: number;
-    emissive?: string;
-    emissiveIntensity?: number;
+export interface ModelMaterialOverride extends MaterialSurfaceParameters {
     /** Real PBR texture maps applied over the model's material — see {@link ModelMaterialMaps}. */
     maps?: ModelMaterialMaps;
     /**
@@ -225,6 +229,12 @@ export interface ModelConfig {
     collisionMesh?: CollisionMeshData;
     /** Per-entity PBR tint/finish override (#151.3); cloned onto each `MeshStandardMaterial` in the model so shared GLTF caches stay untouched. */
     material?: ModelMaterialOverride;
+    /** Reusable authored surfaces available to this model's named slot assignments. */
+    materialAssets?: readonly MaterialAsset[];
+    /** Sparse per-slot assignments; unselected imported materials keep their original appearance. */
+    materialAssignments?: readonly MaterialAssignment[];
+    /** Hide named visual subtrees on this instance before placement measurement. Exact runtime names or unique original imported names resolve without removing bones or changing the cached model; missing or ambiguous names warn and leave existing visibility unchanged. Malformed lists reject before model or texture allocation. Omit or pass [] to retain imported visibility. */
+    hiddenNodes?: readonly string[];
     /** Shadow participation of every mesh in the model. Default `"both"` (casts and receives); `"none"` for foliage cards, decals, or viewmodels that must never shadow the world. */
     shadows?: "cast" | "receive" | "both" | "none";
     /**
@@ -236,17 +246,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 +261,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 +354,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 +381,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. */
@@ -371,6 +426,8 @@ export interface PlayerMovementConfig {
      * colliders instead of relying on this switch.
      */
     collideObjects?: boolean;
+    /** Heightfield collision span from feet, finite and positive; default 1.8 meters. Live growth waits for clear headroom. Capsule and voxel paths retain their own dimensions; model proportions and camera placement remain game-owned. */
+    collisionHeight?: number;
     /** Tallest object ledge stepped up while walking (and largest drop still snapped down instead of falling). Default 0.4. */
     stepHeight?: number;
     /** 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. */
@@ -379,6 +436,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 heightfield and physics-backed capsule paths share jump feel; a `collision.voxel`
+     * body retains press-frame jumping 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. */
@@ -389,12 +453,25 @@ export interface PlayerMovementConfig {
     slopeSlide?: {
         maxClimbSlope?: number;
     } | boolean;
+    /**
+     * Maximum sampled uphill rise/run for heightfield walking, including jumps. A rejected step
+     * slides along a traversable X or Z axis and feet use the accepted ground. Finite, nonnegative;
+     * omitted means unrestricted. Capsule, voxel and flight paths retain their own collision rules.
+     */
+    maxClimbGrade?: number;
+    /**
+     * Optional terrain-policy sampler for `maxClimbGrade`; defaults to the resolved ground sampler.
+     * Use when grade rules follow a different terrain field (for example before road cuts). This
+     * does not change foot grounding. Called at most four times per constrained walking step;
+     * must return finite heights or the step throws with the invalid sampling coordinate.
+     */
+    climbGradeHeight?: (x: number, z: number) => number;
     /**
      * 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,25 +614,35 @@ 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). */
     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; `maxDistance` hides bars beyond this many world units from the player (default 60). */
+    /** 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; `maxDistance` hides bars beyond this many world units from the render camera (default 60). */
     worldHealthBars?: boolean | {
         statId?: string;
         roles?: readonly CatalogEntityRole[];
         maxDistance?: number;
-        /** Hide a bar when world geometry stands between the player and the entity. These bars are a screen-space overlay outside the depth buffer, so by default they draw through walls. Default false. */
+        /** Maximum overlays and visibility rays per refresh. Default 64, capped at 256. */
+        maxSamples?: number;
+        /** Minimum refresh interval in ms. Default 80 for bars, 120 for plates. */
+        tickMs?: number;
+        /** Hide bars behind blocking geometry from the render camera. Default true; false explicitly reveals through walls. */
         occlude?: boolean;
     };
     /**
      * 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
+     * world units from the render camera (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. Set `showHealth: false` for a name-only plate when a game already
      * draws the HP bar itself (its own HUD, or `worldHealthBars`) — otherwise the nameplate's built-in bar
@@ -565,7 +652,15 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
         statId?: string;
         roles?: readonly CatalogEntityRole[];
         maxDistance?: number;
+        /** Maximum overlays and visibility rays per refresh. Default 64, capped at 256. */
+        maxSamples?: number;
+        /** Minimum refresh interval in ms. Default 80 for bars, 120 for plates. */
+        tickMs?: number;
         showHealth?: boolean;
+        /** Hide plates behind blocking geometry from the render camera. Default true; false explicitly reveals through walls. */
+        occlude?: boolean;
+        /** Authored display name. Return null to omit a plate; default suppresses machine identifiers. */
+        resolveName?: (entity: SceneEntity) => string | null;
     };
     /**
      * Combat presentation stack mounted inside the 3D canvas (telegraphs, spell VFX, retained VFX,
@@ -577,6 +672,10 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     /** 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>;
+        /** SFX playback/patch budget, including pending samples; individual synth oscillators share one slot. Default 64; zero disables SFX. */
+        maxVoices?: number;
+        /** Overflow rejects new cues or steals the lowest-priority oldest cue. Default "steal-lowest". */
+        voiceOverflow?: "steal-lowest" | "reject";
         buses?: Record<string, AudioBusDef>;
         music?: Record<string, MusicTheme>;
         musicBus?: string;

package/dist/game/quest.d.ts

@@ -59,12 +59,17 @@ export interface QuestJournalDeps {
         grantItem(userId: string, inventoryId: string, itemId: string, count: number): {
             reason: string;
         } | null;
+        /** Grant the whole item batch, or reject without granting any items. Required for multiple item rewards. */
+        grantItems?(userId: string, items: Readonly<NonNullable<QuestRewards["items"]>>): {
+            reason: string;
+        } | null;
         grantUnlock(userId: string, unlockId: string): void;
     };
     hasUnlock?(userId: string, id: string): boolean;
     partyMembersNear?(userId: string, radius: number): string[];
 }
 export interface QuestJournal {
+    /** Add or replace definitions and refresh active credit indexes; re-register after editing objectives. */
     register(catalog: readonly QuestDef[] | Record<string, QuestDef>): void;
     has(questId: string): boolean;
     canAccept(userId: string, questId: string): {
@@ -86,6 +91,7 @@ export interface QuestJournal {
     }): void;
     revoke(userId: string, questId: string): void;
     list(userId: string): QuestInstance[];
+    /** Credit objectives active at event start in catalog order; quests activated during credit join the next event. */
     bind(action: "entity.died" | "inventory.added"): () => void;
     snapshot(userId: string): QuestSnapshotEntry[];
     hydrate(userId: string, data: QuestSnapshotEntry[]): void;
@@ -157,12 +163,21 @@ export interface QuestEvaluator {
     creditCollect(state: readonly QuestSnapshotEntry[], itemId: string, count: number): QuestSnapshotEntry[];
     list(state: readonly QuestSnapshotEntry[]): QuestInstance[];
 }
+/**
+ * Apply items before XP, currency, and unlocks. Multiple items require an all-or-reject `grantItems`
+ * callback; legacy single-item appliers remain supported. Rejected callbacks must make no writes.
+ * Arbitrary callback side effects or thrown exceptions cannot be rolled back by this helper.
+ */
 export declare function applyQuestRewards(rewards: QuestRewards, appliers: {
     grantXp?(amount: number): void;
     grantEconomy?(currencyId: string, amount: number): void;
     grantItem?(inventoryId: string, itemId: string, count: number): {
         reason: string;
     } | null | void;
+    /** Grant every item, or reject without writes. Takes precedence over `grantItem`. */
+    grantItems?(items: Readonly<NonNullable<QuestRewards["items"]>>): {
+        reason: string;
+    } | null | void;
     grantUnlock?(unlockId: string): void;
 }): {
     reason: string;