@jgengine/core 0.9.0 → 0.11.0

package/dist/world/scatterRegion.js

@@ -0,0 +1,409 @@
+import { masksInfluence, } from "./geometry.js";
+import { scatter } from "./scatter.js";
+/** The editor path kind that marks a closed polyline as a foliage/scatter region. */
+export const SCATTER_PATH_KIND = "scatter";
+/** Defaults a bare scatter region fills with: sparse grass, lightly spaced. */
+export const SCATTER_DEFAULTS = {
+    density: 0.15,
+    minSpacing: 1.5,
+    seed: "",
+    minScale: 0.8,
+    maxScale: 1.3,
+    minYaw: 0,
+    maxYaw: Math.PI * 2,
+    verticalOffset: 0,
+    alignToNormal: false,
+    maxSlope: 0,
+    minHeight: Number.NEGATIVE_INFINITY,
+    maxHeight: Number.POSITIVE_INFINITY,
+    edgeFalloff: 0,
+    jitter: 1,
+    palette: [{ item: "grass", weight: 1 }],
+    avoid: [],
+    autoAvoid: true,
+};
+/** Default clearance radius (m) for an auto-avoided gameplay marker with no explicit `meta.clearance`. */
+export const DEFAULT_MARKER_CLEARANCE = 3.5;
+/** Marker/volume kinds that repel scatter and flatten terrain by default (spawns, objectives, vendors). */
+export const DEFAULT_CLEARANCE_KINDS = [
+    "player_spawn",
+    "spawn",
+    "boss",
+    "goal",
+    "keep",
+    "vendor",
+    "chest",
+    "travel",
+];
+function hash(text) {
+    let h = 2166136261 >>> 0;
+    for (let i = 0; i < text.length; i += 1) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return (h >>> 0) / 4294967296;
+}
+/** Ray-casting point-in-polygon test on the XZ plane. */
+export function pointInPolygon(point, polygon) {
+    let inside = false;
+    const [px, pz] = point;
+    for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i, i += 1) {
+        const [xi, zi] = polygon[i];
+        const [xj, zj] = polygon[j];
+        if (zi > pz !== zj > pz && px < ((xj - xi) * (pz - zi)) / (zj - zi) + xi)
+            inside = !inside;
+    }
+    return inside;
+}
+function distanceToSegment(px, pz, ax, az, bx, bz) {
+    const dx = bx - ax;
+    const dz = bz - az;
+    const lenSq = dx * dx + dz * dz || 1;
+    let t = ((px - ax) * dx + (pz - az) * dz) / lenSq;
+    t = t < 0 ? 0 : t > 1 ? 1 : t;
+    return Math.hypot(px - (ax + dx * t), pz - (az + dz * t));
+}
+/** Shortest distance from a point to a polygon's boundary. */
+export function distanceToPolygonEdge(point, polygon) {
+    let best = Number.POSITIVE_INFINITY;
+    const [px, pz] = point;
+    for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i, i += 1) {
+        const [xi, zi] = polygon[i];
+        const [xj, zj] = polygon[j];
+        best = Math.min(best, distanceToSegment(px, pz, xi, zi, xj, zj));
+    }
+    return best;
+}
+/** Axis-aligned bounds of a polygon, or null if it has no points. */
+export function polygonBounds(polygon) {
+    if (polygon.length === 0)
+        return null;
+    let minX = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxZ = -Infinity;
+    for (const [x, z] of polygon) {
+        if (x < minX)
+            minX = x;
+        if (x > maxX)
+            maxX = x;
+        if (z < minZ)
+            minZ = z;
+        if (z > maxZ)
+            maxZ = z;
+    }
+    return { minX, minZ, maxX, maxZ };
+}
+/** Shoelace area of a polygon (always non-negative), in square meters. */
+export function polygonArea(polygon) {
+    if (polygon.length < 3)
+        return 0;
+    let sum = 0;
+    for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i, i += 1) {
+        const [xi, zi] = polygon[i];
+        const [xj, zj] = polygon[j];
+        sum += xj * zi - xi * zj;
+    }
+    return Math.abs(sum) / 2;
+}
+function pickWeighted(palette, roll) {
+    if (palette.length === 0)
+        return "grass";
+    const total = palette.reduce((sum, entry) => sum + Math.max(0, entry.weight), 0);
+    if (total <= 0)
+        return palette[0].item;
+    let acc = roll * total;
+    for (const entry of palette) {
+        acc -= Math.max(0, entry.weight);
+        if (acc <= 0)
+            return entry.item;
+    }
+    return palette[palette.length - 1].item;
+}
+/**
+ * Deterministic placements for one scatter region: scatter its polygon footprint at `density`
+ * items/m² (respecting `minSpacing`), clip to the polygon, thin near the edge, drop placements
+ * outside the slope/height mask, and derive item/scale/yaw from the region id + seed — so the same
+ * saved region always grows the same field. Grounds each instance on `terrain` when provided.
+ */
+export function resolveScatterRegion(region, terrain, avoid) {
+    const rules = region.rules;
+    const bounds = polygonBounds(region.polygon);
+    if (bounds === null || region.polygon.length < 3 || rules.density <= 0)
+        return [];
+    const ownDiscs = rules.avoid ?? [];
+    const masks = {
+        discs: avoid === undefined ? ownDiscs : ownDiscs.length === 0 ? avoid.discs : [...ownDiscs, ...avoid.discs],
+        corridors: avoid?.corridors ?? [],
+    };
+    const hasMasks = masks.discs.length > 0 || masks.corridors.length > 0;
+    const points = scatter({
+        area: bounds,
+        density: rules.density,
+        minDistance: rules.minSpacing,
+        jitter: rules.jitter,
+        seed: `${region.id}:${rules.seed}`,
+    });
+    const instances = [];
+    for (const point of points) {
+        const p = [point.x, point.z];
+        if (!pointInPolygon(p, region.polygon))
+            continue;
+        // Clearance masks repel scatter: hard reject in the solid core, thin probabilistically in the feather.
+        if (hasMasks) {
+            const influence = masksInfluence(point.x, point.z, masks);
+            if (influence >= 1)
+                continue;
+            if (influence > 0 && hash(`${region.id}:avoid:${point.index}`) < influence)
+                continue;
+        }
+        if (rules.edgeFalloff > 0) {
+            const edge = distanceToPolygonEdge(p, region.polygon);
+            if (edge < rules.edgeFalloff && hash(`${region.id}:edge:${point.index}`) > edge / rules.edgeFalloff)
+                continue;
+        }
+        let y = rules.verticalOffset;
+        let normal;
+        if (terrain !== undefined) {
+            const height = terrain.sampleHeight(point.x, point.z);
+            if (height < rules.minHeight || height > rules.maxHeight)
+                continue;
+            const n = terrain.sampleNormal(point.x, point.z);
+            if (rules.maxSlope > 0) {
+                const slope = Math.hypot(n[0], n[2]) / Math.max(n[1], 1e-9);
+                if (slope > rules.maxSlope)
+                    continue;
+            }
+            y = height + rules.verticalOffset;
+            if (rules.alignToNormal)
+                normal = n;
+        }
+        const scaleRoll = hash(`${region.id}:${rules.seed}:scale:${point.index}`);
+        const yawRoll = hash(`${region.id}:${rules.seed}:yaw:${point.index}`);
+        const itemRoll = hash(`${region.id}:${rules.seed}:item:${point.index}`);
+        instances.push({
+            id: `${region.id}/${point.index}`,
+            regionId: region.id,
+            item: pickWeighted(rules.palette, itemRoll),
+            x: point.x,
+            y,
+            z: point.z,
+            rotationY: rules.minYaw + (rules.maxYaw - rules.minYaw) * yawRoll,
+            scale: rules.minScale + (rules.maxScale - rules.minScale) * scaleRoll,
+            ...(normal === undefined ? {} : { normal }),
+        });
+    }
+    return instances;
+}
+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;
+}
+function metaBool(meta, key, fallback) {
+    const value = meta?.[key];
+    return typeof value === "boolean" ? value : fallback;
+}
+/** Parses a scatter region's palette from meta: a weighted `palette` array, else a single `item`. */
+export function readScatterPalette(meta) {
+    const raw = meta?.["palette"];
+    if (Array.isArray(raw)) {
+        const entries = raw
+            .filter((entry) => typeof entry === "object" && entry !== null)
+            .map((entry) => ({
+            item: typeof entry.item === "string" ? entry.item : "grass",
+            weight: typeof entry.weight === "number" && Number.isFinite(entry.weight) ? Math.max(0, entry.weight) : 1,
+        }))
+            .filter((entry) => entry.item.length > 0);
+        if (entries.length > 0)
+            return entries;
+    }
+    const single = metaString(meta, "item", "");
+    if (single.length > 0)
+        return [{ item: single, weight: 1 }];
+    return [...SCATTER_DEFAULTS.palette];
+}
+/** True when an editor path is a foliage/scatter region. */
+export function isScatterPath(path) {
+    return path.kind === SCATTER_PATH_KIND;
+}
+/** The path's scatter rules with defaults filled in; null for non-scatter paths. */
+export function readScatterRules(path) {
+    if (!isScatterPath(path))
+        return null;
+    const meta = path.meta;
+    return {
+        density: Math.max(0, metaNumber(meta, "density", SCATTER_DEFAULTS.density)),
+        minSpacing: Math.max(0, metaNumber(meta, "minSpacing", SCATTER_DEFAULTS.minSpacing)),
+        seed: metaString(meta, "seed", SCATTER_DEFAULTS.seed),
+        minScale: metaNumber(meta, "minScale", SCATTER_DEFAULTS.minScale),
+        maxScale: metaNumber(meta, "maxScale", SCATTER_DEFAULTS.maxScale),
+        minYaw: metaNumber(meta, "minYaw", SCATTER_DEFAULTS.minYaw),
+        maxYaw: metaNumber(meta, "maxYaw", SCATTER_DEFAULTS.maxYaw),
+        verticalOffset: metaNumber(meta, "verticalOffset", SCATTER_DEFAULTS.verticalOffset),
+        alignToNormal: metaBool(meta, "alignToNormal", SCATTER_DEFAULTS.alignToNormal),
+        maxSlope: Math.max(0, metaNumber(meta, "maxSlope", SCATTER_DEFAULTS.maxSlope)),
+        minHeight: metaNumber(meta, "minHeight", SCATTER_DEFAULTS.minHeight),
+        maxHeight: metaNumber(meta, "maxHeight", SCATTER_DEFAULTS.maxHeight),
+        edgeFalloff: Math.max(0, metaNumber(meta, "edgeFalloff", SCATTER_DEFAULTS.edgeFalloff)),
+        jitter: metaNumber(meta, "jitter", SCATTER_DEFAULTS.jitter),
+        palette: readScatterPalette(meta),
+        avoid: readAvoidZones(meta),
+        autoAvoid: metaBool(meta, "autoAvoid", SCATTER_DEFAULTS.autoAvoid),
+    };
+}
+/**
+ * Parses a region's manual clearance discs from `meta.avoid` (array of {x,z,radius,feather?}).
+ * @internal — used by `readScatterRules`; games author `avoid` through the region inspector.
+ */
+export function readAvoidZones(meta) {
+    const raw = meta?.["avoid"];
+    if (!Array.isArray(raw))
+        return [];
+    const zones = [];
+    for (const entry of raw) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const e = entry;
+        if (typeof e.x !== "number" || typeof e.z !== "number" || typeof e.radius !== "number")
+            continue;
+        zones.push({
+            x: e.x,
+            z: e.z,
+            radius: Math.max(0, e.radius),
+            ...(typeof e.feather === "number" ? { feather: Math.max(0, e.feather) } : {}),
+        });
+    }
+    return zones;
+}
+/** Builds a resolvable {@link ScatterRegion} from a scatter path (XZ polygon + rules), or null. */
+export function scatterRegionFromPath(path) {
+    const rules = readScatterRules(path);
+    if (rules === null || path.points.length < 3)
+        return null;
+    return {
+        id: path.id,
+        polygon: path.points.map((point) => [point.x, point.z]),
+        rules,
+    };
+}
+/** Estimated placement count for a scatter path — density × polygon area, for a live UI readout. */
+export function scatterRegionEstimate(path) {
+    const rules = readScatterRules(path);
+    if (rules === null)
+        return { area: 0, count: 0 };
+    const area = polygonArea(path.points.map((point) => [point.x, point.z]));
+    return { area, count: Math.floor(area * rules.density) };
+}
+/** Reads a gameplay object's clearance radius: explicit `meta.clearance`, else a kind default, else 0. */
+function clearanceOf(kind, meta, kinds, defaultClearance) {
+    const explicit = meta?.["clearance"];
+    if (typeof explicit === "number" && Number.isFinite(explicit))
+        return Math.max(0, explicit);
+    return kinds.includes(kind) ? defaultClearance : 0;
+}
+/**
+ * Point-pad clearance **discs** from a document's markers/volumes — the terrain-flatten set (spawns,
+ * plots, POIs get a level pad). A marker/volume contributes a disc when it carries `meta.clearance`
+ * or its kind is in `kinds`. Paths are *not* included (they render draped, never flattened — see
+ * {@link clearanceMasksFrom} for their foliage corridor). Pass `ids`/`kinds` to scope it.
+ */
+export function clearanceZonesFrom(doc, options = {}) {
+    const kinds = options.ids !== undefined ? [] : options.kinds ?? DEFAULT_CLEARANCE_KINDS;
+    const idSet = options.ids === undefined ? null : new Set(options.ids);
+    const defaultClearance = options.defaultClearance ?? DEFAULT_MARKER_CLEARANCE;
+    const feather = options.feather ?? 2;
+    const zones = [];
+    const consider = (id, kind, x, z, meta, extra) => {
+        if (idSet !== null && !idSet.has(id))
+            return;
+        const clearance = idSet !== null ? defaultClearance : clearanceOf(kind, meta, kinds, defaultClearance);
+        if (clearance <= 0)
+            return;
+        zones.push({ x, z, radius: clearance + extra, feather });
+    };
+    for (const marker of doc.markers)
+        consider(marker.id, marker.kind, marker.position.x, marker.position.z, marker.meta, 0);
+    for (const volume of doc.volumes)
+        consider(volume.id, volume.kind, volume.center.x, volume.center.z, volume.meta, volume.radius ?? 0);
+    return zones;
+}
+/**
+ * The full clearance region for scatter avoidance: point-pad {@link clearanceZonesFrom} **discs**
+ * plus clean-edged **corridors** along non-scatter paths (each `halfWidth` = `path.width/2 +
+ * clearance`). Corridors give a straight tree-line along a road instead of a scalloped disc chain —
+ * this is what `resolveScatter` auto-avoids. Set `includePaths: false` to drop the path corridors.
+ * @internal — `resolveScatter` builds these automatically; games rarely call it directly.
+ */
+export function clearanceMasksFrom(doc, options = {}) {
+    const kinds = options.ids !== undefined ? [] : options.kinds ?? DEFAULT_CLEARANCE_KINDS;
+    const idSet = options.ids === undefined ? null : new Set(options.ids);
+    const defaultClearance = options.defaultClearance ?? DEFAULT_MARKER_CLEARANCE;
+    const feather = options.feather ?? 2;
+    const includePaths = options.includePaths ?? true;
+    const corridors = [];
+    if (includePaths) {
+        for (const path of doc.paths) {
+            if (isScatterPath(path) || path.points.length < 2)
+                continue;
+            if (idSet !== null && !idSet.has(path.id))
+                continue;
+            const clearance = idSet !== null ? defaultClearance : clearanceOf(path.kind, path.meta, kinds, defaultClearance);
+            const explicit = typeof path.meta?.["clearance"] === "number";
+            if (clearance <= 0 && !explicit)
+                continue;
+            const half = (path.width ?? 4) / 2 + (clearance > 0 ? clearance : defaultClearance);
+            corridors.push({ points: path.points.map((point) => [point.x, point.z]), halfWidth: half, feather });
+        }
+    }
+    return { discs: clearanceZonesFrom(doc, options), corridors };
+}
+/**
+ * Every scatter region's placements across a document, grounded on `terrain` when provided. Regions
+ * honor clearance masks: their own manual `avoid` discs, plus (when the region's `autoAvoid` is on and
+ * `options.autoAvoid !== false`) the document-wide discs + path corridors from {@link clearanceMasksFrom}
+ * — so foliage auto-clears spawns, plots, and paths without hand-carving the polygon.
+ */
+export function resolveScatter(doc, terrain, options = {}) {
+    const baseDiscs = options.avoid ?? [];
+    const auto = options.autoAvoid === false ? { discs: [], corridors: [] } : clearanceMasksFrom(doc, options);
+    const out = [];
+    for (const path of doc.paths) {
+        const region = scatterRegionFromPath(path);
+        if (region === null)
+            continue;
+        const useAuto = region.rules.autoAvoid && options.autoAvoid !== false;
+        const masks = {
+            discs: useAuto ? [...baseDiscs, ...auto.discs] : baseDiscs,
+            corridors: useAuto ? auto.corridors : [],
+        };
+        out.push(...resolveScatterRegion(region, terrain, masks));
+    }
+    return out;
+}
+/**
+ * Buckets scatter instances into a uniform XZ grid of `chunkSize`-meter cells, so a dense region
+ * renders as many small draw units instead of one huge mesh — each chunk carries its own bounds and
+ * is frustum-culled independently, and offscreen chunks cost nothing. Empty chunks are omitted;
+ * order is deterministic (row-major by grid coordinate).
+ * @internal — the chunking behind the `InstancedScatter` renderer; not called directly by games.
+ */
+export function chunkScatterInstances(instances, chunkSize) {
+    const size = chunkSize > 0 ? chunkSize : 32;
+    const byKey = new Map();
+    for (const instance of instances) {
+        const gx = Math.floor(instance.x / size);
+        const gz = Math.floor(instance.z / size);
+        const key = `${gx}:${gz}`;
+        let chunk = byKey.get(key);
+        if (chunk === undefined) {
+            chunk = { key, min: [gx * size, gz * size], size, instances: [] };
+            byKey.set(key, chunk);
+        }
+        chunk.instances.push(instance);
+    }
+    return [...byKey.values()].sort((a, b) => a.key.localeCompare(b.key));
+}

