@jgengine/core 0.6.0 → 0.7.0

package/dist/world/carve.js

@@ -0,0 +1,175 @@
+import { withNormal } from "./terrain.js";
+export const EMPTY_VOXEL = 0;
+/**
+ * A runtime-editable dense voxel grid — the carve/deposit op behind destructible dig worlds (Deep
+ * Rock Galactic tunnels, Astroneer terrain). Cells hold a material id (0 = empty); `carve` clears a
+ * sphere of solid cells that a tool is strong enough to break and returns how many it removed (feed
+ * that to a loot roll), `deposit` fills a sphere with a material. World↔cell mapping is `origin`+`scale`.
+ */
+export class VoxelVolume {
+    nx;
+    ny;
+    nz;
+    scale;
+    origin;
+    cells;
+    materials;
+    solidCount = 0;
+    constructor(config) {
+        this.nx = Math.max(1, Math.floor(config.dims[0]));
+        this.ny = Math.max(1, Math.floor(config.dims[1]));
+        this.nz = Math.max(1, Math.floor(config.dims[2]));
+        this.scale = config.scale ?? 1;
+        this.origin = config.origin ?? [0, 0, 0];
+        this.materials = config.materials ?? {};
+        this.cells = new Uint16Array(this.nx * this.ny * this.nz);
+        const fill = config.fill ?? 1;
+        if (fill !== EMPTY_VOXEL) {
+            this.cells.fill(fill);
+            this.solidCount = this.cells.length;
+        }
+    }
+    get solid() {
+        return this.solidCount;
+    }
+    index(ix, iy, iz) {
+        return (iz * this.ny + iy) * this.nx + ix;
+    }
+    inBounds(ix, iy, iz) {
+        return ix >= 0 && ix < this.nx && iy >= 0 && iy < this.ny && iz >= 0 && iz < this.nz;
+    }
+    get(ix, iy, iz) {
+        if (!this.inBounds(ix, iy, iz))
+            return EMPTY_VOXEL;
+        return this.cells[this.index(ix, iy, iz)];
+    }
+    set(ix, iy, iz, material) {
+        if (!this.inBounds(ix, iy, iz))
+            return;
+        const at = this.index(ix, iy, iz);
+        const prev = this.cells[at];
+        if (prev === material)
+            return;
+        if (prev === EMPTY_VOXEL)
+            this.solidCount += 1;
+        else if (material === EMPTY_VOXEL)
+            this.solidCount -= 1;
+        this.cells[at] = material;
+    }
+    worldToCell(x, y, z) {
+        return [
+            Math.floor((x - this.origin[0]) / this.scale),
+            Math.floor((y - this.origin[1]) / this.scale),
+            Math.floor((z - this.origin[2]) / this.scale),
+        ];
+    }
+    solidAtWorld(x, y, z) {
+        const [ix, iy, iz] = this.worldToCell(x, y, z);
+        return this.get(ix, iy, iz) !== EMPTY_VOXEL;
+    }
+    strengthOf(material) {
+        return this.materials[material]?.strength ?? 0;
+    }
+    forEachCellInSphere(center, radius, visit) {
+        const s = this.scale;
+        const [cx, cy, cz] = this.worldToCell(center[0], center[1], center[2]);
+        const reach = Math.ceil(radius / s) + 1;
+        const r2 = radius * radius;
+        for (let iz = cz - reach; iz <= cz + reach; iz += 1) {
+            for (let iy = cy - reach; iy <= cy + reach; iy += 1) {
+                for (let ix = cx - reach; ix <= cx + reach; ix += 1) {
+                    if (!this.inBounds(ix, iy, iz))
+                        continue;
+                    const wx = this.origin[0] + (ix + 0.5) * s;
+                    const wy = this.origin[1] + (iy + 0.5) * s;
+                    const wz = this.origin[2] + (iz + 0.5) * s;
+                    const dx = wx - center[0];
+                    const dy = wy - center[1];
+                    const dz = wz - center[2];
+                    if (dx * dx + dy * dy + dz * dz <= r2)
+                        visit(ix, iy, iz);
+                }
+            }
+        }
+    }
+    /** Clear every solid cell in the sphere the tool can break; returns the number removed. */
+    carve(op) {
+        const tool = op.toolStrength ?? Number.POSITIVE_INFINITY;
+        let removed = 0;
+        this.forEachCellInSphere(op.center, op.radius, (ix, iy, iz) => {
+            const m = this.get(ix, iy, iz);
+            if (m === EMPTY_VOXEL)
+                return;
+            if (this.strengthOf(m) > tool)
+                return;
+            this.set(ix, iy, iz, EMPTY_VOXEL);
+            removed += 1;
+        });
+        return removed;
+    }
+    /** Fill every empty cell in the sphere with `material`; returns the number filled. */
+    deposit(op) {
+        let filled = 0;
+        this.forEachCellInSphere(op.center, op.radius, (ix, iy, iz) => {
+            if (this.get(ix, iy, iz) !== EMPTY_VOXEL)
+                return;
+            this.set(ix, iy, iz, op.material);
+            filled += 1;
+        });
+        return filled;
+    }
+}
+function bowl(t) {
+    const s = t * t * (3 - 2 * t);
+    return s;
+}
+/**
+ * A `TerrainField` you can write craters and mounds into at runtime — the height-field side of
+ * destructible terrain (Helldivers 2 explosion craters, engineer-deposited berms). Wraps a base field
+ * and layers smooth radial deformations on top, so `sampleHeight` (and therefore ground-snap,
+ * collision, and the shell's terrain mesh) all read the deformed surface. `carve` digs a bowl,
+ * `deposit` raises a mound.
+ */
+export class CarvableField {
+    bounds;
+    waterLevel;
+    sampleNormal;
+    base;
+    edits = [];
+    constructor(base) {
+        this.base = base;
+        if (base.bounds !== undefined)
+            this.bounds = base.bounds;
+        if (base.waterLevel !== undefined)
+            this.waterLevel = base.waterLevel;
+        this.sampleNormal = withNormal((x, z) => this.sampleHeight(x, z));
+    }
+    get editCount() {
+        return this.edits.length;
+    }
+    sampleHeight(x, z) {
+        let h = this.base.sampleHeight(x, z);
+        for (let i = 0; i < this.edits.length; i += 1) {
+            const e = this.edits[i];
+            const dx = x - e.x;
+            const dz = z - e.z;
+            const d = Math.sqrt(dx * dx + dz * dz);
+            if (d >= e.radius)
+                continue;
+            h += e.delta * bowl(1 - d / e.radius);
+        }
+        return h;
+    }
+    carve(op) {
+        this.edits.push({ x: op.x, z: op.z, radius: op.radius, delta: -op.depth });
+    }
+    deposit(op) {
+        this.edits.push({ x: op.x, z: op.z, radius: op.radius, delta: op.height });
+    }
+    clear() {
+        this.edits.length = 0;
+    }
+}
+export function carvableTerrain(base) {
+    return new CarvableField(base);
+}

