@jgengine/shell 0.6.0 → 0.8.0

package/dist/pointer/PointerProbe.js

@@ -0,0 +1,40 @@
+import { useThree } from "@react-three/fiber";
+import { useEffect } from "react";
+export function PointerProbe({ service }) {
+    const camera = useThree((state) => state.camera);
+    const scene = useThree((state) => state.scene);
+    const gl = useThree((state) => state.gl);
+    const size = useThree((state) => state.size);
+    service.bind({ camera, scene, width: size.width, height: size.height });
+    useEffect(() => {
+        const el = gl.domElement;
+        let locked = false;
+        const onMove = (event) => {
+            if (locked)
+                return;
+            const rect = el.getBoundingClientRect();
+            const x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
+            const y = -(((event.clientY - rect.top) / rect.height) * 2 - 1);
+            service.setCursor(x, y, true);
+        };
+        const onLeave = () => {
+            if (!locked)
+                service.setCursor(0, 0, false);
+        };
+        const onLockChange = () => {
+            locked = document.pointerLockElement === el;
+            if (locked)
+                service.setCursor(0, 0, true);
+        };
+        el.addEventListener("pointermove", onMove);
+        el.addEventListener("pointerleave", onLeave);
+        document.addEventListener("pointerlockchange", onLockChange);
+        return () => {
+            el.removeEventListener("pointermove", onMove);
+            el.removeEventListener("pointerleave", onLeave);
+            document.removeEventListener("pointerlockchange", onLockChange);
+            service.bind(null);
+        };
+    }, [gl, service]);
+    return null;
+}

package/dist/pointer/pointerService.d.ts

@@ -0,0 +1,26 @@
+import * as THREE from "three";
+import type { PointerHit, PointerVec3 } from "@jgengine/core/input/pointer";
+export declare const POINTER_ENTITY_KEY = "jgEntityId";
+export declare const POINTER_OBJECT_KEY = "jgObjectId";
+interface PointerDeps {
+    camera: THREE.Camera;
+    scene: THREE.Scene;
+    width: number;
+    height: number;
+}
+export interface PointerService {
+    /** Cast the current cursor into the world; null when the cursor is off-canvas. */
+    worldHit(): PointerHit | null;
+    /** Cast from the viewport center regardless of cursor presence (pointer-lock aim); null before the probe binds. */
+    worldHitCenter(): PointerHit | null;
+    /** Project a world point to CSS pixels for the marquee / HUD; null before the probe binds. */
+    screenOf(world: PointerVec3): {
+        x: number;
+        y: number;
+    } | null;
+    hasCursor(): boolean;
+    bind(deps: PointerDeps | null): void;
+    setCursor(ndcX: number, ndcY: number, present: boolean): void;
+}
+export declare function createPointerService(): PointerService;
+export {};

package/dist/pointer/pointerService.js

