@jgengine/core 0.19.0 → 0.22.0

package/dist/scene/vehicleSeat.js

@@ -1,4 +1,6 @@
 import { createMountController, MountController } from "./mount.js";
+import { validateCameraRig, validateChaseCameraTuning } from "../runtime/cameraDirector.js";
+import { forgetPlayerMovement } from "../movement/playerMovement.js";
 /**
  * Composes `scene/mount`'s control-transfer bookkeeping with the seat/camera/movement-mode transition
  * every enter/exit-vehicle flow needs (#533.2): boarding resolves a free seat and reports the camera
@@ -27,14 +29,21 @@ export class VehicleSeats {
         };
     }
     exit(riderId, vehiclePose, offset = {}) {
-        const vehicleId = this.controller.dismount(riderId);
-        if (vehicleId === null)
+        const vehicleId = this.controller.seatOf(riderId)?.mountId;
+        if (vehicleId === undefined)
             return { ok: false, reason: "not_seated" };
         const distance = offset.distance ?? 2.2;
+        if (!Array.isArray(vehiclePose.position) || vehiclePose.position.length !== 3 || !vehiclePose.position.every(Number.isFinite) ||
+            !Number.isFinite(vehiclePose.rotationY) || !Number.isFinite(distance) ||
+            (offset.side !== undefined && offset.side !== "left" && offset.side !== "right"))
+            return { ok: false, reason: "invalid_pose" };
         const sign = offset.side === "left" ? -1 : 1;
         const side = vehiclePose.rotationY + (Math.PI / 2) * sign;
         const x = vehiclePose.position[0] + Math.sin(side) * distance;
         const z = vehiclePose.position[2] + Math.cos(side) * distance;
+        if (!Number.isFinite(x) || !Number.isFinite(z))
+            return { ok: false, reason: "invalid_pose" };
+        this.controller.dismount(riderId);
         return {
             ok: true,
             vehicleId,
@@ -49,6 +58,19 @@ export class VehicleSeats {
     driverOf(vehicleId) {
         return this.controller.driver(vehicleId);
     }
+    /** The seated rider's controlled mount; `null` for passengers and unseated riders. */
+    drivenBy(riderId) {
+        return this.isSeated(riderId) ? this.controller.driveTarget(riderId) : null;
+    }
+    snapshot() {
+        return this.controller.snapshot();
+    }
+    restore(next) {
+        this.controller.restore(next);
+    }
+    reset() {
+        this.controller.reset();
+    }
     get mounts() {
         return this.controller;
     }
