@jgengine/core 0.19.0 → 0.22.0

package/dist/game/lootModifiers.js

@@ -0,0 +1,26 @@
+/**
+ * Multiply weighted odds (or independent chances, clamped to one) by a caller-authored elapsed-time
+ * curve. Keeps source tables unchanged and uses the existing pipeline's modifier provenance.
+ * Elapsed time and multipliers must be finite and nonnegative; invalid curves reject the roll.
+ *
+ * @capability time-scaled-loot shape loot odds by elapsed hours with caller-authored curves and pipeline provenance
+ */
+export function timeScaledRarity(options) {
+    return {
+        id: options.id ?? "time-scaled-rarity",
+        plan(plan, ctx) {
+            if (!Number.isFinite(ctx.elapsedMs) || ctx.elapsedMs < 0)
+                throw new RangeError("Loot elapsedMs must be finite and nonnegative");
+            const hours = ctx.elapsedMs / 3_600_000;
+            return { ...plan, entries: plan.entries.map(candidate => {
+                    const factor = options.ramp(candidate.entry, hours);
+                    if (!Number.isFinite(factor) || factor < 0)
+                        throw new RangeError("Loot time multiplier must be finite and nonnegative");
+                    const value = (plan.mode === "weighted" ? candidate.weight : candidate.chance ?? 0) * factor;
+                    if (!Number.isFinite(value))
+                        throw new RangeError("Loot time weighting overflowed");
+                    return plan.mode === "weighted" ? { ...candidate, weight: value } : { ...candidate, chance: Math.min(1, value) };
+                }) };
+        },
+    };
+}

package/dist/game/narrativeAuthoring.d.ts

@@ -0,0 +1,67 @@
+import { type DialogueGraph } from "./dialogueGraph.js";
+/** Caller-reviewed facts for one authoring revision; event ids are in strict chronological order. */
+export interface NarrativeCanon {
+    readonly revision: string;
+    readonly characterIds: readonly string[];
+    readonly facts: Readonly<Record<string, string>>;
+    readonly eventIds: readonly string[];
+}
+/** An explicit assertion attached to a dialogue node; dialogue prose is never parsed. */
+export type NarrativeClaim = {
+    readonly nodeId: string;
+} & ({
+    readonly kind: "character";
+    readonly characterId: string;
+} | {
+    readonly kind: "fact";
+    readonly factId: string;
+    readonly value: string;
+} | {
+    readonly kind: "before";
+    readonly earlier: string;
+    readonly later: string;
+});
+/** Authored dialogue with optional structured assertions against canon. */
+export interface NarrativeDialogue {
+    readonly id: string;
+    readonly graph: DialogueGraph;
+    readonly claims: readonly NarrativeClaim[];
+}
+/** A candidate batch never changes canon; accepted new facts need a separately reviewed revision. */
+export interface NarrativeBatch {
+    readonly canonRevision: string;
+    readonly dialogues: readonly NarrativeDialogue[];
+}
+/** Caller budgets across the entire batch, including graph branches and explicit assertions. */
+export interface NarrativeBatchLimits {
+    readonly maxDialogues: number;
+    readonly maxNodes: number;
+    readonly maxChoices: number;
+    readonly maxClaims: number;
+    /** Sum of spoken lines and player choice text lengths (UTF-16 code units). */
+    readonly maxTextCharacters: number;
+}
+/** A repair diagnostic with a JSON-pointer location in the candidate batch. */
+export interface NarrativeIssue {
+    readonly code: string;
+    readonly severity: "error" | "warning";
+    readonly path: string;
+    readonly message: string;
+}
+/**
+ * Detach and freeze reviewed canon before passing it to an asynchronous authoring callback.
+ * Duplicate character/event ids and an empty revision throw; facts retain exact caller values.
+ *
+ * @capability narrative-canon freeze caller-reviewed character ids, facts and chronology for a narrative authoring revision
+ */
+export declare function freezeNarrativeCanon(canon: NarrativeCanon): NarrativeCanon;
+/**
+ * Check a typed candidate against caller budgets, canon revision, explicit claims and graph topology.
+ * Stops at the first exceeded budget before topology work; stale revisions also stop immediately.
+ * Claims check exact fact values and the declared strict event order, never prose, speaker labels,
+ * motivations, branch consequences or story quality. O(canon + bounded nodes + choices + claims).
+ * Validate/parse external JSON before calling; this is not an untrusted JSON decoder.
+ *
+ * @capability narrative-batch-validation locate stale canon, oversized batches, explicit character/fact/chronology contradictions and dialogue graph issues for bounded repair
+ */
+export declare function validateNarrativeBatch(canon: NarrativeCanon, batch: NarrativeBatch, limits: NarrativeBatchLimits): NarrativeIssue[];

