@jgengine/core 0.9.0 → 0.11.0

package/dist/world/vec2.js

@@ -0,0 +1,128 @@
+/** Sum of two 2D vectors.
+ * @internal
+ */
+export function add(a, b) {
+    return [a[0] + b[0], a[1] + b[1]];
+}
+/** Difference `a - b` of two 2D vectors.
+ * @internal
+ */
+export function sub(a, b) {
+    return [a[0] - b[0], a[1] - b[1]];
+}
+/** Scale a 2D vector by a scalar.
+ * @internal
+ */
+export function scale(a, s) {
+    return [a[0] * s, a[1] * s];
+}
+/** Negate a 2D vector.
+ * @internal
+ */
+export function negate(a) {
+    return [-a[0], -a[1]];
+}
+/** Dot product of two 2D vectors.
+ * @internal
+ */
+export function dot(a, b) {
+    return a[0] * b[0] + a[1] * b[1];
+}
+/** 2D cross product (scalar z of the 3D cross), positive when `b` is counter-clockwise from `a`.
+ * @internal
+ */
+export function cross(a, b) {
+    return a[0] * b[1] - a[1] * b[0];
+}
+/** Euclidean length of a 2D vector.
+ * @internal
+ */
+export function length(a) {
+    return Math.hypot(a[0], a[1]);
+}
+/** Squared length of a 2D vector; cheaper than `length` when only comparing magnitudes.
+ * @internal
+ */
+export function lengthSquared(a) {
+    return a[0] * a[0] + a[1] * a[1];
+}
+/** Unit vector in the direction of `a`; returns the zero vector when `a` has no length.
+ * @internal
+ */
+export function normalize(a) {
+    const len = Math.hypot(a[0], a[1]);
+    return len < 1e-9 ? [0, 0] : [a[0] / len, a[1] / len];
+}
+/** Distance between two points.
+ * @internal
+ */
+export function distance(a, b) {
+    return Math.hypot(a[0] - b[0], a[1] - b[1]);
+}
+/** Squared distance between two points; cheaper than `distance` for radius comparisons.
+ * @internal
+ */
+export function distanceSquared(a, b) {
+    const dx = a[0] - b[0];
+    const dy = a[1] - b[1];
+    return dx * dx + dy * dy;
+}
+/** Linearly interpolate between points `a` and `b` by fraction `t`.
+ * @internal
+ */
+export function lerp(a, b, t) {
+    return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t];
+}
+/** Left-hand perpendicular of `a` (rotated 90° counter-clockwise).
+ * @internal
+ */
+export function perp(a) {
+    return [-a[1], a[0]];
+}
+/** Rotate a 2D vector by `radians` about the origin.
+ * @internal
+ */
+export function rotate(a, radians) {
+    const c = Math.cos(radians);
+    const s = Math.sin(radians);
+    return [a[0] * c - a[1] * s, a[0] * s + a[1] * c];
+}
+/**
+ * Reflect a velocity off a surface with unit `normal`, losing energy by `restitution` (0..1). At
+ * `restitution` 1 the normal component mirrors elastically (`v − 2(v·n)n`); at 0 it is removed so the
+ * vector slides along the surface. Only the normal component is scaled — tangential motion is kept — so
+ * this is the wall/paddle/boundary bounce every arcade ball game hand-rolls.
+  * @internal
+  */
+export function reflect(v, normal, restitution = 1) {
+    const vn = v[0] * normal[0] + v[1] * normal[1];
+    const j = (1 + restitution) * vn;
+    return [v[0] - j * normal[0], v[1] - j * normal[1]];
+}
+/** Unit vector for a heading measured clockwise from +Y (the engine's XZ-plane convention).
+ * @internal
+ */
+export function fromHeading(headingRad) {
+    return [Math.sin(headingRad), Math.cos(headingRad)];
+}
+/** Heading in radians of a vector, measured clockwise from +Y to match `fromHeading`.
+ * @internal
+ */
+export function heading(a) {
+    return Math.atan2(a[0], a[1]);
+}
+/** Wrap an angle in radians into `[0, 2π)`.
+ * @internal
+ */
+export function normalizeAngle(angleRad) {
+    const twoPi = Math.PI * 2;
+    const a = angleRad % twoPi;
+    return a < 0 ? a + twoPi : a;
+}
+/** Wrap an angle in degrees into `[0, 360)`.
+ * @internal
+ */
+export function normalizeAngleDeg(angleDeg) {
+    const a = angleDeg % 360;
+    return a < 0 ? a + 360 : a;
+}

