@jgengine/shell 0.8.0 → 0.10.0

package/dist/settings/settingsController.js

@@ -0,0 +1,165 @@
+import { useEffect, useReducer } from "react";
+import { actionLabel, bindingLabel } from "@jgengine/core/input/actionBindings";
+import { BUILT_IN_SETTING_CATEGORIES, busVolumeSettingId, DEFAULT_GRAPHICS_QUALITY, DEFAULT_GRAPHICS_SHADOWS, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_OPTIONS, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
+import { useSettingsStore, } from "@jgengine/react/settings";
+import { usePlayerFov } from "../camera/PlayerFov.js";
+const DEFAULT_CATEGORY_LABELS = {
+    sound: "Sound",
+    graphics: "Graphics",
+    gameplay: "Gameplay",
+    controls: "Controls",
+};
+const percent = (value) => `${Math.round(value * 100)}%`;
+export function useSettingsCategories(config) {
+    const store = useSettingsStore();
+    const fov = usePlayerFov();
+    const [, force] = useReducer((n) => n + 1, 0);
+    useEffect(() => store.subscribe(() => force()), [store]);
+    const hidden = new Set(config.hide);
+    const extrasFor = (category) => config.extra
+        .filter((def) => def.category === category)
+        .map((def) => ({
+        id: def.id,
+        label: def.label,
+        kind: def.kind,
+        value: store.get(def.id, def.default),
+        min: def.min,
+        max: def.max,
+        step: def.step,
+        options: def.options,
+        set: (value) => store.set(def.id, value),
+    }));
+    const soundRows = [
+        {
+            id: SETTING_IDS.masterVolume,
+            label: "Master volume",
+            kind: "slider",
+            value: store.get(SETTING_IDS.masterVolume, DEFAULT_MASTER_VOLUME),
+            min: 0,
+            max: 1,
+            step: 0.01,
+            format: percent,
+            set: (value) => store.set(SETTING_IDS.masterVolume, value),
+        },
+        ...Object.values(config.buses ?? {}).map((bus) => {
+            const id = busVolumeSettingId(bus.id);
+            return {
+                id,
+                label: `${bus.id.charAt(0).toUpperCase()}${bus.id.slice(1)} volume`,
+                kind: "slider",
+                value: store.get(id, bus.gain ?? 1),
+                min: 0,
+                max: 1,
+                step: 0.01,
+                format: percent,
+                set: (value) => store.set(id, value),
+            };
+        }),
+        ...extrasFor("sound"),
+    ];
+    const graphicsRows = [
+        {
+            id: SETTING_IDS.graphicsQuality,
+            label: "Quality",
+            kind: "select",
+            value: store.get(SETTING_IDS.graphicsQuality, DEFAULT_GRAPHICS_QUALITY),
+            options: GRAPHICS_QUALITY_OPTIONS,
+            set: (value) => store.set(SETTING_IDS.graphicsQuality, value),
+        },
+        {
+            id: SETTING_IDS.graphicsShadows,
+            label: "Shadows",
+            kind: "toggle",
+            value: store.get(SETTING_IDS.graphicsShadows, DEFAULT_GRAPHICS_SHADOWS),
+            set: (value) => store.set(SETTING_IDS.graphicsShadows, value),
+        },
+        {
+            id: SETTING_IDS.graphicsUiScale,
+            label: "UI scale",
+            kind: "slider",
+            value: store.get(SETTING_IDS.graphicsUiScale, DEFAULT_UI_SCALE),
+            min: UI_SCALE_MIN,
+            max: UI_SCALE_MAX,
+            step: 0.05,
+            format: percent,
+            set: (value) => store.set(SETTING_IDS.graphicsUiScale, value),
+        },
+        ...extrasFor("graphics"),
+    ];
+    const gameplayRows = [
+        ...(config.fovEnabled
+            ? [
+                {
+                    id: "gameplay.fov",
+                    label: "Field of view",
+                    kind: "slider",
+                    value: fov.fov,
+                    min: fov.bounds.min,
+                    max: fov.bounds.max,
+                    step: 1,
+                    format: (value) => `${Math.round(value)}`,
+                    set: (value) => fov.setFov(Number(value)),
+                },
+            ]
+            : []),
+        ...extrasFor("gameplay"),
+    ];
+    const hiddenBindings = new Set(config.hideBindings);
+    const keybinds = Object.keys(config.input)
+        .filter((action) => !hiddenBindings.has(action))
+        .map((action) => {
+        const override = config.overrides[action];
+        const effective = override === undefined ? config.input : { ...config.input, [action]: override };
+        return {
+            action,
+            label: humanizeAction(action),
+            bindingLabel: actionLabel(effective, action) ?? "Unbound",
+            isDefault: override === undefined,
+            rebind: (code) => config.rebind(action, code),
+            reset: () => config.resetBinding(action),
+        };
+    });
+    const builtInRows = {
+        sound: soundRows,
+        graphics: graphicsRows,
+        gameplay: gameplayRows,
+        controls: extrasFor("controls"),
+    };
+    const builtInKeybinds = { controls: keybinds };
+    const declaredLabels = new Map(config.categories.map((c) => [c.id, c.label]));
+    const declaredOrder = new Map(config.categories.map((c, index) => [c.id, c.order ?? 1000 + index]));
+    const order = [];
+    const push = (id) => {
+        if (!order.includes(id))
+            order.push(id);
+    };
+    for (const id of BUILT_IN_SETTING_CATEGORIES)
+        push(id);
+    for (const c of config.categories)
+        push(c.id);
+    for (const def of config.extra)
+        push(def.category);
+    const views = order
+        .filter((id) => !hidden.has(id))
+        .map((id) => ({
+        id,
+        label: declaredLabels.get(id) ?? DEFAULT_CATEGORY_LABELS[id] ?? humanizeAction(id),
+        rows: builtInRows[id] ?? extrasFor(id),
+        keybinds: builtInKeybinds[id] ?? [],
+    }))
+        .filter((view) => view.rows.length > 0 || view.keybinds.length > 0);
+    views.sort((a, b) => (declaredOrder.get(a.id) ?? indexOrder(order, a.id)) - (declaredOrder.get(b.id) ?? indexOrder(order, b.id)));
+    return views;
+}
+function indexOrder(order, id) {
+    const index = order.indexOf(id);
+    return index === -1 ? 999 : index;
+}
+function humanizeAction(action) {
+    const spaced = action
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[._-]+/g, " ")
+        .trim();
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+export { bindingLabel };

package/dist/structures/GeneratedBuilding.d.ts

@@ -40,5 +40,15 @@ export interface GeneratedBuildingProps {
     kit?: BuildingKitRenderer;
     visibleKinds?: readonly BuildingPartKind[];
 }
+export interface InstancedBuildingPlacement {
+    building: GeneratedBuildingData;
+    position?: readonly [number, number, number];
+}
+export interface InstancedBuildingsProps {
+    buildings: readonly InstancedBuildingPlacement[];
+    palette?: BuildingMaterialPalette;
+    visibleKinds?: readonly BuildingPartKind[];
+}
+export declare function InstancedBuildings({ buildings, palette, visibleKinds }: InstancedBuildingsProps): import("react").JSX.Element | null;
 export declare function BuildingBlock({ part, palette }: BuildingBlockProps): import("react").JSX.Element;
 export declare function GeneratedBuilding({ building, palette, kit, visibleKinds }: GeneratedBuildingProps): import("react").JSX.Element;

package/dist/structures/GeneratedBuilding.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo } from "react";
+import { useEffect, useLayoutEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
 const DEFAULT_PALETTE = {
     wall: "#83766a",
     window: "#8ecae6",
@@ -50,6 +51,84 @@ function materialFor(part, palette) {
     }
     return _jsx("meshStandardMaterial", { color: color, roughness: 0.88, metalness: 0 });
 }
+function batchMaterialFor(kind, palette) {
+    const color = colorFor(kind, palette);
+    if (kind === "window" || kind === "storefront") {
+        return new THREE.MeshPhysicalMaterial({ color, roughness: 0.12, metalness: 0, transparent: true, opacity: 0.56 });
+    }
+    if (kind === "storeSign") {
+        return new THREE.MeshStandardMaterial({ color, emissive: color, emissiveIntensity: 0.6, roughness: 0.5 });
+    }
+    if (kind === "roofProp") {
+        return new THREE.MeshStandardMaterial({ color, roughness: 0.65, metalness: 0.1 });
+    }
+    return new THREE.MeshStandardMaterial({ color, roughness: 0.88, metalness: 0 });
+}
+const CLOTHESLINE_ROW_OFFSETS = [-0.09, 0.09];
+function bucketPartMatrices(buildings, visible) {
+    const dummy = new THREE.Object3D();
+    const buckets = new Map();
+    for (const placement of buildings) {
+        const [ox, oy, oz] = placement.position ?? [0, 0, 0];
+        for (const part of placement.building.parts) {
+            if (visible !== null && !visible.has(part.kind))
+                continue;
+            const [nx, nz] = normalFor(part.facade);
+            const offset = outwardOffset(part);
+            const px = ox + part.position[0] + nx * offset;
+            const py = oy + part.position[1];
+            const pz = oz + part.position[2] + nz * offset;
+            let bucket = buckets.get(part.kind);
+            if (bucket === undefined) {
+                bucket = [];
+                buckets.set(part.kind, bucket);
+            }
+            if (part.kind === "clothesline") {
+                const sin = Math.sin(part.rotationY);
+                const cos = Math.cos(part.rotationY);
+                for (const row of CLOTHESLINE_ROW_OFFSETS) {
+                    dummy.position.set(px + row * sin, py, pz + row * cos);
+                    dummy.rotation.set(0, part.rotationY, 0);
+                    dummy.scale.set(part.scale[0], Math.max(part.scale[1], 0.025), 0.025);
+                    dummy.updateMatrix();
+                    bucket.push(dummy.matrix.clone());
+                }
+                continue;
+            }
+            dummy.position.set(px, py, pz);
+            dummy.rotation.set(0, part.rotationY, 0);
+            dummy.scale.set(part.scale[0], part.scale[1], part.scale[2]);
+            dummy.updateMatrix();
+            bucket.push(dummy.matrix.clone());
+        }
+    }
+    return buckets;
+}
+function BuildingKindBatch({ kind, matrices, palette, geometry, }) {
+    const meshRef = useRef(null);
+    const material = useMemo(() => batchMaterialFor(kind, palette), [kind, palette]);
+    useEffect(() => () => material.dispose(), [material]);
+    useLayoutEffect(() => {
+        const mesh = meshRef.current;
+        if (mesh === null)
+            return;
+        matrices.forEach((matrix, index) => mesh.setMatrixAt(index, matrix));
+        mesh.instanceMatrix.needsUpdate = true;
+        mesh.computeBoundingSphere();
+    }, [matrices, material]);
+    return (_jsx("instancedMesh", { ref: meshRef, args: [geometry, material, matrices.length], castShadow: true, receiveShadow: true }, matrices.length));
+}
+export function InstancedBuildings({ buildings, palette, visibleKinds }) {
+    const geometry = useMemo(() => new THREE.BoxGeometry(1, 1, 1), []);
+    useEffect(() => () => geometry.dispose(), [geometry]);
+    const buckets = useMemo(() => {
+        const visible = visibleKinds === undefined ? null : new Set(visibleKinds);
+        return bucketPartMatrices(buildings, visible);
+    }, [buildings, visibleKinds]);
+    if (buckets.size === 0)
+        return null;
+    return (_jsx("group", { children: [...buckets.entries()].map(([kind, matrices]) => (_jsx(BuildingKindBatch, { kind: kind, matrices: matrices, palette: palette, geometry: geometry }, kind))) }));
+}
 function BlockMesh({ part, palette }) {
     const [nx, nz] = normalFor(part.facade);
     const offset = outwardOffset(part);
@@ -74,13 +153,22 @@ export function BuildingBlock({ part, palette }) {
     return _jsx(BlockMesh, { part: part, palette: palette });
 }
 export function GeneratedBuilding({ building, palette, kit, visibleKinds }) {
-    const visible = useMemo(() => (visibleKinds === undefined ? null : new Set(visibleKinds)), [visibleKinds]);
-    return (_jsx("group", { name: building.id, children: building.parts.map((part) => {
+    const { kitParts, batched } = useMemo(() => {
+        const visible = visibleKinds === undefined ? null : new Set(visibleKinds);
+        const kitRendered = [];
+        const batchedParts = [];
+        for (const part of building.parts) {
             if (visible !== null && !visible.has(part.kind))
-                return null;
+                continue;
             const rendered = kit?.renderPart?.(part);
-            if (rendered !== undefined)
-                return _jsx("group", { children: rendered }, part.id);
-            return _jsx(BuildingBlock, { part: part, palette: palette }, part.id);
-        }) }));
+            if (rendered !== undefined) {
+                kitRendered.push({ id: part.id, node: rendered });
+                continue;
+            }
+            batchedParts.push(part);
+        }
+        const placements = batchedParts.length === 0 ? [] : [{ building: { id: building.id, parts: batchedParts } }];
+        return { kitParts: kitRendered, batched: placements };
+    }, [building, kit, visibleKinds]);
+    return (_jsxs("group", { name: building.id, children: [kitParts.map((entry) => (_jsx("group", { children: entry.node }, entry.id))), _jsx(InstancedBuildings, { buildings: batched, palette: palette })] }));
 }

package/dist/structures/index.d.ts

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

package/dist/structures/index.js

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

package/dist/terrain/CarvedTerrain.d.ts

@@ -1,4 +1,5 @@
 import { type ThreeElements } from "@react-three/fiber";
+import * as THREE from "three";
 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"> {
@@ -9,8 +10,11 @@ export interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" |
     center?: FieldGroundOptions["center"];
     colors?: FieldGroundOptions["colors"];
     heightRange?: FieldGroundOptions["heightRange"];
+    paletteAt?: FieldGroundOptions["paletteAt"];
     roughness?: number;
     metalness?: number;
+    /** Override the default vertex-colour material (e.g. a procedural detail material). The caller owns its lifecycle; it is not disposed here. */
+    surfaceMaterial?: THREE.Material;
     /** Bump after a runtime carve/deposit to re-mesh the deformed surface. */
     epoch?: number;
 }
@@ -19,4 +23,4 @@ export interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" |
  * 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;
+export declare function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, roughness, metalness, surfaceMaterial, receiveShadow, epoch, ...meshProps }: CarvedTerrainProps): import("react").JSX.Element;