@@ -0,0 +1,89 @@
+import * as THREE from "three";
+export const POINTER_ENTITY_KEY = "jgEntityId";
+export const POINTER_OBJECT_KEY = "jgObjectId";
+function tagOf(object, key) {
+    let cursor = object;
+    while (cursor !== null) {
+        const value = cursor.userData[key];
+        if (typeof value === "string")
+            return value;
+        cursor = cursor.parent;
+    }
+    return null;
+}
+function standardMaterialSample(material) {
+    const candidates = Array.isArray(material) ? material : [material];
+    const standard = candidates.find((entry) => entry instanceof THREE.MeshStandardMaterial);
+    if (standard === undefined)
+        return null;
+    return { color: `#${standard.color.getHexString()}`, metalness: standard.metalness, roughness: standard.roughness };
+}
+export function createPointerService() {
+    const raycaster = new THREE.Raycaster();
+    const ndc = new THREE.Vector2();
+    const centerNdc = new THREE.Vector2(0, 0);
+    const scratch = new THREE.Vector3();
+    const normalMatrix = new THREE.Matrix3();
+    const groundPlane = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
+    let deps = null;
+    let cursorPresent = false;
+    function hitAtNdc(target) {
+        if (deps === null)
+            return null;
+        raycaster.setFromCamera(target, deps.camera);
+        const intersects = raycaster.intersectObjects(deps.scene.children, true);
+        for (const hit of intersects) {
+            const mesh = hit.object;
+            if (!mesh.isMesh)
+                continue;
+            const point = [hit.point.x, hit.point.y, hit.point.z];
+            let normal = [0, 1, 0];
+            if (hit.face !== null && hit.face !== undefined) {
+                normalMatrix.getNormalMatrix(hit.object.matrixWorld);
+                scratch.copy(hit.face.normal).applyMatrix3(normalMatrix).normalize();
+                normal = [scratch.x, scratch.y, scratch.z];
+            }
+            const uv = hit.uv !== undefined ? { u: hit.uv.x, v: hit.uv.y } : undefined;
+            return {
+                point,
+                normal,
+                entity: tagOf(hit.object, POINTER_ENTITY_KEY),
+                object: tagOf(hit.object, POINTER_OBJECT_KEY),
+                ...(uv !== undefined ? { uv } : {}),
+                material: standardMaterialSample(mesh.material),
+                ...(hit.instanceId !== undefined ? { instanceId: hit.instanceId } : {}),
+            };
+        }
+        const grounded = raycaster.ray.intersectPlane(groundPlane, scratch);
+        if (grounded === null)
+            return null;
+        return { point: [grounded.x, grounded.y, grounded.z], normal: [0, 1, 0], entity: null, object: null };
+    }
+    return {
+        hasCursor: () => cursorPresent,
+        bind: (next) => {
+            deps = next;
+        },
+        setCursor: (ndcX, ndcY, present) => {
+            ndc.set(ndcX, ndcY);
+            cursorPresent = present;
+        },
+        worldHit() {
+            if (!cursorPresent)
+                return null;
+            return hitAtNdc(ndc);
+        },
+        worldHitCenter() {
+            return hitAtNdc(centerNdc);
+        },
+        screenOf(world) {
+            if (deps === null)
+                return null;
+            scratch.set(world[0], world[1], world[2]).project(deps.camera);
+            return {
+                x: (scratch.x * 0.5 + 0.5) * deps.width,
+                y: (-scratch.y * 0.5 + 0.5) * deps.height,
+            };
+        },
+    };
+}

package/dist/registry.d.ts

@@ -1,6 +1,9 @@
 import type { ComponentType, ReactNode } from "react";
 import type { PlayableGame as EnginePlayableGame } from "@jgengine/core/game/playableGame";
 import type { SceneEntity } from "@jgengine/core/scene/entityStore";
+import type { SceneObject } from "@jgengine/core/scene/objectStore";
 export type RenderEntity = (entity: SceneEntity) => ReactNode;
-export type PlayableGame = EnginePlayableGame<ComponentType, ComponentType, RenderEntity>;
+export type RenderObject = (object: SceneObject) => ReactNode;
+export type PlayableGame = EnginePlayableGame<ComponentType, ComponentType, RenderEntity, RenderObject>;
 export type GameRegistry = Record<string, () => Promise<PlayableGame>>;
+export declare function resolveGameLoader(registry: GameRegistry, gameId: string, fallbackGameId?: string): (() => Promise<PlayableGame>) | undefined;

package/dist/registry.js

@@ -1 +1,3 @@
-export {};
+export function resolveGameLoader(registry, gameId, fallbackGameId) {
+    return registry[gameId] ?? (fallbackGameId === undefined ? undefined : registry[fallbackGameId]);
+}

package/dist/render/modelRender.d.ts

@@ -0,0 +1,14 @@
+import * as THREE from "three";
+import type { PaintStroke } from "@jgengine/core/scene/paintLayer";
+export declare const PAINT_TEXTURE_SIZE = 512;
+export declare function cloneModelScene(source: THREE.Object3D): THREE.Object3D;
+export declare function standardMaterialsOf(root: THREE.Object3D): THREE.MeshStandardMaterial[];
+export interface PaintCanvas {
+    canvas: HTMLCanvasElement;
+    context: CanvasRenderingContext2D;
+    texture: THREE.CanvasTexture;
+}
+export declare function createPaintCanvas(seed: THREE.MeshStandardMaterial, size?: number): PaintCanvas;
+export declare function drawPaintStrokes(paint: PaintCanvas, strokes: readonly PaintStroke[]): void;
+export declare function applyPaintTexture(root: THREE.Object3D, paint: PaintCanvas): void;
+export declare function syncPaintCanvas(paint: PaintCanvas, seedColor: THREE.Color, strokes: readonly PaintStroke[], drawnCount: number): number;

