@jgengine/core 0.14.0 → 0.15.0-next.0

package/dist/ai/flock.js

@@ -88,40 +88,28 @@ export function flockSteer(agent, neighbors, config, target) {
     return [steerX * scale, steerY * scale, steerZ * scale];
 }
 const CELL_KEY_STRIDE = 1_048_576;
-const gridCells = new Map();
-const freeBuckets = [];
-const neighborScratch = [];
-let steerScratch = new Float64Array(0);
 function cellKey(cx, cz) {
     return cx * CELL_KEY_STRIDE + cz;
 }
-function takeBucket() {
-    return freeBuckets.pop() ?? [];
-}
-function ensureSteerCapacity(agentCount) {
-    const needed = agentCount * 3;
-    if (steerScratch.length < needed) {
-        steerScratch = new Float64Array(needed);
-    }
-}
+/**
+ * Per-call spatial index + scratch — never module-global.
+ * Two `stepFlock` worlds in one process must not share a grid (#1545 / sdk remediation Phase 3a).
+ */
 function buildAgentGrid(agents, invCell) {
-    for (const bucket of gridCells.values()) {
-        bucket.length = 0;
-        freeBuckets.push(bucket);
-    }
-    gridCells.clear();
+    const gridCells = new Map();
     for (let i = 0; i < agents.length; i += 1) {
         const position = agents[i].position;
         const key = cellKey(Math.floor(position[0] * invCell), Math.floor(position[2] * invCell));
         let bucket = gridCells.get(key);
         if (bucket === undefined) {
-            bucket = takeBucket();
+            bucket = [];
             gridCells.set(key, bucket);
         }
         bucket.push(i);
     }
+    return gridCells;
 }
