@jgengine/core 0.33.0 → 0.35.0

package/dist/runtime/headlessRunner.d.ts

@@ -26,6 +26,8 @@ export interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultipl
     };
     /** Wall-clock source for the sim clock — inject a deterministic counter for reproducible runs. */
     now?: () => number;
+    /** Seed for `ctx.rng` — pass one so a recorded run and its replay draw the same numbers. Defaults to the definition's name. */
+    seed?: string | number;
     /** Per-step real-dt clamp in seconds, matching the shell's frame cap so one long stall can't fast-forward the sim. Default `0.05`. */
     maxStepSeconds?: number;
     /**
@@ -36,7 +38,9 @@ export interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultipl
     playerMovement?: boolean;
     /** Movement tuning — when `playerMovement` is on, the shell resolves from `definition.world`/`physics`; pass a direct config to test flight or other movement overrides headlessly. */
     movement?: import("../game/playableGame.js").PlayerMovementConfig;
-    /** Yaw heading (radians) fed to the movement controller when `playerMovement` is on; the shell supplies its camera yaw. */
+    /** Voxel collision config (`defineGame({ collision })`) — the shell's walk controller reads it, so a headless caller passes the same object to walk the same geometry. */
+    collision?: import("../game/playableGame.js").VoxelCollisionConfig;
+    /** Yaw heading (radians) fed to the movement controller when `playerMovement` is on; the shell supplies its camera yaw. Change it mid-run with {@link HeadlessRunner.aim}. */
     heading?: number;
     /** Pitch (radians) fed alongside yaw for 6DOF spectator flight when `alignWithLook` is set. */
     pitch?: number;
@@ -78,6 +82,11 @@ export interface HeadlessRunner {
     publishInput(input: HeadlessInput): void;
     /** Drive the game's own UI commands / intents headlessly — the same registry `ctx.game.commands` and the shell's command sink dispatch into. No renderer, no pointer simulation: dispatch an intent, then read reactive state off `ctx`. */
     readonly ui: HeadlessCommandInterface;
+    /** Point the movement controller at a yaw/pitch mid-run — what the shell does when the camera turns, so a scripted run can walk one way and then another. */
+    aim(look: {
+        heading?: number;
+        pitch?: number;
+    }): void;
     /** Capture the whole simulation (world, clock, loop, rng cursor) for {@link restore}; with a fixed `simulation.hz` and recorded input, replaying from it reproduces the run exactly. */
     snapshot(): SimSnapshot;
     restore(snapshot: SimSnapshot): void;

package/dist/runtime/headlessRunner.js

@@ -12,13 +12,16 @@ export function createHeadlessRunner(options) {
         content,
         player,
         ...(options.now === undefined ? {} : { now: options.now }),
+        ...(options.seed === undefined ? {} : { seed: options.seed }),
         ...(options.models === undefined ? {} : { models: options.models }),
     });
     loop?.onInit?.(ctx);
     loop?.onNewPlayer?.(ctx);
     const simSnapshot = createContextSimSnapshot(ctx);
