@jgengine/shell 0.5.0 → 0.7.0

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/grassGeometry.d.ts

@@ -0,0 +1,27 @@
+import * as THREE from "three";
+import { type TerrainSeed } from "./random.js";
+import { type TerrainArea, type TerrainHeightSampler } from "./terrainMath.js";
+export type GrassRange = number | readonly [min: number, max: number];
+export interface GrassBladeGeometryOptions {
+    count?: number;
+    area?: TerrainArea;
+    seed?: TerrainSeed;
+    segments?: number;
+    height?: GrassRange;
+    width?: GrassRange;
+    bend?: GrassRange;
+    heightAt?: TerrainHeightSampler;
+}
+export interface ResolvedGrassBladeGeometryOptions {
+    count: number;
+    area: TerrainArea;
+    seed: TerrainSeed;
+    segments: number;
+    height: readonly [min: number, max: number];
+    width: readonly [min: number, max: number];
+    bend: readonly [min: number, max: number];
+    heightAt: TerrainHeightSampler;
+}
+export declare function resolveGrassRange(value: GrassRange | undefined, fallback: readonly [number, number]): readonly [number, number];
+export declare function resolveGrassBladeGeometryOptions(options?: GrassBladeGeometryOptions): ResolvedGrassBladeGeometryOptions;
+export declare function createGrassBladeGeometry(options?: GrassBladeGeometryOptions): THREE.InstancedBufferGeometry;

package/dist/terrain/grassGeometry.js

@@ -0,0 +1,77 @@
+import * as THREE from "three";
+import { createSeededRandom } from "./random.js";
+import { resolveTerrainSize } from "./terrainMath.js";
+export function resolveGrassRange(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    return typeof value === "number" ? [value, value] : value;
+}
+export function resolveGrassBladeGeometryOptions(options = {}) {
+    return {
+        count: Math.max(0, Math.floor(options.count ?? 6000)),
+        area: options.area ?? 40,
+        seed: options.seed ?? 1,
+        segments: Math.max(1, Math.floor(options.segments ?? 4)),
+        height: resolveGrassRange(options.height, [0.55, 1.1]),
+        width: resolveGrassRange(options.width, [0.035, 0.075]),
+        bend: resolveGrassRange(options.bend, [0.08, 0.32]),
+        heightAt: options.heightAt ?? (() => 0),
+    };
+}
+function randomRange(random, range) {
+    return THREE.MathUtils.lerp(range[0], range[1], random());
+}
+export function createGrassBladeGeometry(options = {}) {
+    const resolved = resolveGrassBladeGeometryOptions(options);
+    const size = resolveTerrainSize(resolved.area);
+    const positions = [];
+    const normals = [];
+    const uvs = [];
+    const indices = [];
+    for (let segment = 0; segment <= resolved.segments; segment += 1) {
+        const t = segment / resolved.segments;
+        positions.push(-0.5, t, 0, 0.5, t, 0);
+        normals.push(0, 0, 1, 0, 0, 1);
+        uvs.push(0, t, 1, t);
+        if (segment < resolved.segments) {
+            const base = segment * 2;
+            indices.push(base, base + 1, base + 3, base, base + 3, base + 2);
+        }
+    }
+    const geometry = new THREE.InstancedBufferGeometry();
+    geometry.setAttribute("position", new THREE.Float32BufferAttribute(positions, 3));
+    geometry.setAttribute("normal", new THREE.Float32BufferAttribute(normals, 3));
+    geometry.setAttribute("uv", new THREE.Float32BufferAttribute(uvs, 2));
+    geometry.setIndex(indices);
+    const random = createSeededRandom(resolved.seed);
+    const offsets = new Float32Array(resolved.count * 3);
+    const yaw = new Float32Array(resolved.count);
+    const heights = new Float32Array(resolved.count);
+    const widths = new Float32Array(resolved.count);
+    const bend = new Float32Array(resolved.count);
+    const phase = new Float32Array(resolved.count);
+    const colorMix = new Float32Array(resolved.count);
+    for (let index = 0; index < resolved.count; index += 1) {
+        const x = (random() - 0.5) * size.width;
+        const z = (random() - 0.5) * size.depth;
+        offsets[index * 3] = x;
+        offsets[index * 3 + 1] = resolved.heightAt(x, z);
+        offsets[index * 3 + 2] = z;
+        yaw[index] = random() * Math.PI * 2;
+        heights[index] = randomRange(random, resolved.height);
+        widths[index] = randomRange(random, resolved.width);
+        bend[index] = randomRange(random, resolved.bend);
+        phase[index] = random() * Math.PI * 2;
+        colorMix[index] = random();
+    }
+    geometry.setAttribute("instanceOffset", new THREE.InstancedBufferAttribute(offsets, 3));
+    geometry.setAttribute("instanceYaw", new THREE.InstancedBufferAttribute(yaw, 1));
+    geometry.setAttribute("instanceHeight", new THREE.InstancedBufferAttribute(heights, 1));
+    geometry.setAttribute("instanceWidth", new THREE.InstancedBufferAttribute(widths, 1));
+    geometry.setAttribute("instanceBend", new THREE.InstancedBufferAttribute(bend, 1));
+    geometry.setAttribute("instancePhase", new THREE.InstancedBufferAttribute(phase, 1));
+    geometry.setAttribute("instanceColorMix", new THREE.InstancedBufferAttribute(colorMix, 1));
+    geometry.instanceCount = resolved.count;
+    geometry.boundingSphere = new THREE.Sphere(new THREE.Vector3(0, 0, 0), Math.max(size.width, size.depth) * 0.75 + resolved.height[1]);
+    return geometry;
+}

