@jgengine/core 0.9.0 → 0.11.0

package/dist/world/visibilityField.js

@@ -0,0 +1,271 @@
+/** Numeric code for a cell no group member has seen, or has fully forgotten. */
+export const VISIBILITY_HIDDEN = 0;
+/** Numeric code for a cell seen before but not currently in view (last-known). */
+export const VISIBILITY_REMEMBERED = 1;
+/** Numeric code for a cell a group currently observes. */
+export const VISIBILITY_OBSERVED = 2;
+function clampInt(value, min, max) {
+    const rounded = Math.floor(value);
+    return rounded < min ? min : rounded > max ? max : rounded;
+}
+function stateOf(code) {
+    return code === VISIBILITY_OBSERVED
+        ? "observed"
+        : code === VISIBILITY_REMEMBERED
+            ? "remembered"
+            : "hidden";
+}
+/**
+ * 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 function createVisibilityField(config) {
+    const cellSize = config.cellSize;
+    if (cellSize <= 0)
+        throw new Error("createVisibilityField: cellSize must be positive");
+    const restore = config.restore;
+    const minX = restore?.minX ?? config.bounds.minX;
+    const minZ = restore?.minZ ?? config.bounds.minZ;
+    const cols = restore?.cols ?? Math.max(1, Math.ceil((config.bounds.maxX - config.bounds.minX) / cellSize));
+    const rows = restore?.rows ?? Math.max(1, Math.ceil((config.bounds.maxZ - config.bounds.minZ) / cellSize));
+    const total = cols * rows;
+    const defaultMemory = restore?.memory ?? config.memory ?? { kind: "permanent" };
+    const groups = new Map();
+    function makeGroup(memory) {
+        return {
+            codes: new Uint8Array(total),
+            observed: new Set(),
+            remembered: new Map(),
+            tick: 0,
+            memory,
+        };
+    }
+    function getGroup(group) {
+        let data = groups.get(group);
+        if (data === undefined) {
+            data = makeGroup(defaultMemory);
+            groups.set(group, data);
+        }
+        return data;
+    }
+    if (restore !== undefined) {
+        for (const [name, state] of Object.entries(restore.groups)) {
+            const data = makeGroup(state.memory ?? defaultMemory);
+            data.tick = state.tick;
+            for (const cell of state.observed) {
+                if (cell >= 0 && cell < total) {
+                    data.codes[cell] = VISIBILITY_OBSERVED;
+                    data.observed.add(cell);
+                }
+            }
+            for (const [cell, tick] of state.remembered) {
+                if (cell >= 0 && cell < total && data.codes[cell] === VISIBILITY_HIDDEN) {
+                    data.codes[cell] = VISIBILITY_REMEMBERED;
+                    data.remembered.set(cell, tick);
+                }
+            }
+            groups.set(name, data);
+        }
+    }
+    function colOf(x) {
+        return clampInt((x - minX) / cellSize, 0, cols - 1);
+    }
+    function rowOf(z) {
+        return clampInt((z - minZ) / cellSize, 0, rows - 1);
+    }
+    function cellIndex(x, z) {
+        return rowOf(z) * cols + colOf(x);
+    }
+    function cellsInRadius(x, z, radius, out = []) {
+        const centerCol = colOf(x);
+        const centerRow = rowOf(z);
+        if (radius <= 0) {
+            out.push(centerRow * cols + centerCol);
+            return out;
+        }
+        const span = Math.ceil(radius / cellSize);
+        const radiusSq = radius * radius;
+        for (let dr = -span; dr <= span; dr += 1) {
+            const row = centerRow + dr;
+            if (row < 0 || row >= rows)
+                continue;
+            for (let dc = -span; dc <= span; dc += 1) {
+                const col = centerCol + dc;
+                if (col < 0 || col >= cols)
+                    continue;
+                const cellX = minX + (col + 0.5) * cellSize;
+                const cellZ = minZ + (row + 0.5) * cellSize;
+                const dx = cellX - x;
+                const dz = cellZ - z;
+                if (dx * dx + dz * dz > radiusSq)
+                    continue;
+                out.push(row * cols + col);
+            }
+        }
+        return out;
+    }
+    function observe(group, cells) {
+        const data = getGroup(group);
+        data.tick += 1;
+        const now = data.tick;
+        const remembering = data.memory.kind !== "none";
+        const next = new Set();
+        const observedDelta = [];
+        for (const cell of cells) {
+            if (cell < 0 || cell >= total || next.has(cell))
+                continue;
+            next.add(cell);
+            if (data.codes[cell] !== VISIBILITY_OBSERVED) {
+                data.codes[cell] = VISIBILITY_OBSERVED;
+                data.remembered.delete(cell);
+                observedDelta.push(cell);
+            }
+        }
+        const rememberedDelta = [];
+        const hiddenDelta = [];
+        for (const cell of data.observed) {
+            if (next.has(cell))
+                continue;
+            if (remembering) {
+                data.codes[cell] = VISIBILITY_REMEMBERED;
+                data.remembered.set(cell, now);
+                rememberedDelta.push(cell);
+            }
+            else {
+                data.codes[cell] = VISIBILITY_HIDDEN;
+                hiddenDelta.push(cell);
+            }
+        }
+        data.observed = next;
+        if (data.memory.kind === "decay") {
+            const maxAge = data.memory.updates;
+            for (const [cell, seen] of data.remembered) {
+                if (now - seen >= maxAge) {
+                    data.codes[cell] = VISIBILITY_HIDDEN;
+                    data.remembered.delete(cell);
+                    hiddenDelta.push(cell);
+                }
+            }
+        }
+        return { group, observed: observedDelta, remembered: rememberedDelta, hidden: hiddenDelta };
+    }
+    return {
+        cols,
+        rows,
+        cellCount() {
+            return total;
+        },
+        colOf,
+        rowOf,
+        cellIndex,
+        ensureGroup(group, memory) {
+            const existing = groups.get(group);
+            if (existing === undefined) {
+                groups.set(group, makeGroup(memory ?? defaultMemory));
+            }
+            else if (memory !== undefined) {
+                existing.memory = memory;
+            }
+        },
+        hasGroup(group) {
+            return groups.has(group);
+        },
+        groups() {
+            return Array.from(groups.keys());
+        },
+        removeGroup(group) {
+            groups.delete(group);
+        },
+        cellsInRadius,
+        observe,
+        observeCircle(group, x, z, radius) {
+            return observe(group, cellsInRadius(x, z, radius));
+        },
+        stateAtCell(group, cell) {
+            const data = groups.get(group);
+            if (data === undefined || cell < 0 || cell >= total)
+                return "hidden";
+            return stateOf(data.codes[cell]);
+        },
+        stateAt(group, x, z) {
+            const data = groups.get(group);
+            if (data === undefined)
+                return "hidden";
+            return stateOf(data.codes[cellIndex(x, z)]);
+        },
+        isObserved(group, x, z) {
+            const data = groups.get(group);
+            return data !== undefined && data.codes[cellIndex(x, z)] === VISIBILITY_OBSERVED;
+        },
+        isRemembered(group, x, z) {
+            const data = groups.get(group);
+            return data !== undefined && data.codes[cellIndex(x, z)] === VISIBILITY_REMEMBERED;
+        },
+        isKnown(group, x, z) {
+            const data = groups.get(group);
+            return data !== undefined && data.codes[cellIndex(x, z)] !== VISIBILITY_HIDDEN;
+        },
+        observedCount(group) {
+            return groups.get(group)?.observed.size ?? 0;
+        },
+        knownCount(group) {
+            const data = groups.get(group);
+            if (data === undefined)
+                return 0;
+            return data.observed.size + data.remembered.size;
+        },
+        visibleTo(group, entities, positionOf) {
+            const data = groups.get(group);
+            if (data === undefined)
+                return [];
+            const result = [];
+            for (const entity of entities) {
+                const position = positionOf(entity);
+                if (data.codes[cellIndex(position.x, position.z)] === VISIBILITY_OBSERVED) {
+                    result.push(entity);
+                }
+            }
+            return result;
+        },
+        cells(group) {
+            const data = groups.get(group);
+            const codes = data === undefined ? new Uint8Array(total) : data.codes.slice();
+            return { cols, rows, minX, minZ, cellSize, codes };
+        },
+        toState() {
+            const out = {};
+            for (const [name, data] of groups) {
+                const remembered = Array.from(data.remembered.entries()).sort((a, b) => a[0] - b[0]);
+                out[name] = {
+                    observed: Array.from(data.observed).sort((a, b) => a - b),
+                    remembered,
+                    tick: data.tick,
+                    memory: data.memory,
+                };
+            }
+            return { cols, rows, minX, minZ, cellSize, memory: defaultMemory, groups: out };
+        },
+        reset(group) {
+            if (group === undefined) {
+                for (const data of groups.values()) {
+                    data.codes.fill(VISIBILITY_HIDDEN);
+                    data.observed.clear();
+                    data.remembered.clear();
+                    data.tick = 0;
+                }
+                return;
+            }
+            const data = groups.get(group);
+            if (data === undefined)
+                return;
+            data.codes.fill(VISIBILITY_HIDDEN);
+            data.observed.clear();
+            data.remembered.clear();
+            data.tick = 0;
+        },
+    };
+}

package/dist/world/volumetricClouds.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Volumetric cloud layer config for `sky()` — a raymarched cloud slab mounted from the environment
+ * `sky` seam. Pure config + defaulting here; the raymarch shader lives in the `shell` renderer
+ * (`environment/VolumetricClouds.tsx`), mounted alongside `SkyDome` whenever a sky descriptor carries
+ * this field. Off by default — omit `volumetricClouds` on `sky({...})` and no layer mounts.
+ *
+ * @capability volumetric-clouds raymarched cloud layer sky option
+ */
+/** Volumetric cloud layer params, as authored on `sky({ volumetricClouds })`. All fields optional. */
+export interface VolumetricCloudsConfig {
+    /** Fraction of the sky covered by cloud mass, 0..1. Higher = more overcast. Default 0.42. */
+    coverage?: number;
+    /** Raymarch density multiplier — thicker, more opaque cloud bodies at higher values. Default 1.5. */
+    density?: number;
+    /** Cloud layer base altitude in world units. Default 90. */
+    height?: number;
+    /** Cloud layer vertical thickness in world units. Default 55. */
+    thickness?: number;
+    /** Horizontal drift speed, world units/second. Default 1.1. */
+    speed?: number;
+    /** Noise feature scale — world units per cloud puff; larger = bigger, fewer puffs. Default 140. */
+    scale?: number;
+    /** Cloud body base color (shadowed side). Default "#c9d3de". */
+    color?: string;
+    /** Sun-facing lit edge color (silver-lining / forward scatter). Default "#fff6e0". */
+    sunColor?: string;
+    /** Forward sun-scatter strength, 0..1 — brighter, more luminous edges toward the sun. Default 0.9. */
+    sunScatter?: number;
+    /** Seed string; same seed reproduces the same cloud layout. */
+    seed?: string;
+}
+/** Fully-defaulted volumetric cloud params, resolved from a `VolumetricCloudsConfig`. */
+export interface VolumetricCloudsRules {
+    coverage: number;
+    density: number;
+    height: number;
+    thickness: number;
+    speed: number;
+    scale: number;
+    color: string;
+    sunColor: string;
+    sunScatter: number;
+    seed: string;
+}
+/** Volumetric cloud defaults: a moderate, drifting cumulus layer. */
+export declare const VOLUMETRIC_CLOUDS_DEFAULTS: VolumetricCloudsRules;
+/**
+ * Resolve a `VolumetricCloudsConfig` into fully-defaulted, clamped rules — pure, no shader/DOM
+ * involved, so the defaulting logic is unit-testable without a renderer.
+ * @internal
+ */
+export declare function resolveVolumetricClouds(config?: VolumetricCloudsConfig): VolumetricCloudsRules;