package/dist/world/sceneShapes.d.ts

@@ -0,0 +1,43 @@
+/** A world-space point — structurally compatible with the editor's `EditorVec3`. */
+export interface ScenePoint3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/** The minimal polyline shape {@link resolveScatterRegion} et al. read; any `EditorPath` satisfies it. */
+export interface ScenePathLike {
+    id: string;
+    kind: string;
+    points: readonly ScenePoint3[];
+    width?: number;
+    meta?: Record<string, unknown>;
+}
+/** The minimal point-object shape clearance reads from a document's markers; any `EditorMarker` satisfies it. */
+export interface SceneMarkerLike {
+    id: string;
+    kind: string;
+    position: ScenePoint3;
+    meta?: Record<string, unknown>;
+}
+/** The minimal volume shape vegetation/clearance/triggers read; any `EditorVolume` satisfies it. */
+export interface SceneVolumeLike {
+    id: string;
+    kind: string;
+    shape: "sphere" | "cylinder" | "box";
+    center: ScenePoint3;
+    radius?: number;
+    /** Cylinder height (m); containment and editors use this when shape is `cylinder`. */
+    height?: number;
+    halfExtents?: ScenePoint3;
+    meta?: Record<string, unknown>;
+}
+/**
+ * The minimal document shape scatter/vegetation resolve against — markers, volumes, and paths only.
+ * Any `EditorDocument` satisfies it structurally; this module never imports the editor domain, so
+ * world stays the one-directional dependency editor already builds on.
+ */
+export interface SceneDocumentLike {
+    markers: readonly SceneMarkerLike[];
+    volumes: readonly SceneVolumeLike[];
+    paths: readonly ScenePathLike[];
+}

