@jgengine/core 0.18.1 → 0.19.0

package/dist/sensor/freezeMonitor.d.ts

@@ -7,9 +7,15 @@ export interface FreezeViolation {
     speed: number;
     movedSeconds: number;
 }
+/** Plain JSON state of a {@link FreezeMonitor}: seconds each frozen subject has kept moving. */
+export interface FreezeMonitorState {
+    moved: Record<string, number>;
+}
 export interface FreezeMonitor {
     tick(subjects: readonly FreezeSubject[], frozenIds: ReadonlySet<string>, dt: number): FreezeViolation[];
     reset(id?: string): void;
+    snapshot(): FreezeMonitorState;
+    restore(next: FreezeMonitorState): void;
 }
 /** @internal */
 export declare function createFreezeMonitor(config?: {

package/dist/sensor/freezeMonitor.js

@@ -32,5 +32,13 @@ export function createFreezeMonitor(config) {
             else
                 moved.delete(id);
         },
+        snapshot() {
+            return { moved: Object.fromEntries(moved) };
+        },
+        restore(next) {
+            moved.clear();
+            for (const [id, seconds] of Object.entries(next.moved))
+                moved.set(id, seconds);
+        },
     };
 }

package/dist/sensor/perception.d.ts

@@ -7,6 +7,7 @@ export interface PerceptionStimulus {
     kind: PerceptionStimulusKind;
     sourceId: string;
     position: PerceptionPosition;
+    /** Multiplies `hearingRange` for this sound: a footstep might be `0.3`, a gunshot `4`. Default `1`. */
     loudness?: number;
     at: number;
 }
@@ -34,6 +35,8 @@ export interface PerceptionConfig {
     sightConeDeg: number;
     hearingRange: number;
     memorySeconds: number;
+    /** Most stimuli retained at once; the oldest are dropped first. Default 256. */
+    maxStimuli?: number;
     occluded?: (from: PerceptionPosition, to: PerceptionPosition) => boolean;
 }
 /** Serializable state for a perception service. */
@@ -42,14 +45,21 @@ export interface PerceptionSnapshot {
         observerId: string;
         memory: PerceptionMemory;
     }>;
-    stimuli: PerceptionStimulus[];
+    stimuli: Array<PerceptionStimulus & {
+        seq?: number;
+    }>;
     nowMs: number;
