@jgengine/core 0.18.1 → 0.21.0

package/dist/vfx/particleDirector.js

@@ -1,60 +1,92 @@
+import { validateEmitterConfig } from "./particles.js";
 /**
  * Create the particle intent registry a `GameContext` exposes as `ctx.particles`.
  * State is data-only and serializable: standing emitters survive `snapshot`/`restore`,
  * queued bursts are transient. The renderer subscribes, drains bursts, and mirrors
  * the emitter list — the director never allocates particle pools itself.
  *
- * @capability particle-director game-reachable VFX seam: queue one-shot particle bursts and keyed follow-capable standing emitters as serializable data for the shell to render
+ * @capability particle-director named particle start/stop/burst/retune lifecycle, local/world following, render outputs, bounded cosmetic event exchange, and serializable emitter definitions
  */
-export function createParticleDirector() {
+export function createParticleDirector(options = {}) {
     let nextSeq = 1;
     let bursts = [];
     const emitters = new Map();
     const listeners = new Set();
+    let events = [];
+    const limit = (n, fallback, cap) => Number.isFinite(n) ? Math.max(0, Math.min(cap, Math.floor(n))) : fallback;
+    const maxEmitters = limit(options.maxEmitters, 128, 1024);
+    const maxBursts = limit(options.maxBursts, 32, 256);
+    const maxEvents = limit(options.maxEvents, 128, 4096);
+    function queue(config, count, blending, emitterId, attachOptions) {
+        const wanted = Number.isFinite(count) ? Math.min(65536, Math.floor(count)) : 0;
+        if (wanted <= 0 || bursts.length >= maxBursts)
+            return;
+        bursts.push({ seq: nextSeq++, config: structuredClone(config), count: wanted,
+            ...(blending === undefined ? {} : { blending }),
+            ...(emitterId === undefined ? {} : { emitterId }),
+            ...(attachOptions === undefined ? {} : { options: structuredClone(attachOptions) }) });
+        notify();
+    }
+    function setActive(id, active) {
+        const current = emitters.get(id);
+        if (current === undefined || (current.active ?? true) === active)
+            return;
+        emitters.set(id, { ...current, active });
+        notify();
+    }
     function notify() {
         for (const listener of listeners)
             listener();
     }
     return {
-        burst(config, count, blending) {
-            const wanted = Math.floor(count);
-            if (wanted <= 0)
-                return;
-            bursts.push({ seq: nextSeq++, config, count: wanted, ...(blending === undefined ? {} : { blending }) });
-            notify();
+        burst(config, count, blending, options) {
+            queue(config, count, blending, undefined, options);
         },
         attach(id, config, options) {
-            emitters.set(id, {
-                id,
-                config,
-                ...(options?.follow === undefined ? {} : { follow: options.follow }),
-                ...(options?.offset === undefined ? {} : { offset: options.offset }),
-                ...(options?.blending === undefined ? {} : { blending: options.blending }),
-            });
+            if (!emitters.has(id) && emitters.size >= maxEmitters)
+                throw new RangeError(`Particle emitter capacity ${maxEmitters} exceeded by ${id}`);
+            emitters.set(id, { id, config: structuredClone(config), ...structuredClone(options ?? {}) });
             notify();
         },
-        retune(id, patch) {
+        retune(id, patch, options) {
             const current = emitters.get(id);
             if (current === undefined)
                 return;
-            emitters.set(id, { ...current, config: { ...current.config, ...patch } });
+            emitters.set(id, { ...current, ...structuredClone(options ?? {}), config: { ...current.config, ...structuredClone(patch) } });
             notify();
         },
+        start(id) { setActive(id, true); },
+        stop(id) { setActive(id, false); },
+        burstNamed(id, count) {
+            const spec = emitters.get(id);
+            if (spec === undefined)
+                return;
+            const { id: _, config, ...options } = spec;
+            queue(config, count, spec.blending, id, options);
+        },
+        reportEvents(id, next) {
+            for (let i = 0, n = Math.min(next.length, maxEvents - events.length); i < n; i++) {
+                events.push({ ...structuredClone(next[i]), emitterId: id });
+            }
+        },
+        drainEvents() { const drained = events; events = []; return drained; },
         detach(id) {
             if (!emitters.delete(id))
                 return;
             notify();
         },
         clear() {
-            if (emitters.size === 0 && bursts.length === 0)
+            if (emitters.size === 0 && bursts.length === 0 && events.length === 0)
                 return;
             emitters.clear();
             bursts = [];
+            events = [];
             notify();
         },
         emitters() {
             return Array.from(emitters.values());
         },
+        limits() { return { maxEmitters, maxBursts, maxEvents }; },
         drainBursts() {
             if (bursts.length === 0)
                 return [];
@@ -67,15 +99,74 @@ export function createParticleDirector() {
             return () => listeners.delete(listener);
         },
         snapshot() {
-            return { nextSeq, emitters: Array.from(emitters.values()) };
+            return { nextSeq, emitters: structuredClone(Array.from(emitters.values())) };
         },
         restore(state) {
-            nextSeq = state.nextSeq;
+            nextSeq = Math.max(1, Number.isFinite(state.nextSeq) ? Math.floor(state.nextSeq) : 1);
             bursts = [];
             emitters.clear();
-            for (const spec of state.emitters)
-                emitters.set(spec.id, spec);
+            events = [];
+            for (const spec of state.emitters.slice(0, maxEmitters))
+                emitters.set(spec.id, structuredClone(spec));
             notify();
         },
     };
 }
+/**
+ * Validate serializable binding, output, and bounded collision-child descriptors.
+ * @capability particle-binding-validation validate named particle follow spaces, render outputs, environment influence, and bounded collision child effects
+ */
+export function validateParticleAttachOptions(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return ["particle options must be an object"];
+    const options = value;
+    const errors = [];
+    if (options.follow !== undefined && typeof options.follow !== "string")
+        errors.push("follow must be an entity id");
+    if (options.offset !== undefined && (!Array.isArray(options.offset) || options.offset.length !== 3 || options.offset.some((v) => typeof v !== "number" || !Number.isFinite(v))))
+        errors.push("offset must contain three finite numbers");
+    if (options.space !== undefined && options.space !== "world" && options.space !== "local")
+        errors.push("space must be world or local");
+    if (options.active !== undefined && typeof options.active !== "boolean")
+        errors.push("active must be boolean");
+    const output = (render, blending, prefix) => {
+        if (blending !== undefined && blending !== "normal" && blending !== "additive")
+            errors.push(`${prefix}blending must be normal or additive`);
+        if (render === undefined)
+            return;
+        if (render === null || typeof render !== "object" || Array.isArray(render)) {
+            errors.push(`${prefix}render must be an output descriptor`);
+            return;
+        }
+        const hint = render;
+        if (!["point", "streak", "flake", "flame", "smoke", "ribbon", "ripple"].includes(hint.shape))
+            errors.push(`${prefix}render.shape is unsupported`);
+        if (hint.stretch !== undefined && (typeof hint.stretch !== "number" || !Number.isFinite(hint.stretch) || hint.stretch < 0))
+            errors.push(`${prefix}render.stretch must be finite and nonnegative`);
+    };
+    output(options.render, options.blending, "");
+    if (options.environment !== undefined) {
+        const influence = options.environment;
+        if (influence === null || typeof influence !== "object" || Array.isArray(influence))
+            errors.push("environment must be an influence descriptor");
+        else {
+            for (const name of ["windResponse", "maxAcceleration"])
+                if (influence[name] !== undefined && (typeof influence[name] !== "number" || !Number.isFinite(influence[name]) || influence[name] < 0 || influence[name] > 1e12))
+                    errors.push(`environment.${name} must be finite in 0..1e12`);
+            if (influence.mask !== undefined && (typeof influence.mask !== "number" || !Number.isInteger(influence.mask) || influence.mask < 0 || influence.mask > 0xffffffff))
+                errors.push("environment.mask must be an unsigned 32-bit integer");
+        }
+    }
+    if (options.collisionEffect !== undefined) {
+        const child = options.collisionEffect;
+        if (child === null || typeof child !== "object" || Array.isArray(child))
+            errors.push("collisionEffect must be a child effect descriptor");
+        else {
+            errors.push(...validateEmitterConfig(child.config).map((error) => `collisionEffect.config.${error}`));
+            if (typeof child.count !== "number" || !Number.isInteger(child.count) || child.count < 1 || child.count > 65536)
+                errors.push("collisionEffect.count must be an integer in [1, 65536]");
+            output(child.render, child.blending, "collisionEffect.");
+        }
+    }
+    return errors;
+}

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[];