@jgengine/core 0.18.1 → 0.21.0

package/dist/settings/settingsModel.d.ts

@@ -67,10 +67,18 @@ export declare const SETTING_IDS: {
     readonly graphicsQuality: "graphics.quality";
     readonly graphicsShadows: "graphics.shadows";
     readonly graphicsUiScale: "graphics.uiScale";
+    readonly graphicsRenderScale: "graphics.renderScale";
+    readonly graphicsPostAo: "graphics.post.ao";
+    readonly graphicsPostBloom: "graphics.post.bloom";
+    readonly graphicsPostDof: "graphics.post.dof";
+    readonly graphicsPostSmaa: "graphics.post.smaa";
+    readonly graphicsFrameRateLimit: "graphics.frameRateLimit";
+    readonly graphicsAnisotropy: "graphics.anisotropy";
+    readonly graphicsShowFps: "graphics.showFps";
     readonly touchStyle: "controls.touchStyle";
     readonly touchJoystick: "controls.touchJoystick";
 };
-export type GraphicsQuality = "low" | "medium" | "high";
+export type GraphicsQuality = "low" | "medium" | "high" | "ultra";
 export declare const GRAPHICS_QUALITY_OPTIONS: readonly SettingOption[];
 export declare const DEFAULT_MASTER_VOLUME = 1;
 export declare const DEFAULT_GRAPHICS_QUALITY: GraphicsQuality;

package/dist/settings/settingsModel.js

@@ -11,6 +11,14 @@ export const SETTING_IDS = {
     graphicsQuality: "graphics.quality",
     graphicsShadows: "graphics.shadows",
     graphicsUiScale: "graphics.uiScale",
+    graphicsRenderScale: "graphics.renderScale",
+    graphicsPostAo: "graphics.post.ao",
+    graphicsPostBloom: "graphics.post.bloom",
+    graphicsPostDof: "graphics.post.dof",
+    graphicsPostSmaa: "graphics.post.smaa",
+    graphicsFrameRateLimit: "graphics.frameRateLimit",
+    graphicsAnisotropy: "graphics.anisotropy",
+    graphicsShowFps: "graphics.showFps",
     touchStyle: "controls.touchStyle",
     touchJoystick: "controls.touchJoystick",
 };
@@ -18,6 +26,7 @@ export const GRAPHICS_QUALITY_OPTIONS = [
     { value: "low", label: "Low" },
     { value: "medium", label: "Medium" },
     { value: "high", label: "High" },
+    { value: "ultra", label: "Ultra" },
 ];
 export const DEFAULT_MASTER_VOLUME = 1;
 export const DEFAULT_GRAPHICS_QUALITY = "high";