+    /** Per observer, the last stimulus sequence number it has already judged. Absent in older saves. */
+    heard?: Record<string, number>;
+    nextSeq?: number;
 }
 /** Stateful perception API with retuning and save/restore support. */
 export interface PerceptionService {
     pushStimulus(stimulus: PerceptionStimulus): void;
     observe(observer: PerceptionObserver, candidates: readonly PerceptionCandidate[], nowMs: number): void;
     memory(observerId: string): PerceptionMemory[];
+    /** Drop one remembered target, or everything an observer remembers (despawn, reset, disguise). */
+    forget(observerId: string, targetId?: string): void;
     retune(patch: Partial<PerceptionConfig>): void;
     snapshot(): PerceptionSnapshot;
     restore(snapshot: PerceptionSnapshot): void;

package/dist/sensor/perception.js

@@ -28,7 +28,10 @@ function validate(config) {
         throw new Error("hearingRange must be non-negative.");
     if (!Number.isFinite(config.memorySeconds) || config.memorySeconds <= 0)
         throw new Error("memorySeconds must be positive.");
+    if (config.maxStimuli !== undefined && (!Number.isInteger(config.maxStimuli) || config.maxStimuli < 1))
+        throw new Error("maxStimuli must be a positive integer.");
 }
+const DEFAULT_MAX_STIMULI = 256;
 /** Creates a deterministic sight, sound, and damage perception service with expiring target memory.
  * @capability perception-service retain sight, sound, and damage observations with range, cone, occlusion, and decay policy
  */
@@ -37,6 +40,8 @@ export function createPerception(initial) {
     let config = { ...initial };
     let nowMs = 0;
     const stimuli = [];
+    const heard = new Map();
+    let nextSeq = 1;
     const memories = new Map();
     function remember(observerId, targetId, position, at, confidence) {
         if (confidence <= 0)
@@ -62,8 +67,11 @@ export function createPerception(initial) {
                 memories.delete(observerId);
         }
         const cutoff = nowMs - memoryMs;
-        while (stimuli.length > 0 && stimuli[0].at < cutoff)
-            stimuli.shift();
+        let drop = Math.max(0, stimuli.length - (config.maxStimuli ?? DEFAULT_MAX_STIMULI));
+        while (drop < stimuli.length && stimuli[drop].at < cutoff)
+            drop += 1;
+        if (drop > 0)
+            stimuli.splice(0, drop);
     }
     return {
         pushStimulus(stimulus) {
@@ -72,8 +80,10 @@ export function createPerception(initial) {
             if (stimulus.kind === "sound" && stimulus.loudness !== undefined && (!Number.isFinite(stimulus.loudness) || stimulus.loudness < 0)) {
                 throw new Error("stimulus.loudness must be non-negative.");
             }
-            stimuli.push({ ...stimulus, position: [...stimulus.position] });
-            stimuli.sort((a, b) => a.at - b.at);
+            let index = stimuli.length;
+            while (index > 0 && stimuli[index - 1].at > stimulus.at)
+                index -= 1;
+            stimuli.splice(index, 0, { ...stimulus, position: [...stimulus.position], seq: nextSeq++ });
             nowMs = Math.max(nowMs, stimulus.at);
             prune();
         },
@@ -88,20 +98,33 @@ export function createPerception(initial) {
                     continue;
                 remember(observer.id, candidate.id, candidate.position, nowMs, 1);
             }
+            // Each observer judges a stimulus once, from where it stood when it first observed after the stimulus;
+            // re-judging every tick would make an old noise louder as the observer walks toward it.
+            const judgedThrough = heard.get(observer.id) ?? 0;
+            let judged = judgedThrough;
+            let firstFuture = Number.POSITIVE_INFINITY;
             for (const stimulus of stimuli) {
-                if (stimulus.at > nowMs || stimulus.sourceId === observer.id)
+                if (stimulus.seq <= judgedThrough)
+                    continue;
+                if (stimulus.at > nowMs) {
+                    firstFuture = Math.min(firstFuture, stimulus.seq);
+                    continue;
+                }
+                judged = Math.max(judged, stimulus.seq);
+                if (stimulus.sourceId === observer.id)
                     continue;
                 const range = distance(observer.position, stimulus.position);
                 if (stimulus.kind === "sound") {
-                    if (range > config.hearingRange)
+                    const audible = config.hearingRange * (stimulus.loudness ?? 1);
+                    if (range >= audible)
                         continue;
-                    const falloff = 1 - range / Math.max(config.hearingRange, 1e-9);
-                    remember(observer.id, stimulus.sourceId, stimulus.position, stimulus.at, falloff * (stimulus.loudness ?? 1));
+                    remember(observer.id, stimulus.sourceId, stimulus.position, stimulus.at, 1 - range / audible);
                 }
                 else if (stimulus.kind === "damage") {
                     remember(observer.id, stimulus.sourceId, stimulus.position, stimulus.at, 1);
                 }
             }
+            heard.set(observer.id, Math.min(judged, firstFuture - 1));
             prune();
         },
         memory(observerId) {
@@ -117,13 +140,29 @@ export function createPerception(initial) {
             }
             return result;
         },
+        forget(observerId, targetId) {
+            if (targetId === undefined) {
+                memories.delete(observerId);
+                return;
+            }
+            const observerMemories = memories.get(observerId);
+            observerMemories?.delete(targetId);
+            if (observerMemories?.size === 0)
+                memories.delete(observerId);
+        },
         retune(patch) {
             config = { ...config, ...patch };
             validate(config);
             prune();
         },
         snapshot() {
-            const result = { memories: [], stimuli: stimuli.map((stimulus) => ({ ...stimulus, position: [...stimulus.position] })), nowMs };
+            const result = {
+                memories: [],
+                stimuli: stimuli.map((stimulus) => ({ ...stimulus, position: [...stimulus.position] })),
+                nowMs,
+                heard: Object.fromEntries(heard),
+                nextSeq,
+            };
             for (const [observerId, observerMemories] of memories)
                 for (const memory of observerMemories.values())
                     result.memories.push({ observerId, memory: { ...memory, lastKnownPos: [...memory.lastKnownPos] } });
@@ -133,7 +172,15 @@ export function createPerception(initial) {
             memories.clear();
             stimuli.length = 0;
             nowMs = snapshot.nowMs;
-            stimuli.push(...snapshot.stimuli.map((stimulus) => ({ ...stimulus, position: [...stimulus.position] })));
+            heard.clear();
+            for (const [observerId, seq] of Object.entries(snapshot.heard ?? {}))
+                heard.set(observerId, seq);
+            let seq = 0;
+            for (const stimulus of snapshot.stimuli) {
+                seq = stimulus.seq ?? seq + 1;
+                stimuli.push({ ...stimulus, position: [...stimulus.position], seq });
+            }
+            nextSeq = Math.max(snapshot.nextSeq ?? 0, seq + 1);
             for (const entry of snapshot.memories)
                 remember(entry.observerId, entry.memory.targetId, entry.memory.lastKnownPos, entry.memory.lastSeenAt, entry.memory.confidence);
             prune();

package/dist/sensor/recordingBuffer.d.ts

@@ -24,6 +24,9 @@ export interface RecordingBuffer<T> {
     clear(): void;
     duration(): number;
     frames(): readonly RecordingFrame<T>[];
+    /** Copies the frame list; each frame's `data` is shared, since the buffer never mutates it. */
+    snapshot(): RecordingFrame<T>[];
+    restore(next: readonly RecordingFrame<T>[]): void;
 }
 /**
  * A session-recording buffer for replay / photo mode / kill-cam: append

package/dist/sensor/recordingBuffer.js

@@ -65,5 +65,13 @@ export function createRecordingBuffer(options = {}) {
         frames() {
             return frames;
         },
+        snapshot() {
+            return frames.map((frame) => ({ t: frame.t, data: frame.data }));
+        },
+        restore(next) {
+            frames.length = 0;
+            for (const frame of next)
+                frames.push({ t: frame.t, data: frame.data });
+        },
     };
 }

package/dist/session/roundState.d.ts

@@ -56,6 +56,8 @@ export interface RoundSnapshot<TPhase extends string = RoundPhase> {
     lossStreaks: Record<string, number>;
     roles: Record<string, string | undefined>;
     matchOver: boolean;
+    /** Winner of the round being settled, or null; drives `economyFor` until the next round starts. */
+    pendingWinner: string | null;
 }
 export interface RoundState<TPhase extends string = RoundPhase> {
     tick(dt: number): RoundEvent<TPhase>[];
@@ -71,6 +73,8 @@ export interface RoundState<TPhase extends string = RoundPhase> {
     /** The role tag configured for `team`, if any. */
     roleOf(team: string): string | undefined;
     snapshot(): RoundSnapshot<TPhase>;
+    /** Puts a {@link RoundState.snapshot} back; phase hooks stay registered. */
+    restore(next: RoundSnapshot<TPhase>): void;
 }
 /** @internal */
 export declare function lossBonusFor(rule: LossBonusRule | undefined, streak: number): number;

package/dist/session/roundState.js

@@ -104,6 +104,7 @@ export function createRoundState(config) {
             lossStreaks: { ...lossStreaks },
             roles: { ...roles },
             matchOver,
+            pendingWinner,
         };
     }
     function concludeRoundImpl(winner) {
@@ -156,5 +157,15 @@ export function createRoundState(config) {
         economyFor,
         roleOf: (team) => roles[team],
         snapshot: currentSnapshot,
+        restore(next) {
+            round = next.round;
+            phase = next.phase;
+            timeLeft = next.timeLeft;
+            matchOver = next.matchOver;
+            pendingWinner = next.pendingWinner;
+            Object.assign(scores, next.scores);
+            Object.assign(lossStreaks, next.lossStreaks);
+            Object.assign(roles, next.roles);
+        },
     };
 }

package/dist/settings/frameRateLimit.d.ts

@@ -0,0 +1,16 @@
+import { type SettingOption, type SettingsStore } from "./settingsModel.js";
+/** Stored value for "render every display refresh" — the browser's vsync-locked rate. */
+export declare const FRAME_RATE_LIMIT_DISPLAY = "display";
+/**
+ * Frame-rate limit choices. Browsers always present on the display's vsync, so the uncapped
+ * option runs at the monitor's refresh rate; the numeric caps skip refreshes to save GPU and battery.
+ */
+export declare const FRAME_RATE_LIMIT_OPTIONS: readonly SettingOption[];
+/** The player's frame-rate cap in frames per second, or 0 for the display rate. */
+export declare function readFrameRateLimit(store: Pick<SettingsStore, "get">): number;
+/**
+ * Frame pacing for a capped render loop driven by display refreshes. Returns the new frame
+ * anchor when a frame should render at `now`, or `null` to skip this refresh. The anchor keeps
+ * the remainder so a 60 cap on a 144 Hz display averages 60 instead of drifting to 48.
+ */
+export declare function paceFrame(now: number, anchor: number, fps: number): number | null;

package/dist/settings/frameRateLimit.js

@@ -0,0 +1,37 @@
+import { SETTING_IDS } from "./settingsModel.js";
+/** Stored value for "render every display refresh" — the browser's vsync-locked rate. */
+export const FRAME_RATE_LIMIT_DISPLAY = "display";
+/**
+ * Frame-rate limit choices. Browsers always present on the display's vsync, so the uncapped
+ * option runs at the monitor's refresh rate; the numeric caps skip refreshes to save GPU and battery.
+ */
+export const FRAME_RATE_LIMIT_OPTIONS = [
+    { value: FRAME_RATE_LIMIT_DISPLAY, label: "V-Sync" },
+    { value: "30", label: "30" },
+    { value: "60", label: "60" },
+    { value: "120", label: "120" },
+    { value: "144", label: "144" },
+];
+/** The player's frame-rate cap in frames per second, or 0 for the display rate. */
+export function readFrameRateLimit(store) {
+    const raw = store.get(SETTING_IDS.graphicsFrameRateLimit, FRAME_RATE_LIMIT_DISPLAY);
+    const fps = Number(raw);
+    return Number.isFinite(fps) && fps > 0 ? fps : 0;
+}
+/**
+ * Frame pacing for a capped render loop driven by display refreshes. Returns the new frame
+ * anchor when a frame should render at `now`, or `null` to skip this refresh. The anchor keeps
+ * the remainder so a 60 cap on a 144 Hz display averages 60 instead of drifting to 48.
+ */
+export function paceFrame(now, anchor, fps) {
+    if (fps <= 0)
+        return now;
+    const interval = 1000 / fps;
+    const elapsed = now - anchor;
+    // Half a millisecond of slack absorbs rAF timestamp jitter so a 60 cap on 60 Hz never skips.
+    if (elapsed < interval - 0.5)
+        return null;
+    if (elapsed > interval * 4)
+        return now;
+    return anchor + Math.max(1, Math.floor((elapsed + 0.5) / interval)) * interval;
+}

package/dist/settings/graphicsProfile.d.ts

@@ -6,6 +6,8 @@ export interface GraphicsProfile {
     cascades: 1 | 2 | 3 | 4;
     drawDistance: number;
     particleCap: number;
+    /** Anisotropic texture filtering samples; clamped to the GPU maximum. 1 is plain trilinear. */
+    anisotropy: 1 | 2 | 4 | 8 | 16;
     postStages: {
         ao: boolean;
         bloom: boolean;

package/dist/settings/graphicsProfile.js

@@ -6,6 +6,7 @@ export const DEFAULT_GRAPHICS_PROFILES = {
         cascades: 1,
         drawDistance: 120,
         particleCap: 128,
+        anisotropy: 2,
         postStages: { ao: false, bloom: true, dof: false, smaa: true },
     },
     medium: {
@@ -14,6 +15,7 @@ export const DEFAULT_GRAPHICS_PROFILES = {
         cascades: 2,
         drawDistance: 240,
         particleCap: 256,
+        anisotropy: 4,
         postStages: { ao: true, bloom: true, dof: true, smaa: true },
     },
     high: {
@@ -22,6 +24,16 @@ export const DEFAULT_GRAPHICS_PROFILES = {
         cascades: 4,
         drawDistance: 400,
         particleCap: 512,
+        anisotropy: 8,
+        postStages: { ao: true, bloom: true, dof: true, smaa: true },
+    },
+    ultra: {
+        renderScale: 2,
+        shadowMapSize: 4096,
+        cascades: 4,
+        drawDistance: 800,
+        particleCap: 1024,
+        anisotropy: 16,
         postStages: { ao: true, bloom: true, dof: true, smaa: true },
     },
 };

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/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>;