package/dist/world/sceneShapes.js

@@ -0,0 +1 @@
+export {};

package/dist/world/segment.d.ts

@@ -0,0 +1,27 @@
+import type { Vec2 } from "./geometry.js";
+/** Closest point on segment `a`→`b` to `p`, and the clamped parameter `t` in [0,1] where it lies. */
+export interface ClosestOnSegment {
+    point: Vec2;
+    t: number;
+}
+/** Closest point on the segment `a`→`b` to point `p`, with the clamped parameter `t` (0 at `a`, 1 at `b`). */
+export declare function closestPointOnSegment(p: Vec2, a: Vec2, b: Vec2): ClosestOnSegment;
+/** A resolved circle-vs-segment contact. */
+export interface CircleSegmentHit {
+    /** Unit surface normal pointing from the segment toward the circle center — the axis to bounce off. */
+    normal: Vec2;
+    /** Penetration depth; push the center out by `normal · depth` to separate. */
+    depth: number;
+    /** Closest point on the segment (the contact point). */
+    contact: Vec2;
+    /** Circle center pushed just outside the segment — a tunnel-proof resolved position. */
+    resolved: Vec2;
+}
+/**
+ * Circle (center + `radius`) against a capsule segment `a`→`b` of half-thickness `thickness` (0 for a thin
+ * wall). Returns the contact — surface normal, penetration depth, contact point, and the separated center —
+ * or `null` when they do not overlap. Endpoints are rounded (the segment is a capsule), so a ball never
+ * catches on a corner. Reflect the velocity across `normal` for the bounce; the pure geometry every 2D
+ * ball game (pinball, breakout, air hockey) reimplemented per wall, bumper, and paddle.
+ */
+export declare function circleVsSegment(center: Vec2, radius: number, a: Vec2, b: Vec2, thickness?: number): CircleSegmentHit | null;

