@jgengine/core 0.18.0 → 0.19.0

package/dist/settings/graphicsSettings.d.ts

@@ -0,0 +1,40 @@
+import { type GraphicsProfile } from "./graphicsProfile.js";
+import { type GraphicsQuality, type SettingsStore } from "./settingsModel.js";
+/** The post-processing stages a player can toggle individually on top of the quality tier. */
+export type GraphicsPostStage = keyof GraphicsProfile["postStages"];
+/** Ordered stage list used to build settings rows. */
+export declare const GRAPHICS_POST_STAGES: readonly GraphicsPostStage[];
+/** Player-facing labels for each post stage. */
+export declare const GRAPHICS_POST_STAGE_LABELS: Record<GraphicsPostStage, string>;
+/** Setting id that stores one stage toggle (`graphics.post.<stage>`). */
+export declare function graphicsPostStageSettingId(stage: GraphicsPostStage): string;
+/** Lowest player render scale; the value is the device-pixel-ratio cap handed to the canvas. */
+export declare const RENDER_SCALE_MIN = 0.5;
+/** Highest player render scale. */
+export declare const RENDER_SCALE_MAX = 2;
+/** Render-scale slider increment. */
+export declare const RENDER_SCALE_STEP = 0.05;
+/** Texture-filtering choices offered to the player; the value is the anisotropy sample count. */
+export declare const ANISOTROPY_OPTIONS: readonly {
+    value: string;
+    label: string;
+}[];
+/** Per-tier profile overrides a game authors with `defineGame({ graphics })`. */
+export type GraphicsProfileOverrides = Partial<Record<GraphicsQuality, Partial<GraphicsProfile>>>;
+/** The resolved player graphics choice: the tier plus the profile after per-stage and render-scale overrides. */
+export interface GraphicsSettingsState {
+    quality: GraphicsQuality;
+    profile: GraphicsProfile;
+}
+/** The stored quality tier, falling back to the default when the value is missing or unknown. */
+export declare function readGraphicsQuality(store: Pick<SettingsStore, "get">): GraphicsQuality;
+/**
+ * Resolve the player's graphics state from a settings store. The tier profile (with the game's
+ * overrides) supplies every default; a stored render scale or stage toggle replaces its field.
+ */
+export declare function readGraphicsSettings(store: Pick<SettingsStore, "get">, overrides?: GraphicsProfileOverrides): GraphicsSettingsState;
+/**
+ * Select a quality tier and re-apply its render scale, texture filtering and stage defaults, so picking a preset
+ * resets the individual overrides instead of leaving stale toggles behind.
+ */
+export declare function applyGraphicsQuality(store: Pick<SettingsStore, "set">, quality: GraphicsQuality, overrides?: GraphicsProfileOverrides): GraphicsProfile;

package/dist/settings/graphicsSettings.js