package/dist/render/modelRender.js

@@ -0,0 +1,79 @@
+import * as THREE from "three";
+import { clone as cloneSkinned } from "three/examples/jsm/utils/SkeletonUtils.js";
+export const PAINT_TEXTURE_SIZE = 512;
+export function cloneModelScene(source) {
+    const clone = cloneSkinned(source);
+    clone.traverse((node) => {
+        const mesh = node;
+        if (!mesh.isMesh)
+            return;
+        mesh.material = Array.isArray(mesh.material)
+            ? mesh.material.map((material) => material.clone())
+            : mesh.material.clone();
+    });
+    return clone;
+}
+function isMeshStandardMaterial(material) {
+    return material.isMeshStandardMaterial === true;
+}
+export function standardMaterialsOf(root) {
+    const materials = [];
+    root.traverse((node) => {
+        const mesh = node;
+        if (!mesh.isMesh)
+            return;
+        const list = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        for (const material of list)
+            if (isMeshStandardMaterial(material))
+                materials.push(material);
+    });
+    return materials;
+}
+export function createPaintCanvas(seed, size = PAINT_TEXTURE_SIZE) {
+    const canvas = document.createElement("canvas");
+    canvas.width = size;
+    canvas.height = size;
+    const context = canvas.getContext("2d");
+    const seedImage = seed.map?.image;
+    if (seedImage !== undefined && seedImage.width) {
+        context.drawImage(seedImage, 0, 0, size, size);
+    }
+    else {
+        context.fillStyle = `#${seed.color.getHexString()}`;
+        context.fillRect(0, 0, size, size);
+    }
+    const texture = new THREE.CanvasTexture(canvas);
+    texture.colorSpace = seed.map?.colorSpace ?? THREE.SRGBColorSpace;
+    return { canvas, context, texture };
+}
+export function drawPaintStrokes(paint, strokes) {
+    const { canvas, context, texture } = paint;
+    for (const stroke of strokes) {
+        context.fillStyle = stroke.color;
+        context.beginPath();
+        context.arc(stroke.u * canvas.width, (1 - stroke.v) * canvas.height, stroke.radius * canvas.width, 0, Math.PI * 2);
+        context.fill();
+    }
+    texture.needsUpdate = true;
+}
+export function applyPaintTexture(root, paint) {
+    for (const material of standardMaterialsOf(root)) {
+        material.map = paint.texture;
+        material.needsUpdate = true;
+    }
+}
+export function syncPaintCanvas(paint, seedColor, strokes, drawnCount) {
+    if (strokes.length < drawnCount) {
+        const { canvas, context } = paint;
+        context.clearRect(0, 0, canvas.width, canvas.height);
+        context.fillStyle = `#${seedColor.getHexString()}`;
+        context.fillRect(0, 0, canvas.width, canvas.height);
+        drawPaintStrokes(paint, strokes);
+        return strokes.length;
+    }
+    if (strokes.length > drawnCount) {
+        drawPaintStrokes(paint, strokes.slice(drawnCount));
+        return strokes.length;
+    }
+    return drawnCount;
+}

package/dist/replay/useSessionRecorder.d.ts

@@ -0,0 +1,14 @@
+import { type RecordingBuffer, type RecordingBufferOptions } from "@jgengine/core/sensor/recordingBuffer";
+import type { EntityPosition } from "@jgengine/core/scene/entityStore";
+export interface RecordedPose {
+    position: EntityPosition;
+    rotationY: number;
+}
+/**
+ * Session-recording buffer (#120) for replay / photo mode / kill-cam: records
+ * an entity's pose on game-time every frame into a `RecordingBuffer`, which a
+ * game can then `seek()` to scrub, drive an observer cam ghost, or export a
+ * kill-cam clip. Recording rides on `ctx.time.now()`, so pause/fast-forward
+ * scrub the recording exactly like the live sim.
+ */
+export declare function useSessionRecorder(entityId: string, options?: RecordingBufferOptions): RecordingBuffer<RecordedPose>;