package/dist/world/segment.js

@@ -0,0 +1,43 @@
+/** Closest point on the segment `a`→`b` to point `p`, with the clamped parameter `t` (0 at `a`, 1 at `b`). */
+export function closestPointOnSegment(p, a, b) {
+    const abx = b[0] - a[0];
+    const aby = b[1] - a[1];
+    const l2 = abx * abx + aby * aby;
+    const raw = l2 > 0 ? ((p[0] - a[0]) * abx + (p[1] - a[1]) * aby) / l2 : 0;
+    const t = raw < 0 ? 0 : raw > 1 ? 1 : raw;
+    return { point: [a[0] + t * abx, a[1] + t * aby], t };
+}
+/**
+ * Circle (center + `radius`) against a capsule segment `a`→`b` of half-thickness `thickness` (0 for a thin
+ * wall). Returns the contact — surface normal, penetration depth, contact point, and the separated center —
+ * or `null` when they do not overlap. Endpoints are rounded (the segment is a capsule), so a ball never
+ * catches on a corner. Reflect the velocity across `normal` for the bounce; the pure geometry every 2D
+ * ball game (pinball, breakout, air hockey) reimplemented per wall, bumper, and paddle.
+ */
+export function circleVsSegment(center, radius, a, b, thickness = 0) {
+    const { point } = closestPointOnSegment(center, a, b);
+    const dx = center[0] - point[0];
+    const dy = center[1] - point[1];
+    const dist = Math.hypot(dx, dy);
+    const reach = radius + thickness;
+    if (dist >= reach)
+        return null;
+    let nx;
+    let ny;
+    if (dist > 1e-6) {
+        nx = dx / dist;
+        ny = dy / dist;
+    }
+    else {
+        const segLen = Math.hypot(b[0] - a[0], b[1] - a[1]);
+        nx = segLen > 1e-6 ? -(b[1] - a[1]) / segLen : 0;
+        ny = segLen > 1e-6 ? (b[0] - a[0]) / segLen : 1;
+    }
+    const depth = reach - dist;
+    return {
+        normal: [nx, ny],
+        depth,
+        contact: point,
+        resolved: [point[0] + nx * reach, point[1] + ny * reach],
+    };
+}