package/dist/terrain/CarvedTerrain.js

@@ -8,12 +8,13 @@ import { createFieldGroundGeometry } from "./terrainMath.js";
  * 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 }), 
+export function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, roughness = 0.95, metalness = 0, surfaceMaterial, receiveShadow = true, epoch = 0, ...meshProps }) {
+    const geometry = useMemo(() => createFieldGroundGeometry(field, { size, segments, center, colors, heightRange, paletteAt }), 
     // 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]);
+    [field, size, segments, center, colors, heightRange, paletteAt, epoch]);
+    const defaultMaterial = useMemo(() => new THREE.MeshStandardMaterial({ color: "#ffffff", roughness, metalness, vertexColors: true }), [metalness, roughness]);
+    const material = surfaceMaterial ?? defaultMaterial;
     useEffect(() => () => geometry.dispose(), [geometry]);
-    useEffect(() => () => material.dispose(), [material]);
+    useEffect(() => () => defaultMaterial.dispose(), [defaultMaterial]);
     return _jsx("mesh", { ...meshProps, geometry: geometry, material: material, receiveShadow: receiveShadow });
 }

package/dist/terrain/GrassField.d.ts

@@ -2,9 +2,11 @@ import { type ThreeElements } from "@react-three/fiber";
 import { type GrassBladeGeometryOptions, type GrassRange } from "./grassGeometry.js";
 import { type GrassMaterialOptions, type GrassWindOptions } from "./grassMaterial.js";
 import type { TerrainArea, TerrainHeightSampler } from "./terrainMath.js";