package/dist/world/vec3.d.ts

@@ -0,0 +1,49 @@
+import type { Vec3 } from "./geometry.js";
+/** Sum of two 3D vectors.
+ * @internal
+ */
+export declare function add(a: Vec3, b: Vec3): Vec3;
+/** Difference `a - b` of two 3D vectors.
+ * @internal
+ */
+export declare function sub(a: Vec3, b: Vec3): Vec3;
+/** Scale a 3D vector by a scalar.
+ * @internal
+ */
+export declare function scale(a: Vec3, s: number): Vec3;
+/** Negate a 3D vector.
+ * @internal
+ */
+export declare function negate(a: Vec3): Vec3;
+/** Dot product of two 3D vectors.
+ * @internal
+ */
+export declare function dot(a: Vec3, b: Vec3): number;
+/** Cross product `a × b` of two 3D vectors.
+ * @internal
+ */
+export declare function cross(a: Vec3, b: Vec3): Vec3;
+/** Euclidean length of a 3D vector.
+ * @internal
+ */
+export declare function length(a: Vec3): number;
+/** Squared length of a 3D vector; cheaper than `length` when only comparing magnitudes.
+ * @internal
+ */
+export declare function lengthSquared(a: Vec3): number;
+/** Unit vector in the direction of `a`; returns the zero vector when `a` has no length.
+ * @internal
+ */
+export declare function normalize(a: Vec3): Vec3;
+/** Distance between two points.
+ * @internal
+ */
+export declare function distance(a: Vec3, b: Vec3): number;
+/** Squared distance between two points; cheaper than `distance` for radius comparisons on hot paths.
+ * @internal
+ */
+export declare function distanceSquared(a: Vec3, b: Vec3): number;
+/** Linearly interpolate between points `a` and `b` by fraction `t`.
+ * @internal
+ */
+export declare function lerp(a: Vec3, b: Vec3, t: number): Vec3;

package/dist/world/vec3.js

@@ -0,0 +1,76 @@
+/** Sum of two 3D vectors.
+ * @internal
+ */
+export function add(a, b) {
+    return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+}
+/** Difference `a - b` of two 3D vectors.
+ * @internal
+ */
+export function sub(a, b) {
+    return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+/** Scale a 3D vector by a scalar.
+ * @internal
+ */
+export function scale(a, s) {
+    return [a[0] * s, a[1] * s, a[2] * s];
+}
+/** Negate a 3D vector.
+ * @internal
+ */
+export function negate(a) {
+    return [-a[0], -a[1], -a[2]];
+}
+/** Dot product of two 3D vectors.
+ * @internal
+ */
+export function dot(a, b) {
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+/** Cross product `a × b` of two 3D vectors.
+ * @internal
+ */
+export 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]];
+}
+/** Euclidean length of a 3D vector.
+ * @internal
+ */
+export function length(a) {
+    return Math.hypot(a[0], a[1], a[2]);
+}
+/** Squared length of a 3D vector; cheaper than `length` when only comparing magnitudes.
+ * @internal
+ */
+export function lengthSquared(a) {
+    return a[0] * a[0] + a[1] * a[1] + a[2] * a[2];
+}
+/** Unit vector in the direction of `a`; returns the zero vector when `a` has no length.
+ * @internal
+ */
+export function normalize(a) {
+    const len = Math.hypot(a[0], a[1], a[2]);
+    return len < 1e-9 ? [0, 0, 0] : [a[0] / len, a[1] / len, a[2] / len];
+}
+/** Distance between two points.
+ * @internal
+ */
+export function distance(a, b) {
+    return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+}
+/** Squared distance between two points; cheaper than `distance` for radius comparisons on hot paths.
+ * @internal
+ */
+export function distanceSquared(a, b) {
+    const dx = a[0] - b[0];
+    const dy = a[1] - b[1];
+    const dz = a[2] - b[2];
+    return dx * dx + dy * dy + dz * dz;
+}
+/** Linearly interpolate between points `a` and `b` by fraction `t`.
+ * @internal
+ */
+export function lerp(a, b, t) {
+    return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t];
+}

