@jgengine/core 0.18.0 → 0.19.0

package/dist/scene/behaviors.d.ts

@@ -1,5 +1,6 @@
 import { type ProximityPrompt } from "../interaction/proximityPrompt.js";
 import type { PathProgress, Waypoint } from "../nav/pathFollow.js";
+import type { Blackboard, DecisionGraph } from "../ai/decisionGraph.js";
 export interface WanderBehavior {
     kind: "wander";
     radius: number;
@@ -27,7 +28,17 @@ export interface PromptableBehavior {
 export interface PlayerBehavior {
     kind: "player";
 }
-export type BehaviorDescriptor = WanderBehavior | PatrolBehavior | PromptableBehavior | PlayerBehavior;
+/** Decision graph behavior descriptor using a named registered action set. */
+export interface DecisionGraphBehavior {
+    kind: "decisionGraph";
+    graph: DecisionGraph;
+    actions: string;
+    /** Initial facts for this entity's persistent blackboard; systems write more through `behaviorControl(ctx).blackboard(id)`. */
+    blackboard?: Blackboard;
+    /** Seconds between graph ticks (`0` = every frame). Siblings are staggered; actions receive the elapsed time. */
+    thinkInterval?: number;
+}
+export type BehaviorDescriptor = WanderBehavior | PatrolBehavior | PromptableBehavior | PlayerBehavior | DecisionGraphBehavior;
 export declare function wander({ radius }: {
     radius: number;
 }): WanderBehavior;

package/dist/scene/builtinSceneKinds.js

@@ -37,6 +37,15 @@ export const SCATTER_SCHEMA = {
         { type: "seed", key: "seed", label: "seed", default: "" },
     ],
 };
+const LIGHT_SCHEMA = {
+    fields: [
+        { type: "select", key: "type", label: "type", options: [{ value: "point", label: "Point" }, { value: "spot", label: "Spot" }], default: "point" },
+        { type: "color", key: "color", label: "color", default: "#ffd6a0" },
+        { type: "number", key: "intensity", label: "intensity", min: 0, step: 0.1, default: 2 },
+        { type: "number", key: "range", label: "range", min: 0, step: 0.5, default: 12 },
+        { type: "bool", key: "castShadow", label: "cast shadow", default: false },
+    ],
+};
 let registered = false;
 /** Idempotently registers the engine's built-in environment scene kinds + generators. @internal */
 export function registerBuiltinSceneKinds() {
@@ -65,6 +74,7 @@ export function registerBuiltinSceneKinds() {
             return describeScatterCoverage(densityCoverage("scatter", area, density));
         },
     });
+    registerSceneKind({ kind: "light", target: "marker", label: "Light", addCategory: "Environment", accent: "#fbbf24", schema: LIGHT_SCHEMA });
     registerWaterKind();
     registerGrassKind();
     registerSoilKind();

package/dist/scene/sceneKinds.d.ts

@@ -5,6 +5,7 @@
  * party ship a new authorable "studio" (pole line, water, bookcase) — schema + resolver here, a
  * matching renderer in `shell` — without editing editor or engine files. Scatter is the proof adopter.
  */
+import type { WorldSolid } from "../world/worldSolids.js";
 /** Which document collection a scene kind lives in. Drives placement + which `meta` bag holds params. */
 export type SceneKindTarget = "path" | "marker" | "volume";
 /** A closed-polygon area vs an open polyline, for path-target kinds. Ignored for marker/volume kinds. */
