@jgengine/core 0.34.0 → 0.36.0

package/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.34.0";
+export declare const VERSION = "0.36.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];

package/dist/meta/changelog.js

@@ -1,12 +1,54 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.34.0";
+export const VERSION = "0.36.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "0.36.0": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.36.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.33.0`; `@jgengine/github` is `0.23.0`.",
+        ],
+        added: [
+            "`createAgentSystem` (`@jgengine/core/agents/system`) takes a game's needs, options, mood weights, members and schedules once and returns a running cast: one `tick(dt)` for everyone, one target selector for the whole system, a fallback declared once, and a plain-JSON `save()`/`load()` that rides the game's own save.",
+            "`--quick` on `bun run shoot` and `bun run drive` is the 960x540 iteration preset: one settled frame (a 2s settle window in drive), no video, no perf pass, written as `<name>-quick.png` and timed on its own line. It refuses a 1600x900 pixel claim, a frame-time claim, a non-desktop device and a recording flag by name instead of producing weaker evidence; full stays the default for PR shots. On a warm daemon a two-shot `drive` of ember-command went 9.3s to 8.2s and 4316KB to 1383KB of PNG.",
+            "`createPlayScript` / `runPlayScript` (`@jgengine/shell/play`) play a real `PlayableGame` headlessly from a tick-based script: `move`, `aim`, `fire`, `use`, `wait` and `command` steps plus `setup`/`onTick` hooks, `expect` assertions read after setup and on their own tick, a tick timeline, and an FNV digest for replay comparison. It replays the shell's own frame pipeline — held movement through the walk controller, a bound action resolving to its command on press and repeat, interact prompts, hotbar — so a script proves the same code path a player's hands do. No browser, no wall clock, fixed `dt`.",
+            "`bun run simulate <game> <script>` runs a committed `<game>/scripts/*.play.ts` against a game under `./Games`, prints the timeline, names a failed assertion and exits 1. It merges the game's own tsconfig `paths` with this checkout's source packages, so the game imports and the engine under test are one module graph.",
+            "`HeadlessRunner.aim()` steers the walk controller mid-run; `HeadlessRunnerOptions` gains `seed` (deterministic `ctx.rng`) and `collision` (the shell's voxel config, previously dropped on the headless path).",
+        ],
+        changed: [
+            "The graphics quality tier now costs what it claims on the render path. A tier's post chain renders at its own resolution scale (`low` 0.7, `medium` 0.85, `high`/`ultra` native) instead of always at the canvas size, and a game's authored `shadowMapSize` and `cascades` are a ceiling the tier caps rather than a value it ignored — every reference game authored 3 cascades and 1024/2048, so no tier changed a shadow before this. `low` and `medium` also stretch the far cascades' refresh interval, and the smallest caster worth a depth draw grows as the map shrinks. `high` and `ultra` keep native resolution, the authored shadow sizes and the measured cadence, so their frames are unchanged.",
+            "Measured uncapped at 1600x900: whole-frame draws at `low` fell 53% in harbor-heat (515 → 242) and 63% in drift-foundry (1,098 → 408), with the shadow pass there down from 911 ms to 344 ms over a 6 s window; `high` and `ultra` held their draw counts.",
+            "Terrain build no longer scans every road and path segment for every vertex. A baked path corridor, a draped road and a painted polyline region each answer \"how far is this point?\" from a precomputed segment grid, so Scrap Signal's world build drops from 16.6 s to 0.51 s on the same machine and its longest boot stall from 11.6–18.4 s to 1.2 s. Sampled heights and palettes are bit-identical to the previous full scan, and `withPathProfiles` still composes profiles in order.",
+            "Load-time shader warmup compiles against the render state the first frame actually draws with. A scene whose post chain renders into its own buffer was linking two programs per material, one linear untone-mapped set the frame draws and one canvas set nothing ever drew; the cover no longer waits for the second set. Harbor Heat links 84 programs to 58 and Scrap Signal 124 to 83 before the cover lifts, with no visual change.",
+        ],
+        removed: [],
+    },
+    "0.35.0": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.35.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.32.0`; `@jgengine/github` is `0.22.0`.",
+        ],
+        added: [
+            "`ModelLodConfig.crowdCapacity` declares how many characters of one model a batch draws (default 128). A character past the cap keeps its own rig at its distance tier instead of disappearing.",
+            "`ModelLodConfig.crowdDistance` accepts `0`, which batches a character at every distance instead of only past 25 m. A game with a near crowd or a close-quarters army sets it to batch members in front of the camera too.",
+            "`characterRigTier` (`@jgengine/shell/render/characterLod`) resolves the distance tier a character poses its own rig on, which is the fallback for an over-cap crowd.",
+            "`audio.zones` (`@jgengine/core/game/playableGame`): a scene declares world-space ambience zones, one looping bed per zone. The shell crossfades bed levels from the listener position on each sound's own bus, so entering, leaving and walking between zones hand over instead of cutting.",
+            "`audio.occlusion` (`@jgengine/core/audio/occlusion`): budgeted geometry occlusion for retained positional loops. A blocked line attenuates the loop and darkens it through a low-pass; the per-tick test budget and interval bound the cost, and a loop that cannot be tested stays on distance-only.",
+            "`SoundDef.duck`: a cue can lower named buses for its own duration. `AudioEngine.duck` returns a release, and the player's own gain is restored exactly even when they move the slider mid-duck.",
+            "`AudioEngine.ambience()`, `AudioEngine.occlusionStats()` and `window.__jgengineAudio` report the zone mix, the newest occlusion test and the measured per-test cost for capture and diagnostics.",
+        ],
+        changed: [
+            "The character batch path now covers every drawable character model, not only skinned locomotion rigs: a node-transform character (rotating limbs, no skin) rides the node a clip moves, and a model with no clips at all batches as a static geometry. Both still bake to one geometry per material, so a crowd draws once per model and material.",
+            "Batched characters are pickable: the batch carries the entity ids of the instances it drew, so `worldHit().entity` and a click on a batched character resolve to the character instead of falling through to the ground.",
+            "Load-time shader warmup compiles what the first frame can reach, reveals as soon as those programs are linked, and finishes the rest in background rounds, so a scene no longer holds the loading cover for its whole model stream and no longer drops a compile onto a frame that is already showing. The loading cover names the shader count, the seconds waited and the work left for the background.",
+            "A crowd batch silently dropped members past its fixed 128 instances while their markers still hid them, so a full scene lost characters. Members past the declared capacity now keep their own rigs.",
+            "A crowd batch's clock now follows the game clock when one is bound, so a paused game no longer keeps its crowd walking.",
+        ],
+        removed: [],
+    },
     "0.34.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.34.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.31.0`; `@jgengine/github` is `0.21.0`.",
         ],
         added: [
+            "`PaceBand` on `DriverGoal` (`paceBand` + caller-measured `paceGap`) gives catch-up pacing an owner in `@jgengine/core/ai/driver`: a dead zone around `margin` (`tolerance`), `ease` shedding pace for a car ahead over `easeAt`, `push` adding it for a car behind over `pushAt`, and `scale` as the per-car share. `paceBandFactor(band, gap)` exposes the rule on its own. Deterministic scalar math, no allocation per step; the push never outdrives `DriverTuning.maxSpeed`. First adopter: Drift Foundry's rival field, which deletes its own `paceBand`; second: Harbor Heat's interceptors.",
             "`createRunLoop` (`@jgengine/core/run/runLoop`) holds a run's at-risk haul, banks it scaled by the line or loses it on a failure, and draws one authored change for each next run from a seeded table, so the same seed and run history replay the same sequence. State round-trips through `snapshot`/`restore`; the money stays in `progression/careerBank`.",
         ],
         changed: [],

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.34.0",
+  "version": "0.36.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.34.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.36.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.34.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.36.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