@@ -0,0 +1,81 @@
+import { resolveGraphicsProfile } from "./graphicsProfile.js";
+import { DEFAULT_GRAPHICS_QUALITY, GRAPHICS_QUALITY_OPTIONS, SETTING_IDS, } from "./settingsModel.js";
+/** Ordered stage list used to build settings rows. */
+export const GRAPHICS_POST_STAGES = ["ao", "bloom", "dof", "smaa"];
+/** Player-facing labels for each post stage. */
+export const GRAPHICS_POST_STAGE_LABELS = {
+    ao: "Ambient occlusion",
+    bloom: "Bloom",
+    dof: "Depth of field",
+    smaa: "Anti-aliasing (SMAA)",
+};
+/** Setting id that stores one stage toggle (`graphics.post.<stage>`). */
+export function graphicsPostStageSettingId(stage) {
+    return `graphics.post.${stage}`;
+}
+/** Lowest player render scale; the value is the device-pixel-ratio cap handed to the canvas. */
+export const RENDER_SCALE_MIN = 0.5;
+/** Highest player render scale. */
+export const RENDER_SCALE_MAX = 2;
+/** Render-scale slider increment. */
+export const RENDER_SCALE_STEP = 0.05;
+/** Texture-filtering choices offered to the player; the value is the anisotropy sample count. */
+export const ANISOTROPY_OPTIONS = [
+    { value: "1", label: "Off" },
+    { value: "2", label: "2x" },
+    { value: "4", label: "4x" },
+    { value: "8", label: "8x" },
+    { value: "16", label: "16x" },
+];
+const ANISOTROPY_VALUES = [1, 2, 4, 8, 16];
+function toAnisotropy(raw, fallback) {
+    const value = Number(raw);
+    return ANISOTROPY_VALUES.find((option) => option === value) ?? fallback;
+}
+const QUALITY_VALUES = new Set(GRAPHICS_QUALITY_OPTIONS.map((option) => option.value));
+function isGraphicsQuality(value) {
+    return typeof value === "string" && QUALITY_VALUES.has(value);
+}
+function clampRenderScale(value) {
+    return Math.min(RENDER_SCALE_MAX, Math.max(RENDER_SCALE_MIN, value));
+}
+/** The stored quality tier, falling back to the default when the value is missing or unknown. */
+export function readGraphicsQuality(store) {
+    const raw = store.get(SETTING_IDS.graphicsQuality, DEFAULT_GRAPHICS_QUALITY);
+    return isGraphicsQuality(raw) ? raw : DEFAULT_GRAPHICS_QUALITY;
+}
+/**
+ * Resolve the player's graphics state from a settings store. The tier profile (with the game's
+ * overrides) supplies every default; a stored render scale or stage toggle replaces its field.
+ */
+export function readGraphicsSettings(store, overrides) {
+    const quality = readGraphicsQuality(store);
+    const tier = resolveGraphicsProfile(quality, overrides?.[quality]);
+    const postStages = { ...tier.postStages };
+    for (const stage of GRAPHICS_POST_STAGES) {
+        postStages[stage] = store.get(graphicsPostStageSettingId(stage), tier.postStages[stage]);
+    }
+    return {
+        quality,
+        profile: {
+            ...tier,
+            renderScale: clampRenderScale(store.get(SETTING_IDS.graphicsRenderScale, tier.renderScale)),
+            anisotropy: toAnisotropy(store.get(SETTING_IDS.graphicsAnisotropy, String(tier.anisotropy)), tier.anisotropy),
+            postStages,
+        },
+    };
+}
+/**
+ * Select a quality tier and re-apply its render scale, texture filtering and stage defaults, so picking a preset
+ * resets the individual overrides instead of leaving stale toggles behind.
+ */
+export function applyGraphicsQuality(store, quality, overrides) {
+    const tier = resolveGraphicsProfile(quality, overrides?.[quality]);
+    store.set(SETTING_IDS.graphicsQuality, quality);
+    store.set(SETTING_IDS.graphicsRenderScale, tier.renderScale);
+    store.set(SETTING_IDS.graphicsAnisotropy, String(tier.anisotropy));
+    for (const stage of GRAPHICS_POST_STAGES) {
+        store.set(graphicsPostStageSettingId(stage), tier.postStages[stage]);
+    }
+    return tier;
+}

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/eventMeter.d.ts