package/dist/terrain/grassMaterial.d.ts

@@ -0,0 +1,33 @@
+import * as THREE from "three";
+export interface GrassWindOptions {
+    direction?: readonly [x: number, z: number];
+    strength?: number;
+    speed?: number;
+    gustScale?: number;
+    flutter?: number;
+}
+export interface GrassMaterialOptions {
+    colorBase?: THREE.ColorRepresentation;
+    colorTip?: THREE.ColorRepresentation;
+    colorVariation?: number;
+    wind?: GrassWindOptions | false;
+    roughness?: number;
+}
+export interface GrassShaderUniforms {
+    uTime: THREE.IUniform<number>;
+    uWindDirection: THREE.IUniform<THREE.Vector2>;
+    uWindStrength: THREE.IUniform<number>;
+    uWindSpeed: THREE.IUniform<number>;
+    uWindGustScale: THREE.IUniform<number>;
+    uWindFlutter: THREE.IUniform<number>;
+    uColorBase: THREE.IUniform<THREE.Color>;
+    uColorTip: THREE.IUniform<THREE.Color>;
+    uColorVariation: THREE.IUniform<number>;
+}
+export interface GrassMaterialHandle {
+    material: THREE.MeshStandardMaterial;
+    uniforms: GrassShaderUniforms;
+}
+export declare const DEFAULT_GRASS_WIND: Required<GrassWindOptions>;
+export declare function resolveGrassWind(wind: GrassWindOptions | false | undefined): Required<GrassWindOptions>;
+export declare function createGrassMaterial(options?: GrassMaterialOptions): GrassMaterialHandle;

package/dist/terrain/grassMaterial.js