@@ -48,6 +48,35 @@
 - `AgentScheduleStop` (interface): interface AgentScheduleStop extends RoutineStopSpec — One authored stop in an agent's day. The shape is the routine owner's (`sim/routine`) plus a beat: the places a working stop walks in order, so a janitor on patrol is an agent with a route rather than a special case.
 - `createAgentSchedule` (function): function createAgentSchedule(config: AgentScheduleConfig): AgentSchedule — Resolve an authored day plan into a clock-driven schedule. Timing, travel and arrival slips come from `sim/routine`; this adds the work beat and the refills a stop carries, so an off-hours stop is just another authored stop and a patrol is not a second scheduler.
 
+## @jgengine/core/agents/system
+
+- `Agent` (interface): interface Agent — Needs, mood, schedule and a chosen action, in one object a game ticks.
+- `AgentAction` (interface): interface AgentAction — What the agent is doing.
+- `AgentFallback` (interface): interface AgentFallback — Where an agent goes when the thing it wanted is gone: a named option and a named place.
+- `AgentFrame` (interface): interface AgentFrame — What one update produced: the action, the feeling, and where the day plan puts the agent.
+- `AgentMemberSpec` (interface): interface AgentMemberSpec extends UtilityTunables — One member: an id, and only what differs from the system's defaults.
+- `AgentMemberState` (interface): interface AgentMemberState — One member's saved state: its agent snapshot plus the off-camera flag the snapshot does not carry.
+- `AgentMoodConfig` (interface): interface AgentMoodConfig — The mood policy a member runs on: which needs matter, and the game's own words for the bands.
+- `AgentScheduleConfig` (interface): interface AgentScheduleConfig — An agent's whole day as data: what it does, where, and when.
+- `AgentSchedulePhase` (interface): interface AgentSchedulePhase — Where a schedule puts an agent at one instant.
+- `AgentScheduleStop` (interface): interface AgentScheduleStop extends RoutineStopSpec — One authored stop in an agent's day. The shape is the routine owner's (`sim/routine`) plus a beat: the places a working stop walks in order, so a janitor on patrol is an agent with a route rather than a special case.
+- `AgentSelectView` (interface): interface AgentSelectView — What a selector is told about the member asking: who it is, its live agent, and where it stands.
+- `AgentSelector` (type): type AgentSelector = (view: AgentSelectView) => readonly AgentTarget[] — Everything the member could do right now, as the game's world offers it. Declared once per system.
+- `AgentSnapshot` (interface): interface AgentSnapshot — Serializable whole agent: needs, feeling, held action, day-plan cursor and the far flag.
+- `AgentSystem` (interface): interface AgentSystem — A whole cast of agents behind one factory and one tick.
+- `AgentSystemConfig` (interface): interface AgentSystemConfig — The game's data, in one place: what its people need, what they can do, and how they feel.
+- `AgentSystemState` (interface): interface AgentSystemState — The whole system as plain JSON - drop it in a save, read it back with {@link AgentSystem.load}.
+- `AgentSystemStorage` (interface): interface AgentSystemStorage — Where a system keeps its save data: a key-value store, a save slot, or a test's map.
+- `AgentTarget` (interface): interface AgentTarget — One reachable thing the agent could do this tick, as the game sees its own world.
+- `Mood` (interface): interface Mood — What the agent feels right now, on the caller's own tier labels.
+- `MoodTier` (interface): interface MoodTier — One labelled band of the 0-100 mood score.
+- `MoodWeight` (interface): interface MoodWeight — One need's say in the mood score; weights are relative, so they need no fixed total.
+- `NeedDefinition` (type): type NeedDefinition = DecayMeterConfig — A decaying need is a survival decay meter (`max`/`min`/`start`/`rate`, optional moodle thresholds) whose satisfaction an agent brain reads to score actions. The meter owns the numbers; per-need appeal lives in the game's utility options.
+- `UtilityInterrupt` (interface): interface UtilityInterrupt — A need level that overrides the sticky pick the moment it is crossed.
+- `UtilityOption` (interface): interface UtilityOption — A thing an agent can decide to do, scored against its needs.
+- `UtilityTunables` (interface): interface UtilityTunables — In-play dials that stay reachable through {@link UtilityBrain.retune}.
+- `createAgentSystem` (function): function createAgentSystem(config: AgentSystemConfig): AgentSystem — One call for a whole cast: a game hands over its needs, options, mood weights, schedules and one target selector, and gets back a running system with a single `tick(dt)` and a save blob that goes into the game's own save.
+
 ## @jgengine/core/behaviour/behaviour
 
 - `Behaviour` (class): class Behaviour — Subclass and override the lifecycle hooks. A behaviour only joins the per-frame update dispatch if it actually overrides `onUpdate` (prototype-identity check at each activation), so hook-only behaviours cost nothing per frame.

package/skills/jgengine-gameplay/capabilities.md

@@ -23,6 +23,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 ## agents — a needs, thought, action and mood loop an agent runs on the world clock
 
 - `createAgent` (function) · `import { createAgent } from "@jgengine/core/agents/agent"`
+- `createAgentSystem` (function) · `import { createAgentSystem } from "@jgengine/core/agents/system"`
 
 ## auction-book — timed bid auctions with escrowed bids, buyout, anti-snipe close extension, and collection-box settlement