package/dist/world/connectors.d.ts

@@ -0,0 +1,40 @@
+export type ConnectorVec3 = readonly [number, number, number];
+export interface ConnectorSocket {
+    id: string;
+    type: string;
+    offset: ConnectorVec3;
+    accepts?: readonly string[];
+}
+export interface ConnectorPieceDef {
+    kind: string;
+    sockets: readonly ConnectorSocket[];
+}
+export interface PlacedPiece {
+    id: string;
+    kind: string;
+    position: ConnectorVec3;
+    rotationY: number;
+}
+export interface WorldSocket {
+    pieceId: string;
+    socket: ConnectorSocket;
+    position: ConnectorVec3;
+}
+export interface SnapResult {
+    socketId: string;
+    targetPieceId: string;
+    targetSocketId: string;
+    position: ConnectorVec3;
+    rotationY: number;
+    distance: number;
+}
+export interface SnapOptions {
+    snapDistance?: number;
+    rotationY?: number;
+}
+export declare function socketsCompatible(a: ConnectorSocket, b: ConnectorSocket): boolean;
+export declare function socketWorldPosition(socket: ConnectorSocket, origin: ConnectorVec3, rotationY: number): ConnectorVec3;
+export declare function worldSockets(def: ConnectorPieceDef, piece: PlacedPiece): WorldSocket[];
+export type ConnectorRegistry = (kind: string) => ConnectorPieceDef | null;
+export declare function collectWorldSockets(registry: ConnectorRegistry, pieces: readonly PlacedPiece[]): WorldSocket[];
+export declare function snapToNearest(registry: ConnectorRegistry, placed: readonly PlacedPiece[], movingDef: ConnectorPieceDef, cursor: ConnectorVec3, options?: SnapOptions): SnapResult | null;