@@ -0,0 +1,108 @@
+import * as THREE from "three";
+export const DEFAULT_GRASS_WIND = {
+    direction: [1, 0.35],
+    strength: 0.22,
+    speed: 1.6,
+    gustScale: 0.16,
+    flutter: 0.08,
+};
+function normalizeWindDirection(direction) {
+    const vector = new THREE.Vector2(direction[0], direction[1]);
+    return vector.lengthSq() === 0 ? new THREE.Vector2(1, 0) : vector.normalize();
+}
+export function resolveGrassWind(wind) {
+    if (wind === false)
+        return { ...DEFAULT_GRASS_WIND, strength: 0, flutter: 0 };
+    return {
+        direction: wind?.direction ?? DEFAULT_GRASS_WIND.direction,
+        strength: wind?.strength ?? DEFAULT_GRASS_WIND.strength,
+        speed: wind?.speed ?? DEFAULT_GRASS_WIND.speed,
+        gustScale: wind?.gustScale ?? DEFAULT_GRASS_WIND.gustScale,
+        flutter: wind?.flutter ?? DEFAULT_GRASS_WIND.flutter,
+    };
+}
+export function createGrassMaterial(options = {}) {
+    const wind = resolveGrassWind(options.wind);
+    const uniforms = {
+        uTime: { value: 0 },
+        uWindDirection: { value: normalizeWindDirection(wind.direction) },
+        uWindStrength: { value: wind.strength },
+        uWindSpeed: { value: wind.speed },
+        uWindGustScale: { value: wind.gustScale },
+        uWindFlutter: { value: wind.flutter },
+        uColorBase: { value: new THREE.Color(options.colorBase ?? "#2d431f") },
+        uColorTip: { value: new THREE.Color(options.colorTip ?? "#a6cc58") },
+        uColorVariation: { value: options.colorVariation ?? 0.28 },
+    };
+    const material = new THREE.MeshStandardMaterial({
+        color: "#ffffff",
+        side: THREE.DoubleSide,
+        roughness: options.roughness ?? 0.82,
+        metalness: 0,
+    });
+    material.onBeforeCompile = (shader) => {
+        Object.assign(shader.uniforms, uniforms);
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <common>", `
+#include <common>
+attribute vec3 instanceOffset;
+attribute float instanceYaw;
+attribute float instanceHeight;
+attribute float instanceWidth;
+attribute float instanceBend;
+attribute float instancePhase;
+attribute float instanceColorMix;
+uniform float uTime;
+uniform vec2 uWindDirection;
+uniform float uWindStrength;
+uniform float uWindSpeed;
+uniform float uWindGustScale;
+uniform float uWindFlutter;
+varying float vGrassBladeT;
+varying float vGrassColorMix;
+vec3 jgGrassPosition;
+vec3 jgGrassNormal;
+void jgComputeGrassBlade() {
+  float t = position.y;
+  float side = position.x;
+  float taper = (1.0 - t) * (0.72 + 0.28 * (1.0 - t));
+  float width = instanceWidth * taper;
+  float arc = instanceBend * t * t;
+  vec3 localPosition = vec3(side * width, instanceHeight * t - arc * instanceHeight * 0.18, arc * instanceHeight);
+  vec3 localNormal = normalize(vec3(0.0, -instanceBend * t, 1.0));
+  float cy = cos(instanceYaw);
+  float sy = sin(instanceYaw);
+  vec3 yawedPosition = vec3(localPosition.x * cy + localPosition.z * sy, localPosition.y, -localPosition.x * sy + localPosition.z * cy);
+  vec3 yawedNormal = normalize(vec3(localNormal.x * cy + localNormal.z * sy, localNormal.y, -localNormal.x * sy + localNormal.z * cy));
+  float gustPhase = dot(instanceOffset.xz, uWindDirection) * uWindGustScale + uTime * uWindSpeed + instancePhase;
+  float gust = sin(gustPhase) * 0.7 + sin(gustPhase * 0.43 + 2.4) * 0.3;
+  float flutter = sin(uTime * 7.5 + instancePhase * 2.7) * uWindFlutter;
+  vec2 windOffset = uWindDirection * (gust * uWindStrength + flutter) * t * t;
+  jgGrassPosition = instanceOffset + yawedPosition + vec3(windOffset.x, 0.0, windOffset.y);
+  jgGrassNormal = yawedNormal;
+  vGrassBladeT = t;
+  vGrassColorMix = instanceColorMix;
+}
+`)
+            .replace("#include <beginnormal_vertex>", "jgComputeGrassBlade();\nvec3 objectNormal = jgGrassNormal;")
+            .replace("#include <begin_vertex>", "vec3 transformed = jgGrassPosition;");
+        shader.fragmentShader = shader.fragmentShader
+            .replace("#include <common>", `
+#include <common>
+uniform vec3 uColorBase;
+uniform vec3 uColorTip;
+uniform float uColorVariation;
+varying float vGrassBladeT;
+varying float vGrassColorMix;
+`)
+            .replace("#include <color_fragment>", `
+#include <color_fragment>
+vec3 grassColor = mix(uColorBase, uColorTip, smoothstep(0.0, 1.0, vGrassBladeT));
+grassColor *= mix(1.0 - uColorVariation, 1.0 + uColorVariation, vGrassColorMix);
+grassColor *= mix(0.58, 1.0, smoothstep(0.05, 0.45, vGrassBladeT));
+diffuseColor.rgb = grassColor;
+`);
+    };
+    material.customProgramCacheKey = () => `jgengine-grass-${wind.strength}-${wind.flutter}`;
+    return { material, uniforms };
+}

package/dist/terrain/index.d.ts

@@ -0,0 +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 { createFieldGroundGeometry, createProceduralGroundGeometry, createProceduralTerrainSampler, 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

@@ -0,0 +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 { createFieldGroundGeometry, createProceduralGroundGeometry, createProceduralTerrainSampler, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, } from "./terrainMath.js";
+export { arenaField, flatField, fractalNoise, noiseField, resolveGroundStep, resolveTerrainField, valueNoise, withNormal, } from "@jgengine/core/world/terrain";

package/dist/terrain/random.d.ts

@@ -0,0 +1,4 @@
+export type TerrainSeed = number | string;
+export declare function seedToUint32(seed?: TerrainSeed): number;
+export declare function createSeededRandom(seed?: TerrainSeed): () => number;
+export declare function hashNoise2(x: number, z: number, seed?: TerrainSeed): number;

package/dist/terrain/random.js

@@ -0,0 +1,27 @@
+export function seedToUint32(seed = 1) {
+    if (typeof seed === "number")
+        return seed >>> 0;
+    let hash = 2166136261;
+    for (let index = 0; index < seed.length; index += 1) {
+        hash ^= seed.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    return hash >>> 0;
+}
+export function createSeededRandom(seed = 1) {
+    let state = seedToUint32(seed);
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let value = state;
+        value = Math.imul(value ^ (value >>> 15), value | 1);
+        value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+        return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
+    };
+}
+export function hashNoise2(x, z, seed = 1) {
+    let hash = seedToUint32(seed);
+    hash ^= Math.imul(x | 0, 374761393);
+    hash ^= Math.imul(z | 0, 668265263);
+    hash = Math.imul(hash ^ (hash >>> 13), 1274126177);
+    return ((hash ^ (hash >>> 16)) >>> 0) / 4294967295;
+}

package/dist/terrain/terrainMath.d.ts

@@ -0,0 +1,47 @@
+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];
+export type TerrainHeightSampler = (x: number, z: number) => number;
+export interface ProceduralTerrainConfig {
+    size?: TerrainArea;
+    segments?: number | readonly [x: number, z: number];
+    seed?: TerrainSeed;
+    height?: number;
+    moundScale?: number;
+    octaves?: number;
+    ridged?: boolean;
+    baseOffset?: number;
+}
+export interface ResolvedTerrainSize {
+    width: number;
+    depth: number;
+}
+export interface ResolvedTerrainSegments {
+    x: number;
+    z: number;
+}
+export interface TerrainVertexColorOptions {
+    low?: THREE.ColorRepresentation;
+    high?: THREE.ColorRepresentation;
+    waterline?: THREE.ColorRepresentation;
+    waterlineHeight?: 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

@@ -0,0 +1,172 @@
+import { noiseField } from "@jgengine/core/world/terrain";
+import * as THREE from "three";
+import {} from "./random.js";
+export function resolveTerrainSize(size = 40) {
+    return typeof size === "number" ? { width: size, depth: size } : { width: size[0], depth: size[1] };
+}
+export function resolveTerrainSegments(segments = 96) {
+    if (typeof segments !== "number")
+        return { x: Math.max(1, Math.floor(segments[0])), z: Math.max(1, Math.floor(segments[1])) };
+    const resolved = Math.max(1, Math.floor(segments));
+    return { x: resolved, z: resolved };
+}
+export function toNoiseFieldConfig(config = {}) {
+    return {
+        seed: config.seed,
+        amplitude: config.height ?? 1.4,
+        frequency: config.moundScale ?? 0.075,
+        octaves: config.octaves ?? 4,
+        ridged: config.ridged ?? false,
+        baseHeight: config.baseOffset ?? 0,
+    };
+}
+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 = THREE.MathUtils.clamp((y - minHeight) / (maxHeight - minHeight), 0, 1);
+            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);
+    const sampler = createProceduralTerrainSampler(config);
+    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 = (config.baseOffset ?? 0) - (config.height ?? 1.4) * 1.2;
+    const maxHeight = (config.baseOffset ?? 0) + (config.height ?? 1.4) * 1.2;
+    let index = 0;
+    let uvIndex = 0;
+    let colorIndex = 0;
+    for (let zIndex = 0; zIndex < vertexCountZ; zIndex += 1) {
+        const v = zIndex / segments.z;
+        const z = (v - 0.5) * size.depth;
+        for (let xIndex = 0; xIndex < vertexCountX; xIndex += 1) {
+            const u = xIndex / segments.x;
+            const x = (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 = THREE.MathUtils.clamp((y - minHeight) / (maxHeight - minHeight), 0, 1);
+            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;
+}

package/dist/terrain.d.ts

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

package/dist/terrain.js

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

package/dist/vision/FrustumSensorHud.d.ts

@@ -0,0 +1,21 @@
+import { type FramingConfig, type FrustumSample } from "@jgengine/core/sensor/frustumSensor";
+export interface FrustumSensorProbeOptions extends FramingConfig {
+    subjectIds: readonly string[];
+    subjectRadius?: number;
+}
+/**
+ * View-frustum sensor (#117) driven by the live render camera: which held-camera
+ * subjects are in frame, how well framed, and their dwell time on-screen
+ * (Content Warning-style "is this monster filmed well" scoring). Returns the
+ * best-framed in-view subject each frame for a photo-mode HUD readout.
+ */
+export declare function useFrustumSensor(options: FrustumSensorProbeOptions): FrustumSample | null;
+/**
+ * Renders inside the Canvas (needs the live camera via `useFrame`/`useThree`)
+ * but portals a real HTML readout via drei's `Html fullscreen` — a photo-mode
+ * "is this subject framed" HUD.
+ */
+export declare function FrustumSensorReadout(props: FrustumSensorProbeOptions & {
+    wrapperClassName?: string;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/vision/FrustumSensorHud.js

@@ -0,0 +1,67 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Html } from "@react-three/drei";
+import { useFrame, useThree } from "@react-three/fiber";
+import { useMemo, useRef, useState } from "react";
+import { PerspectiveCamera, Vector3 } from "three";
+import { createFrustumSensor, } from "@jgengine/core/sensor/frustumSensor";
+import { useSceneEntities } from "@jgengine/react/hooks";
+function isPerspective(camera) {
+    return camera.isPerspectiveCamera === true;
+}
+/**
+ * View-frustum sensor (#117) driven by the live render camera: which held-camera
+ * subjects are in frame, how well framed, and their dwell time on-screen
+ * (Content Warning-style "is this monster filmed well" scoring). Returns the
+ * best-framed in-view subject each frame for a photo-mode HUD readout.
+ */
+export function useFrustumSensor(options) {
+    const camera = useThree((state) => state.camera);
+    const size = useThree((state) => state.size);
+    const entities = useSceneEntities();
+    const sensor = useMemo(() => createFrustumSensor(options), []);
+    const [best, setBest] = useState(null);
+    const forward = useRef(new Vector3());
+    useFrame((_, dt) => {
+        const targets = [];
+        for (const id of options.subjectIds) {
+            const entity = entities.find((candidate) => candidate.id === id);
+            if (entity === undefined)
+                continue;
+            targets.push({ id, position: entity.position, radius: options.subjectRadius });
+        }
+        if (targets.length === 0) {
+            setBest(null);
+            return;
+        }
+        camera.getWorldDirection(forward.current);
+        const samples = sensor.tick({
+            position: [camera.position.x, camera.position.y, camera.position.z],
+            lookAt: [
+                camera.position.x + forward.current.x,
+                camera.position.y + forward.current.y,
+                camera.position.z + forward.current.z,
+            ],
+            fovDeg: isPerspective(camera) ? camera.fov : 55,
+            aspect: size.height === 0 ? 16 / 9 : size.width / size.height,
+        }, targets, dt);
+        let leader = null;
+        for (const sample of samples) {
+            if (!sample.inView)
+                continue;
+            if (leader === null || sample.framing > leader.framing)
+                leader = sample;
+        }
+        setBest(leader);
+    });
+    return best;
+}
+/**
+ * Renders inside the Canvas (needs the live camera via `useFrame`/`useThree`)
+ * but portals a real HTML readout via drei's `Html fullscreen` — a photo-mode
+ * "is this subject framed" HUD.
+ */
+export function FrustumSensorReadout(props) {
+    const sample = useFrustumSensor(props);
+    return (_jsx(Html, { fullscreen: true, children: _jsx("div", { className: props.wrapperClassName ?? "pointer-events-none absolute bottom-24 right-4", children: sample === null ? (_jsx("div", { className: props.className ?? "rounded border border-white/15 bg-black/60 px-3 py-1.5 text-xs text-white/50", children: "No subject framed" })) : (_jsxs("div", { className: props.className ??
+                    "rounded border border-amber-300/40 bg-black/70 px-3 py-1.5 text-xs text-amber-200 shadow-lg", children: [_jsx("span", { className: "font-semibold uppercase tracking-wide", children: sample.id }), _jsxs("span", { className: "ml-2 tabular-nums", children: ["framing ", Math.round(sample.framing * 100), "%"] }), _jsxs("span", { className: "ml-2 tabular-nums", children: ["dwell ", sample.dwellSeconds.toFixed(1), "s"] })] })) }) }));
+}

package/dist/vision/HiddenStateProbeHud.d.ts

@@ -0,0 +1,11 @@
+import { probeHiddenState, type HiddenStateSource, type SensorProbeOptions } from "@jgengine/core/sensor/hiddenStateProbe";
+import type { EntityPosition } from "@jgengine/core/scene/entityStore";
+/** Reads a hidden zone/entity state variable in range (EMF / thermometer / geiger style sensor verb, #116). */
+export declare function useHiddenStateProbe(origin: EntityPosition, sources: readonly HiddenStateSource[], options: SensorProbeOptions): import("@jgengine/core/sensor/hiddenStateProbe").SensorReading | null;
+export interface SensorReadoutMeterProps {
+    label: string;
+    reading: ReturnType<typeof probeHiddenState>;
+    className?: string;
+}
+/** A handheld-sensor readout: needle strength bar + the raw reading, or a "no signal" idle state. */
+export declare function SensorReadoutMeter({ label, reading, className }: SensorReadoutMeterProps): import("react").JSX.Element;