package/dist/game/narrativeAuthoring.js

@@ -0,0 +1,122 @@
+import { validateDialogueGraph } from "./dialogueGraph.js";
+/**
+ * Detach and freeze reviewed canon before passing it to an asynchronous authoring callback.
+ * Duplicate character/event ids and an empty revision throw; facts retain exact caller values.
+ *
+ * @capability narrative-canon freeze caller-reviewed character ids, facts and chronology for a narrative authoring revision
+ */
+export function freezeNarrativeCanon(canon) {
+    if (canon.revision.length === 0)
+        throw new RangeError("Canon revision must not be empty.");
+    for (const ids of [canon.characterIds, canon.eventIds]) {
+        if (new Set(ids).size !== ids.length)
+            throw new RangeError("Canon ids must be unique within each list.");
+    }
+    return Object.freeze({
+        revision: canon.revision,
+        characterIds: Object.freeze([...canon.characterIds]),
+        facts: Object.freeze({ ...canon.facts }),
+        eventIds: Object.freeze([...canon.eventIds]),
+    });
+}
+/**
+ * Check a typed candidate against caller budgets, canon revision, explicit claims and graph topology.
+ * Stops at the first exceeded budget before topology work; stale revisions also stop immediately.
+ * Claims check exact fact values and the declared strict event order, never prose, speaker labels,
+ * motivations, branch consequences or story quality. O(canon + bounded nodes + choices + claims).
+ * Validate/parse external JSON before calling; this is not an untrusted JSON decoder.
+ *
+ * @capability narrative-batch-validation locate stale canon, oversized batches, explicit character/fact/chronology contradictions and dialogue graph issues for bounded repair
+ */
+export function validateNarrativeBatch(canon, batch, limits) {
+    for (const value of Object.values(limits)) {
+        if (!Number.isSafeInteger(value) || value < 0)
+            throw new RangeError("Narrative limits must be non-negative safe integers.");
+    }
+    if (batch.canonRevision !== canon.revision) {
+        return [{ code: "stale-canon", severity: "error", path: "/canonRevision", message: "Candidate uses a different canon revision." }];
+    }
+    const budget = (path) => [{
+            code: "batch-budget", severity: "error", path, message: "Candidate exceeds the caller's narrative batch budget.",
+        }];
+    if (batch.dialogues.length > limits.maxDialogues)
+        return budget("/dialogues");
+    let nodes = 0;
+    let choices = 0;
+    let claims = 0;
+    let text = 0;
+    for (let index = 0; index < batch.dialogues.length; index++) {
+        const dialogue = batch.dialogues[index];
+        const path = `/dialogues/${index}`;
+        nodes += dialogue.graph.nodes.length;
+        claims += dialogue.claims.length;
+        if (nodes > limits.maxNodes)
+            return budget(`${path}/graph/nodes`);
+        if (claims > limits.maxClaims)
+            return budget(`${path}/claims`);
+        for (let nodeIndex = 0; nodeIndex < dialogue.graph.nodes.length; nodeIndex++) {
+            const node = dialogue.graph.nodes[nodeIndex];
+            choices += node.choices?.length ?? 0;
+            if (choices > limits.maxChoices)
+                return budget(`${path}/graph/nodes/${nodeIndex}/choices`);
+            text += node.text.length;
+            for (const choice of node.choices ?? [])
+                text += choice.text.length;
+            if (text > limits.maxTextCharacters)
+                return budget(`${path}/graph/nodes/${nodeIndex}`);
+        }
+    }
+    const issues = [];
+    const add = (code, path, message) => {
+        issues.push({ code, severity: "error", path, message });
+    };
+    const characters = new Set(canon.characterIds);
+    const facts = new Map(Object.entries(canon.facts));
+    const events = new Map(canon.eventIds.map((id, index) => [id, index]));
+    const dialogueIds = new Set();
+    for (let index = 0; index < batch.dialogues.length; index++) {
+        const dialogue = batch.dialogues[index];
+        const path = `/dialogues/${index}`;
+        if (dialogueIds.has(dialogue.id))
+            add("duplicate-dialogue", `${path}/id`, "Dialogue id repeats within the batch.");
+        dialogueIds.add(dialogue.id);
+        for (const issue of validateDialogueGraph(dialogue.graph)) {
+            let location = `${path}/graph`;
+            if (issue.nodeIndex !== undefined)
+                location += `/nodes/${issue.nodeIndex}`;
+            if (issue.choiceIndex !== undefined)
+                location += `/choices/${issue.choiceIndex}/to`;
+            if (issue.code === "missing-start")
+                location += "/start";
+            issues.push({ code: `dialogue:${issue.code}`, severity: issue.severity, path: location, message: issue.message });
+        }
+        const nodeIds = new Set(dialogue.graph.nodes.map((node) => node.id));
+        for (let claimIndex = 0; claimIndex < dialogue.claims.length; claimIndex++) {
+            const claim = dialogue.claims[claimIndex];
+            const location = `${path}/claims/${claimIndex}`;
+            if (!nodeIds.has(claim.nodeId))
+                add("missing-claim-node", `${location}/nodeId`, "Claim references an unknown dialogue node.");
+            if (claim.kind === "character" && !characters.has(claim.characterId)) {
+                add("unknown-character", `${location}/characterId`, "Claim references an unknown canon character.");
+            }
+            else if (claim.kind === "fact") {
+                if (!facts.has(claim.factId))
+                    add("unknown-fact", `${location}/factId`, "Claim references an unknown canon fact.");
+                else if (facts.get(claim.factId) !== claim.value)
+                    add("fact-conflict", `${location}/value`, "Claim differs from the reviewed fact value.");
+            }
+            else if (claim.kind === "before") {
+                const earlier = events.get(claim.earlier);
+                const later = events.get(claim.later);
+                if (earlier === undefined)
+                    add("unknown-event", `${location}/earlier`, "Claim references an unknown canon event.");
+                if (later === undefined)
+                    add("unknown-event", `${location}/later`, "Claim references an unknown canon event.");
+                if (earlier !== undefined && later !== undefined && earlier >= later) {
+                    add("chronology-conflict", location, "Claim contradicts the reviewed strict event order.");
+                }
+            }
+        }
+    }
+    return issues;
+}

package/dist/game/playableGame.d.ts

@@ -1,6 +1,7 @@
 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";
@@ -17,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";
@@ -120,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. */
@@ -151,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;
     /**
@@ -234,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";
     /**
@@ -425,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. */
@@ -436,8 +439,8 @@ export interface PlayerMovementConfig {
     /**
      * Walk-controller feel. Acceleration and friction are exponential response rates (1/s): higher reaches
      * the target velocity or stops sooner. Omitted fields keep the engine defaults, so nothing changes until a
-     * game sets one. The jump fields apply to the kinematic walk; a `physics.backend` capsule or `collision.voxel`
-     * body jumps on the press frame with plain gravity. Tune against `measureMovement` (`@jgengine/core/movement/movementProbe`).
+     * 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). */
@@ -450,6 +453,19 @@ 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;
@@ -610,19 +626,23 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     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
@@ -632,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,
@@ -644,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;