@jgengine/core 0.6.0 → 0.8.0

package/dist/scene/spatial.js

@@ -14,11 +14,62 @@ function forwardXZ(aim) {
     }
     return [Math.sin(aim.yaw), Math.cos(aim.yaw)];
 }
+function cellCoord(value, cellSize) {
+    return Math.floor(value / cellSize);
+}
+function gridCellKey(cx, cz) {
+    return `${cx}:${cz}`;
+}
 export function createSpatialApi(options) {
-    const { resolvePosition, candidates, occluder } = options;
+    const { resolvePosition, candidates, occluder, grid } = options;
+    const cellSize = grid?.cellSize;
+    let gridIndex = null;
+    let gridDirty = true;
     function resolveTarget(target) {
         return typeof target === "string" ? resolvePosition(target) : target;
     }
+    function ensureGrid() {
+        if (cellSize === undefined)
+            return null;
+        if (!gridDirty && gridIndex !== null)
+            return gridIndex;
+        const cells = new Map();
+        const indexed = new Set();
+        for (const instanceId of candidates()) {
+            const position = resolvePosition(instanceId);
+            if (position === undefined)
+                continue;
+            indexed.add(instanceId);
+            const key = gridCellKey(cellCoord(position[0], cellSize), cellCoord(position[2], cellSize));
+            let bucket = cells.get(key);
+            if (bucket === undefined) {
+                bucket = [];
+                cells.set(key, bucket);
+            }
+            bucket.push(instanceId);
+        }
+        gridIndex = { cells, indexed };
+        gridDirty = false;
+        return gridIndex;
+    }
+    function inRangeSet(index, centerX, centerZ, radius) {
+        const size = cellSize;
+        const cxMin = cellCoord(centerX - radius, size);
+        const cxMax = cellCoord(centerX + radius, size);
+        const czMin = cellCoord(centerZ - radius, size);
+        const czMax = cellCoord(centerZ + radius, size);
+        const near = new Set();
+        for (let cz = czMin; cz <= czMax; cz += 1) {
+            for (let cx = cxMin; cx <= cxMax; cx += 1) {
+                const bucket = index.cells.get(gridCellKey(cx, cz));
+                if (bucket === undefined)
+                    continue;
+                for (const id of bucket)
+                    near.add(id);
+            }
+        }
+        return near;
+    }
     return {
         distance(aInstanceId, bInstanceId) {
             const a = resolvePosition(aInstanceId);
@@ -32,11 +83,15 @@ export function createSpatialApi(options) {
             const centerPosition = resolveTarget(center);
             if (centerPosition === undefined)
                 return [];
+            const index = ensureGrid();
+            const near = index === null ? null : inRangeSet(index, centerPosition[0], centerPosition[2], radius);
             return candidates().filter((instanceId) => {
                 if (instanceId === centerId)
                     return false;
                 if (filter !== undefined && !filter(instanceId))
                     return false;
+                if (near !== null && index.indexed.has(instanceId) && !near.has(instanceId))
+                    return false;
                 const position = resolvePosition(instanceId);
                 return position !== undefined && distanceBetween(centerPosition, position) <= radius;
             });
@@ -58,9 +113,13 @@ export function createSpatialApi(options) {
             if (forward === null)
                 return [];
             const minDot = Math.cos((halfAngleDeg * Math.PI) / 180);
+            const index = ensureGrid();
+            const near = index === null ? null : inRangeSet(index, origin[0], origin[2], radius);
             return candidates().filter((instanceId) => {
                 if (instanceId === from)
                     return false;
+                if (near !== null && index.indexed.has(instanceId) && !near.has(instanceId))
+                    return false;
                 const position = resolvePosition(instanceId);
                 if (position === undefined)
                     return false;
@@ -75,6 +134,9 @@ export function createSpatialApi(options) {
                 return dot >= minDot;
             });
         },
+        invalidate() {
+            gridDirty = true;
+        },
         moveToward(instanceId, target, { speed, stopDistance = 0, dt }) {
             const current = resolvePosition(instanceId);
             const destination = resolveTarget(target);

package/dist/scene/stationClaim.d.ts

@@ -0,0 +1,43 @@
+import { MountController, type MountKit } from "./mount.js";
+export interface Station {
+    id: string;
+    facet: string;
+    offset: readonly [number, number, number];
+    control?: boolean;
+}
+export interface SharedVehicleConfig {
+    id: string;
+    kit: MountKit;
+    stations: readonly Station[];
+}
+export type ClaimResult = {
+    ok: true;
+    station: Station;
+} | {
+    ok: false;
+    reason: "unknown_vehicle" | "unknown_facet" | "station_taken" | "vehicle_full";
+};
+export declare class StationClaim {
+    private readonly controller;
+    private readonly vehicles;
+    constructor(controller?: MountController);
+    register(config: SharedVehicleConfig): void;
+    private resolveStation;
+    claim(playerId: string, vehicleId: string, facetOrStationId: string): ClaimResult;
+    release(playerId: string): string | null;
+    facetOf(playerId: string): string | null;
+    stationOf(playerId: string): Station | null;
+    controllerOf(vehicleId: string, facet: string): string | null;
+    crew(vehicleId: string): {
+        playerId: string;
+        stationId: string;
+        facet: string;
+    }[];
+    stationsOf(vehicleId: string): readonly Station[];
+    openFacets(vehicleId: string): string[];
+    driver(vehicleId: string): string | null;
+    cameraTarget(playerId: string): string;
+    driveTarget(playerId: string): string | null;
+    get mounts(): MountController;
+}
+export declare function createStationClaim(controller?: MountController): StationClaim;

package/dist/scene/stationClaim.js

@@ -0,0 +1,109 @@
+import { createMountController, MountController } from "./mount.js";
+export class StationClaim {
+    controller;
+    vehicles = new Map();
+    constructor(controller) {
+        this.controller = controller ?? createMountController();
+    }
+    register(config) {
+        const byStationId = new Map();
+        const facetToStation = new Map();
+        for (const station of config.stations) {
+            byStationId.set(station.id, station);
+            if (!facetToStation.has(station.facet))
+                facetToStation.set(station.facet, station.id);
+        }
+        this.vehicles.set(config.id, { config, byStationId, facetToStation });
+        this.controller.register({
+            id: config.id,
+            kit: config.kit,
+            seats: config.stations.map((station) => ({
+                id: station.id,
+                offset: station.offset,
+                control: station.control,
+            })),
+        });
+    }
+    resolveStation(vehicle, facetOrStationId) {
+        const direct = vehicle.byStationId.get(facetOrStationId);
+        if (direct !== undefined)
+            return direct;
+        const stationId = vehicle.facetToStation.get(facetOrStationId);
+        if (stationId === undefined)
+            return null;
+        return vehicle.byStationId.get(stationId) ?? null;
+    }
+    claim(playerId, vehicleId, facetOrStationId) {
+        const vehicle = this.vehicles.get(vehicleId);
+        if (vehicle === undefined)
+            return { ok: false, reason: "unknown_vehicle" };
+        const station = this.resolveStation(vehicle, facetOrStationId);
+        if (station === null)
+            return { ok: false, reason: "unknown_facet" };
+        const result = this.controller.mount(playerId, vehicleId, station.id);
+        if (!result.ok) {
+            return { ok: false, reason: result.reason === "seat_taken" ? "station_taken" : "vehicle_full" };
+        }
+        return { ok: true, station };
+    }
+    release(playerId) {
+        return this.controller.dismount(playerId);
+    }
+    facetOf(playerId) {
+        const ref = this.controller.seatOf(playerId);
+        if (ref === null)
+            return null;
+        return this.vehicles.get(ref.mountId)?.byStationId.get(ref.seatId)?.facet ?? null;
+    }
+    stationOf(playerId) {
+        const ref = this.controller.seatOf(playerId);
+        if (ref === null)
+            return null;
+        return this.vehicles.get(ref.mountId)?.byStationId.get(ref.seatId) ?? null;
+    }
+    controllerOf(vehicleId, facet) {
+        const vehicle = this.vehicles.get(vehicleId);
+        if (vehicle === undefined)
+            return null;
+        for (const occupant of this.controller.occupants(vehicleId)) {
+            if (vehicle.byStationId.get(occupant.seatId)?.facet === facet)
+                return occupant.riderId;
+        }
+        return null;
+    }
+    crew(vehicleId) {
+        const vehicle = this.vehicles.get(vehicleId);
+        if (vehicle === undefined)
+            return [];
+        return this.controller.occupants(vehicleId).map((occupant) => ({
+            playerId: occupant.riderId,
+            stationId: occupant.seatId,
+            facet: vehicle.byStationId.get(occupant.seatId)?.facet ?? "",
+        }));
+    }
+    stationsOf(vehicleId) {
+        return this.vehicles.get(vehicleId)?.config.stations ?? [];
+    }
+    openFacets(vehicleId) {
+        const vehicle = this.vehicles.get(vehicleId);
+        if (vehicle === undefined)
+            return [];
+        const taken = new Set(this.controller.occupants(vehicleId).map((o) => o.seatId));
+        return vehicle.config.stations.filter((s) => !taken.has(s.id)).map((s) => s.facet);
+    }
+    driver(vehicleId) {
+        return this.controller.driver(vehicleId);
+    }
+    cameraTarget(playerId) {
+        return this.controller.cameraTarget(playerId);
+    }
+    driveTarget(playerId) {
+        return this.controller.driveTarget(playerId);
+    }
+    get mounts() {
+        return this.controller;
+    }
+}
+export function createStationClaim(controller) {
+    return new StationClaim(controller);
+}

package/dist/sensor/concealment.d.ts

@@ -0,0 +1,21 @@
+export type ColorHex = string;
+export declare function colorDistance(a: ColorHex, b: ColorHex): number;
+export declare function concealmentScore(entityColors: readonly ColorHex[], backgroundColors: readonly ColorHex[]): number;
+export interface ConcealmentTarget {
+    id: string;
+    entityColors: readonly ColorHex[];
+    backgroundColors: readonly ColorHex[];
+}
+export interface ConcealmentSample {
+    id: string;
+    score: number;
+    concealed: boolean;
+    dwellSeconds: number;
+}
+export interface ConcealmentSensor {
+    tick(targets: readonly ConcealmentTarget[], dt: number): ConcealmentSample[];
+    reset(id?: string): void;
+}
+export declare function createConcealmentSensor(config?: {
+    threshold?: number;
+}): ConcealmentSensor;

package/dist/sensor/concealment.js

@@ -0,0 +1,63 @@
+function parseHex(hex) {
+    const match = /^#?([0-9a-fA-F]{6})$/.exec(hex.trim());
+    if (match === null)
+        return [0, 0, 0];
+    const value = parseInt(match[1], 16);
+    return [(value >> 16) & 0xff, (value >> 8) & 0xff, value & 0xff];
+}
+function redmean(a, b) {
+    const rmean = (a[0] + b[0]) / 2;
+    const dr = a[0] - b[0];
+    const dg = a[1] - b[1];
+    const db = a[2] - b[2];
+    return Math.sqrt((2 + rmean / 256) * dr * dr + 4 * dg * dg + (2 + (255 - rmean) / 256) * db * db);
+}
+const REDMEAN_MAX = redmean([0, 0, 0], [255, 255, 255]);
+export function colorDistance(a, b) {
+    const distance = redmean(parseHex(a), parseHex(b));
+    return REDMEAN_MAX === 0 ? 0 : Math.min(1, distance / REDMEAN_MAX);
+}
+export function concealmentScore(entityColors, backgroundColors) {
+    if (entityColors.length === 0 || backgroundColors.length === 0)
+        return 0;
+    let total = 0;
+    for (const entityColor of entityColors) {
+        let nearest = Number.POSITIVE_INFINITY;
+        for (const backgroundColor of backgroundColors) {
+            const distance = colorDistance(entityColor, backgroundColor);
+            if (distance < nearest)
+                nearest = distance;
+        }
+        total += nearest;
+    }
+    return 1 - total / entityColors.length;
+}
+export function createConcealmentSensor(config) {
+    const threshold = config?.threshold ?? 0.7;
+    const dwell = new Map();
+    return {
+        tick(targets, dt) {
+            const seen = new Set();
+            const samples = [];
+            for (const target of targets) {
+                seen.add(target.id);
+                const score = concealmentScore(target.entityColors, target.backgroundColors);
+                const concealed = score >= threshold;
+                const nextDwell = concealed ? (dwell.get(target.id) ?? 0) + dt : 0;
+                dwell.set(target.id, nextDwell);
+                samples.push({ id: target.id, score, concealed, dwellSeconds: nextDwell });
+            }
+            for (const id of dwell.keys()) {
+                if (!seen.has(id))
+                    dwell.delete(id);
+            }
+            return samples;
+        },
+        reset(id) {
+            if (id === undefined)
+                dwell.clear();
+            else
+                dwell.delete(id);
+        },
+    };
+}

package/dist/sensor/freezeMonitor.d.ts

@@ -0,0 +1,17 @@
+export interface FreezeSubject {
+    id: string;
+    groundSpeed: number;
+}
+export interface FreezeViolation {
+    id: string;
+    speed: number;
+    movedSeconds: number;
+}
+export interface FreezeMonitor {
+    tick(subjects: readonly FreezeSubject[], frozenIds: ReadonlySet<string>, dt: number): FreezeViolation[];
+    reset(id?: string): void;
+}
+export declare function createFreezeMonitor(config?: {
+    toleranceSpeed?: number;
+    graceSeconds?: number;
+}): FreezeMonitor;

package/dist/sensor/freezeMonitor.js

@@ -0,0 +1,35 @@
+export function createFreezeMonitor(config) {
+    const toleranceSpeed = config?.toleranceSpeed ?? 0.05;
+    const graceSeconds = config?.graceSeconds ?? 0;
+    const moved = new Map();
+    return {
+        tick(subjects, frozenIds, dt) {
+            const seen = new Set();
+            const violations = [];
+            for (const subject of subjects) {
+                seen.add(subject.id);
+                const shouldHoldStill = frozenIds.has(subject.id) && subject.groundSpeed > toleranceSpeed;
+                if (!shouldHoldStill) {
+                    moved.delete(subject.id);
+                    continue;
+                }
+                const movedSeconds = (moved.get(subject.id) ?? 0) + dt;
+                moved.set(subject.id, movedSeconds);
+                if (movedSeconds > graceSeconds) {
+                    violations.push({ id: subject.id, speed: subject.groundSpeed, movedSeconds });
+                }
+            }
+            for (const id of moved.keys()) {
+                if (!seen.has(id))
+                    moved.delete(id);
+            }
+            return violations;
+        },
+        reset(id) {
+            if (id === undefined)
+                moved.clear();
+            else
+                moved.delete(id);
+        },
+    };
+}

package/dist/sensor/frustumSensor.d.ts

@@ -0,0 +1,60 @@
+import type { EntityPosition } from "../scene/entityStore.js";
+export interface FrustumCamera {
+    position: EntityPosition;
+    lookAt: EntityPosition;
+    /** Vertical field of view in degrees. Default 55. */
+    fovDeg?: number;
+    /** Width / height. Default 16 / 9. */
+    aspect?: number;
+    near?: number;
+    far?: number;
+}
+export interface FrustumTarget {
+    id: string;
+    position: EntityPosition;
+    /** Subject radius in world units, used by the framing-size score. Default 0.5. */
+    radius?: number;
+}
+export interface FrustumProjection {
+    inView: boolean;
+    distance: number;
+    /** -1..1, 0 = screen center, negative = left/down. */
+    screenX: number;
+    screenY: number;
+}
+/**
+ * Project a world point into the camera's view. Pure geometry — no three.js —
+ * so a game can run "is this framed?" checks headlessly (photo-mode scoring,
+ * server-side kill-cam validation) as well as from the live render camera.
+ */
+export declare function projectToView(camera: FrustumCamera, point: EntityPosition): FrustumProjection;
+export interface FramingConfig {
+    /** World-unit distance from camera that reads as "ideally framed" size. Default 6. */
+    idealDistance?: number;
+    /** Weight of screen-center placement in the framing score. Default 0.6. */
+    centerWeight?: number;
+    /** Weight of subject size (distance-to-ideal) in the framing score. Default 0.4. */
+    sizeWeight?: number;
+}
+/** 0 (not framed) .. 1 (dead-center, ideal distance) framing quality for an in-view projection. */
+export declare function framingScore(projection: FrustumProjection, config?: FramingConfig): number;
+export interface FrustumSample {
+    id: string;
+    inView: boolean;
+    distance: number;
+    screenX: number;
+    screenY: number;
+    framing: number;
+    /** Seconds continuously in view, up to and including this tick; resets to 0 the instant the subject leaves view. */
+    dwellSeconds: number;
+}
+export interface FrustumSensor {
+    tick(camera: FrustumCamera, targets: readonly FrustumTarget[], dt: number): FrustumSample[];
+    reset(id?: string): void;
+}
+/**
+ * A view-frustum sensor on a held camera object: which entities are in frame,
+ * how well framed they are, and how long they've stayed on-screen (photo-mode
+ * "is this subject framed", Content Warning-style monster-filming scoring).
+ */
+export declare function createFrustumSensor(config?: FramingConfig): FrustumSensor;

package/dist/sensor/frustumSensor.js

@@ -0,0 +1,104 @@
+function subtract(a, b) {
+    return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+function length(v) {
+    return Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
+}
+function normalize(v) {
+    const len = length(v);
+    return len === 0 ? [0, 0, 0] : [v[0] / len, v[1] / len, v[2] / len];
+}
+function cross(a, b) {
+    return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}
+function dot(a, b) {
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+const WORLD_UP = [0, 1, 0];
+/**
+ * Project a world point into the camera's view. Pure geometry — no three.js —
+ * so a game can run "is this framed?" checks headlessly (photo-mode scoring,
+ * server-side kill-cam validation) as well as from the live render camera.
+ */
+export function projectToView(camera, point) {
+    const forward = normalize(subtract(camera.lookAt, camera.position));
+    const relative = subtract(point, camera.position);
+    const distance = length(relative);
+    const depth = dot(relative, forward);
+    const near = camera.near ?? 0.1;
+    const far = camera.far ?? Number.POSITIVE_INFINITY;
+    if (forward[0] === 0 && forward[1] === 0 && forward[2] === 0) {
+        return { inView: false, distance, screenX: 0, screenY: 0 };
+    }
+    if (depth <= near || depth >= far) {
+        return { inView: false, distance, screenX: 0, screenY: 0 };
+    }
+    let right = normalize(cross(forward, WORLD_UP));
+    if (right[0] === 0 && right[1] === 0 && right[2] === 0) {
+        right = normalize(cross(forward, [1, 0, 0]));
+    }
+    const up = cross(right, forward);
+    const fovDeg = camera.fovDeg ?? 55;
+    const aspect = camera.aspect ?? 16 / 9;
+    const halfHeight = Math.tan((fovDeg * Math.PI) / 360);
+    const halfWidth = halfHeight * aspect;
+    const screenX = dot(relative, right) / (depth * halfWidth);
+    const screenY = dot(relative, up) / (depth * halfHeight);
+    const inView = Math.abs(screenX) <= 1 && Math.abs(screenY) <= 1;
+    return { inView, distance, screenX, screenY };
+}
+/** 0 (not framed) .. 1 (dead-center, ideal distance) framing quality for an in-view projection. */
+export function framingScore(projection, config) {
+    if (!projection.inView)
+        return 0;
+    const idealDistance = config?.idealDistance ?? 6;
+    const centerWeight = config?.centerWeight ?? 0.6;
+    const sizeWeight = config?.sizeWeight ?? 0.4;
+    const radial = Math.min(1, Math.sqrt(projection.screenX * projection.screenX + projection.screenY * projection.screenY));
+    const centerScore = 1 - radial;
+    const sizeScore = idealDistance <= 0
+        ? 0
+        : Math.max(0, 1 - Math.abs(projection.distance - idealDistance) / idealDistance);
+    return Math.max(0, Math.min(1, centerWeight * centerScore + sizeWeight * sizeScore));
+}
+/**
+ * A view-frustum sensor on a held camera object: which entities are in frame,
+ * how well framed they are, and how long they've stayed on-screen (photo-mode
+ * "is this subject framed", Content Warning-style monster-filming scoring).
+ */
+export function createFrustumSensor(config) {
+    const dwell = new Map();
+    return {
+        tick(camera, targets, dt) {
+            const seen = new Set();
+            const samples = [];
+            for (const target of targets) {
+                seen.add(target.id);
+                const projection = projectToView(camera, target.position);
+                const framing = framingScore(projection, config);
+                const nextDwell = projection.inView ? (dwell.get(target.id) ?? 0) + dt : 0;
+                dwell.set(target.id, nextDwell);
+                samples.push({
+                    id: target.id,
+                    inView: projection.inView,
+                    distance: projection.distance,
+                    screenX: projection.screenX,
+                    screenY: projection.screenY,
+                    framing,
+                    dwellSeconds: nextDwell,
+                });
+            }
+            for (const id of dwell.keys()) {
+                if (!seen.has(id))
+                    dwell.delete(id);
+            }
+            return samples;
+        },
+        reset(id) {
+            if (id === undefined)
+                dwell.clear();
+            else
+                dwell.delete(id);
+        },
+    };
+}

package/dist/sensor/hiddenStateProbe.d.ts

@@ -0,0 +1,31 @@
+import type { EntityPosition } from "../scene/entityStore.js";
+export type HiddenStateValue = number | string | boolean;
+export interface HiddenStateSource {
+    id: string;
+    position: EntityPosition;
+    variables: Readonly<Record<string, HiddenStateValue>>;
+}
+export interface SensorProbeOptions {
+    range: number;
+    variableId: string;
+    /** How reading `strength` falls off with distance. Default "linear". */
+    falloff?: "linear" | "none";
+}
+export interface SensorReading {
+    sourceId: string;
+    variableId: string;
+    value: HiddenStateValue;
+    /** 1 at the source, 0 at the edge of `range` ("none" falloff always reads 1 in range). */
+    strength: number;
+    distance: number;
+}
+/**
+ * A sensor verb: probe a hidden zone/entity state variable in range and surface
+ * a reading (EMF reader, spirit box, thermometer, geiger counter). Unlike
+ * `proximityPrompt` (a UI affordance), this reads world state the player has no
+ * other way to see — the strongest in-range reading wins, mirroring how a real
+ * handheld sensor needle settles on the loudest nearby source.
+ */
+export declare function probeHiddenState(origin: EntityPosition, sources: readonly HiddenStateSource[], options: SensorProbeOptions): SensorReading | null;
+/** All in-range readings for `variableId`, strongest first. */
+export declare function probeHiddenStateAll(origin: EntityPosition, sources: readonly HiddenStateSource[], options: SensorProbeOptions): SensorReading[];

package/dist/sensor/hiddenStateProbe.js

@@ -0,0 +1,40 @@
+import { distanceBetween } from "../scene/spatial.js";
+function strengthAt(distance, range, falloff) {
+    if (falloff === "none")
+        return 1;
+    if (range <= 0)
+        return 0;
+    return Math.max(0, 1 - distance / range);
+}
+/**
+ * A sensor verb: probe a hidden zone/entity state variable in range and surface
+ * a reading (EMF reader, spirit box, thermometer, geiger counter). Unlike
+ * `proximityPrompt` (a UI affordance), this reads world state the player has no
+ * other way to see — the strongest in-range reading wins, mirroring how a real
+ * handheld sensor needle settles on the loudest nearby source.
+ */
+export function probeHiddenState(origin, sources, options) {
+    const readings = probeHiddenStateAll(origin, sources, options);
+    return readings.length === 0 ? null : readings[0];
+}
+/** All in-range readings for `variableId`, strongest first. */
+export function probeHiddenStateAll(origin, sources, options) {
+    const { range, variableId, falloff = "linear" } = options;
+    const readings = [];
+    for (const source of sources) {
+        if (!(variableId in source.variables))
+            continue;
+        const distance = distanceBetween(origin, source.position);
+        if (distance > range)
+            continue;
+        readings.push({
+            sourceId: source.id,
+            variableId,
+            value: source.variables[variableId],
+            strength: strengthAt(distance, range, falloff),
+            distance,
+        });
+    }
+    readings.sort((a, b) => b.strength - a.strength);
+    return readings;
+}

package/dist/sensor/recordingBuffer.d.ts

@@ -0,0 +1,29 @@
+export interface RecordingFrame<T> {
+    /** Game-time seconds (from `ctx.time`), so pause/fast-forward scrub the recording consistently with the sim. */
+    t: number;
+    data: T;
+}
+export interface RecordingBufferOptions {
+    /** Evict frames older than `latestT - maxDurationSeconds`. Default unlimited. */
+    maxDurationSeconds?: number;
+    /** Hard cap on frame count, oldest evicted first. Default unlimited. */
+    maxFrames?: number;
+}
+export interface RecordingBuffer<T> {
+    append(t: number, data: T): void;
+    /** Nearest frame at or before `t`, or null if the buffer is empty or `t` precedes every frame. */
+    seek(t: number): RecordingFrame<T> | null;
+    /** Frames with `fromT <= t <= toT`, in recorded order. */
+    range(fromT: number, toT: number): RecordingFrame<T>[];
+    clear(): void;
+    duration(): number;
+    frames(): readonly RecordingFrame<T>[];
+}
+/**
+ * A session-recording buffer for replay / photo mode / kill-cam: append
+ * timestamped snapshots (poses, camera state, whatever `T` is) on game-time,
+ * then seek/scrub the recording independent of the live sim. Frames are
+ * expected in non-decreasing `t` order (one push per tick); `seek`/`range`
+ * binary-search on that assumption.
+ */
+export declare function createRecordingBuffer<T>(options?: RecordingBufferOptions): RecordingBuffer<T>;