@@ -212,6 +213,12 @@ export interface SceneKindDefinition<TResolved = unknown> {
      * marker/volume/path; `params` is `parseParams(schema, object.meta)`.
      */
     resolve?: (object: SceneKindObject, params: ParsedParams, context: SceneKindResolveContext) => TResolved;
+    /**
+     * World-space collision for a resolved object. Omitted, the kind is render-only. `syncAuthoredSolids`
+     * (`world/authoredSolids`) writes these into `ctx.world.solids`, so movement, NPCs, physics
+     * backends and nav grids all collide with what the studio draws.
+     */
+    solids?: (resolved: TResolved, object: SceneKindObject, params: ParsedParams, context: SceneKindResolveContext) => readonly WorldSolid[];
     /** Optional one-line readout under the inspector fields (estimate, dimensions) — owned by the studio. */
     note?: (object: SceneKindObject, params: ParsedParams) => string;
     /**
@@ -258,6 +265,8 @@ export interface SceneKindObject {
 export interface SceneKindResolveContext {
     sampleHeight?: (x: number, z: number) => number;
     sampleNormal?: (x: number, z: number) => readonly [number, number, number];
+    /** Every studio object in the same document, for kinds that read siblings (a `city` reads its `cityzone` volumes). */
+    objects?: readonly SceneKindObject[];
 }
 /**
  * Register a scene kind — the plug-in point for a new parametric studio. Idempotent per `kind` (last

package/dist/scene/vehicleSeat.d.ts

@@ -64,5 +64,9 @@ export declare class VehicleSeats {
     driverOf(vehicleId: string): string | null;
     get mounts(): MountController;
 }
-/** 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 declare function createVehicleSeats(controller?: MountController): VehicleSeats;

package/dist/scene/vehicleSeat.js

@@ -53,7 +53,11 @@ export class VehicleSeats {
         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);
 }

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

@@ -0,0 +1,70 @@
+/** A world position used by perception, in `[x, y, z]` order. */
+export type PerceptionPosition = readonly [number, number, number];
+/** The kinds of stimulus the perception service can retain. */
+export type PerceptionStimulusKind = "sight" | "sound" | "damage";
+/** An event that can seed an observer's memory. */
+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;
+}
+/** The observer pose used for a sight check. */
+export interface PerceptionObserver {
+    id: string;
+    position: PerceptionPosition;
+    yaw: number;
+}
+/** A candidate target considered by a sight check. */
+export interface PerceptionCandidate {
+    id: string;
+    position: PerceptionPosition;
+}
+/** A remembered target and its linearly decaying confidence. */
+export interface PerceptionMemory {
+    targetId: string;
+    lastSeenAt: number;
+    lastKnownPos: PerceptionPosition;
+    confidence: number;
+}
+/** Configuration for sight, hearing, memory decay, and optional occlusion. */
+export interface PerceptionConfig {
+    sightRange: number;
+    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. */
+export interface PerceptionSnapshot {
+    memories: Array<{
+        observerId: string;
+        memory: PerceptionMemory;
+    }>;
+    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;
+}
+/** 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
+ */
+export declare function createPerception(initial: PerceptionConfig): PerceptionService;

package/dist/sensor/perception.js

@@ -0,0 +1,189 @@
+function distance(a, b) {
+    return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+}
+function confidenceAt(memory, nowMs, memoryMs) {
+    return memory.confidence * Math.max(0, 1 - Math.max(0, nowMs - memory.lastSeenAt) / memoryMs);
+}
+function inSight(observer, target, config) {
+    const dx = target[0] - observer.position[0];
+    const dz = target[2] - observer.position[2];
+    const range = Math.hypot(dx, dz);
+    if (range > config.sightRange)
+        return false;
+    if (range < 1e-9)
+        return true;
+    let delta = Math.atan2(dx, dz) - observer.yaw;
+    while (delta > Math.PI)
+        delta -= Math.PI * 2;
+    while (delta < -Math.PI)
+        delta += Math.PI * 2;
+    return Math.abs(delta) <= (config.sightConeDeg * Math.PI) / 360;
+}
+function validate(config) {
+    if (!Number.isFinite(config.sightRange) || config.sightRange < 0)
+        throw new Error("sightRange must be non-negative.");
+    if (!Number.isFinite(config.sightConeDeg) || config.sightConeDeg < 0 || config.sightConeDeg > 360)
+        throw new Error("sightConeDeg must be between 0 and 360.");
+    if (!Number.isFinite(config.hearingRange) || config.hearingRange < 0)
+        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
+ */
+export function createPerception(initial) {
+    validate(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)
+            return;
+        let observerMemories = memories.get(observerId);
+        if (observerMemories === undefined) {
+            observerMemories = new Map();
+            memories.set(observerId, observerMemories);
+        }
+        const previous = observerMemories.get(targetId);
+        if (previous === undefined || at >= previous.lastSeenAt) {
+            observerMemories.set(targetId, { targetId, lastSeenAt: at, lastKnownPos: [...position], confidence });
+        }
+    }
+    function prune() {
+        const memoryMs = config.memorySeconds * 1000;
+        for (const [observerId, observerMemories] of memories) {
+            for (const [targetId, memory] of observerMemories) {
+                if (confidenceAt(memory, nowMs, memoryMs) <= 0)
+                    observerMemories.delete(targetId);
+            }
+            if (observerMemories.size === 0)
+                memories.delete(observerId);
+        }
+        const cutoff = nowMs - memoryMs;
+        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) {
+            if (!Number.isFinite(stimulus.at))
+                throw new Error("stimulus.at must be finite.");
+            if (stimulus.kind === "sound" && stimulus.loudness !== undefined && (!Number.isFinite(stimulus.loudness) || stimulus.loudness < 0)) {
+                throw new Error("stimulus.loudness must be non-negative.");
+            }
+            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();
+        },
+        observe(observer, candidates, observedAt) {
+            if (!Number.isFinite(observedAt))
+                throw new Error("nowMs must be finite.");
+            nowMs = observedAt;
+            for (const candidate of candidates) {
+                if (!inSight(observer, candidate.position, config))
+                    continue;
+                if (config.occluded?.(observer.position, candidate.position))
+                    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.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") {
+                    const audible = config.hearingRange * (stimulus.loudness ?? 1);
+                    if (range >= audible)
+                        continue;
+                    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) {
+            const observerMemories = memories.get(observerId);
+            if (observerMemories === undefined)
+                return [];
+            const memoryMs = config.memorySeconds * 1000;
+            const result = [];
+            for (const memory of observerMemories.values()) {
+                const confidence = confidenceAt(memory, nowMs, memoryMs);
+                if (confidence > 0)
+                    result.push({ ...memory, lastKnownPos: [...memory.lastKnownPos], confidence });
+            }
+            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,
+                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] } });
+            return result;
+        },
+        restore(snapshot) {
+            memories.clear();
+            stimuli.length = 0;
+            nowMs = snapshot.nowMs;
+            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

@@ -0,0 +1,21 @@
+import type { GraphicsQuality } from "./settingsModel.js";
+/** Serializable renderer budget selected by the player's graphics tier. */
+export interface GraphicsProfile {
+    renderScale: number;
+    shadowMapSize: 512 | 1024 | 2048 | 4096;
+    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;
+        dof: boolean;
+        smaa: boolean;
+    };
+}
+/** Conservative defaults that preserve the existing high-quality shell behavior. */
+export declare const DEFAULT_GRAPHICS_PROFILES: Record<GraphicsQuality, GraphicsProfile>;
+/** Resolve one tier and apply game-authored field and post-stage overrides. */
+export declare function resolveGraphicsProfile(quality: GraphicsQuality, overrides?: Partial<GraphicsProfile>): GraphicsProfile;

package/dist/settings/graphicsProfile.js

@@ -0,0 +1,48 @@
+/** Conservative defaults that preserve the existing high-quality shell behavior. */
+export const DEFAULT_GRAPHICS_PROFILES = {
+    low: {
+        renderScale: 1,
+        shadowMapSize: 512,
+        cascades: 1,
+        drawDistance: 120,
+        particleCap: 128,
+        anisotropy: 2,
+        postStages: { ao: false, bloom: true, dof: false, smaa: true },
+    },
+    medium: {
+        renderScale: 1.5,
+        shadowMapSize: 1024,
+        cascades: 2,
+        drawDistance: 240,
+        particleCap: 256,
+        anisotropy: 4,
+        postStages: { ao: true, bloom: true, dof: true, smaa: true },
+    },
+    high: {
+        renderScale: 2,
+        shadowMapSize: 2048,
+        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 },
+    },
+};
+/** Resolve one tier and apply game-authored field and post-stage overrides. */
+export function resolveGraphicsProfile(quality, overrides) {
+    const base = DEFAULT_GRAPHICS_PROFILES[quality];
+    return {
+        ...base,
+        ...overrides,
+        postStages: { ...base.postStages, ...overrides?.postStages },
+    };
+}