+export { DEFAULT_GRASS_COUNT, DEFAULT_GRASS_DENSITY, resolveGrassInstanceBudget } from "./grassBudget.js";
 export interface GrassFieldProps extends Omit<ThreeElements["mesh"], "args" | "children" | "geometry" | "material"> {
     count?: number;
     density?: number;
+    budget?: number;
     area?: TerrainArea;
     seed?: GrassBladeGeometryOptions["seed"];
     segments?: number;
@@ -18,4 +20,4 @@ export interface GrassFieldProps extends Omit<ThreeElements["mesh"], "args" | "c
     wind?: GrassWindOptions | false;
     roughness?: number;
 }
-export declare function GrassField({ count, density, area, seed, segments, bladeHeight, bladeWidth, bladeBend, heightAt, colorBase, colorTip, colorVariation, wind, roughness, castShadow, receiveShadow, frustumCulled, ...meshProps }: GrassFieldProps): import("react").JSX.Element;
+export declare function GrassField({ count, density, budget, area, seed, segments, bladeHeight, bladeWidth, bladeBend, heightAt, colorBase, colorTip, colorVariation, wind, roughness, castShadow, receiveShadow, frustumCulled, ...meshProps }: GrassFieldProps): import("react").JSX.Element;

package/dist/terrain/GrassField.js