package/dist/world/soilKind.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `soil` studio: a crack/moss ground-variation patch authored as a box volume — its XZ footprint is
+ * the patch area, its top the ground height (same footprint convention as `grass_field`). Pure config
+ * here (crack scale/intensity/color, moss coverage/color, seed + a footprint resolver); the Worley
+ * (cellular) crack mask and FBM moss mask, injected via `onBeforeCompile` into a soil-patch material
+ * built from the same noise machinery as the terrain detail material, live in the `shell` renderer. An
+ * engine environment kind (like water/grass_field) so cracked, mossy ground is slider-authorable in
+ * the editor and persisted in `editor.scene.json` — the #815 soil studio.
+ */
+import { type ParamSchema, type SceneKindObject } from "../scene/sceneKinds.js";
+/**
+ * The editor volume kind marking a box as a soil crack/moss patch.
+ * @capability soil-patch editor-authorable terrain crack/moss material variation
+ */
+export declare const SOIL_KIND = "soil";
+/** Fully-defaulted soil params parsed from a volume's `meta`. */
+export interface SoilRules {
+    /** Underlying dirt/soil base tint, hex. */
+    baseColor: string;
+    /** Worley cell size in meters — larger cells read as bigger cracked-earth plates. */
+    crackScale: number;
+    /** Crack-line color blended into the cell boundaries, hex. */
+    crackColor: string;
+    /** Crack blend strength, 0..1. */
+    crackIntensity: number;
+    /** Moss patch color, hex. */
+    mossColor: string;
+    /** Fraction of the patch covered by moss, 0..1. */
+    mossCoverage: number;
+    /** Seed string; same seed reproduces the same crack/moss layout. */
+    seed: string;
+}
+/** Soil defaults: sun-cracked dirt with light moss creep. */
+export declare const SOIL_DEFAULTS: SoilRules;
+/** The soil parameter schema — drives the inspector and `meta` parse via the studio seam. */
+export declare const SOIL_SCHEMA: ParamSchema;
+/** Parse a volume's `meta` into fully-defaulted soil rules. @internal */
+export declare function readSoilRules(meta: Record<string, unknown> | undefined): SoilRules;
+/** A resolved soil patch: world-space area center at ground height, footprint size (XZ), and rules. */
+export interface ResolvedSoil {
+    center: readonly [number, number, number];
+    size: readonly [number, number];
+    rules: SoilRules;
+}
+/** Resolve a soil volume into an area footprint (from box half-extents / radius) at the box base. @internal */
+export declare function resolveSoilObject(object: SceneKindObject): ResolvedSoil | null;
+/** Registers the `soil` scene kind (schema + resolver). Called by {@link registerBuiltinSceneKinds}. @internal */
+export declare function registerSoilKind(): void;