+    const look = { heading: options.heading ?? 0, pitch: options.pitch ?? 0 };
     const tuning = options.playerMovement === true
         ? { ...resolvePlayerMovementTuning({
+                collision: options.collision,
                 physics: definition.physics,
                 world: definition.world,
                 movement: options.movement,
@@ -48,6 +51,12 @@ export function createHeadlessRunner(options) {
             names: () => ctx.game.commands.names(),
             has: (name) => ctx.game.commands.has(name),
         },
+        aim(next) {
+            if (next.heading !== undefined && Number.isFinite(next.heading))
+                look.heading = next.heading;
+            if (next.pitch !== undefined && Number.isFinite(next.pitch))
+                look.pitch = next.pitch;
+        },
         step(dtSeconds, input) {
             if (input !== undefined)
                 publishInput(input);
@@ -58,7 +67,7 @@ export function createHeadlessRunner(options) {
                 total += gameDt;
                 ctx.sim.runStages("beforeMovement", stepDt);
                 if (tuning !== null && gameDt > 0) {
-                    stepPlayerMovement(ctx, player.userId, { held: ctx.input.held(), pointer: ctx.input.pointer() }, gameDt, tuning, options.heading, options.pitch);
+                    stepPlayerMovement(ctx, player.userId, { held: ctx.input.held(), pointer: ctx.input.pointer() }, gameDt, tuning, look.heading, look.pitch);
                 }
                 ctx.sim.runStages("afterMovement", stepDt);
                 loop?.onTick?.(ctx, gameDt);

package/dist/world/pathTerrain.js

@@ -1,3 +1,4 @@
+import { buildPolylineIndex } from "./polylineIndex.js";
 function clamp01(value) {
     return value < 0 ? 0 : value > 1 ? 1 : value;
 }
@@ -15,34 +16,28 @@ function buildCorridor(points) {
         const b = points[i];
         cumulative.push(cumulative[i - 1] + Math.hypot(b[0] - a[0], b[1] - a[1]));
     }
-    return { points, cumulative, total: cumulative[cumulative.length - 1] ?? 0 };
+    return { points, cumulative, total: cumulative[cumulative.length - 1] ?? 0, index: buildPolylineIndex(points) };
 }
 /**
- * Closest point on the corridor to `(x, z)`: unsigned lateral distance and arc-length position. Self-
- * contained (each segment projects independently and the minimum lateral wins) so a vertex always reports
- * a near-zero lateral, regardless of which side of the line the neighbours fall.
+ * Closest point on the corridor to `(x, z)` within `limit`: unsigned lateral distance and arc-length
+ * position. Self-contained (each segment projects independently and the minimum lateral wins) so a
+ * vertex always reports a near-zero lateral, regardless of which side of the line the neighbours fall.
+ * Beyond `limit` the corridor cannot change the sample, so the answer is `null`.
  */
-function nearestOnCorridor(corridor, x, z) {
-    let bestLateral = Number.POSITIVE_INFINITY;
-    let bestAlong = 0;
-    let bestPoint = corridor.points[0] ?? [x, z];
-    for (let i = 1; i < corridor.points.length; i += 1) {
-        const a = corridor.points[i - 1];
-        const b = corridor.points[i];
-        const abx = b[0] - a[0];
-        const abz = b[1] - a[1];
-        const segLenSq = abx * abx + abz * abz;
-        const t = segLenSq <= 0 ? 0 : Math.max(0, Math.min(1, ((x - a[0]) * abx + (z - a[1]) * abz) / segLenSq));
-        const px = a[0] + abx * t;
-        const pz = a[1] + abz * t;
-        const lateral = Math.hypot(x - px, z - pz);
-        if (lateral < bestLateral) {
-            bestLateral = lateral;
-            bestAlong = corridor.cumulative[i - 1] + t * Math.sqrt(segLenSq);
-            bestPoint = [px, pz];
-        }
-    }
-    return { lateral: bestLateral, along: bestAlong, point: bestPoint };
+function nearestOnCorridor(corridor, x, z, limit) {
+    const hit = corridor.index.nearest(x, z, limit);
+    if (hit === null)
+        return null;
+    const a = corridor.points[hit.segment];
+    const b = corridor.points[hit.segment + 1];
+    const abx = b[0] - a[0];
+    const abz = b[1] - a[1];
+    const segLenSq = abx * abx + abz * abz;
+    return {
+        lateral: hit.distance,
+        along: corridor.cumulative[hit.segment] + hit.t * Math.sqrt(segLenSq),
+        point: hit.point,
+    };
 }
 function resolveProfile(profile) {
     if (profile.points.length < 2 || profile.width <= 0)
@@ -94,10 +89,10 @@ function centerlineTarget(profile, along, point, base) {
     return base(point[0], point[1]);
 }
 function applyProfileAt(profile, x, z, surrounding, base) {
-    const hit = nearestOnCorridor(profile.corridor, x, z);
-    const lateral = hit.lateral;
-    if (lateral > profile.reach)
+    const hit = nearestOnCorridor(profile.corridor, x, z, profile.reach);
+    if (hit === null)
         return surrounding;
+    const lateral = hit.lateral;
     const target = clampCutFill(centerlineTarget(profile, hit.along, hit.point, base), surrounding, profile.maxCut, profile.maxFill);
     // Inside the core: carve a channel below the target, deepest at the centerline, level at the edge.
     if (lateral <= profile.half) {

package/dist/world/polylineIndex.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Nearest-point queries against a polyline within a distance bound. The corridor sampler, road
+ * draping and the palette's polyline regions ask "is this vertex near that line?" for every vertex of
+ * a terrain mesh, so a linear scan of every segment per vertex turned one authored road into seconds
+ * of boot time. This keeps the exact same arithmetic as a full scan while visiting only the segments
+ * that can possibly win: a query returns the same segment, the same `t` and the same distance a scan
+ * would, and `null` only when the whole polyline is farther away than the bound.
+ * @internal
+ */
+import type { Vec2 } from "./geometry.js";
+/** Where the polyline comes closest to the query, within the query's bound. @internal */
+export interface PolylineHit {
+    /** Index of the winning segment, i.e. the one from `points[segment]` to `points[segment + 1]`. */
+    segment: number;
+    /** Position along that segment, 0..1. */
+    t: number;
+    /** Distance from the query to the projected point. */
+    distance: number;
+    /** Projected point on the polyline. */
+    point: Vec2;
+}
+/** @internal */
+export interface PolylineIndex {
+    /** Exact nearest segment sample within `limit`, or null when the polyline stays farther away. */
+    nearest(x: number, z: number, limit: number): PolylineHit | null;
+    /** Segments tested by the most recent query — the bounded-work invariant tests assert on. */
+    examined(): number;
+}
+/** @internal */
+export declare function buildPolylineIndex(points: readonly Vec2[]): PolylineIndex;

package/dist/world/polylineIndex.js

@@ -0,0 +1,80 @@
+import { buildSpatialBuckets } from "./spatialBuckets.js";
+/** @internal */
+export function buildPolylineIndex(points) {
+    const count = Math.max(0, points.length - 1);
+    const ax = new Float64Array(count);
+    const az = new Float64Array(count);
+    const abx = new Float64Array(count);
+    const abz = new Float64Array(count);
+    const lengthSq = new Float64Array(count);
+    let minX = Number.POSITIVE_INFINITY;
+    let minZ = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxZ = Number.NEGATIVE_INFINITY;
+    for (let i = 0; i < count; i += 1) {
+        const a = points[i];
+        const b = points[i + 1];
+        ax[i] = a[0];
+        az[i] = a[1];
+        abx[i] = b[0] - a[0];
+        abz[i] = b[1] - a[1];
+        lengthSq[i] = abx[i] * abx[i] + abz[i] * abz[i];
+        minX = Math.min(minX, a[0], b[0]);
+        maxX = Math.max(maxX, a[0], b[0]);
+        minZ = Math.min(minZ, a[1], b[1]);
+        maxZ = Math.max(maxZ, a[1], b[1]);
+    }
+    const span = count === 0 ? 1 : Math.max(maxX - minX, maxZ - minZ, 1);
+    // Twice the average segment length keeps a typical reach inside one or two cells, so a query tests a
+    // handful of segments; the 256-cell cap bounds memory on a very long, very dense polyline.
+    const buckets = buildSpatialBuckets(Math.max(1, span / 256, (span / Math.max(1, count)) * 2));
+    for (let i = 0; i < count; i += 1) {
+        buckets.insert(i, Math.min(ax[i], ax[i] + abx[i]), Math.min(az[i], az[i] + abz[i]), Math.max(ax[i], ax[i] + abx[i]), Math.max(az[i], az[i] + abz[i]));
+    }
+    const candidates = [];
+    let examined = 0;
+    return {
+        nearest(x, z, limit) {
+            if (count === 0 || !(limit >= 0)) {
+                examined = 0;
+                return null;
+            }
+            if (x < minX - limit || x > maxX + limit || z < minZ - limit || z > maxZ + limit) {
+                examined = 0;
+                return null;
+            }
+            // A segment closer than `limit` passes through this box, so it is registered in one of its cells.
+            // Clamping to the polyline's own box keeps an infinite bound from walking an infinite grid.
+            const reach = limit * (1 + 1e-9) + 1e-9;
+            buckets.query(Math.max(minX, x - reach), Math.max(minZ, z - reach), Math.min(maxX, x + reach), Math.min(maxZ, z + reach), candidates);
+            examined = candidates.length;
+            if (candidates.length === 0)
+                return null;
+            let bestSegment = -1;
+            let bestT = 0;
+            let bestDistance = Number.POSITIVE_INFINITY;
+            let bestX = 0;
+            let bestZ = 0;
+            for (const segment of candidates) {
+                const offsetX = x - ax[segment];
+                const offsetZ = z - az[segment];
+                const segLengthSq = lengthSq[segment];
+                const t = segLengthSq <= 0 ? 0 : Math.max(0, Math.min(1, (offsetX * abx[segment] + offsetZ * abz[segment]) / segLengthSq));
+                const px = ax[segment] + abx[segment] * t;
+                const pz = az[segment] + abz[segment] * t;
+                const distance = Math.hypot(x - px, z - pz);
+                if (distance < bestDistance) {
+                    bestDistance = distance;
+                    bestSegment = segment;
+                    bestT = t;
+                    bestX = px;
+                    bestZ = pz;
+                }
+            }
+            if (bestSegment < 0 || bestDistance > limit)
+                return null;
+            return { segment: bestSegment, t: bestT, distance: bestDistance, point: [bestX, bestZ] };
+        },
+        examined: () => examined,
+    };
+}

package/dist/world/spatialBuckets.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Uniform XZ grid over items with a rectangular footprint: insert once, then ask which items cover a
+ * box. One mechanism behind the two sampling hot paths — a corridor's segments and a palette's regions
+ * — so a per-vertex query tests the handful of items nearby instead of every item in the world.
+ * @internal
+ */
+/** @internal */
+export interface SpatialBuckets {
+    /** Register `id` under every cell its rectangle overlaps. Ids are returned in insertion order. */
+    insert(id: number, minX: number, minZ: number, maxX: number, maxZ: number): void;
+    /** Ids whose rectangle overlaps the query box, ascending and deduped, written into `out`. */
+    query(minX: number, minZ: number, maxX: number, maxZ: number, out: number[]): number[];
+}
+/** @internal */
+export declare function buildSpatialBuckets(cellSize: number): SpatialBuckets;

package/dist/world/spatialBuckets.js

@@ -0,0 +1,80 @@
+/**
+ * Uniform XZ grid over items with a rectangular footprint: insert once, then ask which items cover a
+ * box. One mechanism behind the two sampling hot paths — a corridor's segments and a palette's regions
+ * — so a per-vertex query tests the handful of items nearby instead of every item in the world.
+ * @internal
+ */
+/** @internal */
+export function buildSpatialBuckets(cellSize) {
+    const cell = Math.max(1e-6, cellSize);
+    const columns = new Map();
+    let marks = new Int32Array(16);
+    let generation = 0;
+    let highest = -1;
+    const mark = (id) => {
+        if (id <= highest)
+            return;
+        highest = id;
+        if (id < marks.length)
+            return;
+        let size = marks.length;
+        while (size <= id)
+            size *= 2;
+        const grown = new Int32Array(size);
+        grown.set(marks);
+        marks = grown;
+    };
+    return {
+        insert(id, minX, minZ, maxX, maxZ) {
+            mark(id);
+            const cx0 = Math.floor(minX / cell);
+            const cx1 = Math.floor(maxX / cell);
+            const cz0 = Math.floor(minZ / cell);
+            const cz1 = Math.floor(maxZ / cell);
+            for (let cx = cx0; cx <= cx1; cx += 1) {
+                let column = columns.get(cx);
+                if (column === undefined) {
+                    column = new Map();
+                    columns.set(cx, column);
+                }
+                for (let cz = cz0; cz <= cz1; cz += 1) {
+                    const bucket = column.get(cz);
+                    if (bucket === undefined)
+                        column.set(cz, [id]);
+                    else
+                        bucket.push(id);
+                }
+            }
+        },
+        query(minX, minZ, maxX, maxZ, out) {
+            out.length = 0;
+            generation += 1;
+            if (generation >= 2147483647) {
+                marks.fill(0);
+                generation = 1;
+            }
+            const cx0 = Math.floor(minX / cell);
+            const cx1 = Math.floor(maxX / cell);
+            const cz0 = Math.floor(minZ / cell);
+            const cz1 = Math.floor(maxZ / cell);
+            for (let cx = cx0; cx <= cx1; cx += 1) {
+                const column = columns.get(cx);
+                if (column === undefined)
+                    continue;
+                for (let cz = cz0; cz <= cz1; cz += 1) {
+                    const bucket = column.get(cz);
+                    if (bucket === undefined)
+                        continue;
+                    for (const id of bucket) {
+                        if (marks[id] === generation)
+                            continue;
+                        marks[id] = generation;
+                        out.push(id);
+                    }
+                }
+            }
+            out.sort((a, b) => a - b);
+            return out;
+        },
+    };
+}

package/dist/world/terrain.js

@@ -1,5 +1,6 @@
 import { withPathProfiles } from "./pathTerrain.js";
-import { isOnRoad, nearestOnPath } from "./roads.js";
+import { buildPolylineIndex } from "./polylineIndex.js";
+import { buildSpatialBuckets } from "./spatialBuckets.js";
 function clamp01(value) {
     return value < 0 ? 0 : value > 1 ? 1 : value;
 }
@@ -321,10 +322,15 @@ export function flattenFieldAround(base, zones) {
 export function roadDrapedField(base, roads) {
     if (roads.length === 0)
         return base;
+    const draped = roads.map((road) => ({
+        elevation: road.elevation,
+        half: road.width / 2,
+        index: buildPolylineIndex(road.path),
+    }));
     const sampleHeight = (x, z) => {
         let lift = 0;
-        for (const road of roads) {
-            if (road.elevation > lift && isOnRoad(road.path, road.width, x, z))
+        for (const road of draped) {
+            if (road.elevation > lift && road.index.nearest(x, z, road.half) !== null)
                 lift = road.elevation;
         }
         return base.sampleHeight(x, z) + lift;
@@ -680,9 +686,13 @@ export function createTerrainPaletteSampler(descriptor) {
     }));
     if (regions.length === 0 && bandSampler === null)
         return () => base;
+    const buckets = buildSpatialBuckets(PALETTE_REGION_CELL);
+    regions.forEach((region, index) => buckets.insert(index, region.minX, region.minZ, region.maxX, region.maxZ));
+    const nearby = [];
     return (x, z) => {
         let palette = bandSampler === null ? base : bandSampler(z);
-        for (const region of regions) {
+        for (const index of buckets.query(x, z, x, z, nearby)) {
+            const region = regions[index];
             const distance = region.coreDistance(x, z);
             if (distance <= 0) {
                 palette = region.palette;
@@ -695,20 +705,44 @@ export function createTerrainPaletteSampler(descriptor) {
         return palette;
     };
 }
+/**
+ * Cell size for the palette's region index, in world units: coarse enough that inserting a small
+ * region touches one cell, fine enough that a vertex only tests the handful of regions over it.
+ */
+const PALETTE_REGION_CELL = 32;
 /**
  * Resolves a `TerrainMaterialRegion` of any shape to a `coreDistance(x, z)` — 0 inside the painted
- * core, growing positive outward — plus its blend-ring `falloff`, so the palette sampler blends every
- * shape through one shape-agnostic loop.
+ * core, growing positive outward — plus its blend-ring `falloff` and the box a region can paint
+ * inside (core plus blend ring), so the palette sampler blends every shape through one shape-agnostic
+ * loop that only visits regions covering the sample.
  */
 function resolveRegionShape(region) {
     if (region.shape === "polyline") {
         const half = region.width * 0.5;
+        const falloff = region.falloff ?? half;
+        const index = buildPolylineIndex(region.points);
+        const limit = half + falloff;
+        let minX = Number.POSITIVE_INFINITY;
+        let minZ = Number.POSITIVE_INFINITY;
+        let maxX = Number.NEGATIVE_INFINITY;
+        let maxZ = Number.NEGATIVE_INFINITY;
+        for (const point of region.points) {
+            minX = Math.min(minX, point[0]);
+            maxX = Math.max(maxX, point[0]);
+            minZ = Math.min(minZ, point[1]);
+            maxZ = Math.max(maxZ, point[1]);
+        }
+        const empty = region.points.length < 2;
         return {
-            falloff: region.falloff ?? half,
+            falloff,
             coreDistance: (x, z) => {
-                const sample = nearestOnPath(region.points, x, z);
-                return sample === null ? Number.POSITIVE_INFINITY : Math.max(0, sample.distance - half);
+                const hit = index.nearest(x, z, limit);
+                return hit === null ? Number.POSITIVE_INFINITY : Math.max(0, hit.distance - half);
             },
+            minX: empty ? 0 : minX - limit,
+            minZ: empty ? 0 : minZ - limit,
+            maxX: empty ? -1 : maxX + limit,
+            maxZ: empty ? -1 : maxZ + limit,
         };
     }
     if (region.shape === "rect") {
@@ -716,8 +750,11 @@ function resolveRegionShape(region) {
         const angle = region.rotationY ?? 0;
         const cos = Math.cos(angle);
         const sin = Math.sin(angle);
+        const falloff = region.falloff ?? Math.min(hx, hz) * 0.5;
+        const extentX = Math.abs(hx * cos) + Math.abs(hz * sin) + falloff;
+        const extentZ = Math.abs(hx * sin) + Math.abs(hz * cos) + falloff;
         return {
-            falloff: region.falloff ?? Math.min(hx, hz) * 0.5,
+            falloff,
             coreDistance: (x, z) => {
                 const dx = x - region.center[0];
                 const dz = z - region.center[1];
@@ -725,11 +762,21 @@ function resolveRegionShape(region) {
                 const lz = -dx * sin + dz * cos;
                 return Math.hypot(Math.max(0, Math.abs(lx) - hx), Math.max(0, Math.abs(lz) - hz));
             },
+            minX: region.center[0] - extentX,
+            minZ: region.center[1] - extentZ,
+            maxX: region.center[0] + extentX,
+            maxZ: region.center[1] + extentZ,
         };
     }
+    const falloff = region.falloff ?? region.radius * 0.5;
+    const extent = region.radius + falloff;
     return {
-        falloff: region.falloff ?? region.radius * 0.5,
+        falloff,
         coreDistance: (x, z) => Math.max(0, Math.hypot(x - region.center[0], z - region.center[1]) - region.radius),
+        minX: region.center[0] - extent,
+        minZ: region.center[1] - extent,
+        maxX: region.center[0] + extent,
+        maxZ: region.center[1] + extent,
     };
 }
 function withFlattenMasks(sampleHeight, masks) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "jgengine core — pure-TypeScript game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. Agent skills ship in the tarball. https://jgengine.com",
   "keywords": [
     "jgengine",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.33.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.35.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.33.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.35.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 
@@ -436,7 +436,7 @@
 - `HeadlessCommandInterface` (interface): interface HeadlessCommandInterface — Canvas-free command/intent surface for {@link HeadlessRunner} — invoke a game's registered UI commands and read the resulting reactive state off `ctx`.
 - `HeadlessInput` (interface): interface HeadlessInput — One step's worth of player intent handed to {@link HeadlessRunner.step} — the held-action set and pointer state the shell would otherwise publish from the browser each frame.
 - `HeadlessRunner` (interface): interface HeadlessRunner — A renderer-free driver for a game loop: builds a {@link GameContext} from a {@link GameDefinition}, runs the init hooks, then advances the simulation one step at a time from injected input. No React, R3F, or three.js — the whole play path (time, input, `onTick`, behaviour nav, optional player movement) runs from `core` primitives alone, so a non-React host (a server tick, a test, a CLI replay) can play a real game and read its world snapshot. The shell's FrameDriver is one such driver bolted to `useFrame`; this is the same step distilled out of the render tree.
-- `HeadlessRunnerOptions` (interface): interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> { definition: GameDefinition<TAssetRef, TMultiplayer>; content?: GameContextContent; loop?: GameLoop<GameContext>; player?: {userId: string; isNew: boolean}; now?: () => number; maxStepSeconds?: number; playerMovement?: boolean; movement?: … — ⚠ undocumented
+- `HeadlessRunnerOptions` (interface): interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> { definition: GameDefinition<TAssetRef, TMultiplayer>; content?: GameContextContent; loop?: GameLoop<GameContext>; player?: {userId: string; isNew: boolean}; now?: () => number; seed?: string | number; maxStepSeconds?: number; playerMovemen… — ⚠ undocumented
 - `createHeadlessRunner` (function): function createHeadlessRunner<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HeadlessRunnerOptions<TAssetRef, TMultiplayer>): HeadlessRunner — ⚠ undocumented
 
 ## @jgengine/core/runtime/hostPersistence

package/skills/jgengine-gameplay/api.md

@@ -2653,6 +2653,17 @@
 - `TriggeredRuleState` (interface): interface TriggeredRuleState — Serializable runtime state — everything that changes future triggers. Rules travel with it.
 - `createTriggeredRuleEngine` (function): function createTriggeredRuleEngine(rules: readonly TriggeredRule[] = []): TriggeredRuleEngine — Create an empty triggered-rule engine. Rules are added as data; dispatching an event returns the firings the caller applies to its own effect system. Time is caller-supplied (`now` in ms), so the engine is deterministic and drives equally from a fixed-step loop or a save-restored timeline.
 
+## @jgengine/core/run/runLoop
+
+- `RunChange` (interface): interface RunChange<T> — One change the next run can open with. `T` is the game's own payload (a tighter rival line, an unlocked part, a route modifier) - the loop only draws and remembers which id was drawn.
+- `RunLoop` (interface): interface RunLoop<T> — A run's lifecycle: what it carries and can lose, and the change it hands the next run.
+- `RunLoopConfig` (interface): interface RunLoopConfig<T> — Configuration for {@link createRunLoop}.
+- `RunLoopState` (interface): interface RunLoopState — Everything a run loop stores as plain JSON: the run in progress plus lifetime totals.
+- `RunOffer` (interface): interface RunOffer<T> — The change a run opens with, and which run it is.
+- `RunOutcome` (type): type RunOutcome = "banked" | "lost" — How a run ended: what it carried reached the bank, or it was lost.
+- `RunSettlement` (interface): interface RunSettlement<T> — What one closed run banked or lost, and what the next run changes.
+- `createRunLoop` (function): function createRunLoop<T>(config: RunLoopConfig<T>): RunLoop<T> — Bank-or-lose between runs, with one deterministic change per run drawn from an authored table.
+
 ## @jgengine/core/session/contestedChannel
 
 - `ContestReaction` (type): type ContestReaction = "pause" | "decay" — ⚠ undocumented

package/skills/jgengine-gameplay/capabilities.md

@@ -648,6 +648,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `rerollRules` (function) · `import { rerollRules } from "@jgengine/core/gameplay"`
 - `selectRules` (function) · `import { selectRules } from "@jgengine/core/gameplay"`
 
+## run-loop — bank or lose what a run carries, with one deterministic change per run
+
+- `createRunLoop` (function) · `import { createRunLoop } from "@jgengine/core/run/runLoop"`
+
 ## run-modifiers — a roguelike run built from stacking drafted modifier picks
 
 - `createRunDraft` (function) · `import { createRunDraft } from "@jgengine/core/gameplay"`

package/skills/jgengine-world/api.md

@@ -106,8 +106,10 @@
 - `DriverState` (interface): interface DriverState — Serializable per-driver state advanced in place by {@link driveStep}.
 - `DriverStep` (interface): interface DriverStep extends AxisInput — {@link driveStep}'s result: the axis sample to feed the vehicle sim, plus arrival.
 - `DriverTuning` (interface): interface DriverTuning — Vehicle-feel numbers the game supplies; everything has a sensible default except `maxSpeed`.
+- `PaceBand` (interface): interface PaceBand — Catch-up pacing for one car in a field: the gap it tries to hold to a reference car (a rival, the player, a convoy lead) and how its pace bends when it drifts off that gap. Past `margin` by `tolerance` it sheds up to `ease` of its pace; short of it by `tolerance` it gains up to `push`; inside that tolerance it leaves the car alone. The push never outdrives `DriverTuning.maxSpeed`, so a band changes how hard a car tries, never what it is built to do.
 - `createDriverState` (function): function createDriverState(targetX = 0, targetZ = 0): DriverState — Fresh driver state committed to an initial target (usually the spawn-time goal or the spawn position itself).
-- `driveStep` (function): function driveStep(state: DriverState, dt: number, pose: DriverPose, goal: DriverGoal, profile: DifficultyProfile, tuning: DriverTuning, rng: () => number, obstacleAhead: number | null = null): DriverStep — Advance one driving step, mutating `state`, and return the {@link AxisInput} to feed the vehicle sim. `obstacleAhead` is the caller-measured distance to the nearest blocker in the driving corridor this step (`null`/omitted when clear) — the driver perceives it late by `speed * reactionSeconds`, so easy tiers brake at the last moment and expert tiers with proper margin. The steering target is a delay-line over the goal — resampled every `reactionSeconds`, so it trails a moving goal by up to that long, which is what makes an easy chaser visibly cut toward where the target *was*. When throttle produces no motion for a tier-scaled while the driver reverses out with counter-steer (brake past standstill — the shared sim's reverse).
+- `driveStep` (function): function driveStep(state: DriverState, dt: number, pose: DriverPose, goal: DriverGoal, profile: DifficultyProfile, tuning: DriverTuning, rng: () => number, obstacleAhead: number | null = null): DriverStep — Advance one driving step, mutating `state`, and return the {@link AxisInput} to feed the vehicle sim. `obstacleAhead` is the caller-measured distance to the nearest blocker in the driving corridor this step (`null`/omitted when clear) — the driver perceives it late by `speed * reactionSeconds`, so easy tiers brake at the last moment and expert tiers with proper margin. The steering target is a delay-line over the goal — resampled every `reactionSeconds`, so it trails a moving goal by up to that long, which is what makes an easy chaser visibly cut toward where the target *was*. A {@link PaceBand} on the goal eases a car ahead of its margin and pushes one behind it, bounded by the car's own top speed. When throttle produces no motion for a tier-scaled while the driver reverses out with counter-steer (brake past standstill — the shared sim's reverse).
+- `paceBandFactor` (function): function paceBandFactor(band: PaceBand, gap: number): number — The pace multiplier a {@link PaceBand} asks for at `gap`: `1` inside the tolerance, `1 - ease * scale` fully ahead of it, `1 + push * scale` fully behind it, ramped linearly across `easeAt` / `pushAt` in between. Pure scalar math, so a band is deterministic and costs no allocation per step; the result never goes negative.
 - `pathTargetAhead` (function): function pathTargetAhead(path: readonly DrivePathPoint[], x: number, z: number, lookahead: number, loop = false): DrivePathPoint | null — The pure-pursuit target for street/route following: the point `lookahead` meters further along the polyline from wherever the vehicle currently projects onto it. Feed the result to {@link driveStep} as the goal each tick and the driver follows the road; `loop` wraps a circuit (traffic block, race lap) instead of pinning at the final point. Returns `null` for a degenerate path. Give sharper tiers a longer `lookahead` to cut corners cleanly and duller tiers a short one so they steer segment-to-segment.
 
 ## @jgengine/core/ai/flock
@@ -453,13 +455,22 @@
 - `sumMagnitude` (function): function sumMagnitude<P>(memberships: readonly AreaMembership<P>[], magnitudeOf: MagnitudeOf<P>): number — Sum a numeric magnitude across memberships — additive aggregation for a total field strength (total damage per tick, total slow). A terminal reducer, not a filter, so it returns the number.
 - `uniqueByStackKey` (function): function uniqueByStackKey<P>(magnitudeOf?: MagnitudeOf<P>): AreaStackPolicy<P> — Keep at most one membership per `stackKey`. With `magnitudeOf` the strongest per key wins (ties broken by `sourceId` for determinism); without it the first-seen per key wins. Use for unique-by-key buffs where reapplying the same aura should not stack.
 
+## @jgengine/core/audio/ambience
+
+- `AmbienceWeight` (interface): interface AmbienceWeight — One zone's share of the ambience mix at a listener position, 0..1.
+- `AmbienceZoneDef` (interface): interface AmbienceZoneDef — One ambience zone: a sound bed keyed to a volume of the scene.
+- `AmbienceZoneShape` (type): type AmbienceZoneShape = | { kind: "sphere"; center: readonly [number, number, number]; radius: number } | { kind: "box"; min: readonly [number, number, number]; max: readonly [number, number, number] } — A world-space volume whose sound bed plays while the listener is inside it.
+- `activeAmbienceZone` (function): function activeAmbienceZone(weights: readonly AmbienceWeight[]): string | null — The loudest zone in a weight list, or null when every zone is silent.
+- `ambienceWeights` (function): function ambienceWeights(zones: readonly AmbienceZoneDef[], x: number, y: number, z: number, out: AmbienceWeight[] = []): AmbienceWeight[] — Every zone's mix weight at a listener position. A zone is at full level `crossfade` units inside its boundary, at half level on the boundary and silent `crossfade` units outside, so a listener walking between two zones that share a boundary hears a constant-sum handover. Weights that would sum above 1 (overlapping zones) are normalized so total bed level never exceeds unity. Writes into `out` when given, so a per-frame caller allocates nothing.
+- `zoneSignedDistance` (function): function zoneSignedDistance(shape: AmbienceZoneShape, x: number, y: number, z: number): number — Distance from a point to a zone boundary, positive inside and negative outside. Spheres measure from the surface; boxes use the nearest face.
+
 ## @jgengine/core/audio/audioFalloff
 
 - `AudioBusDef` (interface): interface AudioBusDef { id: AudioBusId; gain?: number } — ⚠ undocumented · used by `withFeedbackCueSounds` (@jgengine/core/audio/feedbackCues): Merge the default feedback reactions into a game's sound catalog.
 - `AudioBusId` (type): type AudioBusId = string — ⚠ undocumented
 - `AudioFalloffConfig` (interface): interface AudioFalloffConfig { minDistance?: number; maxDistance?: number; curve?: FalloffCurve } — ⚠ undocumented
 - `FalloffCurve` (type): type FalloffCurve = "linear" | "inverse" | "none" — ⚠ undocumented
-- `SoundDef` (interface): interface SoundDef { id: string; url?: string; synth?: SynthPatch; bus: AudioBusId; gain?: number; loop?: boolean; maxVoices?: number; priority?: number; positional?: boolean; falloff?: AudioFalloffConfig; doppler?: number; spatial?: {panning: "hrtf" | "equal… — ⚠ undocumented · used by `DEFAULT_FEEDBACK_CUE_SOUNDS` (@jgengine/core/audio/feedbackCues): Short procedural reactions - no samples to load, so every game has impact feedback without authoring audio.
+- `SoundDef` (interface): interface SoundDef { id: string; url?: string; synth?: SynthPatch; bus: AudioBusId; gain?: number; loop?: boolean; maxVoices?: number; priority?: number; duck?: {buses?: readonly string[]; amount?: number; seconds?: number;}; positional?: boolean; falloff?: A… — ⚠ undocumented · used by `DEFAULT_FEEDBACK_CUE_SOUNDS` (@jgengine/core/audio/feedbackCues): Short procedural reactions - no samples to load, so every game has impact feedback without authoring audio.
 - `computeFalloffGain` (function): function computeFalloffGain(distance: number, config: AudioFalloffConfig = {}): number — ⚠ undocumented
 - `distance3` (function): function distance3(a: { x: number; y: number; z: number }, b: { x: number; y: number; z: number }): number — ⚠ undocumented
 - `resolveEmitterGain` (function): function resolveEmitterGain(distance: number, sound: Pick<SoundDef, "gain" | "positional" | "falloff">, busGain: number): number — ⚠ undocumented
@@ -511,6 +522,13 @@
 - `createMusicState` (function): function createMusicState(): MusicStateSnapshot — Fresh state with no tier entered, so the first resolve always settles and reports `changed`.
 - `resolveMusicState` (function): function resolveMusicState(state: MusicStateSnapshot, input: MusicStateInput, config: MusicStateConfig): MusicStateResult — Pick the theme for the current intensity. Escalation is immediate; de-escalation waits for the tier's `holdMs` and needs the intensity to fall a `release` margin below the tier it is leaving.
 
+## @jgengine/core/audio/occlusion
+
+- `AUDIO_OCCLUSION_DEFAULTS` (const): const AUDIO_OCCLUSION_DEFAULTS: { readonly maxTestsPerTick: 8; readonly intervalMs: 150; readonly attenuation: 0.55; readonly lowpassHz: 1200; readonly maxDistance: 60; } — Defaults for {@link AudioOcclusionConfig}.
+- `AudioOcclusionConfig` (interface): interface AudioOcclusionConfig — Geometry occlusion for retained positional loops: a cheap line test between the listener and an emitter behind blocking geometry, bounded so a busy scene can never turn audio into a raycast pass. The shell runs the test against the scene's blockable colliders; the engine applies the resulting attenuation and low-pass to the loop it already owns.
+- `ResolvedAudioOcclusionConfig` (interface): interface ResolvedAudioOcclusionConfig — A fully specified occlusion policy, with every unset field replaced by its default.
+- `resolveOcclusionConfig` (function): function resolveOcclusionConfig(config: AudioOcclusionConfig | false = {}): ResolvedAudioOcclusionConfig — Fill in the occlusion defaults and clamp each field to a workable range: a finite test budget, a non-negative retest interval and distance cap, and an attenuation in `0..1`.
+
 ## @jgengine/core/audio/stepCadence
 
 - `StepCadenceConfig` (interface): interface StepCadenceConfig — Distance-driven footstep cadence. Pure state-in/state-out: feed it how far a mover travelled this frame and it tells you how many steps landed, so foley stays locked to ground distance instead of a wall-clock timer that desyncs when speed changes.
@@ -2857,7 +2875,7 @@
 - `SnapMode` (type): type SnapMode = "grid" | "free" | "surface" — ⚠ undocumented
 - `SnowEnvironmentDescriptor` (type): type SnowEnvironmentDescriptor = { kind: "snow" } & Required< Pick<SnowEnvironmentConfig, "area" | "density" | "speed" | "flakeSize" | "drift" | "wind" | "color" | "opacity"> > — ⚠ undocumented · used by `snow`: Declares a snowfall weather effect for `environment()` — area, density, drift, wind, and flake opacity.
 - `SoilRules` (interface): interface SoilRules — Fully-defaulted soil params parsed from a volume's `meta`.
-- `SoundDef` (interface): interface SoundDef { id: string; url?: string; synth?: SynthPatch; bus: AudioBusId; gain?: number; loop?: boolean; maxVoices?: number; priority?: number; positional?: boolean; falloff?: AudioFalloffConfig; doppler?: number; spatial?: {panning: "hrtf" | "equal… — ⚠ undocumented · used by `DEFAULT_FEEDBACK_CUE_SOUNDS` (@jgengine/core/audio/feedbackCues): Short procedural reactions - no samples to load, so every game has impact feedback without authoring audio.
+- `SoundDef` (interface): interface SoundDef { id: string; url?: string; synth?: SynthPatch; bus: AudioBusId; gain?: number; loop?: boolean; maxVoices?: number; priority?: number; duck?: {buses?: readonly string[]; amount?: number; seconds?: number;}; positional?: boolean; falloff?: A… — ⚠ undocumented · used by `DEFAULT_FEEDBACK_CUE_SOUNDS` (@jgengine/core/audio/feedbackCues): Short procedural reactions - no samples to load, so every game has impact feedback without authoring audio.
 - `SpatialGrid` (class): class SpatialGrid — A uniform-grid broad-phase over the x/z plane, separate from the rigid-body sim, for cheap same-tick proximity across hundreds–thousands of simple movers (swarm enemies). Rebuild each tick from the caller's own position arrays, then `queryCircle` (enemies hitting the player / an AoE) or `forEachPair` (mutual separation). Both are precise: no false negatives, no false positives beyond the exact distance test.
 - `SpawnDirectorConfig` (interface): interface SpawnDirectorConfig { waves: readonly WaveManifest[]; maxAlive?: number; escalationPerSecond?: number; alertBudgetPerSecond?: number; alertDecayPerSecond?: number; playerBudgetPerSecond?: number; maxSpawnsPerTick?: number; loop?: boolean; seed?: number; spawnP… — ⚠ undocumented
 - `SpawnDirectorState` (interface): interface SpawnDirectorState { wave: number; elapsed: number; waveElapsed: number; budget: number; alert: number; spawnedThisWave: number; spawnedTotal: number; rng: RandomSeed; done: boolean } — ⚠ undocumented