package/dist/world/vegetation.d.ts

@@ -0,0 +1,71 @@
+import type { Aabb } from "./geometry.js";
+import type { GrassEnvironmentConfig } from "./features.js";
+import type { SceneDocumentLike, SceneVolumeLike } from "./sceneShapes.js";
+/** The editor volume kind that marks an area as vegetation fill. */
+export declare const VEGETATION_VOLUME_KIND = "vegetation";
+/**
+ * How a vegetation volume fills its area, read from the volume's `meta`.
+ * `density` is items per square meter — the one slider number: grass blades,
+ * trees, bushes, rocks all scale with it. Every field has a default, so a
+ * freshly placed `kind: "vegetation"` volume already grows grass.
+ */
+export interface VegetationSettings {
+    /** `"grass"` for shell-rendered blades, otherwise an asset/catalog item id the game maps to a model. */
+    item: string;
+    /** Items per square meter (grass blades: ~4; trees: ~0.02; bushes: ~0.08). */
+    density: number;
+    /** Random uniform scale range applied per placement. */
+    minScale: number;
+    maxScale: number;
+    /** Minimum spacing between placements in meters; 0 allows clumping. */
+    minDistance: number;
+    /** Extra seed folded into the volume id so re-rolls are one string away. */
+    seed: string;
+}
+/** Defaults a bare `kind: "vegetation"` volume grows with: grass at 4 blades/m². */
+export declare const VEGETATION_DEFAULTS: VegetationSettings;
+/** True when an editor volume is a vegetation fill area.
+ * @internal
+ */
+export declare function isVegetationVolume(volume: SceneVolumeLike): boolean;
+/** The volume's vegetation settings with defaults filled in; null for non-vegetation volumes.
+ * @internal
+ */
+export declare function readVegetationSettings(volume: SceneVolumeLike): VegetationSettings | null;
+/** The ground-plane footprint of a volume: box half-extents or sphere/cylinder radius.
+ * @internal
+ */
+export declare function vegetationFootprint(volume: SceneVolumeLike): Aabb;
+/** One placed vegetation instance — position on the ground plane plus per-instance variation. */
+export interface VegetationPlacement {
+    id: string;
+    volumeId: string;
+    item: string;
+    x: number;
+    z: number;
+    scale: number;
+    rotation: number;
+}
+/**
+ * Deterministic placements for one vegetation volume: scatter its footprint at
+ * `density` items/m² (respecting `minDistance`), clip round shapes to their
+ * radius, and derive per-instance scale/rotation from the volume id + seed, so
+ * the same saved scene always grows the same field.
+  * @internal
+  */
+export declare function resolveVegetationVolume(volume: SceneVolumeLike): VegetationPlacement[];
+/**
+ * All model-item placements in a document (every vegetation volume except
+ * `item: "grass"`, which the shell renders as blades — see
+ * `grassPatchesFromVegetation`). A game maps each placement's `item` to a
+ * mesh/entity via its render catalog and places it grounded.
+  * @internal
+  */
+export declare function resolveVegetation(doc: SceneDocumentLike): VegetationPlacement[];
+/**
+ * Grass-blade patches for every `item: "grass"` vegetation volume, ready to
+ * spread into `environment()`'s `grass` list — the volume's density number is
+ * the blades-per-m² the shell renders, so the editor slider drives it directly.
+  * @internal
+  */
+export declare function grassPatchesFromVegetation(doc: SceneDocumentLike): GrassEnvironmentConfig[];

package/dist/world/vegetation.js