package/dist/world/volumetricClouds.js

@@ -0,0 +1,43 @@
+/**
+ * Volumetric cloud layer config for `sky()` — a raymarched cloud slab mounted from the environment
+ * `sky` seam. Pure config + defaulting here; the raymarch shader lives in the `shell` renderer
+ * (`environment/VolumetricClouds.tsx`), mounted alongside `SkyDome` whenever a sky descriptor carries
+ * this field. Off by default — omit `volumetricClouds` on `sky({...})` and no layer mounts.
+ *
+ * @capability volumetric-clouds raymarched cloud layer sky option
+ */
+/** Volumetric cloud defaults: a moderate, drifting cumulus layer. */
+export const VOLUMETRIC_CLOUDS_DEFAULTS = {
+    coverage: 0.42,
+    density: 1.5,
+    height: 90,
+    thickness: 55,
+    speed: 1.1,
+    scale: 140,
+    color: "#c9d3de",
+    sunColor: "#fff6e0",
+    sunScatter: 0.9,
+    seed: "",
+};
+/**
+ * Resolve a `VolumetricCloudsConfig` into fully-defaulted, clamped rules — pure, no shader/DOM
+ * involved, so the defaulting logic is unit-testable without a renderer.
+ * @internal
+ */
+export function resolveVolumetricClouds(config = {}) {
+    return {
+        coverage: clamp01(config.coverage ?? VOLUMETRIC_CLOUDS_DEFAULTS.coverage),
+        density: Math.max(0, config.density ?? VOLUMETRIC_CLOUDS_DEFAULTS.density),
+        height: config.height ?? VOLUMETRIC_CLOUDS_DEFAULTS.height,
+        thickness: Math.max(1, config.thickness ?? VOLUMETRIC_CLOUDS_DEFAULTS.thickness),
+        speed: config.speed ?? VOLUMETRIC_CLOUDS_DEFAULTS.speed,
+        scale: Math.max(1, config.scale ?? VOLUMETRIC_CLOUDS_DEFAULTS.scale),
+        color: config.color ?? VOLUMETRIC_CLOUDS_DEFAULTS.color,
+        sunColor: config.sunColor ?? VOLUMETRIC_CLOUDS_DEFAULTS.sunColor,
+        sunScatter: clamp01(config.sunScatter ?? VOLUMETRIC_CLOUDS_DEFAULTS.sunScatter),
+        seed: config.seed ?? VOLUMETRIC_CLOUDS_DEFAULTS.seed,
+    };
+}
+function clamp01(value) {
+    return Math.min(1, Math.max(0, value));
+}