package/dist/world/connectors.js

@@ -0,0 +1,67 @@
+export function socketsCompatible(a, b) {
+    const aAccepts = a.accepts ?? [a.type];
+    const bAccepts = b.accepts ?? [b.type];
+    return aAccepts.includes(b.type) && bAccepts.includes(a.type);
+}
+function rotateY(offset, rotationY) {
+    if (rotationY === 0)
+        return offset;
+    const cos = Math.cos(rotationY);
+    const sin = Math.sin(rotationY);
+    return [offset[0] * cos + offset[2] * sin, offset[1], -offset[0] * sin + offset[2] * cos];
+}
+export function socketWorldPosition(socket, origin, rotationY) {
+    const rotated = rotateY(socket.offset, rotationY);
+    return [origin[0] + rotated[0], origin[1] + rotated[1], origin[2] + rotated[2]];
+}
+export function worldSockets(def, piece) {
+    return def.sockets.map((socket) => ({
+        pieceId: piece.id,
+        socket,
+        position: socketWorldPosition(socket, piece.position, piece.rotationY),
+    }));
+}
+export function collectWorldSockets(registry, pieces) {
+    const out = [];
+    for (const piece of pieces) {
+        const def = registry(piece.kind);
+        if (def === null)
+            continue;
+        for (const world of worldSockets(def, piece))
+            out.push(world);
+    }
+    return out;
+}
+export function snapToNearest(registry, placed, movingDef, cursor, options = {}) {
+    const snapDistance = options.snapDistance ?? 1.5;
+    const rotationY = options.rotationY ?? 0;
+    const targets = collectWorldSockets(registry, placed);
+    let best = null;
+    for (const socket of movingDef.sockets) {
+        const socketWorld = socketWorldPosition(socket, cursor, rotationY);
+        for (const target of targets) {
+            if (!socketsCompatible(socket, target.socket))
+                continue;
+            const distance = Math.hypot(socketWorld[0] - target.position[0], socketWorld[1] - target.position[1], socketWorld[2] - target.position[2]);
+            if (distance > snapDistance)
+                continue;
+            if (best !== null && distance >= best.distance)
+                continue;
+            const localRotated = rotateY(socket.offset, rotationY);
+            const position = [
+                target.position[0] - localRotated[0],
+                target.position[1] - localRotated[1],
+                target.position[2] - localRotated[2],
+            ];
+            best = {
+                socketId: socket.id,
+                targetPieceId: target.pieceId,
+                targetSocketId: target.socket.id,
+                position,
+                rotationY,
+                distance,
+            };
+        }
+    }
+    return best;
+}

package/dist/world/envField.d.ts