-function fillNeighbors(agents, agentIndex, invCell) {
+function fillNeighbors(agents, agentIndex, invCell, gridCells, neighborScratch) {
     const agent = agents[agentIndex];
     const cx = Math.floor(agent.position[0] * invCell);
     const cz = Math.floor(agent.position[2] * invCell);
@@ -152,10 +140,12 @@ export function stepFlock(agents, config, dt, target) {
         return;
     const cellSize = config.neighborRadius > 1e-6 ? config.neighborRadius : 1;
     const invCell = 1 / cellSize;
-    buildAgentGrid(agents, invCell);
-    ensureSteerCapacity(count);
+    // All scratch is call-local so concurrent worlds (or re-entrant steps) never share a grid.
+    const gridCells = buildAgentGrid(agents, invCell);
+    const neighborScratch = [];
+    const steerScratch = new Float64Array(count * 3);
     for (let i = 0; i < count; i += 1) {
-        fillNeighbors(agents, i, invCell);
+        fillNeighbors(agents, i, invCell, gridCells, neighborScratch);
         const steer = flockSteer(agents[i], neighborScratch, config, target);
         const base = i * 3;
         steerScratch[base] = steer[0];

package/dist/ai/laneSelect.js

@@ -1,3 +1,4 @@
+import { resolveRng } from "../random/resolveRng.js";
 /**
  * Live cost-based selection over parallel corridors (#286.7) — the racing-line / lane-merge pick
  * every AI driver hand-rolled. Evaluate each lane's cost this tick (crowding, hazards, distance)
@@ -9,7 +10,7 @@ export function pickLane(candidates, options = {}) {
         return null;
     const stickiness = options.stickiness ?? 1.2;
     const tieEpsilon = options.tieEpsilon ?? 0;
-    const rng = options.rng ?? Math.random;
+    const rng = resolveRng(options.rng, "selectLane");
     let best = candidates[0];
     for (const candidate of candidates) {
         if (candidate.cost < best.cost)

package/dist/ai/mobBrain.js

@@ -1,4 +1,5 @@
 import { createThreatTable } from "./threat.js";
+import { resolveRng } from "../random/resolveRng.js";
 const HOLD = {
     targetId: null,
     moveTo: null,
@@ -18,7 +19,7 @@ export function createMobBrain(config, deps) {
     const wander = config.wander === false || config.wander === undefined ? null : config.wander;
     const wanderInterval = wander?.intervalSeconds ?? 4;
     const wanderArrive = wander?.arriveRadius ?? 0.6;
-    const rng = deps.rng ?? Math.random;
+    const rng = resolveRng(deps.rng, "createMobBrain");
     let currentMode = "idle";
     let currentTarget = null;
     let evading = false;

package/dist/ai/waveRunner.d.ts

@@ -0,0 +1,81 @@
+import { type DirectorContext, type SpawnDirectorConfig, type SpawnDirectorState, type SpawnRequest } from "./spawnDirector.js";
+/**
+ * A callback the wave runner hands each {@link SpawnRequest} the underlying spawn
+ * director emits. The runner never instantiates entities itself — it forwards the
+ * request (a free-string `entryId` "kind", cost, wave, optional point/lane) to the
+ * game, which decides what to build. Keeps the runner genre-agnostic.
+ */
+export type WaveSpawnSink = (request: SpawnRequest) => void;
+/**
+ * Configuration for {@link createWaveRunner}: the full {@link SpawnDirectorConfig}
+ * (escalating waves, budgets, seed, spawn points) plus an optional {@link WaveSpawnSink}.
+ * The runner owns the director state — you never pass a `SpawnDirectorState` here.
+ */
+export interface WaveRunnerConfig extends SpawnDirectorConfig {
+    /** Optional sink invoked once per spawned {@link SpawnRequest} during {@link WaveRunner.update}. */
+    onSpawn?: WaveSpawnSink;
+}
+/**
+ * A pooled, per-frame readout of the current wave — the "brain behind WAVE 3".
+ * Reused across {@link WaveRunner.view} calls (never per-frame allocated), so read
+ * it and render it, don't retain it.
+ */
+export interface WaveView {
+    /** 1-based wave number for display ("WAVE N"). The 0-based index lives on {@link WaveRunner.state}. */
+    wave: number;
+    /**
+     * Progress `0..1` through the current wave: `waveElapsed / duration` when the
+     * wave declares a `duration`, otherwise a budget-drain estimate (`1 - budget /
+     * waveBudget`). A best-effort readout for a progress bar, not an exact schedule.
+     */
+    waveProgress: number;
+    /** Spawn budget currently banked in the director. */
+    budget: number;
+    /** How many entities have spawned during the current wave. */
+    spawnedThisWave: number;
+    /** How many entities have spawned across every wave so far. */
+    spawnedTotal: number;
+    /** Current alert level `0..1` (raised by {@link WaveRunner.raiseAlert}, decays over time). */
+    alert: number;
+    /** True once the final non-looping wave has finished. */
+    done: boolean;
+}
+/** A live, observable, serializable wave/spawn runner over a seeded spawn director. */
+export interface WaveRunner {
+    /**
+     * Advance the director by `dt` seconds: bank budget, roll escalation/alert, cross
+     * wave boundaries, and forward every emitted {@link SpawnRequest} to the configured
+     * `onSpawn` sink. Pass a {@link DirectorContext} (defaults to `{ alive: 0 }`) to feed
+     * back the live alive-count / player positions. Notifies subscribers on change.
+     */
+    update(dt: number, ctx?: DirectorContext): void;
+    /** The pooled current-wave readout to render (do not retain). */
+    view(): WaveView;
+    /** Force an immediate jump to the next wave (delegates to `advanceWave`). Notifies. */
+    forceNextWave(): void;
+    /** Raise the alert level by `amount` (clamped `0..1`), boosting spawn budget. Notifies. */
+    raiseAlert(amount: number): void;
+    /** The raw underlying {@link SpawnDirectorState} (0-based `wave`); read-only snapshot of internals. */
+    state(): SpawnDirectorState;
+    /** Observe changes (update, forceNextWave, raiseAlert, restore). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save — the plain {@link SpawnDirectorState} object. */
+    snapshot(): SpawnDirectorState;
+    /** Restore from a {@link snapshot} (a plain {@link SpawnDirectorState}). Notifies. */
+    restore(snapshot: SpawnDirectorState): void;
+}
+/**
+ * A thin, stateful, observable wrapper around the seeded {@link createSpawnDirectorState}
+ * / {@link advanceSpawnDirector} model. It OWNS a {@link SpawnDirectorState}, ticks it
+ * from `update(dt, ctx?)`, keeps the new state, and forwards each emitted
+ * {@link SpawnRequest} to an optional `onSpawn` sink so the model never instantiates
+ * entities. `view()` returns a pooled per-frame readout — the "brain behind WAVE 3":
+ * the 1-based wave number, wave progress `0..1`, banked budget, per-wave and total
+ * spawn counts, alert, and done flag. `forceNextWave` / `raiseAlert` drive it,
+ * `subscribe` observes it, and `snapshot`/`restore` round-trip the plain serializable
+ * state object through a save. Nothing here is genre-specific: spawn-entry `kind`s
+ * (the director's `entryId`s) stay free strings the runner never interprets.
+ *
+ * @capability wave-runner observable serializable wave/spawn runner over the seeded spawn director — WAVE N, wave progress, budget/alert readout, onSpawn sink, snapshot/restore
+ */
+export declare function createWaveRunner(config: WaveRunnerConfig): WaveRunner;

package/dist/ai/waveRunner.js

@@ -0,0 +1,104 @@
+import { advanceSpawnDirector, advanceWave, createSpawnDirectorState, raiseAlert as raiseDirectorAlert, } from "./spawnDirector.js";
+const DEFAULT_CONTEXT = { alive: 0 };
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+/**
+ * A thin, stateful, observable wrapper around the seeded {@link createSpawnDirectorState}
+ * / {@link advanceSpawnDirector} model. It OWNS a {@link SpawnDirectorState}, ticks it
+ * from `update(dt, ctx?)`, keeps the new state, and forwards each emitted
+ * {@link SpawnRequest} to an optional `onSpawn` sink so the model never instantiates
+ * entities. `view()` returns a pooled per-frame readout — the "brain behind WAVE 3":
+ * the 1-based wave number, wave progress `0..1`, banked budget, per-wave and total
+ * spawn counts, alert, and done flag. `forceNextWave` / `raiseAlert` drive it,
+ * `subscribe` observes it, and `snapshot`/`restore` round-trip the plain serializable
+ * state object through a save. Nothing here is genre-specific: spawn-entry `kind`s
+ * (the director's `entryId`s) stay free strings the runner never interprets.
+ *
+ * @capability wave-runner observable serializable wave/spawn runner over the seeded spawn director — WAVE N, wave progress, budget/alert readout, onSpawn sink, snapshot/restore
+ */
+export function createWaveRunner(config) {
+    const onSpawn = config.onSpawn;
+    let state = createSpawnDirectorState(config);
+    const listeners = new Set();
+    // Pooled readout — reused across view() calls, never per-frame allocated.
+    const readout = {
+        wave: 1,
+        waveProgress: 0,
+        budget: 0,
+        spawnedThisWave: 0,
+        spawnedTotal: 0,
+        alert: 0,
+        done: false,
+    };
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    /** True if any field a HUD cares about differs between two states. */
+    function changed(a, b) {
+        return (a.wave !== b.wave ||
+            a.budget !== b.budget ||
+            a.spawnedThisWave !== b.spawnedThisWave ||
+            a.spawnedTotal !== b.spawnedTotal ||
+            a.alert !== b.alert ||
+            a.done !== b.done);
+    }
+    function waveProgress() {
+        const manifest = config.waves[state.wave];
+        if (manifest === undefined)
+            return state.done ? 1 : 0;
+        if (manifest.duration !== undefined && manifest.duration > 0) {
+            return clamp01(state.waveElapsed / manifest.duration);
+        }
+        if (manifest.budget > 0) {
+            return clamp01(1 - state.budget / manifest.budget);
+        }
+        return state.done ? 1 : 0;
+    }
+    return {
+        update(dt, ctx = DEFAULT_CONTEXT) {
+            const previous = state;
+            const step = advanceSpawnDirector(config, state, dt, ctx);
+            state = step.state;
+            if (onSpawn !== undefined) {
+                for (const spawn of step.spawns)
+                    onSpawn(spawn);
+            }
+            if (step.spawns.length > 0 || changed(previous, state))
+                notify();
+        },
+        view() {
+            readout.wave = state.wave + 1;
+            readout.waveProgress = waveProgress();
+            readout.budget = state.budget;
+            readout.spawnedThisWave = state.spawnedThisWave;
+            readout.spawnedTotal = state.spawnedTotal;
+            readout.alert = state.alert;
+            readout.done = state.done;
+            return readout;
+        },
+        forceNextWave() {
+            state = advanceWave(config, state);
+            notify();
+        },
+        raiseAlert(amount) {
+            state = raiseDirectorAlert(state, amount);
+            notify();
+        },
+        state() {
+            return state;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return state;
+        },
+        restore(snapshot) {
+            state = snapshot;
+            notify();
+        },
+    };
+}

package/dist/authoring.d.ts

@@ -1,9 +1,11 @@
 /**
- * Task-first JGEngine authoring surface.
+ * Core-side convenience barrel for pure authored helpers (loot, world features, ownership,
+ * spawn selection, RNG). **Not the game entrypoint** — game projects start at
+ * `@jgengine/shell/gameKit` (`defineGame`, `GameHost`, stores, systems, HUD). Prefer that
+ * surface; import from here only when you need a core helper the kit does not re-export.
  *
- * Game code should begin here. Domain and runtime deep imports remain available for
- * advanced composition, but this module intentionally exposes common authored
- * concepts without requiring callers to understand the repository layout.
+ * @deprecated Prefer `@jgengine/shell/gameKit` as the start-here surface for games. This
+ * module remains for deep core helpers and existing pure-import consumers; it is not removed.
  */
 export { type GameDefinition, type GameDefinitionConfig, type GameLoop, type InventoryDeclaration, type PhysicsConfig, type GameServerConfig, } from "./game/defineGame.js";
 export { lootTable, type LootTableDef, type LootEntry, type Drop, } from "./game/lootTable.js";

package/dist/authoring.js

@@ -1,9 +1,11 @@
 /**
- * Task-first JGEngine authoring surface.
+ * Core-side convenience barrel for pure authored helpers (loot, world features, ownership,
+ * spawn selection, RNG). **Not the game entrypoint** — game projects start at
+ * `@jgengine/shell/gameKit` (`defineGame`, `GameHost`, stores, systems, HUD). Prefer that
+ * surface; import from here only when you need a core helper the kit does not re-export.
  *
- * Game code should begin here. Domain and runtime deep imports remain available for
- * advanced composition, but this module intentionally exposes common authored
- * concepts without requiring callers to understand the repository layout.
+ * @deprecated Prefer `@jgengine/shell/gameKit` as the start-here surface for games. This
+ * module remains for deep core helpers and existing pure-import consumers; it is not removed.
  */
 export {} from "./game/defineGame.js";
 export { lootTable, } from "./game/lootTable.js";

package/dist/combat/castRunner.d.ts

@@ -3,6 +3,15 @@ export interface CastConfig {
     castTimeMs: number;
     /** Total movement distance tolerated before the cast auto-interrupts; default `0.04`. `Infinity` allows casting on the move. */
     moveTolerance?: number;
+    /**
+     * Per-tick movement at or below this is ignored rather than added to the running total — the
+     * caster's noise floor. A 3D game's pose jitters every frame from terrain-following ground snap
+     * and float drift; since `moveTolerance` accumulates, feeding those raw deltas straight in will
+     * silently cancel casts the player never interrupted, and the failure is intermittent rather than
+     * obvious. Only the game knows its own noise floor, so declare it once here instead of filtering
+     * at every `tick` call site. Default `0` (count every reported movement).
+     */
+    moveDeadzone?: number;
 }
 export interface CastBarSnapshot {
     abilityId: string;
@@ -34,7 +43,10 @@ export interface CastRunner {
     state(): CastBarSnapshot | null;
     /** Interrupt the in-flight cast now; returns the interruption event, or `null` when idle. */
     interrupt(reason?: CastInterruptReason): CastEvent | null;
-    /** Advance by `dtSeconds`; `movedDistance` accumulates toward the config's `moveTolerance`. */
+    /**
+     * Advance by `dtSeconds`; `movedDistance` accumulates toward the config's `moveTolerance`, except
+     * for per-tick movement at or below `moveDeadzone`, which is treated as jitter and ignored.
+     */
     tick(dtSeconds: number, movedDistance?: number): CastEvent | null;
 }
 /**

package/dist/combat/castRunner.js

@@ -26,6 +26,7 @@ export function createCastRunner() {
                 abilityId: config.abilityId,
                 castTimeMs: Math.max(0, config.castTimeMs),
                 moveTolerance: config.moveTolerance ?? DEFAULT_MOVE_TOLERANCE,
+                moveDeadzone: Math.max(0, config.moveDeadzone ?? 0),
                 elapsedMs: 0,
                 movedTotal: 0,
             };
@@ -43,7 +44,10 @@ export function createCastRunner() {
         tick(dtSeconds, movedDistance = 0) {
             if (active === null)
                 return null;
-            active.movedTotal += Math.max(0, movedDistance);
+            const moved = Math.max(0, movedDistance);
+            // Below the caster's noise floor this is jitter, not travel — do not accumulate it.
+            if (moved > active.moveDeadzone)
+                active.movedTotal += moved;
             if (active.movedTotal > active.moveTolerance) {
                 const abilityId = active.abilityId;
                 active = null;

package/dist/combat/comboMeter.d.ts

@@ -0,0 +1,140 @@
+/**
+ * One tier threshold in a {@link ComboMeter}. Tiers gate on the integer combo
+ * `count` (not a filled fraction), and `id` is a free string the game owns and
+ * styles ("good", "great", "savage", …) — the model never interprets it.
+ */
+export interface ComboTier {
+    /** Combo count at or above which this tier becomes active. Tiers sort ascending. */
+    threshold: number;
+    /** Free-string tier id the game styles; the model never branches on it. */
+    id: string;
+    /** Explicit multiplier while this tier is active. Overrides any fallback curve. */
+    multiplier?: number;
+}
+/** Options for {@link createComboMeter}. */
+export interface ComboMeterConfig {
+    /**
+     * Decay window in ms: how long after the last {@link ComboMeter.hit} the combo
+     * survives before it drops. Each `hit` resets this window; when it elapses the
+     * combo drops (to 0, or by {@link ComboMeterConfig.dropStep}).
+     */
+    windowMs: number;
+    /** Tier thresholds on the integer count. Sorted ascending internally; ids are free strings. */
+    tiers?: readonly ComboTier[];
+    /**
+     * When the window elapses, drop the count by this many instead of clearing to 0,
+     * re-arming the window so a long combo bleeds down step by step. Omit → drop to 0.
+     */
+    dropStep?: number;
+    /**
+     * Fallback multiplier growth when the active tier has no explicit `multiplier`:
+     * `1 + (tierIndex + 1) * multiplierPerTier`. Below the first tier the multiplier
+     * is always 1. Ignored where a tier sets its own `multiplier`.
+     */
+    multiplierPerTier?: number;
+    /**
+     * Last-resort multiplier curve when neither the active tier's `multiplier` nor
+     * `multiplierPerTier` applies. Receives the current count and active tier index
+     * (`-1` below the first tier). Not serialized — snapshot/restore carry state, not config.
+     */
+    multiplierCurve?: (count: number, tierIndex: number) => number;
+    /** Injected clock (ms). Default `Date.now`. Ignored once {@link ComboMeter.update} drives time. */
+    now?: () => number;
+    /** Initial combo count (pre-seed a demo/save at a high chain). Default 0. */
+    count?: number;
+}
+/**
+ * A pooled, read-only snapshot of the live meter for a renderer to draw each
+ * frame. Reused across {@link ComboMeter.view} calls and overwritten on the next
+ * one — read it, do not retain it. For a save, use {@link ComboMeter.snapshot}.
+ */
+export interface ComboMeterView {
+    /** Current combo count. */
+    count: number;
+    /** Highest count reached since the last {@link ComboMeter.reset}. */
+    peak: number;
+    /** Active tier id, or `null` below the first tier. */
+    tier: string | null;
+    /** Active tier index into the sorted tier list, or `-1` below the first tier. */
+    tierIndex: number;
+    /** Derived multiplier for the active tier (default 1). */
+    multiplier: number;
+    /** Milliseconds left in the decay window before the next drop (0 when idle). */
+    remainingMs: number;
+    /** Window remaining as `0..1` — for a draining ring/bar. */
+    fraction: number;
+    /** Free-string `kind` of the most recent hit, or `""` — carried through, never interpreted. */
+    kind: string;
+}
+/** Serializable state for save/restore — clock-agnostic (stores time left, not an absolute deadline). */
+export interface ComboMeterSnapshot {
+    /** Combo count. */
+    count: number;
+    /** Peak count reached. */
+    peak: number;
+    /** Milliseconds remaining in the decay window at snapshot time. */
+    remainingMs: number;
+    /** Active tier id at snapshot time (recomputed on restore; kept for readability). */
+    tier: string | null;
+}
+/**
+ * A live, observable combo/multiplier meter — an integer hit chain with a decay
+ * window, free-string tier thresholds, a derived multiplier, and peak tracking.
+ */
+export interface ComboMeter {
+    /**
+     * Register a landed hit: bump the count by one and reset the decay window. `kind`
+     * is a free string carried through to {@link ComboMeter.view} for the renderer to
+     * color/skin; the model never interprets it. Returns the new count.
+     */
+    hit(kind?: string): number;
+    /**
+     * Advance the decay window by `dtSeconds`, dropping the combo when the window
+     * elapses. Calling this once switches the meter to delta-driven time (the injected
+     * `now` clock is then ignored) — drive it each frame, or omit it and let reads read
+     * `now`. Notifies subscribers when the count changes.
+     */
+    update(dtSeconds: number): void;
+    /** Current combo count (processes any pending window expiry against the clock first). */
+    count(): number;
+    /** Highest count reached since the last {@link ComboMeter.reset}. */
+    peak(): number;
+    /** Active tier id, or `null` below the first tier. */
+    tier(): string | null;
+    /** Derived multiplier for the active tier (default 1). */
+    multiplier(): number;
+    /** Milliseconds left in the decay window before the next drop (0 when idle). */
+    remainingMs(): number;
+    /** Window remaining as `0..1`, for a draining ring/bar. */
+    fraction(): number;
+    /** The pooled view to draw this frame (do not retain). */
+    view(): ComboMeterView;
+    /** Clear the chain, peak, and window to empty. Notifies subscribers. */
+    reset(): void;
+    /** Patch config (window, tiers, drop step, multiplier curve) in place. Notifies subscribers. */
+    configure(patch: Partial<ComboMeterConfig>): void;
+    /** Observe changes (hit, drop, reset, configure, restore). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save. */
+    snapshot(): ComboMeterSnapshot;
+    /** Restore from a {@link ComboMeterSnapshot}, re-anchoring the window to the current clock. */
+    restore(snapshot: ComboMeterSnapshot): void;
+}
+/**
+ * A count-based combo / multiplier meter: an integer hit chain that climbs with
+ * every `hit()` and drops when a decay window elapses, crossing free-string tier
+ * thresholds ("good" → "great" → "savage") that derive a score multiplier, while
+ * tracking the peak reached. Time is injected (`now`, default `Date.now`) and/or
+ * driven by `update(dt)`; `view()` returns a pooled draw-state and
+ * `snapshot`/`restore` round-trips the chain through a save.
+ *
+ * Distinct from the existing meters — reused none of them because none is this
+ * shape: `stats/eventMeter` is a value/heat gauge that rises by tagged gains and
+ * decays continuously (not an integer chain count with a reset-on-hit window);
+ * `combat/comboPoints` is a finisher-point pool that hard-expires with no tiers,
+ * multiplier, or subscribe; `stats/accumulatorMeter` is a float gauge crossing
+ * `at`-value tiers, not a count with a draining window and derived multiplier.
+ *
+ * @capability combo-meter count-based combo/multiplier meter with a decay window, free-string tier thresholds, derived multiplier, peak tracking and snapshot/restore
+ */
+export declare function createComboMeter(config: ComboMeterConfig): ComboMeter;