package/dist/world/walls.d.ts

@@ -27,11 +27,17 @@ export interface RoofConfig {
     pitch?: number;
     overhang?: number;
 }
+/** @internal */
 export declare function wallSegments(points: readonly Vec2[], closed: boolean): WallSegment[];
+/** @internal */
 export declare function isEnclosed(points: readonly Vec2[], tolerance?: number): boolean;
+/** @internal */
 export declare function enclosePath(points: readonly Vec2[], tolerance?: number): readonly Vec2[];
+/** @internal */
 export declare function polygonArea(polygon: readonly Vec2[]): number;
+/** @internal */
 export declare function footprintFromWalls(points: readonly Vec2[], tolerance?: number): EnclosedFootprint | null;
+/** @internal */
 export declare function autoRoof(footprint: EnclosedFootprint, config?: RoofConfig): RoofPlan;
 export type PaintTarget = "floor" | "wall";
 export interface SurfacePaintStore {
@@ -42,6 +48,7 @@ export interface SurfacePaintStore {
     snapshot(): Record<PaintTarget, Record<string, string>>;
     restore(snapshot: Record<PaintTarget, Record<string, string>>): void;
 }
+/** @internal */
 export declare function createSurfacePaint(): SurfacePaintStore;
 export interface WallDrawTool {
     addPoint(point: Vec2, snap?: number): Vec2;
@@ -54,8 +61,10 @@ export interface WallDrawTool {
     footprint(): EnclosedFootprint | null;
     roof(config?: RoofConfig): RoofPlan | null;
 }
+/** @internal */
 export declare function createWallDrawTool(config?: {
     snap?: number;
     closeTolerance?: number;
 }): WallDrawTool;
+/** @internal */
 export declare function wallSegmentBounds(segment: WallSegment, thickness: number): Aabb;

package/dist/world/walls.js

@@ -1,4 +1,5 @@
 import { footprintAabb } from "./geometry.js";
+/** @internal */
 export function wallSegments(points, closed) {
     const segments = [];
     const count = closed ? points.length : points.length - 1;
@@ -11,6 +12,7 @@ export function wallSegments(points, closed) {
     }
     return segments;
 }
+/** @internal */
 export function isEnclosed(points, tolerance = 0.5) {
     if (points.length < 3)
         return false;
@@ -18,6 +20,7 @@ export function isEnclosed(points, tolerance = 0.5) {
     const last = points[points.length - 1];
     return Math.hypot(first[0] - last[0], first[1] - last[1]) <= tolerance;
 }
+/** @internal */
 export function enclosePath(points, tolerance = 0.5) {
     if (points.length < 3)
         return points;
@@ -25,6 +28,7 @@ export function enclosePath(points, tolerance = 0.5) {
         return points;
     return points.slice(0, points.length - 1);
 }
+/** @internal */
 export function polygonArea(polygon) {
     let sum = 0;
     for (let index = 0; index < polygon.length; index += 1) {
@@ -34,6 +38,7 @@ export function polygonArea(polygon) {
     }
     return Math.abs(sum) / 2;
 }
+/** @internal */
 export function footprintFromWalls(points, tolerance = 0.5) {
     const closed = isEnclosed(points, tolerance);
     const polygon = enclosePath(points, tolerance);
@@ -65,6 +70,7 @@ export function footprintFromWalls(points, tolerance = 0.5) {
         closed,
     };
 }
+/** @internal */
 export function autoRoof(footprint, config = {}) {
     const style = config.style ?? "hip";
     const eaveHeight = config.eaveHeight ?? 3;
@@ -131,6 +137,7 @@ export function autoRoof(footprint, config = {}) {
     }
     return { style, ridge, apexHeight, eaveHeight, faces };
 }
+/** @internal */
 export function createSurfacePaint() {
     const maps = {
         floor: new Map(),
@@ -166,6 +173,7 @@ function snapPoint(point, grid) {
         return point;
     return [Math.round(point[0] / grid) * grid, Math.round(point[1] / grid) * grid];
 }
+/** @internal */
 export function createWallDrawTool(config = {}) {
     const defaultSnap = config.snap ?? 0;
     const closeTolerance = config.closeTolerance ?? 0.5;
@@ -214,6 +222,7 @@ export function createWallDrawTool(config = {}) {
         },
     };
 }
+/** @internal */
 export function wallSegmentBounds(segment, thickness) {
     const center = [(segment.from[0] + segment.to[0]) / 2, (segment.from[1] + segment.to[1]) / 2];
     const quarterTurns = Math.abs(Math.round(segment.angle / (Math.PI / 2))) % 2;

package/dist/world/waterKind.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `water` studio: a parametric water surface authored as a box volume — its XZ footprint becomes the
+ * water plane, its top face the water height. Pure config here (color/wave/foam/opacity params + a
+ * footprint resolver); the animated shader plane lives in the `shell` renderer, which maps these
+ * params onto the existing Ocean material. A scene kind so a pond or moat is dragged in the editor and
+ * tuned with sliders, persisted in `editor.scene.json`. Distinct from the infinite `waterSurface`
+ * ocean primitive (`./water`) — this is a bounded, editor-authored patch.
+ *
+ * @capability water parametric water surface volume
+ */
+import { type ParamSchema, type SceneKindObject } from "../scene/sceneKinds.js";
+/** The editor volume kind marking a box as a water surface. */
+export declare const WATER_VOLUME_KIND = "water";
+/** Fully-defaulted water surface params parsed from a volume's `meta`. */
+export interface WaterRules {
+    /** Deep-water base color (hex). */
+    color: string;
+    /** Shallow/edge tint blended toward the shore (hex). */
+    shallowColor: string;
+    /** Wave amplitude in meters. */
+    waveHeight: number;
+    /** Wave scroll speed multiplier. */
+    waveSpeed: number;
+    /** Spatial wave frequency (waves per meter). */
+    waveScale: number;
+    /** Foam band width at the shoreline, meters. */
+    foam: number;
+    /** Surface opacity, 0..1. */
+    opacity: number;
+    /** Reflection/metalness strength, 0..1. */
+    reflectivity: number;
+}
+/** Water defaults: a calm blue-green pond with a soft foam edge. */
+export declare const WATER_DEFAULTS: WaterRules;
+/** The water parameter schema — drives the inspector and `meta` parse via the studio seam. */
+export declare const WATER_SCHEMA: ParamSchema;
+/** Parse a volume's `meta` into fully-defaulted water rules. @internal */
+export declare function readWaterRules(meta: Record<string, unknown> | undefined): WaterRules;
+/** A resolved water surface: world-space plane center/size (XZ) at surface height `y`, plus its params. */
+export interface ResolvedWater {
+    center: readonly [number, number, number];
+    /** Full width (X) and depth (Z) of the water plane in meters. */
+    size: readonly [number, number];
+    rules: WaterRules;
+}
+/**
+ * Resolve a water volume into a flat surface: the box footprint (`halfExtents`, else `radius`) becomes
+ * the plane size, the box top (`center.y + halfExtents.y`) the water height. Returns null for a
+ * degenerate footprint. Reads footprint from the object's `halfExtents`/`radius` meta mirror written
+ * by the volume, falling back to a 20 m square.
+ * @internal
+ */
+export declare function resolveWaterObject(object: SceneKindObject): ResolvedWater | null;
+/** Registers the `water` scene kind (schema + resolver). Called by {@link registerBuiltinSceneKinds}. @internal */
+export declare function registerWaterKind(): void;

package/dist/world/waterKind.js

@@ -0,0 +1,99 @@
+/**
+ * `water` studio: a parametric water surface authored as a box volume — its XZ footprint becomes the
+ * water plane, its top face the water height. Pure config here (color/wave/foam/opacity params + a
+ * footprint resolver); the animated shader plane lives in the `shell` renderer, which maps these
+ * params onto the existing Ocean material. A scene kind so a pond or moat is dragged in the editor and
+ * tuned with sliders, persisted in `editor.scene.json`. Distinct from the infinite `waterSurface`
+ * ocean primitive (`./water`) — this is a bounded, editor-authored patch.
+ *
+ * @capability water parametric water surface volume
+ */
+import { registerSceneKind } from "../scene/sceneKinds.js";
+/** The editor volume kind marking a box as a water surface. */
+export const WATER_VOLUME_KIND = "water";
+/** Water defaults: a calm blue-green pond with a soft foam edge. */
+export const WATER_DEFAULTS = {
+    color: "#1c6c86",
+    shallowColor: "#4bb6bf",
+    waveHeight: 0.12,
+    waveSpeed: 0.6,
+    waveScale: 0.35,
+    foam: 1.2,
+    opacity: 0.86,
+    reflectivity: 0.4,
+};
+/** The water parameter schema — drives the inspector and `meta` parse via the studio seam. */
+export const WATER_SCHEMA = {
+    fields: [
+        { type: "color", key: "color", label: "deep color", default: WATER_DEFAULTS.color },
+        { type: "color", key: "shallowColor", label: "shallow color", default: WATER_DEFAULTS.shallowColor },
+        { type: "range", key: "waveHeight", label: "wave height", min: 0, max: 1, step: 0.01, default: WATER_DEFAULTS.waveHeight, unit: "m" },
+        { type: "range", key: "waveSpeed", label: "wave speed", min: 0, max: 3, step: 0.05, default: WATER_DEFAULTS.waveSpeed },
+        { type: "range", key: "waveScale", label: "wave scale", min: 0.02, max: 2, step: 0.02, default: WATER_DEFAULTS.waveScale },
+        { type: "range", key: "foam", label: "foam edge", min: 0, max: 6, step: 0.1, default: WATER_DEFAULTS.foam, unit: "m" },
+        { type: "range", key: "opacity", label: "opacity", min: 0.1, max: 1, step: 0.01, default: WATER_DEFAULTS.opacity },
+        { type: "range", key: "reflectivity", label: "reflectivity", min: 0, max: 1, step: 0.01, default: WATER_DEFAULTS.reflectivity },
+    ],
+};
+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 : fallback;
+}
+/** Parse a volume's `meta` into fully-defaulted water rules. @internal */
+export function readWaterRules(meta) {
+    return {
+        color: metaString(meta, "color", WATER_DEFAULTS.color),
+        shallowColor: metaString(meta, "shallowColor", WATER_DEFAULTS.shallowColor),
+        waveHeight: Math.max(0, metaNumber(meta, "waveHeight", WATER_DEFAULTS.waveHeight)),
+        waveSpeed: Math.max(0, metaNumber(meta, "waveSpeed", WATER_DEFAULTS.waveSpeed)),
+        waveScale: Math.max(0.01, metaNumber(meta, "waveScale", WATER_DEFAULTS.waveScale)),
+        foam: Math.max(0, metaNumber(meta, "foam", WATER_DEFAULTS.foam)),
+        opacity: Math.min(1, Math.max(0, metaNumber(meta, "opacity", WATER_DEFAULTS.opacity))),
+        reflectivity: Math.min(1, Math.max(0, metaNumber(meta, "reflectivity", WATER_DEFAULTS.reflectivity))),
+    };
+}
+/** Reads a numeric field off a possibly-untyped `{x,y,z}`-ish object. */
+function axis(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Resolve a water volume into a flat surface: the box footprint (`halfExtents`, else `radius`) becomes
+ * the plane size, the box top (`center.y + halfExtents.y`) the water height. Returns null for a
+ * degenerate footprint. Reads footprint from the object's `halfExtents`/`radius` meta mirror written
+ * by the volume, falling back to a 20 m square.
+ * @internal
+ */
+export function resolveWaterObject(object) {
+    const center = object.center ?? object.position;
+    if (center === undefined)
+        return null;
+    const meta = object.meta;
+    const he = object.halfExtents;
+    const radius = object.radius ?? axis(meta?.["radius"]);
+    const halfX = axis(he?.x) ?? radius ?? 10;
+    const halfZ = axis(he?.z) ?? radius ?? 10;
+    const halfY = axis(he?.y) ?? 0;
+    const width = Math.max(0.1, halfX * 2);
+    const depth = Math.max(0.1, halfZ * 2);
+    return { center: [center.x, center.y + halfY, center.z], size: [width, depth], rules: readWaterRules(meta) };
+}
+/** Registers the `water` scene kind (schema + resolver). Called by {@link registerBuiltinSceneKinds}. @internal */
+export function registerWaterKind() {
+    registerSceneKind({
+        kind: WATER_VOLUME_KIND,
+        target: "volume",
+        label: "Water surface",
+        addCategory: "Studios",
+        accent: "#38bdf8",
+        schema: WATER_SCHEMA,
+        resolve: (object) => resolveWaterObject(object),
+        note: (object) => {
+            const resolved = resolveWaterObject(object);
+            return resolved === null ? "Give the volume a box footprint." : `${Math.round(resolved.size[0])}×${Math.round(resolved.size[1])} m surface`;
+        },
+    });
+}