@@ -0,0 +1,71 @@
+import type { TerrainField } from "./terrain.js";
+/** A sky-occluding footprint — a roof, dense canopy, a cave mouth. `shade` 0..1 = fraction of sky blocked. */
+export interface OccluderRect {
+    x: number;
+    z: number;
+    w: number;
+    d: number;
+    shade?: number;
+}
+/** A localized warmth source — campfire, forge, geothermal vent. */
+export interface HeatSource {
+    x: number;
+    z: number;
+    radius: number;
+    /** Degrees added at the center, falling to 0 at `radius`. */
+    strength: number;
+}
+export type ShadeProvider = readonly OccluderRect[] | ((x: number, z: number) => number);
+export type ScalarField = number | ((x: number, z: number, time: number) => number);
+export interface EnvironmentFieldConfig {
+    /** Game-seconds per day; drives the sun-elevation cycle. Default matches the sim clock day. */
+    dayLength?: number;
+    /** Temperature at sea level under a noon sun with no weather. Default 20. */
+    baseTemperature?: number;
+    /** Degrees colder at deep night vs noon. Default 12. */
+    nightDrop?: number;
+    /** Degrees lost per world-height unit above `seaLevel` (altitude lapse). Default 0. */
+    altitudeLapse?: number;
+    seaLevel?: number;
+    /** Terrain field used to look up ground altitude when a caller omits `y`. */
+    terrain?: TerrainField;
+    /** Rain/precipitation intensity 0..1 at a position — from a weather state. Default 0. */
+    rain?: ScalarField;
+    /** Sky occluders (structures, canopy) that block sun and shelter from rain. */
+    occluders?: ShadeProvider;
+    /** Campfires and other warmth emitters. */
+    heatSources?: readonly HeatSource[];
+    /** Minimum ambient light at night (moonlight floor), 0..1. Default 0.05. */
+    ambientFloor?: number;
+    /** Per-position base-temperature offset (biome map). Added to `baseTemperature`. */
+    temperatureAt?: (x: number, z: number) => number;
+}
+export interface EnvironmentSample {
+    /** Degrees (game units). */
+    temperature: number;
+    /** 0..1 surface wetness. */
+    wetness: number;
+    /** 0..1 direct sun/sky exposure — full sun open sky = 1, deep shade/night = 0. */
+    lightExposure: number;
+    /** 0..1 overall light level for spawn gating — includes ambient/moonlight. */
+    ambientLight: number;
+    /** Under an occluder (roof/canopy) enough to shelter from rain. */
+    sheltered: boolean;
+}
+export interface EnvironmentField {
+    sample(x: number, z: number, time: number, y?: number): EnvironmentSample;
+    temperature(x: number, z: number, time: number, y?: number): number;
+    wetness(x: number, z: number, time: number): number;
+    lightExposure(x: number, z: number, time: number): number;
+    ambientLight(x: number, z: number, time: number): number;
+    /** Sun elevation -1..1 (1 = noon overhead, 0 = horizon, negative = night). */
+    sunElevation(time: number): number;
+}
+/**
+ * A sampleable environment field: read temperature, wetness, sun/sky exposure, and
+ * ambient light at any world position and time. Built on the same renderer-free footing
+ * as terrain/wind/water so meters, spawn gating, and damage-in-sunlight read the world
+ * the shell renders — no three.js. Instantaneous and pure (no accumulation); stateful
+ * build-up belongs to a decay meter reading this field.
+ */
+export declare function createEnvironmentField(config?: EnvironmentFieldConfig): EnvironmentField;

package/dist/world/envField.js