@@ -3,7 +3,9 @@ import { useFrame } from "@react-three/fiber";
 import { useEffect, useMemo } from "react";
 import { createGrassBladeGeometry } from "./grassGeometry.js";
 import { createGrassMaterial } from "./grassMaterial.js";
-export function GrassField({ count = 6000, density = 1, area = 40, seed = 1, segments = 4, bladeHeight, bladeWidth, bladeBend, heightAt, colorBase, colorTip, colorVariation, wind, roughness, castShadow = false, receiveShadow = true, frustumCulled = false, ...meshProps }) {
+import { DEFAULT_GRASS_COUNT, DEFAULT_GRASS_DENSITY, resolveGrassInstanceBudget, } from "./grassBudget.js";
+export { DEFAULT_GRASS_COUNT, DEFAULT_GRASS_DENSITY, resolveGrassInstanceBudget } from "./grassBudget.js";
+export function GrassField({ count = DEFAULT_GRASS_COUNT, density = DEFAULT_GRASS_DENSITY, budget, area = 40, seed = 1, segments = 4, bladeHeight, bladeWidth, bladeBend, heightAt, colorBase, colorTip, colorVariation, wind, roughness, castShadow = false, receiveShadow = true, frustumCulled = true, ...meshProps }) {
     const geometry = useMemo(() => createGrassBladeGeometry({
         count,
         area,
@@ -21,7 +23,7 @@ export function GrassField({ count = 6000, density = 1, area = 40, seed = 1, seg
         wind,
         roughness,
     }), [colorBase, colorTip, colorVariation, roughness, wind]);
-    geometry.instanceCount = Math.floor(Math.max(0, Math.min(1, density)) * count);
+    geometry.instanceCount = resolveGrassInstanceBudget(count, density, budget);
     useFrame((state) => {
         handle.uniforms.uTime.value = state.clock.elapsedTime;
     });

package/dist/terrain/grassBudget.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_GRASS_COUNT = 1500;
+export declare const DEFAULT_GRASS_DENSITY = 1;
+export declare function resolveGrassInstanceBudget(count: number, density: number, budget?: number): number;

package/dist/terrain/grassBudget.js

@@ -0,0 +1,6 @@
+export const DEFAULT_GRASS_COUNT = 1500;
+export const DEFAULT_GRASS_DENSITY = 1;
+export function resolveGrassInstanceBudget(count, density, budget) {
+    const capped = budget === undefined ? count : Math.min(count, Math.max(0, Math.floor(budget)));
+    return Math.floor(Math.max(0, Math.min(1, density)) * capped);
+}

package/dist/terrain/grassGeometry.js

@@ -8,7 +8,7 @@ export function resolveGrassRange(value, fallback) {
 }
 export function resolveGrassBladeGeometryOptions(options = {}) {
     return {
-        count: Math.max(0, Math.floor(options.count ?? 6000)),
+        count: Math.max(0, Math.floor(options.count ?? 1500)),
         area: options.area ?? 40,
         seed: options.seed ?? 1,
         segments: Math.max(1, Math.floor(options.segments ?? 4)),

package/dist/terrain/terrainDetailMaterial.d.ts

@@ -0,0 +1,14 @@
+import * as THREE from "three";
+import type { ResolvedTerrainDetail } from "@jgengine/core/world/terrain";
+/** The built procedural detail terrain material, ready to mount on the ground mesh. */
+export interface TerrainDetailMaterialHandle {
+    material: THREE.MeshStandardMaterial;
+}
+/**
+ * A `MeshStandardMaterial` whose fragment shader keeps the biome-tinted vertex
+ * colour as the base ground and blends procedural, noise-broken rock (by slope),
+ * sand (by waterline), and snow (by height) over it — textured-reading terrain
+ * with no image assets. Full PBR: lit, shadowed, and fogged like any standard
+ * material, so it composes with the post-processing chain.
+ */
+export declare function createTerrainDetailMaterial(detail: ResolvedTerrainDetail): TerrainDetailMaterialHandle;

package/dist/terrain/terrainDetailMaterial.js

@@ -0,0 +1,90 @@
+import * as THREE from "three";
+const NOISE_GLSL = /* glsl */ `
+float jgHash(vec2 p){ return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453); }
+float jgVNoise(vec2 p){
+  vec2 i = floor(p); vec2 f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  float a = jgHash(i);
+  float b = jgHash(i + vec2(1.0, 0.0));
+  float c = jgHash(i + vec2(0.0, 1.0));
+  float d = jgHash(i + vec2(1.0, 1.0));
+  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
+}
+float jgFbm(vec2 p){
+  float v = 0.0; float amp = 0.5;
+  for (int i = 0; i < 4; i++){ v += amp * jgVNoise(p); p *= 2.0; amp *= 0.5; }
+  return v;
+}
+`;
+/**
+ * A `MeshStandardMaterial` whose fragment shader keeps the biome-tinted vertex
+ * colour as the base ground and blends procedural, noise-broken rock (by slope),
+ * sand (by waterline), and snow (by height) over it — textured-reading terrain
+ * with no image assets. Full PBR: lit, shadowed, and fogged like any standard
+ * material, so it composes with the post-processing chain.
+ */
+export function createTerrainDetailMaterial(detail) {
+    const uniforms = {
+        uRockColor: { value: new THREE.Color(detail.rockColor) },
+        uSandColor: { value: new THREE.Color(detail.sandColor) },
+        uSnowColor: { value: new THREE.Color(detail.snowColor) },
+        uRockSlopeStart: { value: detail.rockSlopeStart },
+        uSnowHeight: { value: detail.snowHeight },
+        uWaterLevel: { value: detail.waterLevel },
+        uDetailScale: { value: Math.max(0.5, detail.detailScale) },
+        uMacroScale: { value: Math.max(0.5, detail.macroScale) },
+        uStrength: { value: detail.strength },
+    };
+    const material = new THREE.MeshStandardMaterial({
+        color: "#ffffff",
+        roughness: detail.roughness,
+        metalness: 0,
+        vertexColors: true,
+    });
+    material.onBeforeCompile = (shader) => {
+        Object.assign(shader.uniforms, uniforms);
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <common>", `#include <common>
+varying vec3 vJgWorldPos;
+varying vec3 vJgWorldNormal;`)
+            .replace("#include <beginnormal_vertex>", `#include <beginnormal_vertex>
+vJgWorldNormal = normalize(mat3(modelMatrix) * objectNormal);`)
+            .replace("#include <begin_vertex>", `#include <begin_vertex>
+vJgWorldPos = (modelMatrix * vec4(transformed, 1.0)).xyz;`);
+        shader.fragmentShader = shader.fragmentShader
+            .replace("#include <common>", `#include <common>
+varying vec3 vJgWorldPos;
+varying vec3 vJgWorldNormal;
+uniform vec3 uRockColor;
+uniform vec3 uSandColor;
+uniform vec3 uSnowColor;
+uniform float uRockSlopeStart;
+uniform float uSnowHeight;
+uniform float uWaterLevel;
+uniform float uDetailScale;
+uniform float uMacroScale;
+uniform float uStrength;
+${NOISE_GLSL}`)
+            .replace("#include <color_fragment>", `#include <color_fragment>
+vec2 jgWp = vJgWorldPos.xz;
+float jgFine = jgFbm(jgWp / uDetailScale);
+float jgMacro = jgFbm(jgWp / uMacroScale);
+float jgSlope = 1.0 - clamp(vJgWorldNormal.y, 0.0, 1.0);
+float jgH = vJgWorldPos.y;
+vec3 jgBase = diffuseColor.rgb;
+jgBase *= mix(1.0 - 0.22 * uStrength, 1.0 + 0.18 * uStrength, jgFine);
+jgBase = mix(jgBase, jgBase * vec3(0.86, 0.9, 0.82), jgMacro * 0.25 * uStrength);
+vec3 jgRock = uRockColor * mix(0.72, 1.15, jgFbm(jgWp / (uDetailScale * 1.7)));
+float jgRockW = smoothstep(uRockSlopeStart, uRockSlopeStart + 0.18, jgSlope) * uStrength;
+vec3 jgCol = mix(jgBase, jgRock, jgRockW);
+vec3 jgSand = uSandColor * mix(0.9, 1.08, jgFine);
+float jgSandW = smoothstep(uWaterLevel + 2.4, uWaterLevel - 0.4, jgH) * (1.0 - jgRockW) * uStrength;
+jgCol = mix(jgCol, jgSand, jgSandW);
+vec3 jgSnow = uSnowColor * mix(0.94, 1.04, jgFine);
+float jgSnowW = smoothstep(uSnowHeight, uSnowHeight + 8.0, jgH) * (1.0 - jgRockW * 0.6) * uStrength;
+jgCol = mix(jgCol, jgSnow, jgSnowW);
+diffuseColor.rgb = jgCol;`);
+    };
+    material.customProgramCacheKey = () => `jgengine-terrain-detail-${detail.rockSlopeStart}-${detail.snowHeight}`;
+    return { material };
+}

package/dist/terrain/terrainMath.d.ts

@@ -32,12 +32,20 @@ export declare function resolveTerrainSize(size?: TerrainArea): ResolvedTerrainS
 export declare function resolveTerrainSegments(segments?: ProceduralTerrainConfig["segments"]): ResolvedTerrainSegments;
 export declare function toNoiseFieldConfig(config?: ProceduralTerrainConfig): NoiseFieldConfig;
 export declare function createProceduralTerrainSampler(config?: ProceduralTerrainConfig): TerrainHeightSampler;
+/** Per-position palette override for multi-biome ground coloring — `createTerrainPaletteSampler` from `@jgengine/core/world/terrain` returns exactly this shape. */
+export type TerrainPaletteSampler = (x: number, z: number) => {
+    low: string;
+    high: string;
+    waterline?: string;
+};
 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];
+    /** Sampled per vertex when set; `colors` still supplies `waterlineHeight` and the fallback. */
+    paletteAt?: TerrainPaletteSampler;
 }
 /**
  * Mesh any `TerrainField` — including a `CarvableField` with craters/mounds written into it — into a

package/dist/terrain/terrainMath.js

@@ -42,10 +42,12 @@ export function createFieldGroundGeometry(field, options = {}) {
         colors: options.colors ?? {},
         center: [cx, cz],
         heightRange: options.heightRange,
+        paletteAt: options.paletteAt,
     });
 }
 function buildGroundGeometry(size, segments, sampler, opts) {
     const colors = opts.colors;
+    const paletteAt = opts.paletteAt;
     const vertexCountX = segments.x + 1;
     const vertexCountZ = segments.z + 1;
     const positions = new Float32Array(vertexCountX * vertexCountZ * 3);
@@ -72,6 +74,13 @@ function buildGroundGeometry(size, segments, sampler, opts) {
             positions[index + 2] = z;
             uvs[uvIndex] = u;
             uvs[uvIndex + 1] = v;
+            if (paletteAt !== undefined) {
+                const palette = paletteAt(x, z);
+                low.set(palette.low);
+                high.set(palette.high);
+                if (waterline !== null && palette.waterline !== undefined)
+                    waterline.set(palette.waterline);
+            }
             const blend = normalizeHeightBlend(y, minHeight, maxHeight);
             const color = low.clone().lerp(high, blend);
             if (waterline !== null && y <= (colors.waterlineHeight ?? 0))

package/dist/touch/OrientationHint.d.ts

@@ -0,0 +1,3 @@
+export declare function OrientationHint({ wanted }: {
+    wanted: "landscape" | "portrait";
+}): import("react").JSX.Element | null;

package/dist/touch/OrientationHint.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+const AUTO_HIDE_MS = 6000;
+export function OrientationHint({ wanted }) {
+    const [dismissed, setDismissed] = useState(false);
+    useEffect(() => {
+        const timer = setTimeout(() => setDismissed(true), AUTO_HIDE_MS);
+        return () => clearTimeout(timer);
+    }, []);
+    if (dismissed)
+        return null;
+    return (_jsx("div", { className: "pointer-events-none absolute inset-x-0 z-50 flex justify-center", style: { top: "calc(env(safe-area-inset-top, 0px) + 12px)" }, children: _jsxs("div", { className: "pointer-events-auto flex items-center gap-2 rounded-full border border-white/25 bg-black/70 px-4 py-2 text-xs font-medium text-white/90 backdrop-blur-sm", children: [_jsx("span", { "aria-hidden": true, className: "text-base leading-none", children: "\u27F3" }), _jsxs("span", { children: ["Best played in ", wanted, " \u2014 rotate your device"] }), _jsx("button", { type: "button", "aria-label": "Dismiss", className: "ml-1 text-white/60 active:text-white", onClick: () => setDismissed(true), children: "\u2715" })] }) }));
+}

package/dist/touch/TouchControlsOverlay.d.ts

@@ -4,6 +4,21 @@ export interface TouchCodeSink {
     onCodeDown(code: string): void;
     onCodeUp(code: string): void;
 }
+/**
+ * Thumb-arc placement for primary buttons around the bottom-right corner:
+ * up to three on an inner ring, the rest on an outer ring. Null means too
+ * many buttons for an arc — the dock falls back to a wrapping grid.
+ */
+export declare function primaryButtonOffsets(count: number, scale?: number): {
+    right: number;
+    bottom: number;
+}[] | null;
+/**
+ * Vertical space (px, excluding device safe areas) the dock occupies above
+ * the bottom edge. The shell publishes it as `--jg-hud-dock-clearance` so
+ * `HudCanvas` regions never collide with touch controls.
+ */
+export declare function touchDockClearance(scheme: TouchScheme | null, scale?: number): number;
 export declare function TouchPlaySurface({ scheme, sink, yawRef, pitchRef, maxPitch, onPrimaryTap, }: {
     scheme: TouchScheme;
     sink: TouchCodeSink;
@@ -12,7 +27,8 @@ export declare function TouchPlaySurface({ scheme, sink, yawRef, pitchRef, maxPi
     maxPitch: number;
     onPrimaryTap: () => void;
 }): import("react").JSX.Element;
-export declare function TouchControlsDock({ scheme, sink }: {
+export declare function TouchControlsDock({ scheme, sink, scale }: {
     scheme: TouchScheme;
     sink: TouchCodeSink;
+    scale?: number;
 }): import("react").JSX.Element;