@@ -34,6 +34,6 @@ export interface EventMeter {
 /**
  * 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";

package/dist/time/accrueSince.d.ts

@@ -0,0 +1,10 @@
+/** Elapsed duration and the next anchor to persist with accrued effects. */
+export interface Accrual {
+    elapsedMs: number;
+    elapsedSeconds: number;
+    anchorMs: number;
+}
+/** Elapsed time since a persisted anchor, capped once; persist anchorMs with the accrued result. */
+export declare function accrueSince(anchorMs: number, nowMs: number, options?: {
+    capMs?: number;
+}): Accrual;

package/dist/time/accrueSince.js

@@ -0,0 +1,9 @@
+/** Elapsed time since a persisted anchor, capped once; persist anchorMs with the accrued result. */
+export function accrueSince(anchorMs, nowMs, options = {}) {
+    const cap = options.capMs ?? Infinity;
+    if (!Number.isFinite(anchorMs) || !Number.isFinite(nowMs) || Number.isNaN(cap) || cap < 0) {
+        throw new RangeError("Accrual requires finite anchors and a nonnegative cap");
+    }
+    const elapsedMs = Math.min(cap, Math.max(0, nowMs - anchorMs));
+    return { elapsedMs, elapsedSeconds: elapsedMs / 1000, anchorMs: Math.max(anchorMs, nowMs) };
+}

package/dist/time/rateWindow.d.ts

@@ -0,0 +1,16 @@
+/** Maximum accepted operations in a sliding duration. */
+export interface RateWindowPolicy {
+    windowMs: number;
+    max: number;
+}
+/** Admission result, next stored timestamps, and wait before retrying. */
+export interface RateWindowDecision {
+    allowed: boolean;
+    timestamps: number[];
+    retryAfterMs: number;
+}
+/**
+ * A sliding rate window; persist timestamps only alongside the accepted operation.
+ * @capability rate-window-policy Evaluate deterministic request windows with retry timing.
+ */
+export declare function decideRateWindow(timestamps: readonly number[], nowMs: number, policy: RateWindowPolicy): RateWindowDecision;

package/dist/time/rateWindow.js

@@ -0,0 +1,14 @@
+/**
+ * A sliding rate window; persist timestamps only alongside the accepted operation.
+ * @capability rate-window-policy Evaluate deterministic request windows with retry timing.
+ */
+export function decideRateWindow(timestamps, nowMs, policy) {
+    if (!Number.isFinite(nowMs) || !Number.isFinite(policy.windowMs) || policy.windowMs <= 0 ||
+        !Number.isSafeInteger(policy.max) || policy.max < 1)
+        throw new RangeError("Invalid rate window policy");
+    const active = timestamps.filter((at) => Number.isFinite(at) && at > nowMs - policy.windowMs).sort((a, b) => a - b);
+    if (active.length >= policy.max) {
+        return { allowed: false, timestamps: active, retryAfterMs: Math.max(0, active[active.length - policy.max] + policy.windowMs - nowMs) };
+    }
+    return { allowed: true, timestamps: [...active, nowMs], retryAfterMs: 0 };
+}

package/dist/time/serverTick.d.ts

@@ -2,11 +2,26 @@ export interface TickSystemDefinition<TSystemId extends string = string> {
     id: TSystemId;
     /** Minimum real time between runs; the heartbeat fires the system on the first tick at or past it. */
     intervalMs: number;
+    scope?: "onlinePlayers" | "allServers";
+    batchSize?: number;
 }
 /** Last-run timestamp per system id. */
 export type TickAnchors = Record<string, number>;
+/** One due system and how many times this heartbeat owes it. */
+export interface TickSystemRun<TSystemId extends string = string> {
+    id: TSystemId;
+    /** Times to run the system now; above 1 when wall time stalled past several intervals. */
+    runs: number;
+    scope?: "onlinePlayers" | "allServers";
+    batchSize?: number;
+}
 export interface ServerTickPlan<TSystemId extends string = string> {
-    due: TSystemId[];
+    /**
+     * Due systems, at most one entry per id. `runs` carries catch-up multiplicity — the anchors were
+     * advanced by that many intervals, so a host that runs the handler once per entry silently drops
+     * the rest.
+     */
+    due: TickSystemRun<TSystemId>[];
     anchors: TickAnchors;
 }
 export type PlanServerTickOptions = {
@@ -15,8 +30,11 @@ export type PlanServerTickOptions = {
 };
 /**
  * Decides which systems a heartbeat should run. A system with no anchor runs immediately.
- * When wall time stalls past multiple intervals, the system id is repeated (bounded by
- * maxCatchUp). Excess lag past the bound resyncs the anchor to `now`.
+ * When wall time stalls past multiple intervals the system's `runs` climbs (bounded by
+ * maxCatchUp), and the returned anchor moves by that many intervals — so a host that ignores
+ * `runs` loses the catch-up work. Excess lag past the bound resyncs the anchor to `now`.
  * Returned anchors carry only systems present in the pipeline, so removed systems clean up.
  */
 export declare function planServerTick<TSystemId extends string>(systems: readonly TickSystemDefinition<TSystemId>[], anchors: TickAnchors, now: number, options?: PlanServerTickOptions): ServerTickPlan<TSystemId>;
+/** Times this plan owes `id`, or 0 when it is not due. Saves a host a lookup over {@link ServerTickPlan.due}. */
+export declare function tickRunCount<TSystemId extends string>(plan: ServerTickPlan<TSystemId>, id: TSystemId): number;

package/dist/time/serverTick.js

@@ -1,8 +1,9 @@
 const DEFAULT_MAX_CATCH_UP = 3;
 /**
  * Decides which systems a heartbeat should run. A system with no anchor runs immediately.
- * When wall time stalls past multiple intervals, the system id is repeated (bounded by
- * maxCatchUp). Excess lag past the bound resyncs the anchor to `now`.
+ * When wall time stalls past multiple intervals the system's `runs` climbs (bounded by
+ * maxCatchUp), and the returned anchor moves by that many intervals — so a host that ignores
+ * `runs` loses the catch-up work. Excess lag past the bound resyncs the anchor to `now`.
  * Returned anchors carry only systems present in the pipeline, so removed systems clean up.
  */
 export function planServerTick(systems, anchors, now, options) {
@@ -10,14 +11,12 @@ export function planServerTick(systems, anchors, now, options) {
     const due = [];
     const nextAnchors = {};
     for (const system of systems) {
+        if (system.batchSize !== undefined && (!Number.isSafeInteger(system.batchSize) || system.batchSize < 1 || system.batchSize > 1000))
+            throw new RangeError("batchSize must be an integer from 1 to 1000");
+        const dispatch = { ...(system.scope === undefined ? {} : { scope: system.scope }), ...(system.batchSize === undefined ? {} : { batchSize: system.batchSize }) };
         const lastRunAt = anchors[system.id];
-        if (lastRunAt === undefined) {
-            due.push(system.id);
-            nextAnchors[system.id] = now;
-            continue;
-        }
-        if (system.intervalMs <= 0) {
-            due.push(system.id);
+        if (lastRunAt === undefined || system.intervalMs <= 0) {
+            due.push({ id: system.id, runs: 1, ...dispatch });
             nextAnchors[system.id] = now;
             continue;
         }
@@ -28,14 +27,16 @@ export function planServerTick(systems, anchors, now, options) {
         }
         const missed = Math.floor(elapsed / system.intervalMs);
         if (missed > maxCatchUp) {
-            for (let i = 0; i < maxCatchUp; i += 1)
-                due.push(system.id);
+            due.push({ id: system.id, runs: maxCatchUp, ...dispatch });
             nextAnchors[system.id] = now;
             continue;
         }
-        for (let i = 0; i < missed; i += 1)
-            due.push(system.id);
+        due.push({ id: system.id, runs: missed, ...dispatch });
         nextAnchors[system.id] = lastRunAt + missed * system.intervalMs;
     }
     return { due, anchors: nextAnchors };
 }
+/** Times this plan owes `id`, or 0 when it is not due. Saves a host a lookup over {@link ServerTickPlan.due}. */
+export function tickRunCount(plan, id) {
+    return plan.due.find((entry) => entry.id === id)?.runs ?? 0;
+}

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

@@ -0,0 +1,68 @@
+import type { EmitterConfig, 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";
+/** 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. */
+    seq: number;
+    config: EmitterConfig;
+    /** Particles to emit immediately. */
+    count: number;
+    blending?: ParticleBlendHint;
+}
+/** Options for {@link ParticleDirector.attach}. */
+export interface ParticleAttachOptions {
+    /** Scene entity id the emitter origin tracks each frame (plus `offset`). */
+    follow?: string;
+    /** World offset from the followed entity (or from the config position when unfollowed). */
+    offset?: Vec3;
+    blending?: ParticleBlendHint;
+}
+/** A keyed continuous emitter owned by the director until detached. */
+export interface ParticleEmitterSpec {
+    id: string;
+    config: EmitterConfig;
+    follow?: string;
+    offset?: Vec3;
+    blending?: ParticleBlendHint;
+}
+/** Serializable director state: the standing emitters (bursts are transient by nature). */
+export interface ParticleDirectorState {
+    nextSeq: number;
+    emitters: ParticleEmitterSpec[];
+}
+/**
+ * The game-side seam for particle effects. Game logic requests one-shot bursts and
+ * standing emitters as plain data; the shell renders them through
+ * `createParticleSystem`/`ParticleField`, applies the graphics-quality particle cap,
+ * and tracks `follow` entities. Nothing here touches a renderer, so commands and
+ * `onTick` systems can drive VFX headlessly and tests can assert the requested effects.
+ */
+export interface ParticleDirector {
+    /** Queue a one-shot burst (impact puff, debris, muzzle smoke). */
+    burst(config: EmitterConfig, count: number, blending?: ParticleBlendHint): 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;
+    /** 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[];
+    /** Return and forget the queued bursts — the renderer's consume-once read. */
+    drainBursts(): ParticleBurst[];
+    subscribe(listener: () => void): () => void;
+    snapshot(): ParticleDirectorState;
+    restore(state: ParticleDirectorState): void;
+}
+/**
+ * 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
+ */
+export declare function createParticleDirector(): ParticleDirector;