@jgengine/core 0.32.0 → 0.34.0

package/dist/movement/solidObstacles.js

@@ -48,34 +48,91 @@ export function solidObstacleReach(ctx) {
 }
 /** {@link solidObstacleReach} against a bare source and caller-owned cache. */
 export function sourceObstacleReach(source, cache) {
+    ensureSourceCache(source, cache);
+    return cache.value;
+}
+/** Coarse XZ cell for the obstacle index: a movement box spans tens of metres, so 1 m cells would be
+ * almost all empty lookups while a handful of these cover the whole query. */
+const INDEX_CELL_SIZE = 16;
+/** Beyond this many coarse cells a query walks the whole group list instead. */
+const INDEX_CELL_VOLUME_LIMIT = 4096;
+/** Two signed axis indices packed into one small-integer key (no string allocation, no boxing). */
+const INDEX_KEY_RADIX = 32768;
+const INDEX_KEY_BIAS = 16384;
+const INDEX_KEY_LIMIT = 16384;
+function indexCell(value) {
+    return Math.floor(value / INDEX_CELL_SIZE);
+}
+function indexKey(cx, cz) {
+    return (cx + INDEX_KEY_BIAS) * INDEX_KEY_RADIX + (cz + INDEX_KEY_BIAS);
+}
+/**
+ * Refresh `cache` for `source`: one scan resolves the broadphase reach and, when the source reports a
+ * version, every blocking object's obstacles into a coarse XZ index. A versioned source is scanned only
+ * when that version changes, so a per-frame query costs index lookups instead of a world scan.
+ */
+function ensureSourceCache(source, cache) {
+    const version = source.version?.();
+    if (version !== undefined) {
+        if (cache.version === version && cache.index !== undefined)
+            return;
+        cache.version = version;
+        cache.count = -1;
+        cache.index = undefined;
+        buildSourceCache(source, cache, source.list(), true);
+        return;
+    }
     const objects = source.list();
     if (cache.count === objects.length)
-        return cache.value;
+        return;
+    cache.count = objects.length;
+    cache.version = undefined;
+    cache.index = undefined;
+    buildSourceCache(source, cache, objects, false);
+}
+function buildSourceCache(source, cache, objects, index) {
+    const groups = index ? [] : EMPTY_GROUPS;
+    const cells = index ? new Map() : null;
     let horizontal = OBSTACLE_MAX_HALF_EXTENT;
     let vertical = OBSTACLE_VERTICAL_FLOOR;
     for (const object of objects) {
         const set = source.collidersOf(object.instanceId);
-        if (set === null)
-            continue;
-        for (const collider of resolveColliders(set)) {
-            if (!collider.blocks || collider.purpose !== "physical")
-                continue;
-            const shape = collider.shape;
-            const offset = shape.offset;
-            const ox = offset !== undefined ? Math.abs(offset[0]) : 0;
-            const oy = offset !== undefined ? Math.abs(offset[1]) : 0;
-            const oz = offset !== undefined ? Math.abs(offset[2]) : 0;
-            if (shape.kind === "sphere") {
-                horizontal = Math.max(horizontal, ox + oz + shape.radius);
-                vertical = Math.max(vertical, oy + shape.radius);
-            }
-            else {
-                // Horizontal bound sums both axes so any yaw of the box stays covered.
-                const h = shape.halfExtents;
-                horizontal = Math.max(horizontal, ox + oz + h[0] + h[2]);
-                vertical = Math.max(vertical, oy + h[1]);
+        const obstacles = [];
+        if (set === null) {
+            // No resolved collider: preserve the default 1×1×1 box.
+            if (index)
+                obstacles.push({ position: object.position });
+        }
+        else {
+            for (const collider of resolveColliders(set)) {
+                if (!collider.blocks || collider.purpose !== "physical")
+                    continue;
+                const reach = blockingReach(collider);
+                horizontal = Math.max(horizontal, reach[0]);
+                vertical = Math.max(vertical, reach[1]);
+                if (index)
+                    obstacles.push(obstacleFromCollider(collider, object.position, object.rotationY));
             }
         }
+        if (!index || obstacles.length === 0)
+            continue;
+        const group = {
+            x: object.position[0],
+            y: object.position[1],
+            z: object.position[2],
+            obstacles,
+        };
+        groups.push(group);
+        const cx = indexCell(group.x);
+        const cz = indexCell(group.z);
+        if (cx <= -INDEX_KEY_LIMIT || cx >= INDEX_KEY_LIMIT || cz <= -INDEX_KEY_LIMIT || cz >= INDEX_KEY_LIMIT)
+            continue;
+        const key = indexKey(cx, cz);
+        const bucket = cells.get(key);
+        if (bucket === undefined)
+            cells.set(key, [group]);
+        else
+            bucket.push(group);
     }
     const value = {
         horizontal: Math.min(horizontal, OBSTACLE_HORIZONTAL_CAP),
@@ -83,7 +140,56 @@ export function sourceObstacleReach(source, cache) {
     };
     cache.count = objects.length;
     cache.value = value;
-    return value;
+    if (index)
+        cache.index = { cells: cells, groups };
+}
+const EMPTY_GROUPS = [];
+/** A blocking collider's center-to-face reach, split so tower height cannot inflate the XZ query. */
+function blockingReach(collider) {
+    const shape = collider.shape;
+    const offset = shape.offset;
+    const ox = offset !== undefined ? Math.abs(offset[0]) : 0;
+    const oy = offset !== undefined ? Math.abs(offset[1]) : 0;
+    const oz = offset !== undefined ? Math.abs(offset[2]) : 0;
+    if (shape.kind === "sphere")
+        return [ox + oz + shape.radius, oy + shape.radius];
+    // Horizontal bound sums both axes so any yaw of the box stays covered.
+    const h = shape.halfExtents;
+    return [ox + oz + h[0] + h[2], oy + h[1]];
+}
+/** Every indexed obstacle whose object centre lies inside `min`..`max` — the set the broadphase promises. */
+function indexedObstaclesNear(index, min, max, out) {
+    const minCx = indexCell(min[0]);
+    const maxCx = indexCell(max[0]);
+    const minCz = indexCell(min[2]);
+    const maxCz = indexCell(max[2]);
+    const volume = Math.max(0, maxCx - minCx + 1) * Math.max(0, maxCz - minCz + 1);
+    if (volume > INDEX_CELL_VOLUME_LIMIT ||
+        minCx <= -INDEX_KEY_LIMIT || maxCx >= INDEX_KEY_LIMIT ||
+        minCz <= -INDEX_KEY_LIMIT || maxCz >= INDEX_KEY_LIMIT) {
+        for (const group of index.groups)
+            if (groupInBox(group, min, max))
+                pushGroup(group, out);
+        return;
+    }
+    for (let cx = minCx; cx <= maxCx; cx += 1) {
+        const rowBase = (cx + INDEX_KEY_BIAS) * INDEX_KEY_RADIX + minCz + INDEX_KEY_BIAS;
+        for (let cz = minCz; cz <= maxCz; cz += 1) {
+            const bucket = index.cells.get(rowBase + (cz - minCz));
+            if (bucket === undefined)
+                continue;
+            for (const group of bucket)
+                if (groupInBox(group, min, max))
+                    pushGroup(group, out);
+        }
+    }
+}
+function groupInBox(group, min, max) {
+    return group.x >= min[0] && group.x <= max[0] && group.y >= min[1] && group.y <= max[1] && group.z >= min[2] && group.z <= max[2];
+}
+function pushGroup(group, out) {
+    for (const obstacle of group.obstacles)
+        out.push(obstacle);
 }
 /** Yaw-rotate an entity-local AABB about the object origin and re-fit it to an axis-aligned box, expressed
  * as `min`/`max` relative to `position`. Conservative: the rotated box is grown to its enclosing AABB. */
@@ -188,7 +294,7 @@ export function obstacleFromSolid(solid) {
  * @capability solid-obstacles the one blocking-geometry query the player resolver and NPC movers share
  */
 export function solidObstaclesNear(ctx, position, reachX, reachZ, height = WALKER_HEIGHT) {
-    const obstacles = sourceObstaclesNear(ctx.scene.object, solidObstacleReach(ctx), position, reachX, reachZ, height);
+    const obstacles = sourceObstaclesNear(ctx.scene.object, solidObstacleReach(ctx), position, reachX, reachZ, height, reachCache(ctx));
     appendWorldSolidObstacles(obstacles, ctx.world.solids, position, reachX, reachZ, height);
     return obstacles;
 }
@@ -199,8 +305,12 @@ function appendWorldSolidObstacles(obstacles, solids, position, reachX, reachZ,
         obstacles.push(obstacleFromSolid(solid));
     }
 }
-/** {@link solidObstaclesNear} against a bare source and an already-resolved reach. */
-export function sourceObstaclesNear(source, reach, position, reachX, reachZ, height = WALKER_HEIGHT) {
+/**
+ * {@link solidObstaclesNear} against a bare source and an already-resolved reach. Pass the source's
+ * {@link ObstacleReachCache} to use the version-keyed obstacle index; a source that reports no
+ * `version()` keeps the per-query `inBox` gather.
+ */
+export function sourceObstaclesNear(source, reach, position, reachX, reachZ, height = WALKER_HEIGHT, cache) {
     const min = [
         position[0] - reachX - reach.horizontal,
         position[1] - reach.vertical,
@@ -212,6 +322,15 @@ export function sourceObstaclesNear(source, reach, position, reachX, reachZ, hei
         position[2] + reachZ + reach.horizontal,
     ];
     const obstacles = [];
+    if (cache !== undefined && source.version !== undefined) {
+        ensureSourceCache(source, cache);
+        const index = cache.index;
+        if (index !== undefined) {
+            indexedObstaclesNear(index, min, max, obstacles);
+            appendWorldSolidObstacles(obstacles, source.solids, position, reachX, reachZ, height);
+            return obstacles;
+        }
+    }
     for (const object of source.inBox(min, max)) {
         const set = source.collidersOf(object.instanceId);
         if (set === null) {
@@ -233,8 +352,8 @@ export function sourceObstaclesNear(source, reach, position, reachX, reachZ, hei
  * X/Z it may actually take this tick. A step into a wall is cut on the blocked axis and preserved on the
  * other, exactly as {@link stepPlayerMovement} resolves the player's.
  *
- * Bounded by the same broadphase as the player's gather: one `inBox` query sized to this step, never a
- * full-world scan, so it stays affordable per NPC per tick.
+ * Bounded by the same broadphase as the player's gather: one query sized to this step, answered from the
+ * source's obstacle index, never a full-world scan, so it stays affordable per NPC per tick.
  *
  * The sliding is already axis-separated: X and Z are resolved independently inside, so a caller that
  * also splits its own movement by axis must hand this exactly one axis per call (`stepZ: 0`, then
@@ -265,7 +384,7 @@ export function resolveSourceWalkerStep(source, cache, position, stepX, stepZ, o
     if (stepX === 0 && stepZ === 0)
         return { stepX, stepZ };
     const radius = options.radius ?? DEFAULT_OBSTACLE_PLAYER_RADIUS;
-    const obstacles = sourceObstaclesNear(source, sourceObstacleReach(source, cache), position, Math.abs(stepX) + radius, Math.abs(stepZ) + radius);
+    const obstacles = sourceObstaclesNear(source, sourceObstacleReach(source, cache), position, Math.abs(stepX) + radius, Math.abs(stepZ) + radius, WALKER_HEIGHT, cache);
     return slideStep(position, stepX, stepZ, obstacles, radius, options.stepUpHeight ?? 0);
 }
 /** {@link resolveWalkerStep} against an already-gathered obstacle set. */

package/dist/run/runLoop.d.ts

@@ -0,0 +1,88 @@
+/** How a run ended: what it carried reached the bank, or it was lost. */
+export type RunOutcome = "banked" | "lost";
+/**
+ * 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.
+ */
+export interface RunChange<T> {
+    id: string;
+    value: T;
+    /** Relative draw weight (default `1`); a non-positive weight is never drawn. */
+    weight?: number;
+    /** Completed runs this change needs before it can be drawn (default `0`). */
+    after?: number;
+}
+/** The change a run opens with, and which run it is. */
+export interface RunOffer<T> {
+    /** 1-based run number: `1` is the first run, before anything has been banked. */
+    run: number;
+    changeId: string | null;
+    change: T | null;
+}
+/** Everything a run loop stores as plain JSON: the run in progress plus lifetime totals. */
+export interface RunLoopState {
+    /** The run in progress, or `0` before the first `start`. */
+    run: number;
+    /** Runs settled so far; also the number `after` gates are read against. */
+    completed: number;
+    /** What the run in progress carries and can still lose. */
+    haul: number;
+    /** Change drawn for the run in progress, or `null`. */
+    changeId: string | null;
+    bankedTotal: number;
+    lostTotal: number;
+    bestHaul: number;
+}
+/** What one closed run banked or lost, and what the next run changes. */
+export interface RunSettlement<T> {
+    outcome: RunOutcome;
+    /** What the run carried before the multiplier. */
+    haul: number;
+    /** What reached the bank: the haul after the line multiplier on a bank, `0` on a loss. */
+    banked: number;
+    /** What the run lost: the whole haul on a loss, `0` on a bank. */
+    lost: number;
+    completed: number;
+    bestHaul: number;
+    /** The next run's change, drawn here so a results screen can name it. */
+    next: RunOffer<T>;
+}
+/** Configuration for {@link createRunLoop}. */
+export interface RunLoopConfig<T> {
+    /** Seed for the run-to-run draw: the same seed and history replay the same sequence. */
+    seed: string | number;
+    /** Authored table of next-run changes; omit a table for a loop that never varies. */
+    changes?: readonly RunChange<T>[];
+}
+/**
+ * A run's lifecycle: what it carries and can lose, and the change it hands the next run.
+ */
+export interface RunLoop<T> {
+    /** Open the next run and hand back its offer. Calling it on an open run returns that run's offer and keeps its haul. */
+    start(): RunOffer<T>;
+    /** Add to what the run in progress carries; negative or non-finite amounts are ignored. Returns the haul. */
+    carry(amount: number): number;
+    /** What the run in progress carries. */
+    haul(): number;
+    /** The run in progress's offer, or the offer the next `start` would open. */
+    offer(): RunOffer<T>;
+    /**
+     * Close the run in progress: bank the haul scaled by `multiplier`, or lose it. Throws when no run
+     * is open, so a double settle cannot bank the same haul twice.
+     */
+    settle(outcome: RunOutcome, multiplier?: number): RunSettlement<T>;
+    snapshot(): RunLoopState;
+    restore(next: RunLoopState): void;
+}
+/**
+ * Bank-or-lose between runs, with one deterministic change per run drawn from an authored table.
+ *
+ * A run's haul banks when it ends in a bank and is lost when it ends in a loss; the money itself stays
+ * with the game (pair it with `progression/careerBank`). After each settled run the loop draws the next
+ * run's change from `changes`: eligible when `after <= completed`, never the change just played unless
+ * it is the only one eligible, weighted by `weight`. The draw is `seededRng(seed:run:N)`, so the same
+ * seed and the same run history give the same sequence, before or after a save/load.
+ *
+ * @capability run-loop bank or lose what a run carries, with one deterministic change per run
+ */
+export declare function createRunLoop<T>(config: RunLoopConfig<T>): RunLoop<T>;

package/dist/run/runLoop.js

@@ -0,0 +1,92 @@
+import { pickWeighted } from "../random/pick.js";
+import { seededRng } from "../random/rng.js";
+function positive(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+/**
+ * Bank-or-lose between runs, with one deterministic change per run drawn from an authored table.
+ *
+ * A run's haul banks when it ends in a bank and is lost when it ends in a loss; the money itself stays
+ * with the game (pair it with `progression/careerBank`). After each settled run the loop draws the next
+ * run's change from `changes`: eligible when `after <= completed`, never the change just played unless
+ * it is the only one eligible, weighted by `weight`. The draw is `seededRng(seed:run:N)`, so the same
+ * seed and the same run history give the same sequence, before or after a save/load.
+ *
+ * @capability run-loop bank or lose what a run carries, with one deterministic change per run
+ */
+export function createRunLoop(config) {
+    const table = config.changes ?? [];
+    const known = new Set();
+    for (const change of table) {
+        if (known.has(change.id))
+            throw new Error(`run change "${change.id}" is declared twice`);
+        known.add(change.id);
+    }
+    let run = 0;
+    let completed = 0;
+    let haul = 0;
+    let changeId = null;
+    let bankedTotal = 0;
+    let lostTotal = 0;
+    let bestHaul = 0;
+    function drawFor(index, previous) {
+        const eligible = table.filter((change) => (change.after ?? 0) <= index - 1);
+        const fresh = eligible.filter((change) => change.id !== previous);
+        // A one-entry table still offers its change rather than nothing.
+        const pool = fresh.length > 0 ? fresh : eligible;
+        const rng = seededRng(`${config.seed}:run:${index}`);
+        const drawn = pickWeighted(rng, pool, (change) => change.weight ?? 1) ?? null;
+        return { run: index, changeId: drawn?.id ?? null, change: drawn?.value ?? null };
+    }
+    function offer() {
+        // An open run's change was adopted at `start`, so the offer repeats it instead of redrawing.
+        if (run > completed) {
+            const adopted = table.find((change) => change.id === changeId);
+            return { run, changeId, change: adopted?.value ?? null };
+        }
+        return drawFor(completed + 1, changeId);
+    }
+    return {
+        start() {
+            if (run > completed)
+                return offer();
+            const next = offer();
+            run = next.run;
+            haul = 0;
+            changeId = next.changeId;
+            return next;
+        },
+        carry(amount) {
+            haul += positive(amount);
+            return haul;
+        },
+        haul: () => haul,
+        offer,
+        settle(outcome, multiplier) {
+            if (run <= completed)
+                throw new Error("run loop: no run is open to settle");
+            const settledHaul = haul;
+            const scale = Number.isFinite(multiplier) ? Math.max(0, multiplier ?? 1) : 1;
+            const banked = outcome === "banked" ? Math.round(settledHaul * scale) : 0;
+            const lost = outcome === "lost" ? settledHaul : 0;
+            bankedTotal += banked;
+            lostTotal += lost;
+            bestHaul = Math.max(bestHaul, banked);
+            completed = run;
+            haul = 0;
+            return { outcome, haul: settledHaul, banked, lost, completed, bestHaul, next: drawFor(completed + 1, changeId) };
+        },
+        snapshot: () => ({ run, completed, haul, changeId, bankedTotal, lostTotal, bestHaul }),
+        restore(next) {
+            run = Math.max(0, Math.floor(next.run));
+            completed = Math.max(0, Math.floor(next.completed));
+            if (run < completed)
+                run = completed;
+            haul = positive(next.haul);
+            changeId = next.changeId !== null && known.has(next.changeId) ? next.changeId : null;
+            bankedTotal = positive(next.bankedTotal);
+            lostTotal = positive(next.lostTotal);
+            bestHaul = positive(next.bestHaul);
+        },
+    };
+}

package/dist/runtime/context/combat.js

@@ -68,6 +68,7 @@ export function createCombatSubsystem(d) {
                 absorbed: Math.max(0, application.incoming - application.dealt),
                 remaining: application.remaining,
                 lethal: application.lethal,
+                ...(application.at === undefined ? {} : { position: application.at }),
             });
         },
         onLethal(instanceId, lethalCtx) {

package/dist/runtime/context/scene.js

@@ -51,20 +51,22 @@ export function createSceneSubsystem(d) {
         return object === null ? undefined : content.objectById?.(object.catalogId);
     }
     // `moveToward` reads the same blocking colliders the player resolver does, so a chaser stops at the
-    // wall that stops the player rather than lerping through it.
+    // wall that stops the player rather than lerping through it. The obstacle index behind it rebuilds
+    // only when this version moves: an object placed, moved, rotated or re-collidered.
     const walkerReach = createObstacleReachCache();
     const solidSource = {
         solids: d.solids,
         list: () => objects.list(),
         inBox: (min, max) => objects.inBox(min, max),
         collidersOf: (instanceId) => objectCollidersOf(instanceId),
+        version: () => objects.version(),
     };
     const spatial = createSpatialApi({
         resolvePosition: (instanceId) => entities.get(instanceId)?.position,
         candidates: entities.ids,
         grid: { cellSize: 8 },
         incremental: true,
-        resolveStep: (position, stepX, stepZ) => slideStep(position, stepX, stepZ, sourceObstaclesNear(solidSource, sourceObstacleReach(solidSource, walkerReach), position, Math.abs(stepX) + DEFAULT_OBSTACLE_PLAYER_RADIUS, Math.abs(stepZ) + DEFAULT_OBSTACLE_PLAYER_RADIUS)),
+        resolveStep: (position, stepX, stepZ) => slideStep(position, stepX, stepZ, sourceObstaclesNear(solidSource, sourceObstacleReach(solidSource, walkerReach), position, Math.abs(stepX) + DEFAULT_OBSTACLE_PLAYER_RADIUS, Math.abs(stepZ) + DEFAULT_OBSTACLE_PLAYER_RADIUS, undefined, walkerReach)),
         ...(occluder !== undefined ? { occluder } : {}),
     });
     const entityColliders = new Map();
@@ -123,6 +125,7 @@ export function createSceneSubsystem(d) {
         return true;
     }
     function reportObjectCollisionMesh(catalogId, mesh) {
+        objects.markSpatialChange();
         if (mesh === null) {
             const existed = meshObjectByCatalogId.delete(catalogId);
             if (existed)
@@ -138,6 +141,7 @@ export function createSceneSubsystem(d) {
         return true;
     }
     function reportObjectBounds(catalogId, bounds) {
+        objects.markSpatialChange();
         if (bounds === null) {
             const existed = measuredObjectByCatalogId.delete(catalogId);
             if (existed)
@@ -350,6 +354,7 @@ export function createSceneSubsystem(d) {
                 objectColliders.delete(instanceId);
             else
                 objectColliders.set(instanceId, colliders);
+            objects.markSpatialChange();
             signalNotify();
         },
         collidersOf: objectCollidersOf,

package/dist/scene/objectStore.d.ts

@@ -69,6 +69,10 @@ export interface ObjectStore {
     ids(): readonly string[];
     at(x: number, y: number, z: number, tolerance?: number): SceneObject[];
     inBox(min: EntityPosition, max: EntityPosition): readonly SceneObject[];
+    /** Bumps whenever membership, a position or a rotation changes — cheap cache key for consumers. */
+    version(): number;
+    /** Bump {@link version} for a change the store cannot see, such as a consumer-owned collider set. */
+    markSpatialChange(): void;
     clear(): void;
     subscribe(listener: () => void): () => void;
     /** Notified only when the object set changes (place/remove), never on move/rotate/setVisual — markers read live poses imperatively. */