@@ -0,0 +1,96 @@
+import { SECONDS_PER_GAME_DAY } from "../time/gameClock.js";
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function resolveScalar(field, x, z, time) {
+    return typeof field === "function" ? field(x, z, time) : field;
+}
+function pointInRect(rect, x, z) {
+    return (x >= rect.x - rect.w / 2 &&
+        x <= rect.x + rect.w / 2 &&
+        z >= rect.z - rect.d / 2 &&
+        z <= rect.z + rect.d / 2);
+}
+function resolveShade(provider, x, z) {
+    if (provider === undefined)
+        return 0;
+    if (typeof provider === "function")
+        return clamp01(provider(x, z));
+    let shade = 0;
+    for (const rect of provider) {
+        if (pointInRect(rect, x, z))
+            shade = Math.max(shade, rect.shade ?? 1);
+    }
+    return shade;
+}
+/**
+ * A sampleable environment field: read temperature, wetness, sun/sky exposure, and
+ * ambient light at any world position and time. Built on the same renderer-free footing
+ * as terrain/wind/water so meters, spawn gating, and damage-in-sunlight read the world
+ * the shell renders — no three.js. Instantaneous and pure (no accumulation); stateful
+ * build-up belongs to a decay meter reading this field.
+ */
+export function createEnvironmentField(config = {}) {
+    const dayLength = config.dayLength !== undefined && config.dayLength > 0 ? config.dayLength : SECONDS_PER_GAME_DAY;
+    const baseTemperature = config.baseTemperature ?? 20;
+    const nightDrop = config.nightDrop ?? 12;
+    const altitudeLapse = config.altitudeLapse ?? 0;
+    const seaLevel = config.seaLevel ?? 0;
+    const ambientFloor = clamp01(config.ambientFloor ?? 0.05);
+    const heatSources = config.heatSources ?? [];
+    const sunElevation = (time) => {
+        const dayFraction = ((time % dayLength) + dayLength) % dayLength / dayLength;
+        return Math.sin((dayFraction - 0.25) * 2 * Math.PI);
+    };
+    const heatAt = (x, z) => {
+        let heat = 0;
+        for (const source of heatSources) {
+            const distance = Math.hypot(x - source.x, z - source.z);
+            if (distance >= source.radius)
+                continue;
+            heat += source.strength * (1 - distance / source.radius);
+        }
+        return heat;
+    };
+    const rainAt = (x, z, time) => config.rain === undefined ? 0 : clamp01(resolveScalar(config.rain, x, z, time));
+    const wetness = (x, z, time) => {
+        const shade = resolveShade(config.occluders, x, z);
+        return clamp01(rainAt(x, z, time) * (1 - shade));
+    };
+    const lightExposure = (x, z, time) => {
+        const shade = resolveShade(config.occluders, x, z);
+        const daylight = Math.max(0, sunElevation(time));
+        const cloud = 1 - rainAt(x, z, time) * 0.6;
+        return clamp01(daylight * cloud * (1 - shade));
+    };
+    const ambientLight = (x, z, time) => {
+        const shade = resolveShade(config.occluders, x, z);
+        const daylight = clamp01(sunElevation(time) * 0.5 + 0.5);
+        const sky = ambientFloor + (1 - ambientFloor) * daylight;
+        return clamp01(sky * (1 - shade * 0.75));
+    };
+    const temperature = (x, z, time, y) => {
+        const altitude = y ?? config.terrain?.sampleHeight(x, z) ?? seaLevel;
+        const daylight = clamp01(sunElevation(time) * 0.5 + 0.5);
+        const base = baseTemperature + (config.temperatureAt?.(x, z) ?? 0);
+        const lapse = altitudeLapse * Math.max(0, altitude - seaLevel);
+        const wetChill = wetness(x, z, time) * 4;
+        return base - nightDrop * (1 - daylight) - lapse - wetChill + heatAt(x, z);
+    };
+    return {
+        sample(x, z, time, y) {
+            return {
+                temperature: temperature(x, z, time, y),
+                wetness: wetness(x, z, time),
+                lightExposure: lightExposure(x, z, time),
+                ambientLight: ambientLight(x, z, time),
+                sheltered: resolveShade(config.occluders, x, z) >= 0.5,
+            };
+        },
+        temperature,
+        wetness,
+        lightExposure,
+        ambientLight,
+        sunElevation,
+    };
+}