@@ -31,6 +40,7 @@ export const GRAPHICS_QUALITY_DPR = {
     low: 1,
     medium: 1.5,
     high: 2,
+    ultra: 2,
 };
 export function busVolumeSettingId(busId) {
     return `sound.bus.${busId}`;

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,11 +35,12 @@ 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.
  *
- * @capability event-meter a heat/streak gauge that builds from repeated hits and cools down over time
+ * @capability event-meter a heat/streak/alert gauge (wanted level, rage, combo) that builds from repeated events and cools down over time
  */
 export declare function createEventMeter(config: EventMeterConfig): EventMeter;

package/dist/stats/eventMeter.js

@@ -5,7 +5,7 @@ function readyOf(meter, mode) {
 /**
  * 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.
  *
- * @capability event-meter a heat/streak gauge that builds from repeated hits and cools down over time
+ * @capability event-meter a heat/streak/alert gauge (wanted level, rage, combo) that builds from repeated events and cools down over time
  */
 export function createEventMeter(config) {
     const mode = config.mode ?? "hold";
@@ -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/feedbackMixer.d.ts

@@ -0,0 +1,61 @@
+/** Piecewise-linear map from a signal value to an output value; points in ascending input order, ends clamp. */
+export type FeedbackCurve = readonly (readonly [number, number])[];
+/** One wire from a sim signal to a named output. */
+export interface FeedbackRoute<TSignal extends string, TTarget extends string> {
+    signal: TSignal;
+    target: TTarget;
+    /** Signal → output mapping (default identity). */
+    curve?: FeedbackCurve;
+    /** Units/s the routed value may rise (default `Infinity`: follows instantly). */
+    attack?: number;
+    /** Units/s the routed value may fall (default `attack`). */
+    release?: number;
+}
+/** A one-shot fired when a signal crosses a threshold (landing thud, gear-change clunk, impact rumble). */
+export interface FeedbackEvent<TSignal extends string> {
+    id: string;
+    signal: TSignal;
+    /** Fires when the signal rises to or above this value from below it. */
+    threshold: number;
+    /** Seconds before the same event may fire again (default `0`). */
+    cooldown?: number;
+}
+/** Config for {@link createFeedbackMixer}. */
+export interface FeedbackMixerConfig<TSignal extends string, TTarget extends string> {
+    routes: readonly FeedbackRoute<TSignal, TTarget>[];
+    /** How routes landing on the same target combine (default `"sum"`). */
+    combine?: Partial<Record<TTarget, "sum" | "max">>;
+    /** Value a target starts from before routes add to it (default `0`). */
+    base?: Partial<Record<TTarget, number>>;
+    events?: readonly FeedbackEvent<TSignal>[];
+}
+/** Serializable mixer state: smoothed route values, last signal per event, and event cooldowns. */
+export interface FeedbackMixerState {
+    routes: number[];
+    eventSignals: number[];
+    cooldowns: number[];
+}
+/** Maps sim telemetry to presentation parameters through declared routes, curves and smoothing. */
+export interface FeedbackMixer<TSignal extends string, TTarget extends string> {
+    /**
+     * Advance by `dt` with this tick's signals and return every target's value. The returned record is reused
+     * between calls, so read it before the next update. Missing signals read as `0`.
+     */
+    update(dt: number, signals: Readonly<Partial<Record<TSignal, number>>>): Readonly<Record<TTarget, number>>;
+    /** True when event `id` fired on the last update. */
+    fired(id: string): boolean;
+    value(): Readonly<Record<TTarget, number>>;
+    retune(next: FeedbackMixerConfig<TSignal, TTarget>): void;
+    snapshot(): FeedbackMixerState;
+    restore(state: FeedbackMixerState): void;
+    reset(): void;
+}
+/** Sample a {@link FeedbackCurve}; an empty curve is the identity. */
+export declare function sampleFeedbackCurve(curve: FeedbackCurve | undefined, x: number): number;
+/**
+ * Creates a {@link FeedbackMixer}: the one place a game declares how sim telemetry drives presentation —
+ * rpm to engine pitch, tire saturation to squeal and rumble, speed to FOV, landing speed to a thud — instead
+ * of hand-writing that glue per vehicle, aircraft or weapon. Deterministic, allocation-free per update.
+ * @capability feedback-mixer map sim telemetry to camera, audio and haptic parameters through curves, smoothing and threshold events
+ */
+export declare function createFeedbackMixer<TSignal extends string, TTarget extends string>(initial: FeedbackMixerConfig<TSignal, TTarget>): FeedbackMixer<TSignal, TTarget>;

package/dist/vfx/feedbackMixer.js

@@ -0,0 +1,106 @@
+/** Sample a {@link FeedbackCurve}; an empty curve is the identity. */
+export function sampleFeedbackCurve(curve, x) {
+    if (curve === undefined || curve.length === 0)
+        return x;
+    const first = curve[0];
+    if (x <= first[0])
+        return first[1];
+    for (let i = 1; i < curve.length; i += 1) {
+        const [x1, y1] = curve[i];
+        if (x <= x1) {
+            const [x0, y0] = curve[i - 1];
+            const span = x1 - x0;
+            return span <= 0 ? y1 : y0 + ((y1 - y0) * (x - x0)) / span;
+        }
+    }
+    return curve[curve.length - 1][1];
+}
+function approach(current, target, attack, release, dt) {
+    const rate = target > current ? attack : release;
+    if (!Number.isFinite(rate))
+        return target;
+    const step = Math.max(0, rate) * dt;
+    return Math.abs(target - current) <= step ? target : current + Math.sign(target - current) * step;
+}
+/**
+ * Creates a {@link FeedbackMixer}: the one place a game declares how sim telemetry drives presentation —
+ * rpm to engine pitch, tire saturation to squeal and rumble, speed to FOV, landing speed to a thud — instead
+ * of hand-writing that glue per vehicle, aircraft or weapon. Deterministic, allocation-free per update.
+ * @capability feedback-mixer map sim telemetry to camera, audio and haptic parameters through curves, smoothing and threshold events
+ */
+export function createFeedbackMixer(initial) {
+    let config = initial;
+    let routeValues = [];
+    let eventSignals = [];
+    let cooldowns = [];
+    let firedNow = new Set();
+    const output = {};
+    const touched = new Set();
+    function shapeState() {
+        routeValues = config.routes.map((_, i) => routeValues[i] ?? 0);
+        eventSignals = (config.events ?? []).map((_, i) => eventSignals[i] ?? 0);
+        cooldowns = (config.events ?? []).map((_, i) => cooldowns[i] ?? 0);
+        for (const route of config.routes)
+            output[route.target] ??= 0;
+        for (const key of Object.keys(config.base ?? {}))
+            output[key] ??= config.base?.[key] ?? 0;
+    }
+    shapeState();
+    return {
+        update(dt, signals) {
+            const step = Math.max(0, dt);
+            for (const key of Object.keys(output))
+                output[key] = config.base?.[key] ?? 0;
+            touched.clear();
+            for (let i = 0; i < config.routes.length; i += 1) {
+                const route = config.routes[i];
+                const target = sampleFeedbackCurve(route.curve, signals[route.signal] ?? 0);
+                const attack = route.attack ?? Number.POSITIVE_INFINITY;
+                const value = approach(routeValues[i], target, attack, route.release ?? attack, step);
+                routeValues[i] = value;
+                const mode = config.combine?.[route.target] ?? "sum";
+                if (mode === "max") {
+                    const current = touched.has(route.target) ? output[route.target] : Number.NEGATIVE_INFINITY;
+                    output[route.target] = Math.max(current, value);
+                }
+                else
+                    output[route.target] += value;
+                touched.add(route.target);
+            }
+            firedNow.clear();
+            const events = config.events ?? [];
+            for (let i = 0; i < events.length; i += 1) {
+                const event = events[i];
+                const value = signals[event.signal] ?? 0;
+                cooldowns[i] = Math.max(0, cooldowns[i] - step);
+                if (value >= event.threshold && eventSignals[i] < event.threshold && cooldowns[i] === 0) {
+                    firedNow.add(event.id);
+                    cooldowns[i] = event.cooldown ?? 0;
+                }
+                eventSignals[i] = value;
+            }
+            return output;
+        },
+        fired: (id) => firedNow.has(id),
+        value: () => output,
+        retune(next) {
+            config = next;
+            shapeState();
+        },
+        snapshot: () => ({ routes: [...routeValues], eventSignals: [...eventSignals], cooldowns: [...cooldowns] }),
+        restore(state) {
+            routeValues = [...state.routes];
+            eventSignals = [...state.eventSignals];
+            cooldowns = [...state.cooldowns];
+            shapeState();
+        },
+        reset() {
+            routeValues = routeValues.map(() => 0);
+            eventSignals = eventSignals.map(() => 0);
+            cooldowns = cooldowns.map(() => 0);
+            firedNow = new Set();
+            for (const key of Object.keys(output))
+                output[key] = config.base?.[key] ?? 0;
+        },
+    };
+}

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