@jgengine/core 0.18.1 → 0.21.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,11 +58,93 @@ 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;
     }
 }
-/** Builds a {@link VehicleSeats}, optionally over an existing `MountController` to share its occupancy. */
+/**
+ * Builds a {@link VehicleSeats}, optionally over an existing `MountController` to share its occupancy.
+ *
+ * @capability vehicle-seats enter, exit and swap seats in a car or mount (GTA-style boarding) with driver and passenger slots
+ */
 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/sensor/concealment.d.ts

@@ -14,9 +14,15 @@ export interface ConcealmentSample {
     concealed: boolean;
     dwellSeconds: number;
 }
+/** Plain JSON state of a {@link ConcealmentSensor}: seconds each target has stayed concealed. */
+export interface ConcealmentSensorState {
+    dwell: Record<string, number>;
+}
 export interface ConcealmentSensor {
     tick(targets: readonly ConcealmentTarget[], dt: number): ConcealmentSample[];
     reset(id?: string): void;
+    snapshot(): ConcealmentSensorState;
+    restore(next: ConcealmentSensorState): void;
 }
 /** @internal */
 export declare function createConcealmentSensor(config?: {

package/dist/sensor/concealment.js

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

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