@@ -61,3 +83,68 @@ export class VehicleSeats {
 export function createVehicleSeats(controller) {
     return new VehicleSeats(controller);
 }
+function forgetRiderMovement(ctx, riderId) {
+    const possession = ctx.player.possession;
+    if (possession.active(riderId) === riderId)
+        forgetPlayerMovement(ctx, riderId);
+    for (const [userId, entityId] of Object.entries(possession.snapshotAll().active)) {
+        if (entityId === riderId)
+            forgetPlayerMovement(ctx, userId);
+    }
+}
+/** Apply an existing seat transition to the explicitly named rider. Motor/input policy stays caller-owned.
+ * @capability board-vehicle board a rideable, freeze/hide its rider and apply caller camera policy
+ */
+export function boardVehicle(ctx, seats, riderId, vehicleId, options = {}) {
+    const rider = ctx.scene.entity.get(riderId);
+    if (rider === null)
+        return { ok: false, reason: "unknown_rider" };
+    if (ctx.scene.entity.get(vehicleId) === null)
+        return { ok: false, reason: "unknown_vehicle" };
+    if (options.camera !== false && options.rig !== undefined && options.rig !== null)
+        validateCameraRig(options.rig, options.config);
+    if (options.camera !== false && options.chase !== undefined)
+        validateChaseCameraTuning(options.chase);
+    const result = seats.enter(riderId, vehicleId, options);
+    if (!result.ok)
+        return result;
+    ctx.scene.entity.update(riderId, { hidden: true, movement: { ...rider.movement, ...result.riderMovementPatch } });
+    ctx.scene.entity.setVelocity(riderId, [0, 0, 0]);
+    forgetRiderMovement(ctx, riderId);
+    if (options.camera !== false) {
+        ctx.camera.follow(result.cameraTarget);
+        if (options.rig !== undefined)
+            ctx.camera.setRig(options.rig, options.config);
+        if (options.chase !== undefined)
+            ctx.camera.setChaseTuning(structuredClone(options.chase));
+    }
+    return result;
+}
+/** Apply dismount placement, restore rider movement/visibility and the configured camera rig.
+ * @capability leave-vehicle leave a rideable beside its current pose and restore on-foot camera/movement
+ */
+export function leaveVehicle(ctx, seats, riderId, options = {}) {
+    const rider = ctx.scene.entity.get(riderId);
+    if (rider === null)
+        return { ok: false, reason: "unknown_rider" };
+    const ref = seats.mounts.seatOf(riderId);
+    if (ref === null)
+        return { ok: false, reason: "not_seated" };
+    const vehicle = ctx.scene.entity.get(ref.mountId);
+    const pose = options.pose ?? (vehicle === null ? undefined : { position: vehicle.position, rotationY: vehicle.rotationY });
+    if (pose === undefined)
+        return { ok: false, reason: "unknown_vehicle" };
+    const result = seats.exit(riderId, pose, options);
+    if (!result.ok)
+        return result;
+    ctx.scene.entity.setPose(riderId, result.placement);
+    ctx.scene.entity.update(riderId, { hidden: false, movement: { ...rider.movement, ...result.riderMovementPatch } });
+    ctx.scene.entity.setVelocity(riderId, [0, 0, 0]);
+    forgetRiderMovement(ctx, riderId);
+    if (options.camera !== false) {
+        ctx.camera.follow(result.cameraTarget);
+        ctx.camera.setRig(null);
+        ctx.camera.setChaseTuning(null);
+    }
+    return result;
+}

package/dist/stats/accumulatorMeter.d.ts

@@ -17,7 +17,17 @@ export interface MeterAddResult {
     tier: string | null;
     tierChanged: boolean;
 }
+/** Mutable meter value, hold latch, and time since the last gain. */
+export interface AccumulatorMeterState {
+    value: number;
+    broken: boolean;
+    idleMs: number;
+}
 export interface AccumulatorMeter {
+    /** Detached state for persistence and deterministic continuation. */
+    state(): AccumulatorMeterState;
+    /** Restore using the caller's existing configuration. */
+    restore(next: AccumulatorMeterState): void;
     value(): number;
     fraction(): number;
     tier(): string | null;

package/dist/stats/accumulatorMeter.js

@@ -31,6 +31,12 @@ export function createAccumulatorMeter(config) {
         return Math.max(0, Math.min(config.max, next));
     }
     return {
+        state: () => ({ value, broken, idleMs }),
+        restore(next) {
+            value = clamp(next.value);
+            broken = next.broken;
+            idleMs = Math.max(0, next.idleMs);
+        },
         value() {
             return value;
         },

package/dist/stats/eventMeter.d.ts

@@ -1,4 +1,4 @@
-import { type MeterMode, type MeterTier } from "./accumulatorMeter.js";
+import { type AccumulatorMeterState, type MeterMode, type MeterTier } from "./accumulatorMeter.js";
 export interface EventMeterConfig {
     max: number;
     mode?: MeterMode;
@@ -20,7 +20,13 @@ export interface EventMeterFeedResult {
     tier: string | null;
     tierChanged: boolean;
 }
+/** Event meter persistence uses the underlying accumulator's complete state. */
+export type EventMeterState = AccumulatorMeterState;
 export interface EventMeter {
+    /** Detached value, hold latch, and decay-delay timer. */
+    state(): EventMeterState;
+    /** Restore using the caller's existing event and decay configuration. */
+    restore(next: EventMeterState): void;
     value(): number;
     fraction(): number;
     tier(): string | null;
@@ -29,7 +35,8 @@ export interface EventMeter {
     consume(): boolean;
     drain(amount: number): void;
     reset(): void;
-    tick(dtSeconds: number): void;
+    /** Advance decay and its delay; pass false to pause both while a source is visible. */
+    tick(dtSeconds: number, decayEnabled?: boolean): void;
 }
 /**
  * A heat/hype gauge that rises as tagged events land and cools between them, firing when it fills or breaks — the streak/overdrive meter shooters and fighters hand-roll.

package/dist/stats/eventMeter.js

@@ -18,6 +18,8 @@ export function createEventMeter(config) {
         tiers: config.tiers,
     });
     return {
+        state: meter.state,
+        restore: meter.restore,
         value() {
             return meter.value();
         },
@@ -74,8 +76,9 @@ export function createEventMeter(config) {
         reset() {
             meter.reset();
         },
-        tick(dtSeconds) {
-            meter.tick(dtSeconds);
+        tick(dtSeconds, decayEnabled = true) {
+            if (decayEnabled)
+                meter.tick(dtSeconds);
         },
     };
 }

package/dist/store/defineStore.d.ts

@@ -26,7 +26,9 @@ export interface StoreHandle<T> {
  * with the value type it means, and the `unknown → T` cast lives once, here, behind the boundary. Pass
  * a factory for `initial` when the fallback is a fresh mutable object; the factory runs at most once and
  * its result is reused, so an unwritten slot keeps a stable identity across reads (no per-read churn for
- * a React selector, no allocation on a hot path).
+ * a React selector, no allocation on a hot path). A value that carries functions (a closure-based run
+ * store, an input handle) is runtime-only: snapshots, saves and replication skip it and hydration keeps
+ * it in place. Hold such objects with `perContext` when they need no store notifications.
  *
  * @capability typed-store a cast-free typed handle onto one reactive game-store slot, replayable and host-authoritative
  */

package/dist/store/defineStore.js

@@ -3,7 +3,9 @@
  * with the value type it means, and the `unknown → T` cast lives once, here, behind the boundary. Pass
  * a factory for `initial` when the fallback is a fresh mutable object; the factory runs at most once and
  * its result is reused, so an unwritten slot keeps a stable identity across reads (no per-read churn for
- * a React selector, no allocation on a hot path).
+ * a React selector, no allocation on a hot path). A value that carries functions (a closure-based run
+ * store, an input handle) is runtime-only: snapshots, saves and replication skip it and hydration keeps
+ * it in place. Hold such objects with `perContext` when they need no store notifications.
  *
  * @capability typed-store a cast-free typed handle onto one reactive game-store slot, replayable and host-authoritative
  */

package/dist/store/observableKeyedStore.d.ts

@@ -18,4 +18,4 @@ export interface ObservableKeyedStore<T> {
     hydrate(data: readonly (readonly [string, T])[]): void;
 }
 /** @internal */
-export declare function createObservableKeyedStore<T>(areEqual?: (previous: T, next: T) => boolean): ObservableKeyedStore<T>;
+export declare function createObservableKeyedStore<T>(areEqual?: (previous: T, next: T) => boolean, beforeNotify?: (key: string | undefined, membershipChanged: boolean) => void): ObservableKeyedStore<T>;

package/dist/store/observableKeyedStore.js

@@ -1,5 +1,5 @@
 /** @internal */
-export function createObservableKeyedStore(areEqual) {
+export function createObservableKeyedStore(areEqual, beforeNotify) {
     const store = new Map();
     const listeners = new Set();
     const membershipListeners = new Set();
@@ -11,14 +11,16 @@ export function createObservableKeyedStore(areEqual) {
     let keysDirty = false;
     let mapCache = new Map();
     let mapDirty = false;
-    function emit() {
+    function emit(key, membershipChanged) {
         arrayDirty = true;
         mapDirty = true;
+        if (membershipChanged)
+            keysDirty = true;
+        beforeNotify?.(key, membershipChanged);
         for (const listener of listeners)
             listener();
     }
     function emitMembership() {
-        keysDirty = true;
         for (const listener of membershipListeners)
             listener();
     }
@@ -30,7 +32,7 @@ export function createObservableKeyedStore(areEqual) {
                 return;
             if (previous !== value)
                 store.set(key, value);
-            emit();
+            emit(key, !had);
             if (!had)
                 emitMembership();
         },
@@ -38,7 +40,7 @@ export function createObservableKeyedStore(areEqual) {
             if (!store.has(key))
                 return;
             store.delete(key);
-            emit();
+            emit(key, true);
             emitMembership();
         },
         get(key) {
@@ -83,7 +85,7 @@ export function createObservableKeyedStore(areEqual) {
             store.clear();
             for (const [key, value] of data)
                 store.set(key, value);
-            emit();
+            emit(undefined, true);
             emitMembership();
         },
     };

package/dist/time/simClock.d.ts

@@ -47,9 +47,11 @@ export interface ClockSnapshot {
     calendar: CalendarTime;
 }
 export interface SimClock {
-    /** Advance the world by a real-time delta; returns the scaled game-time delta (0 while paused) and fires any due timers. The shell calls this once per frame and passes the result to `loop.onTick`. */
+    /** Advance the clock directly when used alone. A GameContext's `ctx.sim.advance` owns this call once per step and passes scaled dt to its callback; game loops must not advance it again. */
     advance(realDt: number): number;
     now(): number;
+    /** Local accepted advance seconds × play speed × timescale, excluding calendar scale and saved offsets. Never hydrated or serialized; optional for external clocks. */
+    advancedSeconds?(): number;
     snapshot(): ClockSnapshot;
     /** Restore clock position — game-time, pause state, and speed multipliers — from a {@link ClockSnapshot} for whole-world save/load. Live timers registered via `after`/`every`/`at` are unaffected. */
     hydrate(snapshot: ClockSnapshot): void;
@@ -85,4 +87,6 @@ export interface SimClockOptions {
     /** Called on control changes and once per displayed in-game minute so UI can rebind; never fires per frame. */
     onChange?: () => void;
 }
-export declare function createSimClock(options?: SimClockOptions): SimClock;
+export declare function createSimClock(options?: SimClockOptions): SimClock & {
+    advancedSeconds(): number;
+};

package/dist/time/simClock.js

@@ -16,6 +16,7 @@ export function createSimClock(options = {}) {
     const daysPerYear = config.daysPerYear !== undefined && config.daysPerYear > 0 ? config.daysPerYear : 365;
     const seasons = config.seasons;
     let now = config.start !== undefined && config.start > 0 ? config.start : 0;
+    let advancedSeconds = 0;
     let paused = config.startPaused ?? false;
     let playSpeed = speeds[0];
     let timescale = 1;
@@ -76,7 +77,10 @@ export function createSimClock(options = {}) {
         if (paused || realDt <= 0 || timescale === 0)
             return 0;
         const gameDt = realDt * scale * playSpeed * timescale;
+        const localDt = realDt * playSpeed * timescale;
         now += gameDt;
+        if (Number.isFinite(localDt) && localDt > 0)
+            advancedSeconds += localDt;
         fireDueTimers();
         const minute = minuteIndex(now, dayLength);
         if (minute !== displayMinute) {
@@ -138,6 +142,7 @@ export function createSimClock(options = {}) {
     return {
         advance,
         now: () => now,
+        advancedSeconds: () => advancedSeconds,
         calendar,
         hydrate,
         snapshot: () => ({

package/dist/vfx/particleDirector.d.ts

@@ -1,6 +1,12 @@
-import type { EmitterConfig, Vec3 } from "./particles.js";
+import { type EmitterConfig, type ParticleEvent, type Vec3 } from "./particles.js";
 /** How a particle effect composites on screen: `additive` for sparks/fire/glow, `normal` for smoke/dust. */
 export type ParticleBlendHint = "additive" | "normal";
+/** Render output selected independently of particle spawn and simulation. */
+export interface ParticleRenderHint {
+    shape: "point" | "streak" | "flake" | "flame" | "smoke" | "ribbon" | "ripple";
+    /** Velocity streak length in seconds. Default 0.08. */
+    stretch?: number;
+}
 /** A one-shot burst request — consumed once by the renderer, never serialized. */
 export interface ParticleBurst {
     /** Monotonic sequence id so a renderer can consume each burst exactly once. */
@@ -9,6 +15,15 @@ export interface ParticleBurst {
     /** Particles to emit immediately. */
     count: number;
     blending?: ParticleBlendHint;
+    emitterId?: string;
+    options?: ParticleAttachOptions;
+}
+/** A bounded collision child effect; children cannot spawn further collision children. */
+export interface ParticleCollisionEffect {
+    config: EmitterConfig;
+    count: number;
+    render?: ParticleRenderHint;
+    blending?: ParticleBlendHint;
 }
 /** Options for {@link ParticleDirector.attach}. */
 export interface ParticleAttachOptions {
@@ -17,15 +32,36 @@ export interface ParticleAttachOptions {
     /** World offset from the followed entity (or from the config position when unfollowed). */
     offset?: Vec3;
     blending?: ParticleBlendHint;
+    /** Local particles move with the followed pose; world particles retain their emitted positions. */
+    space?: "world" | "local";
+    active?: boolean;
+    render?: ParticleRenderHint;
+    collisionEffect?: ParticleCollisionEffect;
+    /** Explicit environment influence: windResponse in 1/second, maxAcceleration in metres/second², both 0..1e12. */
+    environment?: {
+        windResponse?: number;
+        maxAcceleration?: number;
+        mask?: number;
+    };
 }
 /** A keyed continuous emitter owned by the director until detached. */
-export interface ParticleEmitterSpec {
+export interface ParticleEmitterSpec extends ParticleAttachOptions {
     id: string;
     config: EmitterConfig;
     follow?: string;
     offset?: Vec3;
     blending?: ParticleBlendHint;
 }
+/** A cosmetic simulation event, labelled with its emitting effect. */
+export interface ParticleDirectorEvent extends ParticleEvent {
+    emitterId: string;
+}
+/** Bounded storage policy for transient effects and event exchange. */
+export interface ParticleDirectorOptions {
+    maxEmitters?: number;
+    maxBursts?: number;
+    maxEvents?: number;
+}
 /** Serializable director state: the standing emitters (bursts are transient by nature). */
 export interface ParticleDirectorState {
     nextSeq: number;
@@ -40,17 +76,28 @@ export interface ParticleDirectorState {
  */
 export interface ParticleDirector {
     /** Queue a one-shot burst (impact puff, debris, muzzle smoke). */
-    burst(config: EmitterConfig, count: number, blending?: ParticleBlendHint): void;
+    burst(config: EmitterConfig, count: number, blending?: ParticleBlendHint, options?: ParticleAttachOptions): void;
     /** Create or replace a standing emitter under `id` (exhaust, dust plume, torch smoke). */
     attach(id: string, config: EmitterConfig, options?: ParticleAttachOptions): void;
     /** Patch a standing emitter's config in place (e.g. scale exhaust rate with speed). */
-    retune(id: string, patch: Partial<EmitterConfig>): void;
+    retune(id: string, patch: Partial<EmitterConfig>, options?: Partial<ParticleAttachOptions>): void;
+    /** Resume a named emitter while preserving its live particles. */
+    start(id: string): void;
+    /** Stop spawning; the renderer lets existing particles finish. */
+    stop(id: string): void;
+    /** Emit once through a named emitter's existing pool, including when stopped. */
+    burstNamed(id: string, count: number): void;
+    /** Renderer-to-game cosmetic event exchange, bounded by the director's event limit. */
+    reportEvents(id: string, events: readonly ParticleEvent[]): void;
+    drainEvents(): ParticleDirectorEvent[];
     /** Remove a standing emitter. Unknown ids are ignored. */
     detach(id: string): void;
     /** Drop every standing emitter and any unconsumed bursts. */
     clear(): void;
     /** The standing emitters, for renderers and assertions. */
     emitters(): readonly ParticleEmitterSpec[];
+    /** Fixed registry and transient queue capacities for transactional preflight. */
+    limits(): Required<ParticleDirectorOptions>;
     /** Return and forget the queued bursts — the renderer's consume-once read. */
     drainBursts(): ParticleBurst[];
     subscribe(listener: () => void): () => void;
@@ -63,6 +110,11 @@ export interface ParticleDirector {
  * 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 declare function createParticleDirector(options?: ParticleDirectorOptions): ParticleDirector;
+/**
+ * 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 declare function createParticleDirector(): ParticleDirector;
+export declare function validateParticleAttachOptions(value: unknown): string[];

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;
+}