@jgengine/core 0.19.0 → 0.22.0

package/dist/vfx/particles.d.ts

@@ -1,3 +1,4 @@
+import { type ForceFieldConfig } from "../physics/forceVolume.js";
 /** A 3D vector `[x, y, z]`. */
 export type Vec3 = readonly [number, number, number];
 /** A `[min, max]` range a spawned particle draws uniformly from. */
@@ -10,6 +11,41 @@ export interface Curve {
     start: number;
     end: number;
 }
+/** Serializable spawn volume in emitter coordinates; cone widens from its base along +Y. */
+export interface ParticleSpawnShape {
+    kind: "disc" | "sphere" | "cone";
+    radius: number;
+    height?: number;
+    /** Spawn on the outer surface instead of filling the volume. */
+    surface?: boolean;
+}
+/** Bounded particle contact policy; a query adapter can replace the fallback horizontal plane. */
+export interface ParticleCollisionConfig {
+    planeY?: number;
+    response?: "kill" | "bounce";
+    restitution?: number;
+    maxQueries?: number;
+    maxEvents?: number;
+}
+/** One contact from an injected scene query, in simulation coordinates. */
+export interface ParticleCollisionHit {
+    position: Vec3;
+    normal: Vec3;
+}
+/** Presentation events never authorize gameplay damage or physical impulses. */
+export interface ParticleEvent {
+    type: "collision" | "death";
+    particleId: number;
+    position: Vec3;
+    velocity: Vec3;
+    normal?: Vec3;
+}
+/** Optional geometry adapter; queries are capped independently of rendering. */
+export interface ParticleSystemOptions {
+    collision?: (from: Vec3, to: Vec3) => ParticleCollisionHit | null;
+    /** External cosmetic acceleration; return `out` to reuse its allocation. */
+    acceleration?: (position: Vec3, velocity: Vec3, out: [number, number, number]) => Vec3;
+}
 /**
  * A particle emitter: how particles spawn and how each one evolves over its life.
  * Every field is data — no functions — so an emitter is fully serializable and an
@@ -24,6 +60,7 @@ export interface EmitterConfig {
     position?: Vec3;
     /** Half-extents of a box the spawn point is jittered within. Default `[0, 0, 0]`. */
     spawnJitter?: Vec3;
+    spawnShape?: ParticleSpawnShape;
     /** Particle lifetime in seconds. Default `{ min: 1, max: 1 }`. */
     lifetime?: Range;
     /** Initial speed along the emit direction, in units/second. Default `{ min: 1, max: 1 }`. */
@@ -44,8 +81,13 @@ export interface EmitterConfig {
     colorEnd?: number;
     /** Opacity over life, each `0..1`. Default `{ start: 1, end: 0 }` (fade out). */
     alpha?: Curve;
-    /** Injected clock — unused by the sim (it is dt-driven) but reserved; determinism comes from `seed`. */
+    /** Seed for deterministic births; retuning it resets future randomness. */
     seed?: string | number;
+    /** Shared physical field descriptors, sampled as cosmetic acceleration; at most eight per particle. */
+    forces?: readonly ForceFieldConfig[];
+    collision?: ParticleCollisionConfig;
+    /** Enable bounded death events. Collision events use `collision.maxEvents`. */
+    deathEvents?: boolean;
 }
 /**
  * Read-only packed buffers of the live particles, laid out for a renderer to
@@ -62,6 +104,11 @@ export interface ParticleBuffers {
     colors: Float32Array;
     /** `count` floats: opacity `0..1` per particle. */
     alphas: Float32Array;