package/dist/world/fog.d.ts

@@ -0,0 +1,40 @@
+export interface FogBounds {
+    minX: number;
+    minZ: number;
+    maxX: number;
+    maxZ: number;
+}
+export interface FogConfig {
+    bounds: FogBounds;
+    cellSize: number;
+    /** Cells revealed on construction (start-of-run known area). */
+    revealed?: readonly number[];
+}
+export interface FogCells {
+    cols: number;
+    rows: number;
+    minX: number;
+    minZ: number;
+    cellSize: number;
+    /** Row-major flags; index = row * cols + col. */
+    revealed: readonly boolean[];
+    revealedCount: number;
+}
+/**
+ * Reveal-on-event fog of war over a fixed grid. Walking (`revealAlong`) and
+ * digging/acting (`reveal`) clear cells; once revealed a cell stays revealed.
+ * Pure and renderer-free — the shell/react map draws `cells()`.
+ */
+export interface FogField {
+    reveal(x: number, z: number, radius?: number): number;
+    revealAlong(from: readonly [number, number], to: readonly [number, number], radius?: number): number;
+    isRevealed(x: number, z: number): boolean;
+    isRevealedCell(col: number, row: number): boolean;
+    revealedCount(): number;
+    cellCount(): number;
+    fraction(): number;
+    cells(): FogCells;
+    reset(): void;
+    subscribe(listener: () => void): () => void;
+}
+export declare function createFogField(config: FogConfig): FogField;

package/dist/world/fog.js