@@ -0,0 +1,151 @@
+import { scatter } from "./scatter.js";
+/** The editor volume kind that marks an area as vegetation fill. */
+export const VEGETATION_VOLUME_KIND = "vegetation";
+/** Defaults a bare `kind: "vegetation"` volume grows with: grass at 4 blades/m². */
+export const VEGETATION_DEFAULTS = {
+    item: "grass",
+    density: 4,
+    minScale: 0.8,
+    maxScale: 1.2,
+    minDistance: 0,
+    seed: "",
+};
+function metaNumber(meta, key, fallback) {
+    const value = meta?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function metaString(meta, key, fallback) {
+    const value = meta?.[key];
+    return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+/** True when an editor volume is a vegetation fill area.
+ * @internal
+ */
+export function isVegetationVolume(volume) {
+    return volume.kind === VEGETATION_VOLUME_KIND;
+}
+/** The volume's vegetation settings with defaults filled in; null for non-vegetation volumes.
+ * @internal
+ */
+export function readVegetationSettings(volume) {
+    if (!isVegetationVolume(volume))
+        return null;
+    return {
+        item: metaString(volume.meta, "item", VEGETATION_DEFAULTS.item),
+        density: Math.max(0, metaNumber(volume.meta, "density", VEGETATION_DEFAULTS.density)),
+        minScale: metaNumber(volume.meta, "minScale", VEGETATION_DEFAULTS.minScale),
+        maxScale: metaNumber(volume.meta, "maxScale", VEGETATION_DEFAULTS.maxScale),
+        minDistance: Math.max(0, metaNumber(volume.meta, "minDistance", VEGETATION_DEFAULTS.minDistance)),
+        seed: metaString(volume.meta, "seed", VEGETATION_DEFAULTS.seed),
+    };
+}
+/** The ground-plane footprint of a volume: box half-extents or sphere/cylinder radius.
+ * @internal
+ */
+export function vegetationFootprint(volume) {
+    const halfW = volume.shape === "box" ? (volume.halfExtents?.x ?? 5) : (volume.radius ?? 5);
+    const halfD = volume.shape === "box" ? (volume.halfExtents?.z ?? 5) : (volume.radius ?? 5);
+    return {
+        minX: volume.center.x - halfW,
+        minZ: volume.center.z - halfD,
+        maxX: volume.center.x + halfW,
+        maxZ: volume.center.z + halfD,
+    };
+}
+function placementHash(volumeId, seed, index, salt) {
+    const text = `${volumeId}:${seed}:${index}:${salt}`;
+    let h = 2166136261 >>> 0;
+    for (let i = 0; i < text.length; i++) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return (h >>> 0) / 4294967296;
+}
+/**
+ * Deterministic placements for one vegetation volume: scatter its footprint at
+ * `density` items/m² (respecting `minDistance`), clip round shapes to their
+ * radius, and derive per-instance scale/rotation from the volume id + seed, so
+ * the same saved scene always grows the same field.
+  * @internal
+  */
+export function resolveVegetationVolume(volume) {
+    const settings = readVegetationSettings(volume);
+    if (settings === null || settings.density <= 0)
+        return [];
+    const area = vegetationFootprint(volume);
+    const points = scatter({
+        area,
+        density: settings.density,
+        minDistance: settings.minDistance,
+        seed: `${volume.id}:${settings.seed}`,
+    });
+    const round = volume.shape !== "box";
+    const radius = volume.radius ?? 5;
+    const radiusSq = radius * radius;
+    const placements = [];
+    for (const point of points) {
+        if (round) {
+            const dx = point.x - volume.center.x;
+            const dz = point.z - volume.center.z;
+            if (dx * dx + dz * dz > radiusSq)
+                continue;
+        }
+        const t = placementHash(volume.id, settings.seed, point.index, 0x51);
+        placements.push({
+            id: `${volume.id}/${point.index}`,
+            volumeId: volume.id,
+            item: settings.item,
+            x: point.x,
+            z: point.z,
+            scale: settings.minScale + (settings.maxScale - settings.minScale) * t,
+            rotation: placementHash(volume.id, settings.seed, point.index, 0x9e) * Math.PI * 2,
+        });
+    }
+    return placements;
+}
+/**
+ * All model-item placements in a document (every vegetation volume except
+ * `item: "grass"`, which the shell renders as blades — see
+ * `grassPatchesFromVegetation`). A game maps each placement's `item` to a
+ * mesh/entity via its render catalog and places it grounded.
+  * @internal
+  */
+export function resolveVegetation(doc) {
+    const out = [];
+    for (const volume of doc.volumes) {
+        if (!isVegetationVolume(volume))
+            continue;
+        const settings = readVegetationSettings(volume);
+        if (settings === null || settings.item === "grass")
+            continue;
+        out.push(...resolveVegetationVolume(volume));
+    }
+    return out;
+}
+/**
+ * Grass-blade patches for every `item: "grass"` vegetation volume, ready to
+ * spread into `environment()`'s `grass` list — the volume's density number is
+ * the blades-per-m² the shell renders, so the editor slider drives it directly.
+  * @internal
+  */
+export function grassPatchesFromVegetation(doc) {
+    const patches = [];
+    for (const volume of doc.volumes) {
+        if (!isVegetationVolume(volume))
+            continue;
+        const settings = readVegetationSettings(volume);
+        if (settings === null || settings.item !== "grass" || settings.density <= 0)
+            continue;
+        const area = vegetationFootprint(volume);
+        patches.push({
+            area: {
+                w: area.maxX - area.minX,
+                d: area.maxZ - area.minZ,
+                position: [volume.center.x, volume.center.z],
+            },
+            density: settings.density,
+            seed: `${volume.id}:${settings.seed}`,
+        });
+    }
+    return patches;
+}

package/dist/world/visibilityField.d.ts

@@ -0,0 +1,154 @@
+import type { FogBounds } from "./fog.js";
+/** Numeric code for a cell no group member has seen, or has fully forgotten. */
+export declare const VISIBILITY_HIDDEN = 0;
+/** Numeric code for a cell seen before but not currently in view (last-known). */
+export declare const VISIBILITY_REMEMBERED = 1;
+/** Numeric code for a cell a group currently observes. */
+export declare const VISIBILITY_OBSERVED = 2;
+/** One viewer group's knowledge of a cell: never/forgotten, last-known, or live. */
+export type VisibilityState = "hidden" | "remembered" | "observed";
+/**
+ * How a cell decays after a group stops observing it — the terrain-memory policy.
+ * `permanent` keeps last-known terrain forever (RTS explored map); `none` drops
+ * it straight back to hidden the moment it leaves view (pure line-of-sight
+ * stealth); `decay` remembers it for `updates` observe cycles, then hides it.
+ * Day/night, height, sensor, and stealth rules are NOT encoded here — the caller
+ * bakes those into which cells it reports as observed each update.
+ */
+export type VisibilityMemory = {
+    readonly kind: "permanent";
+} | {
+    readonly kind: "none";
+} | {
+    readonly kind: "decay";
+    readonly updates: number;
+};
+/** Construction options for {@link createVisibilityField}. */
+export interface VisibilityFieldConfig {
+    /** World-space rectangle the grid covers (reused from `world/fog`). */
+    readonly bounds: FogBounds;
+    /** World units per grid cell. Must be positive. */
+    readonly cellSize: number;
+    /** Default memory policy applied to every group. Default `{ kind: "permanent" }`. */
+    readonly memory?: VisibilityMemory;
+    /** Rehydrate from a previously serialized field (see {@link VisibilityField.toState}). */
+    readonly restore?: VisibilityFieldState;
+}
+/**
+ * The cells that changed state for one group in a single {@link VisibilityField.observe}
+ * call — a pure incremental readout for rendering, minimaps, AI, UI, and
+ * authoritative replication. Never lists unchanged cells, so it stays bounded by
+ * how much the group's view actually moved.
+ */
+export interface VisibilityDelta {
+    readonly group: string;
+    /** Cells that entered observation this update. */
+    readonly observed: readonly number[];
+    /** Cells that left observation into remembered (last-known) state. */
+    readonly remembered: readonly number[];
+    /** Cells that fell out of memory entirely (decay expiry or `none` policy). */
+    readonly hidden: readonly number[];
+}
+/** Sparse serialized knowledge for one group — only non-hidden cells are stored. */
+export interface VisibilityGroupState {
+    /** Currently observed cell indices. */
+    readonly observed: readonly number[];
+    /** Remembered cells as `[cellIndex, lastObservedTick]` pairs. */
+    readonly remembered: readonly (readonly [number, number])[];
+    /** Monotonic update counter, used to age remembered cells under a decay policy. */
+    readonly tick: number;
+    /** Per-group memory override, when it differs from the field default. */
+    readonly memory?: VisibilityMemory;
+}
+/** Serializable snapshot of a whole field — JSON round-trips losslessly. */
+export interface VisibilityFieldState {
+    readonly cols: number;
+    readonly rows: number;
+    readonly minX: number;
+    readonly minZ: number;
+    readonly cellSize: number;
+    readonly memory: VisibilityMemory;
+    readonly groups: Readonly<Record<string, VisibilityGroupState>>;
+}
+/** Dense per-cell readout for one group, shaped for minimap/overlay drawing. */
+export interface VisibilityCells {
+    readonly cols: number;
+    readonly rows: number;
+    readonly minX: number;
+    readonly minZ: number;
+    readonly cellSize: number;
+    /** Row-major `VISIBILITY_*` codes; index = row * cols + col. */
+    readonly codes: Uint8Array;
+}
+/**
+ * A gameplay (fog-of-war) knowledge field: per viewer group, every grid cell is
+ * hidden, remembered, or observed. Distinct from render culling in
+ * `core/visibility` — this models what a team KNOWS, not what a camera can draw.
+ * It generalizes `world/fog`'s single-group reveal-once model to many groups
+ * with configurable terrain memory, and keeps each group's knowledge isolated so
+ * one group's hidden state can never be derived from another's.
+ */
+export interface VisibilityField {
+    readonly cols: number;
+    readonly rows: number;
+    cellCount(): number;
+    colOf(x: number): number;
+    rowOf(z: number): number;
+    /** Row-major cell index for a world point, clamped into the grid. */
+    cellIndex(x: number, z: number): number;
+    /** Register a viewer group, optionally with its own memory policy. Idempotent. */
+    ensureGroup(group: string, memory?: VisibilityMemory): void;
+    hasGroup(group: string): boolean;
+    groups(): string[];
+    /** Forget everything for a group and drop it. */
+    removeGroup(group: string): void;
+    /**
+     * Cell indices whose centers fall within `radius` of a world point (bounded
+     * disc), appended into `out` when supplied. Feed these into {@link observe};
+     * union several sources' discs before observing to model overlapping observers.
+     */
+    cellsInRadius(x: number, z: number, radius: number, out?: number[]): number[];
+    /**
+     * Replace a group's observed set for this update. Cells newly covered become
+     * observed; cells that dropped out become remembered (or hidden under `none`);
+     * decayed memory expires. Work is bounded by the observed + remembered working
+     * sets — it never scans the whole grid. Returns the resulting {@link VisibilityDelta}.
+     */
+    observe(group: string, cells: Iterable<number>): VisibilityDelta;
+    /** Convenience {@link observe} over a single disc around a source. */
+    observeCircle(group: string, x: number, z: number, radius: number): VisibilityDelta;
+    stateAtCell(group: string, cell: number): VisibilityState;
+    stateAt(group: string, x: number, z: number): VisibilityState;
+    isObserved(group: string, x: number, z: number): boolean;
+    isRemembered(group: string, x: number, z: number): boolean;
+    /** Terrain disclosure: observed OR remembered (anything the group has ever mapped). */
+    isKnown(group: string, x: number, z: number): boolean;
+    observedCount(group: string): number;
+    knownCount(group: string): number;
+    /**
+     * Authoritative entity-disclosure filter: keep only entities standing in a cell
+     * the group currently OBSERVES. Remembered and hidden cells never disclose live
+     * entities, so a unit that moved away or was destroyed re-hides. Reads only this
+     * group's state, so it is the seam that stops one group's hidden entities from
+     * leaking into another group's replicated view.
+     */
+    visibleTo<T>(group: string, entities: readonly T[], positionOf: (entity: T) => {
+        readonly x: number;
+        readonly z: number;
+    }): T[];
+    /** Dense per-cell codes for a group, for minimap/overlay rendering. */
+    cells(group: string): VisibilityCells;
+    /** Sparse serializable snapshot; round-trips through {@link createVisibilityField}'s `restore`. */
+    toState(): VisibilityFieldState;
+    /** Forget one group's knowledge, or every group when `group` is omitted. */
+    reset(group?: string): void;
+}
+/**
+ * Build a per-group gameplay visibility field. First adopters: an RTS/stealth
+ * team whose scout observes terrain (which stays remembered after it leaves)
+ * while enemy units re-hide once no scout observes their cell, and any
+ * authoritative host that must filter hidden entities out of a client's replica.
+ *
+ * @capability visibility-field per-viewer-group observed/remembered/hidden fog-of-war knowledge with terrain memory and authoritative entity disclosure
+ */
+export declare function createVisibilityField(config: VisibilityFieldConfig): VisibilityField;