package/dist/replay/useSessionRecorder.js

@@ -0,0 +1,22 @@
+import { useFrame } from "@react-three/fiber";
+import { useMemo } from "react";
+import { createRecordingBuffer } from "@jgengine/core/sensor/recordingBuffer";
+import { useGameContext } from "@jgengine/react/provider";
+/**
+ * Session-recording buffer (#120) for replay / photo mode / kill-cam: records
+ * an entity's pose on game-time every frame into a `RecordingBuffer`, which a
+ * game can then `seek()` to scrub, drive an observer cam ghost, or export a
+ * kill-cam clip. Recording rides on `ctx.time.now()`, so pause/fast-forward
+ * scrub the recording exactly like the live sim.
+ */
+export function useSessionRecorder(entityId, options) {
+    const ctx = useGameContext();
+    const buffer = useMemo(() => createRecordingBuffer(options), []);
+    useFrame(() => {
+        const entity = ctx.scene.entity.get(entityId);
+        if (entity === null)
+            return;
+        buffer.append(ctx.time.now(), { position: entity.position, rotationY: entity.rotationY });
+    });
+    return buffer;
+}

package/dist/structures/PlacementGhost.d.ts

@@ -0,0 +1,8 @@
+import type { PlacementPreview } from "@jgengine/core/world/placementController";
+export interface PlacementGhostProps {
+    preview: PlacementPreview | null;
+    height?: number;
+    validColor?: string;
+    invalidColor?: string;
+}
+export declare function PlacementGhost({ preview, height, validColor, invalidColor, }: PlacementGhostProps): import("react").JSX.Element | null;

package/dist/structures/PlacementGhost.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { quarterTurnsToRotationY } from "@jgengine/core/world/placementController";
+export function PlacementGhost({ preview, height = 1, validColor = "#34d399", invalidColor = "#f87171", }) {
+    const footprint = preview?.footprint;
+    const size = useMemo(() => [footprint?.w ?? 1, height, footprint?.d ?? 1], [footprint?.w, footprint?.d, height]);
+    if (preview === null)
+        return null;
+    const color = preview.valid ? validColor : invalidColor;
+    return (_jsxs("group", { position: [preview.center[0], preview.y, preview.center[1]], "rotation-y": quarterTurnsToRotationY(preview.quarterTurns), children: [_jsxs("mesh", { "position-y": height / 2, children: [_jsx("boxGeometry", { args: size }), _jsx("meshStandardMaterial", { color: color, transparent: true, opacity: 0.35, depthWrite: false, emissive: color, emissiveIntensity: 0.4 })] }), _jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.02, children: [_jsx("ringGeometry", { args: [Math.max(size[0], size[2]) * 0.5, Math.max(size[0], size[2]) * 0.5 + 0.12, 40] }), _jsx("meshBasicMaterial", { color: color, transparent: true, opacity: 0.85 })] })] }));
+}

package/dist/structures/index.d.ts

@@ -0,0 +1,2 @@
+export { BuildingBlock, GeneratedBuilding, type BuildingBlockProps, type GeneratedBuildingProps, } from "./GeneratedBuilding.js";
+export { PlacementGhost, type PlacementGhostProps } from "./PlacementGhost.js";

package/dist/structures/index.js

@@ -0,0 +1,2 @@
+export { BuildingBlock, GeneratedBuilding, } from "./GeneratedBuilding.js";
+export { PlacementGhost } from "./PlacementGhost.js";

package/dist/structures.d.ts

@@ -0,0 +1 @@
+export * from "./structures/index.js";

package/dist/structures.js

@@ -0,0 +1 @@
+export * from "./structures/index.js";

package/dist/terrain/CarvedTerrain.d.ts