@@ -0,0 +1,137 @@
+function clampInt(value, min, max) {
+    const rounded = Math.floor(value);
+    return rounded < min ? min : rounded > max ? max : rounded;
+}
+export function createFogField(config) {
+    const { minX, minZ, maxX, maxZ } = config.bounds;
+    const cellSize = config.cellSize;
+    if (cellSize <= 0)
+        throw new Error("createFogField: cellSize must be positive");
+    const cols = Math.max(1, Math.ceil((maxX - minX) / cellSize));
+    const rows = Math.max(1, Math.ceil((maxZ - minZ) / cellSize));
+    const total = cols * rows;
+    const revealed = new Array(total).fill(false);
+    let revealedCount = 0;
+    const listeners = new Set();
+    let snapshotCache = null;
+    function colOf(x) {
+        return clampInt((x - minX) / cellSize, 0, cols - 1);
+    }
+    function rowOf(z) {
+        return clampInt((z - minZ) / cellSize, 0, rows - 1);
+    }
+    function markCell(col, row) {
+        if (col < 0 || col >= cols || row < 0 || row >= rows)
+            return false;
+        const index = row * cols + col;
+        if (revealed[index])
+            return false;
+        revealed[index] = true;
+        revealedCount += 1;
+        return true;
+    }
+    function notify(changed) {
+        if (changed === 0)
+            return;
+        snapshotCache = null;
+        for (const listener of listeners)
+            listener();
+    }
+    function revealAt(x, z, radius) {
+        const centerCol = colOf(x);
+        const centerRow = rowOf(z);
+        let changed = markCell(centerCol, centerRow) ? 1 : 0;
+        if (radius <= 0)
+            return changed;
+        const span = Math.ceil(radius / cellSize);
+        const radiusSq = radius * radius;
+        for (let dr = -span; dr <= span; dr += 1) {
+            for (let dc = -span; dc <= span; dc += 1) {
+                if (dc === 0 && dr === 0)
+                    continue;
+                const cellX = minX + (centerCol + dc + 0.5) * cellSize;
+                const cellZ = minZ + (centerRow + dr + 0.5) * cellSize;
+                const dx = cellX - x;
+                const dz = cellZ - z;
+                if (dx * dx + dz * dz > radiusSq)
+                    continue;
+                if (markCell(centerCol + dc, centerRow + dr))
+                    changed += 1;
+            }
+        }
+        return changed;
+    }
+    if (config.revealed !== undefined) {
+        for (const index of config.revealed) {
+            if (index >= 0 && index < total && !revealed[index]) {
+                revealed[index] = true;
+                revealedCount += 1;
+            }
+        }
+        snapshotCache = null;
+    }
+    return {
+        reveal(x, z, radius = 0) {
+            const changed = revealAt(x, z, radius);
+            notify(changed);
+            return changed;
+        },
+        revealAlong(from, to, radius = cellSize) {
+            const dx = to[0] - from[0];
+            const dz = to[1] - from[1];
+            const distance = Math.hypot(dx, dz);
+            const steps = Math.max(1, Math.ceil(distance / cellSize));
+            let changed = 0;
+            for (let step = 0; step <= steps; step += 1) {
+                const t = step / steps;
+                changed += revealAt(from[0] + dx * t, from[1] + dz * t, radius);
+            }
+            notify(changed);
+            return changed;
+        },
+        isRevealed(x, z) {
+            return revealed[rowOf(z) * cols + colOf(x)] === true;
+        },
+        isRevealedCell(col, row) {
+            if (col < 0 || col >= cols || row < 0 || row >= rows)
+                return false;
+            return revealed[row * cols + col] === true;
+        },
+        revealedCount() {
+            return revealedCount;
+        },
+        cellCount() {
+            return total;
+        },
+        fraction() {
+            return total === 0 ? 0 : revealedCount / total;
+        },
+        cells() {
+            if (snapshotCache === null) {
+                snapshotCache = {
+                    cols,
+                    rows,
+                    minX,
+                    minZ,
+                    cellSize,
+                    revealed: revealed.slice(),
+                    revealedCount,
+                };
+            }
+            return snapshotCache;
+        },
+        reset() {
+            if (revealedCount === 0)
+                return;
+            revealed.fill(false);
+            revealedCount = 0;
+            notify(1);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}

package/dist/world/markers.d.ts

@@ -0,0 +1,52 @@
+export type MarkerPosition = readonly [number, number, number];
+export interface MapMarker<TMeta = unknown> {
+    id: string;
+    kind: string;
+    position: MarkerPosition;
+    label?: string;
+    owner?: string;
+    createdAt: number;
+    expiresAt?: number;
+    meta?: TMeta;
+}
+export interface MarkerInput<TMeta = unknown> {
+    id?: string;
+    kind: string;
+    position: MarkerPosition;
+    label?: string;
+    owner?: string;
+    createdAt?: number;
+    expiresAt?: number;
+    meta?: TMeta;
+}
+export interface MarkerQuery {
+    kind?: string;
+    owner?: string;
+    near?: MarkerPosition;
+    radius?: number;
+}
+/**
+ * Visual descriptor for a marker kind. Games supply their own palette; the
+ * engine ships `DEFAULT_MARKER_KINDS` as a content-agnostic starting set that
+ * the react minimap/compass read for colors and glyphs.
+ */
+export interface MarkerKindStyle {
+    id: string;
+    color: string;
+    glyph: string;
+    priority: number;
+}
+export declare const DEFAULT_MARKER_KINDS: Record<string, MarkerKindStyle>;
+export declare function markerKindStyle(kind: string, styles?: Record<string, MarkerKindStyle>): MarkerKindStyle;
+export interface MarkerSet<TMeta = unknown> {
+    add(marker: MarkerInput<TMeta>): string;
+    remove(id: string): boolean;
+    get(id: string): MapMarker<TMeta> | null;
+    list(): readonly MapMarker<TMeta>[];
+    query(query: MarkerQuery): MapMarker<TMeta>[];
+    prune(now: number): number;
+    clear(): void;
+    subscribe(listener: () => void): () => void;
+    snapshot(): readonly MapMarker<TMeta>[];
+}
+export declare function createMarkerSet<TMeta = unknown>(now?: () => number): MarkerSet<TMeta>;