package/dist/world/soilKind.js

@@ -0,0 +1,92 @@
+/**
+ * `soil` studio: a crack/moss ground-variation patch authored as a box volume — its XZ footprint is
+ * the patch area, its top the ground height (same footprint convention as `grass_field`). Pure config
+ * here (crack scale/intensity/color, moss coverage/color, seed + a footprint resolver); the Worley
+ * (cellular) crack mask and FBM moss mask, injected via `onBeforeCompile` into a soil-patch material
+ * built from the same noise machinery as the terrain detail material, live in the `shell` renderer. An
+ * engine environment kind (like water/grass_field) so cracked, mossy ground is slider-authorable in
+ * the editor and persisted in `editor.scene.json` — the #815 soil studio.
+ */
+import { registerSceneKind } from "../scene/sceneKinds.js";
+/**
+ * The editor volume kind marking a box as a soil crack/moss patch.
+ * @capability soil-patch editor-authorable terrain crack/moss material variation
+ */
+export const SOIL_KIND = "soil";
+/** Soil defaults: sun-cracked dirt with light moss creep. */
+export const SOIL_DEFAULTS = {
+    baseColor: "#8a7256",
+    crackScale: 3,
+    crackColor: "#42301f",
+    crackIntensity: 0.65,
+    mossColor: "#5c7a3a",
+    mossCoverage: 0.22,
+    seed: "",
+};
+/** The soil parameter schema — drives the inspector and `meta` parse via the studio seam. */
+export const SOIL_SCHEMA = {
+    fields: [
+        { type: "color", key: "baseColor", label: "base color", default: SOIL_DEFAULTS.baseColor },
+        { type: "range", key: "crackScale", label: "crack scale", min: 0.5, max: 12, step: 0.25, default: SOIL_DEFAULTS.crackScale, unit: "m" },
+        { type: "color", key: "crackColor", label: "crack color", default: SOIL_DEFAULTS.crackColor },
+        { type: "range", key: "crackIntensity", label: "crack intensity", min: 0, max: 1, step: 0.02, default: SOIL_DEFAULTS.crackIntensity },
+        { type: "color", key: "mossColor", label: "moss color", default: SOIL_DEFAULTS.mossColor },
+        { type: "range", key: "mossCoverage", label: "moss coverage", min: 0, max: 1, step: 0.02, default: SOIL_DEFAULTS.mossCoverage },
+        { type: "seed", key: "seed", label: "seed", default: "" },
+    ],
+};
+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 soil rules. @internal */
+export function readSoilRules(meta) {
+    return {
+        baseColor: metaString(meta, "baseColor", SOIL_DEFAULTS.baseColor),
+        crackScale: Math.max(0.1, metaNumber(meta, "crackScale", SOIL_DEFAULTS.crackScale)),
+        crackColor: metaString(meta, "crackColor", SOIL_DEFAULTS.crackColor),
+        crackIntensity: Math.min(1, Math.max(0, metaNumber(meta, "crackIntensity", SOIL_DEFAULTS.crackIntensity))),
+        mossColor: metaString(meta, "mossColor", SOIL_DEFAULTS.mossColor),
+        mossCoverage: Math.min(1, Math.max(0, metaNumber(meta, "mossCoverage", SOIL_DEFAULTS.mossCoverage))),
+        seed: metaString(meta, "seed", SOIL_DEFAULTS.seed),
+    };
+}
+function axis(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/** Resolve a soil volume into an area footprint (from box half-extents / radius) at the box base. @internal */
+export function resolveSoilObject(object) {
+    const center = object.center ?? object.position;
+    if (center === undefined)
+        return null;
+    const he = object.halfExtents;
+    const radius = object.radius;
+    const halfX = axis(he?.x) ?? radius ?? 6;
+    const halfZ = axis(he?.z) ?? radius ?? 6;
+    const halfY = axis(he?.y) ?? 0;
+    return {
+        center: [center.x, center.y - halfY, center.z],
+        size: [Math.max(0.5, halfX * 2), Math.max(0.5, halfZ * 2)],
+        rules: readSoilRules(object.meta),
+    };
+}
+/** Registers the `soil` scene kind (schema + resolver). Called by {@link registerBuiltinSceneKinds}. @internal */
+export function registerSoilKind() {
+    registerSceneKind({
+        kind: SOIL_KIND,
+        target: "volume",
+        label: "Soil patch",
+        addCategory: "Studios",
+        accent: "#8a6d4a",
+        schema: SOIL_SCHEMA,
+        resolve: (object) => resolveSoilObject(object),
+        note: (object) => {
+            const resolved = resolveSoilObject(object);
+            return resolved === null ? "Give the volume a box footprint." : `${Math.round(resolved.size[0])}×${Math.round(resolved.size[1])} m patch`;
+        },
+    });
+}