@@ -0,0 +1,22 @@
+import { type ThreeElements } from "@react-three/fiber";
+import type { TerrainField } from "@jgengine/core/world/terrain";
+import { type FieldGroundOptions } from "./terrainMath.js";
+export interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" | "children" | "geometry" | "material"> {
+    /** The terrain field to mesh — a `CarvableField` renders its craters and mounds. */
+    field: TerrainField;
+    size?: FieldGroundOptions["size"];
+    segments?: FieldGroundOptions["segments"];
+    center?: FieldGroundOptions["center"];
+    colors?: FieldGroundOptions["colors"];
+    heightRange?: FieldGroundOptions["heightRange"];
+    roughness?: number;
+    metalness?: number;
+    /** Bump after a runtime carve/deposit to re-mesh the deformed surface. */
+    epoch?: number;
+}
+/**
+ * Renders a `TerrainField` as a deformed ground mesh — the crater/mound view for destructible terrain.
+ * Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl
+ * once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
+ */
+export declare function CarvedTerrain({ field, size, segments, center, colors, heightRange, roughness, metalness, receiveShadow, epoch, ...meshProps }: CarvedTerrainProps): import("react").JSX.Element;

package/dist/terrain/CarvedTerrain.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import {} from "@react-three/fiber";
+import { useEffect, useMemo } from "react";
+import * as THREE from "three";
+import { createFieldGroundGeometry } from "./terrainMath.js";
+/**
+ * Renders a `TerrainField` as a deformed ground mesh — the crater/mound view for destructible terrain.
+ * Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl
+ * once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
+ */
+export function CarvedTerrain({ field, size, segments, center, colors, heightRange, roughness = 0.95, metalness = 0, receiveShadow = true, epoch = 0, ...meshProps }) {
+    const geometry = useMemo(() => createFieldGroundGeometry(field, { size, segments, center, colors, heightRange }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [field, size, segments, center, colors, heightRange, epoch]);
+    const material = useMemo(() => new THREE.MeshStandardMaterial({ color: "#ffffff", roughness, metalness, vertexColors: true }), [metalness, roughness]);
+    useEffect(() => () => geometry.dispose(), [geometry]);
+    useEffect(() => () => material.dispose(), [material]);
+    return _jsx("mesh", { ...meshProps, geometry: geometry, material: material, receiveShadow: receiveShadow });
+}

package/dist/terrain/EditableGround.d.ts

@@ -0,0 +1,11 @@
+import type { Aabb } from "@jgengine/core/world/geometry";
+import type { EditableTerrain } from "@jgengine/core/world/terraform";
+export interface EditableGroundProps {
+    terrain: Pick<EditableTerrain, "sampleHeight" | "surfaceAt">;
+    bounds: Aabb;
+    segments?: number;
+    version?: number;
+    baseColor?: string;
+    surfaceColors?: Record<string, string>;
+}
+export declare function EditableGround({ terrain, bounds, segments, version, baseColor, surfaceColors, }: EditableGroundProps): import("react").JSX.Element;

package/dist/terrain/EditableGround.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import * as THREE from "three";
+const DEFAULT_SURFACE_COLORS = {
+    path: "#b8a06a",
+    gravel: "#8d8d84",
+    stone: "#7c7f86",
+    grass: "#4b7f3f",
+};
+export function EditableGround({ terrain, bounds, segments = 96, version = 0, baseColor = "#3f6b3a", surfaceColors = DEFAULT_SURFACE_COLORS, }) {
+    const geometry = useMemo(() => {
+        void version;
+        const width = bounds.maxX - bounds.minX;
+        const depth = bounds.maxZ - bounds.minZ;
+        const geo = new THREE.PlaneGeometry(width, depth, segments, segments);
+        geo.rotateX(-Math.PI / 2);
+        const position = geo.attributes.position;
+        const base = new THREE.Color(baseColor);
+        const colors = new Float32Array(position.count * 3);
+        const cx = (bounds.minX + bounds.maxX) / 2;
+        const cz = (bounds.minZ + bounds.maxZ) / 2;
+        for (let index = 0; index < position.count; index += 1) {
+            const x = position.getX(index) + cx;
+            const z = position.getZ(index) + cz;
+            position.setY(index, terrain.sampleHeight(x, z));
+            const surface = terrain.surfaceAt(x, z);
+            const color = surface !== null && surfaceColors[surface] !== undefined ? new THREE.Color(surfaceColors[surface]) : base;
+            colors[index * 3] = color.r;
+            colors[index * 3 + 1] = color.g;
+            colors[index * 3 + 2] = color.b;
+        }
+        geo.setAttribute("color", new THREE.BufferAttribute(colors, 3));
+        geo.computeVertexNormals();
+        return geo;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [terrain, bounds, segments, version, baseColor, surfaceColors]);
+    return (_jsx("mesh", { geometry: geometry, receiveShadow: true, children: _jsx("meshStandardMaterial", { vertexColors: true, roughness: 0.95, metalness: 0 }) }));
+}

package/dist/terrain/TerraformBrushCursor.d.ts

@@ -0,0 +1,8 @@
+import type { TerraformMode } from "@jgengine/core/world/terraform";
+export interface TerraformBrushCursorProps {
+    center: readonly [number, number] | null;
+    y?: number;
+    radius: number;
+    mode: TerraformMode;
+}
+export declare function TerraformBrushCursor({ center, y, radius, mode }: TerraformBrushCursorProps): import("react").JSX.Element | null;

package/dist/terrain/TerraformBrushCursor.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const MODE_COLOR = {
+    raise: "#38bdf8",
+    lower: "#fb923c",
+    flatten: "#a3e635",
+    paint: "#e879f9",
+};
+export function TerraformBrushCursor({ center, y = 0.05, radius, mode }) {
+    if (center === null)
+        return null;
+    const color = MODE_COLOR[mode];
+    return (_jsxs("group", { position: [center[0], y, center[1]], children: [_jsxs("mesh", { "rotation-x": -Math.PI / 2, children: [_jsx("ringGeometry", { args: [radius - 0.15, radius, 48] }), _jsx("meshBasicMaterial", { color: color, transparent: true, opacity: 0.9 })] }), _jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": -0.02, children: [_jsx("circleGeometry", { args: [radius, 48] }), _jsx("meshBasicMaterial", { color: color, transparent: true, opacity: 0.14, depthWrite: false })] })] }));
+}

package/dist/terrain/index.d.ts

@@ -1,7 +1,10 @@
+export { CarvedTerrain, type CarvedTerrainProps } from "./CarvedTerrain.js";
 export { GrassField, type GrassFieldProps } from "./GrassField.js";
 export { ProceduralGround, type ProceduralGroundProps } from "./ProceduralGround.js";
+export { EditableGround, type EditableGroundProps } from "./EditableGround.js";
+export { TerraformBrushCursor, type TerraformBrushCursorProps } from "./TerraformBrushCursor.js";
 export { createGrassBladeGeometry, resolveGrassBladeGeometryOptions, resolveGrassRange, type GrassBladeGeometryOptions, type GrassRange, type ResolvedGrassBladeGeometryOptions, } from "./grassGeometry.js";
 export { createGrassMaterial, DEFAULT_GRASS_WIND, resolveGrassWind, type GrassMaterialHandle, type GrassMaterialOptions, type GrassShaderUniforms, type GrassWindOptions, } from "./grassMaterial.js";
 export { createSeededRandom, hashNoise2, seedToUint32, type TerrainSeed } from "./random.js";
-export { createProceduralGroundGeometry, createProceduralTerrainSampler, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, type ProceduralTerrainConfig, type ResolvedTerrainSegments, type ResolvedTerrainSize, type TerrainArea, type TerrainHeightSampler, type TerrainVertexColorOptions, } from "./terrainMath.js";
+export { createFieldGroundGeometry, createProceduralGroundGeometry, createProceduralTerrainSampler, normalizeHeightBlend, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, type FieldGroundOptions, type ProceduralTerrainConfig, type ResolvedTerrainSegments, type ResolvedTerrainSize, type TerrainArea, type TerrainHeightSampler, type TerrainVertexColorOptions, } from "./terrainMath.js";
 export { arenaField, flatField, fractalNoise, noiseField, resolveGroundStep, resolveTerrainField, valueNoise, withNormal, type FractalNoiseConfig, type NoiseFieldConfig, type TerrainField, type TerrainNormal, } from "@jgengine/core/world/terrain";

package/dist/terrain/index.js

@@ -1,7 +1,10 @@
+export { CarvedTerrain } from "./CarvedTerrain.js";
 export { GrassField } from "./GrassField.js";
 export { ProceduralGround } from "./ProceduralGround.js";
+export { EditableGround } from "./EditableGround.js";
+export { TerraformBrushCursor } from "./TerraformBrushCursor.js";
 export { createGrassBladeGeometry, resolveGrassBladeGeometryOptions, resolveGrassRange, } from "./grassGeometry.js";
 export { createGrassMaterial, DEFAULT_GRASS_WIND, resolveGrassWind, } from "./grassMaterial.js";
 export { createSeededRandom, hashNoise2, seedToUint32 } from "./random.js";
-export { createProceduralGroundGeometry, createProceduralTerrainSampler, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, } from "./terrainMath.js";
+export { createFieldGroundGeometry, createProceduralGroundGeometry, createProceduralTerrainSampler, normalizeHeightBlend, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, } from "./terrainMath.js";
 export { arenaField, flatField, fractalNoise, noiseField, resolveGroundStep, resolveTerrainField, valueNoise, withNormal, } from "@jgengine/core/world/terrain";

package/dist/terrain/terrainMath.d.ts

@@ -1,4 +1,4 @@
-import { type NoiseFieldConfig } from "@jgengine/core/world/terrain";
+import { type NoiseFieldConfig, type TerrainField } from "@jgengine/core/world/terrain";
 import * as THREE from "three";
 import { type TerrainSeed } from "./random.js";
 export type TerrainArea = number | readonly [width: number, depth: number];
@@ -27,8 +27,22 @@ export interface TerrainVertexColorOptions {
     waterline?: THREE.ColorRepresentation;
     waterlineHeight?: number;
 }
+export declare function normalizeHeightBlend(height: number, minHeight: number, maxHeight: number): number;
 export declare function resolveTerrainSize(size?: TerrainArea): ResolvedTerrainSize;
 export declare function resolveTerrainSegments(segments?: ProceduralTerrainConfig["segments"]): ResolvedTerrainSegments;
 export declare function toNoiseFieldConfig(config?: ProceduralTerrainConfig): NoiseFieldConfig;
 export declare function createProceduralTerrainSampler(config?: ProceduralTerrainConfig): TerrainHeightSampler;
+export interface FieldGroundOptions {
+    size?: TerrainArea;
+    segments?: number | readonly [x: number, z: number];
+    center?: readonly [x: number, z: number];
+    colors?: TerrainVertexColorOptions;
+    heightRange?: readonly [min: number, max: number];
+}
+/**
+ * Mesh any `TerrainField` — including a `CarvableField` with craters/mounds written into it — into a
+ * vertex-coloured ground geometry. `sampleHeight` drives the vertices, so runtime carves show up as
+ * real depressions the moment the field is re-sampled (bump the caller's rebuild key after a carve).
+ */
+export declare function createFieldGroundGeometry(field: TerrainField, options?: FieldGroundOptions): THREE.BufferGeometry;
 export declare function createProceduralGroundGeometry(config?: ProceduralTerrainConfig, colors?: TerrainVertexColorOptions): THREE.BufferGeometry;

package/dist/terrain/terrainMath.js

@@ -1,6 +1,12 @@
 import { noiseField } from "@jgengine/core/world/terrain";
 import * as THREE from "three";
 import {} from "./random.js";
+export function normalizeHeightBlend(height, minHeight, maxHeight) {
+    const range = maxHeight - minHeight;
+    if (range <= 1e-6)
+        return 0.5;
+    return THREE.MathUtils.clamp((height - minHeight) / range, 0, 1);
+}
 export function resolveTerrainSize(size = 40) {
     return typeof size === "number" ? { width: size, depth: size } : { width: size[0], depth: size[1] };
 }
@@ -23,6 +29,86 @@ export function toNoiseFieldConfig(config = {}) {
 export function createProceduralTerrainSampler(config = {}) {
     return noiseField(toNoiseFieldConfig(config)).sampleHeight;
 }
+/**
+ * Mesh any `TerrainField` — including a `CarvableField` with craters/mounds written into it — into a
+ * vertex-coloured ground geometry. `sampleHeight` drives the vertices, so runtime carves show up as
+ * real depressions the moment the field is re-sampled (bump the caller's rebuild key after a carve).
+ */
+export function createFieldGroundGeometry(field, options = {}) {
+    const size = resolveTerrainSize(options.size);
+    const segments = resolveTerrainSegments(options.segments);
+    const [cx, cz] = options.center ?? [0, 0];
+    return buildGroundGeometry(size, segments, (x, z) => field.sampleHeight(x, z), {
+        colors: options.colors ?? {},
+        center: [cx, cz],
+        heightRange: options.heightRange,
+    });
+}
+function buildGroundGeometry(size, segments, sampler, opts) {
+    const colors = opts.colors;
+    const vertexCountX = segments.x + 1;
+    const vertexCountZ = segments.z + 1;
+    const positions = new Float32Array(vertexCountX * vertexCountZ * 3);
+    const uvs = new Float32Array(vertexCountX * vertexCountZ * 2);
+    const colorValues = new Float32Array(vertexCountX * vertexCountZ * 3);
+    const indices = new Uint32Array(segments.x * segments.z * 6);
+    const low = new THREE.Color(colors.low ?? "#30402c");
+    const high = new THREE.Color(colors.high ?? "#7f8b50");
+    const waterline = colors.waterline === undefined ? null : new THREE.Color(colors.waterline);
+    const minHeight = opts.heightRange?.[0] ?? -3;
+    const maxHeight = opts.heightRange?.[1] ?? 3;
+    let index = 0;
+    let uvIndex = 0;
+    let colorIndex = 0;
+    for (let zIndex = 0; zIndex < vertexCountZ; zIndex += 1) {
+        const v = zIndex / segments.z;
+        const z = opts.center[1] + (v - 0.5) * size.depth;
+        for (let xIndex = 0; xIndex < vertexCountX; xIndex += 1) {
+            const u = xIndex / segments.x;
+            const x = opts.center[0] + (u - 0.5) * size.width;
+            const y = sampler(x, z);
+            positions[index] = x;
+            positions[index + 1] = y;
+            positions[index + 2] = z;
+            uvs[uvIndex] = u;
+            uvs[uvIndex + 1] = v;
+            const blend = normalizeHeightBlend(y, minHeight, maxHeight);
+            const color = low.clone().lerp(high, blend);
+            if (waterline !== null && y <= (colors.waterlineHeight ?? 0))
+                color.lerp(waterline, 0.65);
+            colorValues[colorIndex] = color.r;
+            colorValues[colorIndex + 1] = color.g;
+            colorValues[colorIndex + 2] = color.b;
+            index += 3;
+            uvIndex += 2;
+            colorIndex += 3;
+        }
+    }
+    let triangleIndex = 0;
+    for (let zIndex = 0; zIndex < segments.z; zIndex += 1) {
+        for (let xIndex = 0; xIndex < segments.x; xIndex += 1) {
+            const a = zIndex * vertexCountX + xIndex;
+            const b = a + 1;
+            const c = a + vertexCountX;
+            const d = c + 1;
+            indices[triangleIndex] = a;
+            indices[triangleIndex + 1] = c;
+            indices[triangleIndex + 2] = b;
+            indices[triangleIndex + 3] = b;
+            indices[triangleIndex + 4] = c;
+            indices[triangleIndex + 5] = d;
+            triangleIndex += 6;
+        }
+    }
+    const geometry = new THREE.BufferGeometry();
+    geometry.setAttribute("position", new THREE.BufferAttribute(positions, 3));
+    geometry.setAttribute("uv", new THREE.BufferAttribute(uvs, 2));
+    geometry.setAttribute("color", new THREE.BufferAttribute(colorValues, 3));
+    geometry.setIndex(new THREE.BufferAttribute(indices, 1));
+    geometry.computeVertexNormals();
+    geometry.computeBoundingSphere();
+    return geometry;
+}
 export function createProceduralGroundGeometry(config = {}, colors = {}) {
     const size = resolveTerrainSize(config.size);
     const segments = resolveTerrainSegments(config.segments);
@@ -53,7 +139,7 @@ export function createProceduralGroundGeometry(config = {}, colors = {}) {
             positions[index + 2] = z;
             uvs[uvIndex] = u;
             uvs[uvIndex + 1] = v;
-            const blend = THREE.MathUtils.clamp((y - minHeight) / (maxHeight - minHeight), 0, 1);
+            const blend = normalizeHeightBlend(y, minHeight, maxHeight);
             const color = low.clone().lerp(high, blend);
             if (waterline !== null && y <= (colors.waterlineHeight ?? 0))
                 color.lerp(waterline, 0.65);