+    /** Stable birth ids, retained through pool compaction. */
+    ids: Float64Array;
+    /** Packed velocity and prior integration positions for streak/ribbon outputs. */
+    velocities: Float32Array;
+    previousPositions: Float32Array;
 }
 /** Serializable simulation state for save/restore and deterministic replay. */
 export interface ParticleSnapshot {
@@ -69,6 +116,11 @@ export interface ParticleSnapshot {
     accumulator: number;
     count: number;
     data: number[];
+    running?: boolean;
+    nextId?: number;
+    ids?: number[];
+    previousPositions?: number[];
+    config?: EmitterConfig;
 }
 /** A live, dt-driven particle simulation. */
 export interface ParticleSystem {
@@ -76,14 +128,20 @@ export interface ParticleSystem {
     update(dt: number): void;
     /** Spawn `n` particles immediately (a one-shot puff/explosion), independent of `rate`. */
     emit(n: number): void;
+    /** Resume continuous emission without replacing the live pool. */
+    start(): void;
+    /** Stop spawning while existing particles continue aging. */
+    stop(): void;
+    /** Consume bounded presentation collision/death events exactly once. */
+    drainEvents(): ParticleEvent[];
     /** Live particle count. */
     count(): number;
     /** The packed buffers for rendering (valid until the next `update`/`emit`). */
     buffers(): ParticleBuffers;
     /** Kill all particles and reset the emission accumulator (keeps the seed stream). */
     clear(): void;
-    /** Patch the emitter config in place (e.g. move the origin, change the rate). */
-    configure(patch: Partial<EmitterConfig>): void;
+    /** Patch tuning in place; `replace` resets omitted fields to defaults while retaining live particles. */
+    configure(patch: Partial<EmitterConfig>, replace?: boolean): void;
     subscribe(listener: () => void): () => void;
     snapshot(): ParticleSnapshot;
     restore(snapshot: ParticleSnapshot): void;
@@ -98,6 +156,11 @@ export interface ParticleSystem {
  * embers, magic, or confetti. Travel/gameplay stays elsewhere; this owns only
  * the spawn-integrate-fade lifecycle.
  *
- * @capability particle-system deterministic pooled particle emitter with SoA render buffers, burst/continuous emission, gravity/drag, size/color/alpha-over-life, and serializable state
+ * @capability particle-system deterministic pooled particle emitter with spawn volumes, force fields, bounded collision/death events, live tuning, SoA render buffers, and serializable state
+ */
+export declare function createParticleSystem(config?: EmitterConfig, options?: ParticleSystemOptions): ParticleSystem;
+/**
+ * Validate the serializable spawn/update descriptor before authoring or loading it.
+ * @capability particle-emitter-validation validate finite spawn volumes, force fields, lifetimes, appearance curves, and bounded particle collision policies
  */
-export declare function createParticleSystem(config?: EmitterConfig): ParticleSystem;
+export declare function validateEmitterConfig(value: unknown): string[];

package/dist/vfx/particles.js

@@ -1,25 +1,15 @@
+import { sampleForceField, validateForceField } from "../physics/forceVolume.js";
 import { hashString, randomSeedFrom, stepRandomSeed } from "../random/rng.js";
 function clamp01(v) {
     return v < 0 ? 0 : v > 1 ? 1 : v;
 }
-/**
- * A generic, allocation-aware particle system: one emitter, a fixed pool, and
- * Structure-of-Arrays buffers a renderer uploads straight to the GPU. It is
- * dt-driven (call `update(dt)` each frame) and deterministic — all randomness
- * flows from an injected `seed`, so the same seed and dt sequence reproduce the
- * same frames, and `snapshot`/`restore` round-trips the live pool. Nothing here
- * is combat- or genre-specific: configure it for smoke, sparks, rain, dust,
- * embers, magic, or confetti. Travel/gameplay stays elsewhere; this owns only
- * the spawn-integrate-fade lifecycle.
- *
- * @capability particle-system deterministic pooled particle emitter with SoA render buffers, burst/continuous emission, gravity/drag, size/color/alpha-over-life, and serializable state
- */
-export function createParticleSystem(config = {}) {
-    const cfg = {
+function emitterDefaults(config) {
+    return {
         max: config.max ?? 512,
         rate: config.rate ?? 0,
         position: config.position ?? [0, 0, 0],
         spawnJitter: config.spawnJitter ?? [0, 0, 0],
+        spawnShape: config.spawnShape,
         lifetime: config.lifetime ?? { min: 1, max: 1 },
         speed: config.speed ?? { min: 1, max: 1 },
         direction: config.direction ?? [0, 1, 0],
@@ -30,8 +20,26 @@ export function createParticleSystem(config = {}) {
         colorStart: config.colorStart ?? 0xffffff,
         colorEnd: config.colorEnd ?? config.colorStart ?? 0xffffff,
         alpha: config.alpha ?? { start: 1, end: 0 },
+        forces: config.forces,
+        collision: config.collision,
+        deathEvents: config.deathEvents ?? false,
     };
-    const max = Math.max(1, Math.floor(cfg.max));
+}
+/**
+ * A generic, allocation-aware particle system: one emitter, a fixed pool, and
+ * Structure-of-Arrays buffers a renderer uploads straight to the GPU. It is
+ * dt-driven (call `update(dt)` each frame) and deterministic — all randomness
+ * flows from an injected `seed`, so the same seed and dt sequence reproduce the
+ * same frames, and `snapshot`/`restore` round-trips the live pool. Nothing here
+ * is combat- or genre-specific: configure it for smoke, sparks, rain, dust,
+ * embers, magic, or confetti. Travel/gameplay stays elsewhere; this owns only
+ * the spawn-integrate-fade lifecycle.
+ *
+ * @capability particle-system deterministic pooled particle emitter with spawn volumes, force fields, bounded collision/death events, live tuning, SoA render buffers, and serializable state
+ */
+export function createParticleSystem(config = {}, options = {}) {
+    const cfg = emitterDefaults(config);
+    const max = Number.isFinite(cfg.max) ? Math.max(1, Math.min(65536, Math.floor(cfg.max))) : 512;
     // SoA live pool.
     const px = new Float32Array(max);
     const py = new Float32Array(max);
@@ -41,6 +49,8 @@ export function createParticleSystem(config = {}) {
     const vz = new Float32Array(max);
     const age = new Float32Array(max);
     const life = new Float32Array(max);
+    const ids = new Float64Array(max);
+    const previous = new Float32Array(max * 3);
     // Per-particle baked endpoints (so mid-flight config changes don't recolor existing particles).
     const sizeS = new Float32Array(max);
     const sizeE = new Float32Array(max);
@@ -57,8 +67,19 @@ export function createParticleSystem(config = {}) {
     const outSize = new Float32Array(max);
     const outColor = new Float32Array(max * 3);
     const outAlpha = new Float32Array(max);
+    const outVelocity = new Float32Array(max * 3);
+    const renderBuffers = { count: 0, positions: outPos, sizes: outSize, colors: outColor,
+        alphas: outAlpha, ids, velocities: outVelocity, previousPositions: previous };
     let live = 0;
     let accumulator = 0;
+    let running = true;
+    let nextId = 1;
+    let events = [];
+    let configuredSeed = config.seed;
+    const queryFrom = [0, 0, 0];
+    const queryTo = [0, 0, 0];
+    const sampledForce = [0, 0, 0];
+    const queryVelocity = [0, 0, 0];
     let seed = randomSeedFrom(typeof config.seed === "number" ? config.seed : hashString(String(config.seed ?? "particles")));
     const listeners = new Set();
     function notify() {
@@ -80,11 +101,35 @@ export function createParticleSystem(config = {}) {
         if (live >= max)
             return;
         const i = live++;
+        ids[i] = nextId++;
         const [cr0, cg0, cb0] = unpackColor(cfg.colorStart);
         const [cr1, cg1, cb1] = unpackColor(cfg.colorEnd);
         px[i] = cfg.position[0] + (rand() * 2 - 1) * cfg.spawnJitter[0];
         py[i] = cfg.position[1] + (rand() * 2 - 1) * cfg.spawnJitter[1];
         pz[i] = cfg.position[2] + (rand() * 2 - 1) * cfg.spawnJitter[2];
+        const shape = cfg.spawnShape;
+        if (shape !== undefined) {
+            const theta = rand() * Math.PI * 2;
+            if (shape.kind === "sphere") {
+                const y = rand() * 2 - 1;
+                const radius = shape.radius * (shape.surface ? 1 : Math.cbrt(rand()));
+                const horizontal = Math.sqrt(Math.max(0, 1 - y * y)) * radius;
+                px[i] += Math.cos(theta) * horizontal;
+                py[i] += y * radius;
+                pz[i] += Math.sin(theta) * horizontal;
+            }
+            else {
+                const heightFraction = shape.kind === "cone" ? (shape.surface ? Math.sqrt(rand()) : Math.cbrt(rand())) : 1;
+                const radius = shape.radius * heightFraction * (shape.surface ? 1 : Math.sqrt(rand()));
+                px[i] += Math.cos(theta) * radius;
+                pz[i] += Math.sin(theta) * radius;
+                if (shape.kind === "cone")
+                    py[i] += (shape.height ?? shape.radius) * heightFraction;
+            }
+        }
+        previous[i * 3] = px[i];
+        previous[i * 3 + 1] = py[i];
+        previous[i * 3 + 2] = pz[i];
         // Direction: base dir perturbed within a cone of half-angle `spread`.
         let dx = cfg.direction[0];
         let dy = cfg.direction[1];
@@ -138,6 +183,10 @@ export function createParticleSystem(config = {}) {
             vz[i] = vz[last];
             age[i] = age[last];
             life[i] = life[last];
+            ids[i] = ids[last];
+            previous[i * 3] = previous[last * 3];
+            previous[i * 3 + 1] = previous[last * 3 + 1];
+            previous[i * 3 + 2] = previous[last * 3 + 2];
             sizeS[i] = sizeS[last];
             sizeE[i] = sizeE[last];
             r0[i] = r0[last];
@@ -151,47 +200,128 @@ export function createParticleSystem(config = {}) {
         }
         live--;
     }
+    function bounded(value, fallback, cap) {
+        return Number.isFinite(value) ? Math.max(0, Math.min(cap, Math.floor(value))) : fallback;
+    }
+    function recordEvent(type, i, normal) {
+        events.push({ type, particleId: ids[i], position: [px[i], py[i], pz[i]], velocity: [vx[i], vy[i], vz[i]],
+            ...(normal === undefined ? {} : { normal: [normal[0], normal[1], normal[2]] }) });
+    }
     const system = {
         update(dt) {
-            if (dt <= 0)
+            if (!Number.isFinite(dt) || dt <= 0)
                 return;
             const damp = cfg.drag > 0 ? Math.max(0, 1 - cfg.drag * dt) : 1;
-            // Integrate + reap (iterate backwards because we swap-remove).
+            const contact = cfg.collision;
+            const queryLimit = Math.min(max, bounded(contact?.maxQueries, 64, 4096));
+            const eventLimit = bounded(contact?.maxEvents, 64, 1024);
+            let queries = 0;
             for (let i = live - 1; i >= 0; i--) {
                 age[i] += dt;
                 if (age[i] >= life[i]) {
+                    if (cfg.deathEvents && events.length < eventLimit)
+                        recordEvent("death", i);
                     swapRemove(i);
                     continue;
                 }
-                vx[i] = (vx[i] + cfg.gravity[0] * dt) * damp;
-                vy[i] = (vy[i] + cfg.gravity[1] * dt) * damp;
-                vz[i] = (vz[i] + cfg.gravity[2] * dt) * damp;
+                previous[i * 3] = px[i];
+                previous[i * 3 + 1] = py[i];
+                previous[i * 3 + 2] = pz[i];
+                let ax = cfg.gravity[0], ay = cfg.gravity[1], az = cfg.gravity[2];
+                queryFrom[0] = px[i];
+                queryFrom[1] = py[i];
+                queryFrom[2] = pz[i];
+                for (let f = 0; f < Math.min(8, cfg.forces?.length ?? 0); f++) {
+                    const force = sampleForceField(cfg.forces[f], queryFrom, 0xffffffff, sampledForce);
+                    ax += force[0];
+                    ay += force[1];
+                    az += force[2];
+                }
+                if (options.acceleration !== undefined) {
+                    queryVelocity[0] = vx[i];
+                    queryVelocity[1] = vy[i];
+                    queryVelocity[2] = vz[i];
+                    const force = options.acceleration(queryFrom, queryVelocity, sampledForce);
+                    ax += force[0];
+                    ay += force[1];
+                    az += force[2];
+                }
+                vx[i] = (vx[i] + ax * dt) * damp;
+                vy[i] = (vy[i] + ay * dt) * damp;
+                vz[i] = (vz[i] + az * dt) * damp;
                 px[i] += vx[i] * dt;
                 py[i] += vy[i] * dt;
                 pz[i] += vz[i] * dt;
+                if (contact === undefined)
+                    continue;
+                queryTo[0] = px[i];
+                queryTo[1] = py[i];
+                queryTo[2] = pz[i];
+                let hit = null;
+                if (options.collision !== undefined && queries < queryLimit) {
+                    queries++;
+                    hit = options.collision(queryFrom, queryTo);
+                }
+                if (hit === null && contact.planeY !== undefined && queryFrom[1] >= contact.planeY && py[i] <= contact.planeY && vy[i] < 0) {
+                    const t = (queryFrom[1] - contact.planeY) / (queryFrom[1] - py[i]);
+                    hit = { position: [queryFrom[0] + (px[i] - queryFrom[0]) * t, contact.planeY, queryFrom[2] + (pz[i] - queryFrom[2]) * t], normal: [0, 1, 0] };
+                }
+                if (hit === null)
+                    continue;
+                px[i] = hit.position[0];
+                py[i] = hit.position[1];
+                pz[i] = hit.position[2];
+                if (events.length < eventLimit)
+                    recordEvent("collision", i, hit.normal);
+                if (contact.response !== "bounce") {
+                    swapRemove(i);
+                    continue;
+                }
+                const length = Math.hypot(...hit.normal);
+                if (length === 0)
+                    continue;
+                const nx = hit.normal[0] / length, ny = hit.normal[1] / length, nz = hit.normal[2] / length;
+                const dot = vx[i] * nx + vy[i] * ny + vz[i] * nz;
+                if (dot < 0) {
+                    const impulse = (1 + clamp01(contact.restitution ?? 0.5)) * dot;
+                    vx[i] -= impulse * nx;
+                    vy[i] -= impulse * ny;
+                    vz[i] -= impulse * nz;
+                }
             }
-            // Continuous emission.
-            if (cfg.rate > 0) {
-                accumulator += cfg.rate * dt;
-                while (accumulator >= 1) {
-                    accumulator -= 1;
+            if (running && Number.isFinite(cfg.rate) && cfg.rate > 0) {
+                accumulator = Math.min(Number.MAX_SAFE_INTEGER, accumulator + cfg.rate * dt);
+                const wanted = Math.floor(accumulator);
+                accumulator -= wanted;
+                for (let k = 0, n = Math.min(wanted, max - live); k < n; k++)
                     spawnOne();
-                }
             }
             notify();
         },
         emit(n) {
-            const wanted = Math.max(0, Math.floor(n));
+            const wanted = Number.isFinite(n) ? Math.min(max - live, Math.max(0, Math.floor(n))) : 0;
             for (let k = 0; k < wanted; k++)
                 spawnOne();
             notify();
         },
+        start() { if (!running) {
+            running = true;
+            notify();
+        } },
+        stop() { if (running) {
+            running = false;
+            notify();
+        } },
+        drainEvents() { const drained = events; events = []; return drained; },
         count() {
             return live;
         },
         buffers() {
             for (let i = 0; i < live; i++) {
                 const t = clamp01(age[i] / life[i]);
+                outVelocity[i * 3] = vx[i];
+                outVelocity[i * 3 + 1] = vy[i];
+                outVelocity[i * 3 + 2] = vz[i];
                 outPos[i * 3] = px[i];
                 outPos[i * 3 + 1] = py[i];
                 outPos[i * 3 + 2] = pz[i];
@@ -201,15 +331,21 @@ export function createParticleSystem(config = {}) {
                 outColor[i * 3 + 2] = b0[i] + (b1[i] - b0[i]) * t;
                 outAlpha[i] = a0[i] + (a1[i] - a0[i]) * t;
             }
-            return { count: live, positions: outPos, sizes: outSize, colors: outColor, alphas: outAlpha };
+            renderBuffers.count = live;
+            return renderBuffers;
         },
         clear() {
             live = 0;
             accumulator = 0;
+            events = [];
             notify();
         },
-        configure(patch) {
-            Object.assign(cfg, patch);
+        configure(patch, replace = false) {
+            Object.assign(cfg, replace ? emitterDefaults(patch) : patch);
+            if (patch.seed !== undefined && patch.seed !== configuredSeed) {
+                configuredSeed = patch.seed;
+                seed = randomSeedFrom(typeof patch.seed === "number" ? patch.seed : hashString(patch.seed));
+            }
             notify();
         },
         subscribe(listener) {
@@ -221,12 +357,20 @@ export function createParticleSystem(config = {}) {
             for (let i = 0; i < live; i++) {
                 data.push(px[i], py[i], pz[i], vx[i], vy[i], vz[i], age[i], life[i], sizeS[i], sizeE[i], r0[i], g0[i], b0[i], r1[i], g1[i], b1[i], a0[i], a1[i]);
             }
-            return { seed: seed, accumulator, count: live, data };
+            return { seed: seed, accumulator, count: live, data, running, nextId,
+                ids: Array.from(ids.subarray(0, live)), previousPositions: Array.from(previous.subarray(0, live * 3)), config: structuredClone({ ...cfg, seed: configuredSeed }) };
         },
         restore(snapshot) {
+            if (snapshot.config !== undefined) {
+                Object.assign(cfg, structuredClone(snapshot.config));
+                configuredSeed = snapshot.config.seed;
+            }
             seed = randomSeedFrom(snapshot.seed);
             accumulator = snapshot.accumulator;
-            live = Math.min(max, snapshot.count);
+            live = Math.min(max, Math.max(0, Math.floor(snapshot.count)), Math.floor(snapshot.data.length / 18));
+            running = snapshot.running ?? true;
+            nextId = snapshot.nextId ?? live + 1;
+            events = [];
             const stride = 18;
             for (let i = 0; i < live; i++) {
                 const o = i * stride;
@@ -248,9 +392,117 @@ export function createParticleSystem(config = {}) {
                 b1[i] = snapshot.data[o + 15];
                 a0[i] = snapshot.data[o + 16];
                 a1[i] = snapshot.data[o + 17];
+                ids[i] = snapshot.ids?.[i] ?? i + 1;
+                previous[i * 3] = snapshot.previousPositions?.[i * 3] ?? px[i];
+                previous[i * 3 + 1] = snapshot.previousPositions?.[i * 3 + 1] ?? py[i];
+                previous[i * 3 + 2] = snapshot.previousPositions?.[i * 3 + 2] ?? pz[i];
             }
             notify();
         },
     };
     return system;
 }
+/**
+ * Validate the serializable spawn/update descriptor before authoring or loading it.
+ * @capability particle-emitter-validation validate finite spawn volumes, force fields, lifetimes, appearance curves, and bounded particle collision policies
+ */
+export function validateEmitterConfig(value) {
+    const errors = [];
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return ["emitter must be an object"];
+    const config = value;
+    const finite = (v) => typeof v === "number" && Number.isFinite(v);
+    const number = (name, min, max = Infinity, integer = false) => {
+        const v = config[name];
+        if (v !== undefined && (!finite(v) || v < min || v > max || (integer && !Number.isInteger(v))))
+            errors.push(`${name} must be ${integer ? "an integer" : "finite"} in [${min}, ${max}]`);
+    };
+    const vector = (name, nonnegative = false) => {
+        const v = config[name];
+        if (v !== undefined && (!Array.isArray(v) || v.length !== 3 || v.some((n) => !finite(n) || (nonnegative && n < 0))))
+            errors.push(`${name} must contain three finite${nonnegative ? " nonnegative" : ""} numbers`);
+    };
+    number("max", 1, 65536, true);
+    number("rate", 0);
+    number("spread", 0, Math.PI);
+    number("drag", 0, 1);
+    number("colorStart", 0, 0xffffff, true);
+    number("colorEnd", 0, 0xffffff, true);
+    vector("position");
+    vector("direction");
+    vector("gravity");
+    vector("spawnJitter", true);
+    for (const [name, lower] of [["lifetime", Number.MIN_VALUE], ["speed", 0]]) {
+        const v = config[name];
+        if (v === undefined)
+            continue;
+        if (v === null || typeof v !== "object") {
+            errors.push(`${name} must be a min/max range`);
+            continue;
+        }
+        const range = v;
+        if (!finite(range.min) || !finite(range.max) || range.min < lower || range.max < range.min)
+            errors.push(`${name} must have finite ordered min/max values ${name === "lifetime" ? "above zero" : "at least zero"}`);
+    }
+    for (const name of ["size", "alpha"]) {
+        const v = config[name];
+        if (v === undefined)
+            continue;
+        if (v === null || typeof v !== "object") {
+            errors.push(`${name} must be a start/end curve`);
+            continue;
+        }
+        const curve = v;
+        if (!finite(curve.start) || !finite(curve.end) || curve.start < 0 || curve.end < 0 || (name === "alpha" && (curve.start > 1 || curve.end > 1)))
+            errors.push(`${name} must have finite nonnegative start/end values${name === "alpha" ? " at most one" : ""}`);
+    }
+    if (config.spawnShape !== undefined) {
+        const shape = config.spawnShape;
+        if (shape === null || typeof shape !== "object" || Array.isArray(shape))
+            errors.push("spawnShape must be a volume descriptor");
+        else {
+            if (shape.kind !== "disc" && shape.kind !== "sphere" && shape.kind !== "cone")
+                errors.push("spawnShape.kind must be disc, sphere, or cone");
+            if (!finite(shape.radius) || shape.radius <= 0)
+                errors.push("spawnShape.radius must be finite and positive");
+            if (shape.height !== undefined && (!finite(shape.height) || shape.height <= 0))
+                errors.push("spawnShape.height must be finite and positive");
+            if (shape.surface !== undefined && typeof shape.surface !== "boolean")
+                errors.push("spawnShape.surface must be boolean");
+        }
+    }
+    if (config.seed !== undefined && typeof config.seed !== "string" && !finite(config.seed))
+        errors.push("seed must be a string or finite number");
+    if (config.deathEvents !== undefined && typeof config.deathEvents !== "boolean")
+        errors.push("deathEvents must be boolean");
+    if (config.forces !== undefined) {
+        if (!Array.isArray(config.forces) || config.forces.length > 8)
+            errors.push("forces must be an array of at most eight fields");
+        else
+            config.forces.forEach((value, i) => {
+                try {
+                    validateForceField(value);
+                }
+                catch (error) {
+                    errors.push(`forces[${i}]: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            });
+    }
+    if (config.collision !== undefined) {
+        const contact = config.collision;
+        if (contact === null || typeof contact !== "object" || Array.isArray(contact))
+            errors.push("collision must be a contact policy");
+        else {
+            if (contact.planeY !== undefined && !finite(contact.planeY))
+                errors.push("collision.planeY must be finite");
+            if (contact.response !== undefined && contact.response !== "kill" && contact.response !== "bounce")
+                errors.push("collision.response must be kill or bounce");
+            if (contact.restitution !== undefined && (!finite(contact.restitution) || contact.restitution < 0 || contact.restitution > 1))
+                errors.push("collision.restitution must be in [0, 1]");
+            for (const [name, cap] of [["maxQueries", 4096], ["maxEvents", 1024]])
+                if (contact[name] !== undefined && (!finite(contact[name]) || !Number.isInteger(contact[name]) || contact[name] < 0 || contact[name] > cap))
+                    errors.push(`collision.${name} must be an integer in [0, ${cap}]`);
+        }
+    }
+    return errors;
+}

package/dist/visibility/assetStreaming.d.ts

@@ -11,7 +11,7 @@ export interface CancelSignal {
     readonly cancelled: boolean;
 }
 export interface AssetStreamingOptions {
-    /** Async loader. Must honor `signal.cancelled` and avoid committing work when it flips true. */
+    /** Async loader. Honor `signal.cancelled` and always settle; cancelled successful loads are released through `unload`. */
     readonly load: (assetId: string, signal: CancelSignal) => Promise<AssetLoadResult>;
     /** Release GPU/CPU resources for an asset. */
     readonly unload?: (assetId: string) => void;
@@ -28,6 +28,7 @@ export interface AssetRecord {
     lastActiveMs: number;
     value: unknown;
 }
+/** Current demand/residency gauges and cumulative unload/cancellation counters; clear resets totals. */
 export interface StreamingStats {
     queued: number;
     loading: number;
@@ -36,7 +37,18 @@ export interface StreamingStats {
     errored: number;
     inFlight: number;
     cancelled: number;
+    /** Known resident bytes; missing or invalid loader sizes count as zero. */
     bytes: number;
+    /** Current tracked records, including inactive history until forget or clear. */
+    records: number;
+    /** Known bytes protected by pins or active references. */
+    protectedBytes: number;
+    /** Loaded assets whose resident size is unknown. */
+    unknownSizeLoaded: number;
+    /** Known resident bytes above the configured target, including protected bytes. */
+    overBudgetBytes: number;
+    /** Cumulative resources evicted by resident-byte pressure since clear. */
+    budgetEvicted: number;
 }
 export interface AssetStreamingSystem {
     /** Demand an asset (near/in view). Deduplicated — an already loaded/loading/queued asset is never re-fetched concurrently. */
@@ -49,18 +61,24 @@ export interface AssetStreamingSystem {
     unpin(assetId: string): void;
     /** Refresh the "last needed" timestamp used by the grace-period unload. */
     markActive(assetId: string): void;
-    /** Advance one frame: start up to the load budget, evict past-grace assets up to the unload budget. */
+    /** Advance one frame: bounded load starts and unloads; resident-byte pressure precedes idle unloading. */
     tick(dt: number): void;
-    /** Cancel an in-flight or queued request that is no longer needed. */
+    /** Cancel demand. Unresolved loads still occupy concurrency slots and block same-id retries until settlement. */
     cancel(assetId: string): void;
+    /** Merge policy. Zero concurrency pauses starts; resident-byte target/order changes apply on the next tick. */
+    retune(settings: Partial<StreamingSettings>): void;
     stateOf(assetId: string): AssetLoadState | undefined;
     isLoaded(assetId: string): boolean;
     record(assetId: string): AssetRecord | undefined;
+    /** Drop inactive unloaded/error history. Returns false for missing, pinned, retained, queued, loaded or unresolved assets. Old record handles remain detached; future demand creates a new record. */
+    forget(assetId: string): boolean;
     stats(): StreamingStats;
     /** Merge asset counters into a per-frame VisibilityStats. */
     applyTo(stats: VisibilityStats): void;
     /** Resolve once every in-flight load settles — for deterministic tests. */
     settle(): Promise<void>;
+    /** Release loaded resources and cancel demand; outstanding loads remain tracked until settlement. */
     clear(): void;
 }
+/** Stream shared resources with bounded load concurrency, per-tick resident-byte eviction, and explicit inactive-history cleanup. */
 export declare function createAssetStreamingSystem(options: AssetStreamingOptions): AssetStreamingSystem;