@jgengine/shell 0.22.0 → 0.24.0

package/dist/scene/cityJunctionSurface.js

@@ -0,0 +1,34 @@
+/**
+ * Surface for a crossing's welded patch: gravel only when every street running through the crossing
+ * is gravel, so an unpaved hamlet's junctions stay gravel while a lane meeting a paved main stays asphalt.
+ * @internal
+ */
+export function junctionSurface(cross, streets) {
+    let touched = false;
+    for (const street of streets) {
+        const reach = cross.radius + street.width * 0.5 + 0.5;
+        if (distanceToPath(cross.x, cross.z, street.points) > reach)
+            continue;
+        if (street.surface !== "gravel")
+            return "asphalt";
+        touched = true;
+    }
+    return touched ? "gravel" : "asphalt";
+}
+function distanceToPath(x, z, points) {
+    if (points.length === 0)
+        return Infinity;
+    if (points.length === 1)
+        return Math.hypot(x - points[0][0], z - points[0][1]);
+    let best = Infinity;
+    for (let i = 1; i < points.length; i += 1) {
+        const [ax, az] = points[i - 1];
+        const [bx, bz] = points[i];
+        const dx = bx - ax;
+        const dz = bz - az;
+        const len2 = dx * dx + dz * dz;
+        const t = len2 === 0 ? 0 : Math.max(0, Math.min(1, ((x - ax) * dx + (z - az) * dz) / len2));
+        best = Math.min(best, Math.hypot(x - (ax + dx * t), z - (az + dz * t)));
+    }
+    return best;
+}

package/dist/settings/settingsController.js

@@ -51,7 +51,7 @@ export function useSettingsCategories(config) {
             const id = busVolumeSettingId(bus.id);
             return {
                 id,
-                label: `${bus.id.charAt(0).toUpperCase()}${bus.id.slice(1)} volume`,
+                label: bus.id === "ui" ? "UI volume" : `${bus.id.charAt(0).toUpperCase()}${bus.id.slice(1)} volume`,
                 kind: "slider",
                 value: store.get(id, bus.gain ?? 1),
                 min: 0,

package/dist/terrain/groundEdgeFade.d.ts

@@ -0,0 +1,67 @@
+import * as THREE from "three";
+/** Options for {@link buildGroundCoverageMask}. */
+export interface GroundCoverageOptions {
+    /** Metres inside the outer edge over which ground goes from clear to opaque. */
+    width: number;
+    /** Gaps between layers narrower than twice this (metres) count as inside, not as an outer edge. Default 1.5. */
+    closeRadius?: number;
+    /** Finest cell size in metres. Default 0.5. */
+    cell?: number;
+    /** Upper bound on cells per axis; large districts get coarser cells. Default 640. */
+    maxCells?: number;
+}
+/**
+ * How far each point of a merged ground footprint lies inside its outer edge, as a grid over world
+ * XZ: `data[row * columns + column]` is 0 on or outside the edge and 255 at `width` metres or more
+ * inside. Cell centres sit at `origin + (index + 0.5) * cell`.
+ */
+export interface GroundCoverageMask {
+    data: Uint8Array;
+    columns: number;
+    rows: number;
+    originX: number;
+    originZ: number;
+    cell: number;
+}
+/**
+ * Rasterize the XZ footprint of ground meshes (roads, block land, parks…) into a
+ * {@link GroundCoverageMask}. Small gaps between layers are closed first, so only the merged
+ * footprint's outer edge fades: seams between layers inside it keep their full opacity. Vertical
+ * faces (curbs) add nothing. Returns `null` when the meshes cover nothing.
+ * @capability ground-edge-fade fade merged ground layers into the terrain at their outer edge, keeping inner seams crisp
+ */
+export declare function buildGroundCoverageMask(geometries: readonly (THREE.BufferGeometry | null | undefined)[], options: GroundCoverageOptions): GroundCoverageMask | null;
+/** Shared uniforms for {@link applyGroundEdgeFade}; `setMask` retargets every material using them without a recompile. */
+export interface GroundEdgeFade {
+    readonly uniforms: {
+        uJgFadeMask: {
+            value: THREE.Texture;
+        };
+        /** `(originX, originZ, columns * cell, rows * cell)`. */
+        uJgFadeBounds: {
+            value: THREE.Vector4;
+        };
+        /** Mask width in metres; scales the noise that breaks up the edge. */
+        uJgFadeWidth: {
+            value: number;
+        };
+    };
+    /** Swap in a new mask (`null` = fully opaque everywhere). The previous texture is disposed. */
+    setMask(mask: GroundCoverageMask | null, width: number): void;
+    dispose(): void;
+}
+/**
+ * Uniforms for one faded footprint, shared by every ground material of one district. Starts fully opaque.
+ * @capability ground-edge-fade fade merged ground layers into the terrain at their outer edge, keeping inner seams crisp
+ */
+export declare function createGroundEdgeFade(): GroundEdgeFade;
+/**
+ * Fade a ground material out at the outer edge of a {@link GroundCoverageMask}: clear on the edge,
+ * opaque `width` metres inside, with a noise-broken line. Seams between layers inside the
+ * footprint are untouched, so a district keeps crisp road/plaza edges while its outer boundary
+ * melts into the terrain. Turns on blending (depth writes stay on); give stacked layers ascending
+ * `renderOrder` so lower ones draw first. Chains any existing `onBeforeCompile`, so it composes
+ * with `createSurfaceRibbonMaterial` and plain `MeshStandardMaterial`s alike.
+ * @capability ground-edge-fade fade merged ground layers into the terrain at their outer edge, keeping inner seams crisp
+ */
+export declare function applyGroundEdgeFade<M extends THREE.Material>(material: M, fade: GroundEdgeFade): M;

package/dist/terrain/groundEdgeFade.js

@@ -0,0 +1,234 @@
+import * as THREE from "three";
+const DIAGONAL = Math.SQRT2;
+/** Two-pass chamfer distance (in cells) from every cell to the nearest seed cell. */
+function chamfer(seed, columns, rows) {
+    const d = new Float32Array(columns * rows);
+    for (let i = 0; i < d.length; i += 1)
+        d[i] = seed[i] === 1 ? 0 : Infinity;
+    for (let j = 0; j < rows; j += 1) {
+        for (let i = 0; i < columns; i += 1) {
+            const k = j * columns + i;
+            let best = d[k];
+            if (i > 0)
+                best = Math.min(best, d[k - 1] + 1);
+            if (j > 0) {
+                best = Math.min(best, d[k - columns] + 1);
+                if (i > 0)
+                    best = Math.min(best, d[k - columns - 1] + DIAGONAL);
+                if (i + 1 < columns)
+                    best = Math.min(best, d[k - columns + 1] + DIAGONAL);
+            }
+            d[k] = best;
+        }
+    }
+    for (let j = rows - 1; j >= 0; j -= 1) {
+        for (let i = columns - 1; i >= 0; i -= 1) {
+            const k = j * columns + i;
+            let best = d[k];
+            if (i + 1 < columns)
+                best = Math.min(best, d[k + 1] + 1);
+            if (j + 1 < rows) {
+                best = Math.min(best, d[k + columns] + 1);
+                if (i + 1 < columns)
+                    best = Math.min(best, d[k + columns + 1] + DIAGONAL);
+                if (i > 0)
+                    best = Math.min(best, d[k + columns - 1] + DIAGONAL);
+            }
+            d[k] = best;
+        }
+    }
+    return d;
+}
+/**
+ * Rasterize the XZ footprint of ground meshes (roads, block land, parks…) into a
+ * {@link GroundCoverageMask}. Small gaps between layers are closed first, so only the merged
+ * footprint's outer edge fades: seams between layers inside it keep their full opacity. Vertical
+ * faces (curbs) add nothing. Returns `null` when the meshes cover nothing.
+ * @capability ground-edge-fade fade merged ground layers into the terrain at their outer edge, keeping inner seams crisp
+ */
+export function buildGroundCoverageMask(geometries, options) {
+    const width = Math.max(1e-3, options.width);
+    const closeRadius = Math.max(0, options.closeRadius ?? 1.5);
+    let minX = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxZ = -Infinity;
+    for (const geometry of geometries) {
+        const position = geometry?.getAttribute("position");
+        if (position === undefined)
+            continue;
+        for (let v = 0; v < position.count; v += 1) {
+            const x = position.getX(v);
+            const z = position.getZ(v);
+            if (x < minX)
+                minX = x;
+            if (x > maxX)
+                maxX = x;
+            if (z < minZ)
+                minZ = z;
+            if (z > maxZ)
+                maxZ = z;
+        }
+    }
+    if (!Number.isFinite(minX))
+        return null;
+    const maxCells = Math.max(8, Math.floor(options.maxCells ?? 640));
+    const pad = closeRadius + 2;
+    const spanX = maxX - minX + pad * 2;
+    const spanZ = maxZ - minZ + pad * 2;
+    const cell = Math.max(options.cell ?? 0.5, spanX / maxCells, spanZ / maxCells);
+    const columns = Math.max(2, Math.ceil(spanX / cell));
+    const rows = Math.max(2, Math.ceil(spanZ / cell));
+    const originX = minX - pad;
+    const originZ = minZ - pad;
+    const covered = new Uint8Array(columns * rows);
+    let any = false;
+    for (const geometry of geometries) {
+        const position = geometry?.getAttribute("position");
+        if (geometry == null || position === undefined)
+            continue;
+        const index = geometry.getIndex();
+        const count = index === null ? position.count : index.count;
+        for (let t = 0; t + 2 < count; t += 3) {
+            const a = index === null ? t : index.getX(t);
+            const b = index === null ? t + 1 : index.getX(t + 1);
+            const c = index === null ? t + 2 : index.getX(t + 2);
+            const ax = position.getX(a);
+            const az = position.getZ(a);
+            const bx = position.getX(b);
+            const bz = position.getZ(b);
+            const cx = position.getX(c);
+            const cz = position.getZ(c);
+            const area = (bx - ax) * (cz - az) - (bz - az) * (cx - ax);
+            if (Math.abs(area) < 1e-6)
+                continue;
+            const sign = area > 0 ? 1 : -1;
+            const i0 = Math.max(0, Math.floor((Math.min(ax, bx, cx) - originX) / cell - 0.5));
+            const i1 = Math.min(columns - 1, Math.ceil((Math.max(ax, bx, cx) - originX) / cell - 0.5));
+            const j0 = Math.max(0, Math.floor((Math.min(az, bz, cz) - originZ) / cell - 0.5));
+            const j1 = Math.min(rows - 1, Math.ceil((Math.max(az, bz, cz) - originZ) / cell - 0.5));
+            for (let j = j0; j <= j1; j += 1) {
+                const pz = originZ + (j + 0.5) * cell;
+                for (let i = i0; i <= i1; i += 1) {
+                    const px = originX + (i + 0.5) * cell;
+                    const e0 = ((bx - ax) * (pz - az) - (bz - az) * (px - ax)) * sign;
+                    const e1 = ((cx - bx) * (pz - bz) - (cz - bz) * (px - bx)) * sign;
+                    const e2 = ((ax - cx) * (pz - cz) - (az - cz) * (px - cx)) * sign;
+                    if (e0 >= 0 && e1 >= 0 && e2 >= 0) {
+                        covered[j * columns + i] = 1;
+                        any = true;
+                    }
+                }
+            }
+        }
+    }
+    if (!any)
+        return null;
+    // Morphological closing: grow the footprint by `closeRadius`, then measure inward from the grown
+    // edge less that radius, so a narrow gap between two layers never reads as an outer edge.
+    const toCovered = chamfer(covered, columns, rows);
+    const outsideGrown = new Uint8Array(columns * rows);
+    for (let k = 0; k < outsideGrown.length; k += 1)
+        outsideGrown[k] = toCovered[k] * cell > closeRadius ? 1 : 0;
+    const toOutside = chamfer(outsideGrown, columns, rows);
+    const data = new Uint8Array(columns * rows);
+    for (let k = 0; k < data.length; k += 1) {
+        // Centre-to-centre distance overshoots the edge between two cells by half a cell.
+        const inside = (toOutside[k] - 0.5) * cell - closeRadius;
+        data[k] = Math.round(Math.max(0, Math.min(1, inside / width)) * 255);
+    }
+    return { data, columns, rows, originX, originZ, cell };
+}
+function opaqueTexture() {
+    const texture = new THREE.DataTexture(new Uint8Array([255]), 1, 1, THREE.RedFormat);
+    texture.needsUpdate = true;
+    return texture;
+}
+/**
+ * Uniforms for one faded footprint, shared by every ground material of one district. Starts fully opaque.
+ * @capability ground-edge-fade fade merged ground layers into the terrain at their outer edge, keeping inner seams crisp
+ */
+export function createGroundEdgeFade() {
+    const uniforms = {
+        uJgFadeMask: { value: opaqueTexture() },
+        uJgFadeBounds: { value: new THREE.Vector4(-1e6, -1e6, 2e6, 2e6) },
+        uJgFadeWidth: { value: 1 },
+    };
+    return {
+        uniforms,
+        setMask(mask, width) {
+            uniforms.uJgFadeMask.value.dispose();
+            if (mask === null) {
+                uniforms.uJgFadeMask.value = opaqueTexture();
+                uniforms.uJgFadeBounds.value.set(-1e6, -1e6, 2e6, 2e6);
+            }
+            else {
+                const texture = new THREE.DataTexture(mask.data, mask.columns, mask.rows, THREE.RedFormat);
+                texture.magFilter = THREE.LinearFilter;
+                texture.minFilter = THREE.LinearFilter;
+                texture.wrapS = THREE.ClampToEdgeWrapping;
+                texture.wrapT = THREE.ClampToEdgeWrapping;
+                // One byte per texel: rows are not 4-byte aligned unless `columns` happens to be.
+                texture.unpackAlignment = 1;
+                texture.needsUpdate = true;
+                uniforms.uJgFadeMask.value = texture;
+                uniforms.uJgFadeBounds.value.set(mask.originX, mask.originZ, mask.columns * mask.cell, mask.rows * mask.cell);
+            }
+            uniforms.uJgFadeWidth.value = Math.max(1e-3, width);
+        },
+        dispose() {
+            uniforms.uJgFadeMask.value.dispose();
+        },
+    };
+}
+const FADE_FRAGMENT_GLSL = /* glsl */ `
+{
+  float jgFadeIn = texture2D(uJgFadeMask, (vJgFadePos - uJgFadeBounds.xy) / uJgFadeBounds.zw).r;
+  // Two octaves of value noise keep the edge from reading as a traced outline.
+  float jgFadeN = jgFadeNoise(vJgFadePos / max(0.6, uJgFadeWidth * 1.2)) * 0.7 + jgFadeNoise(vJgFadePos / max(0.25, uJgFadeWidth * 0.3) + 17.3) * 0.3 - 0.5;
+  diffuseColor.a *= smoothstep(0.0, 1.0, (jgFadeIn - 0.15 + jgFadeN * 0.35) / 0.7);
+}
+`;
+const FADE_NOISE_GLSL = /* glsl */ `
+float jgFadeHash(vec2 p) {
+  return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453);
+}
+float jgFadeNoise(vec2 p) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  return mix(mix(jgFadeHash(i), jgFadeHash(i + vec2(1.0, 0.0)), u.x), mix(jgFadeHash(i + vec2(0.0, 1.0)), jgFadeHash(i + vec2(1.0, 1.0)), u.x), u.y);
+}
+`;
+/**
+ * Fade a ground material out at the outer edge of a {@link GroundCoverageMask}: clear on the edge,
+ * opaque `width` metres inside, with a noise-broken line. Seams between layers inside the
+ * footprint are untouched, so a district keeps crisp road/plaza edges while its outer boundary
+ * melts into the terrain. Turns on blending (depth writes stay on); give stacked layers ascending
+ * `renderOrder` so lower ones draw first. Chains any existing `onBeforeCompile`, so it composes
+ * with `createSurfaceRibbonMaterial` and plain `MeshStandardMaterial`s alike.
+ * @capability ground-edge-fade fade merged ground layers into the terrain at their outer edge, keeping inner seams crisp
+ */
+export function applyGroundEdgeFade(material, fade) {
+    const previousCompile = material.onBeforeCompile;
+    const previousKey = material.customProgramCacheKey;
+    material.transparent = true;
+    material.onBeforeCompile = (shader, renderer) => {
+        previousCompile.call(material, shader, renderer);
+        Object.assign(shader.uniforms, fade.uniforms);
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <common>", "#include <common>\nvarying vec2 vJgFadePos;")
+            .replace("#include <begin_vertex>", "#include <begin_vertex>\nvJgFadePos = (modelMatrix * vec4(transformed, 1.0)).xz;");
+        shader.fragmentShader = shader.fragmentShader
+            .replace("#include <common>", `#include <common>
+varying vec2 vJgFadePos;
+uniform sampler2D uJgFadeMask;
+uniform vec4 uJgFadeBounds;
+uniform float uJgFadeWidth;
+${FADE_NOISE_GLSL}`)
+            .replace("#include <alphamap_fragment>", `#include <alphamap_fragment>\n${FADE_FRAGMENT_GLSL}`);
+    };
+    material.customProgramCacheKey = () => `${previousKey.call(material)}-jgedgefade`;
+    material.needsUpdate = true;
+    return material;
+}

package/dist/terrain/index.d.ts

@@ -10,3 +10,8 @@ export { createSeededRandom, hashNoise2, seedToUint32, type TerrainSeed } from "
 export { createFieldGroundGeometry, createProceduralGroundGeometry, createProceduralTerrainSampler, normalizeHeightBlend, resolveTerrainSegments, resolveTerrainSize, toNoiseFieldConfig, type FieldGroundOptions, type ProceduralTerrainConfig, type ResolvedTerrainSegments, type ResolvedTerrainSize, type TerrainArea, type TerrainHeightSampler, type TerrainSurfaceColorOptions, 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";
 export { createTerrainPaintColorSampler, type TerrainPaintColorSampler, type TerrainPaintSource } from "./terrainPaintColor.js";
+export { ALL_TERRAIN_SURFACE_CLASSES, createTerrainDetailMaterial, type TerrainDetailMaterialHandle, type TerrainDetailMaterialOptions, type TerrainDetailMaterialTextures, } from "./terrainDetailMaterial.js";
+export { createTerrainPaintTextures, MAX_TERRAIN_PAINT_LAYERS, packTerrainPaintWeights, terrainSurfaceClass, terrainSurfaceClassIndex, terrainSurfaceRoughness, type TerrainPaintSlot, type TerrainPaintTextures, type TerrainPaintWeights, type TerrainSurfaceClass, } from "./terrainSurfaces.js";
+export { TerrainQualityContext, useTerrainQuality } from "./terrainQuality.js";
+export { createSurfaceRibbonMaterial, resolvePathSurface, RIBBON_FRAME_ATTRIBUTE, ribbonEdgeMargin, ribbonSurfaceFrame, useSurfaceRibbonMaterial, type RibbonSurfaceStyle, type SurfaceRibbonMaterialOptions, } from "./surfaceRibbonMaterial.js";
+export { applyGroundEdgeFade, buildGroundCoverageMask, createGroundEdgeFade, type GroundCoverageMask, type GroundCoverageOptions, type GroundEdgeFade, } from "./groundEdgeFade.js";

package/dist/terrain/index.js

@@ -10,3 +10,8 @@ export { createSeededRandom, hashNoise2, seedToUint32 } from "./random.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";
 export { createTerrainPaintColorSampler } from "./terrainPaintColor.js";
+export { ALL_TERRAIN_SURFACE_CLASSES, createTerrainDetailMaterial, } from "./terrainDetailMaterial.js";
+export { createTerrainPaintTextures, MAX_TERRAIN_PAINT_LAYERS, packTerrainPaintWeights, terrainSurfaceClass, terrainSurfaceClassIndex, terrainSurfaceRoughness, } from "./terrainSurfaces.js";
+export { TerrainQualityContext, useTerrainQuality } from "./terrainQuality.js";
+export { createSurfaceRibbonMaterial, resolvePathSurface, RIBBON_FRAME_ATTRIBUTE, ribbonEdgeMargin, ribbonSurfaceFrame, useSurfaceRibbonMaterial, } from "./surfaceRibbonMaterial.js";
+export { applyGroundEdgeFade, buildGroundCoverageMask, createGroundEdgeFade, } from "./groundEdgeFade.js";

package/dist/terrain/surfaceRibbonMaterial.d.ts

@@ -0,0 +1,62 @@
+import * as THREE from "three";
+import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
+/** Vertex attribute {@link ribbonSurfaceFrame} fills: metres along the ribbon, signed metres across it, metres to its far end. */
+export declare const RIBBON_FRAME_ATTRIBUTE = "jgRibbon";
+/** How a ground ribbon (path, road, sidewalk) shades: procedural surface, edge blend and wear. */
+export interface RibbonSurfaceStyle {
+    /** Surface id classified like terrain paint (`"dirt"`, `"gravel"`, `"asphalt"`, …). */
+    surface: string;
+    /** Width of the edge fade in metres, centred on the authored edge. 0 keeps a hard opaque edge. */
+    feather: number;
+    /** How far noise pushes the edge in or out, in metres. */
+    warp: number;
+    /** Wheel ruts on soft ground, polished tyre lanes on pavement, 0..1. */
+    wear: number;
+}
+/** Options for {@link createSurfaceRibbonMaterial}. */
+export interface SurfaceRibbonMaterialOptions extends Partial<RibbonSurfaceStyle> {
+    /** Authored hue; the procedural surface varies around it. */
+    color: string;
+    /** Authored half width in metres; the edge fade is centred on it. */
+    halfWidth: number;
+    /** Override the surface class's default roughness. */
+    roughness?: number;
+    /** Pattern frequency multiplier. Default 1. */
+    scale?: number;
+    /** Graphics tier, from `useTerrainQuality()`. `low` drops micro-normals and fine octaves. Default `high`. */
+    quality?: GraphicsQuality;
+    /** Pull the ribbon toward the camera in depth so it wins over a coplanar layer beneath. */
+    polygonOffset?: boolean;
+    /** Multiply by the geometry's `color` attribute, as city ground meshes carry per-vertex tints. */
+    vertexColors?: boolean;
+}
+/**
+ * Default ribbon look for an authored path: the surface comes from `meta.surface`, else the path
+ * kind (`"road"` paves, `"gravel-track"` gravels), else dirt. Soft ground gets a noise-warped edge
+ * that fades into the terrain and wheel ruts; pavement keeps a near-hard edge and faint tyre lanes.
+ * `meta.surfaceDetail: false` (or `meta.surface: false`) returns `null` for the old flat ribbon;
+ * `meta.edgeSoftness` scales the fade (0 = hard) and `meta.wear` sets wear 0..1.
+ */
+export declare function resolvePathSurface(kind: string, width: number, meta: Readonly<Record<string, unknown>> | undefined): RibbonSurfaceStyle | null;
+/** Extra ribbon width (metres, both sides together) a style needs so its fade straddles the authored edge. */
+export declare function ribbonEdgeMargin(style: Pick<RibbonSurfaceStyle, "feather" | "warp">): number;
+/**
+ * Per-vertex `(along, across, toEnd)` for a ribbon in `buildRoadRibbon`'s layout (left/right vertex
+ * pairs down the centreline). Pass several ribbons' position arrays to get one concatenated frame
+ * for a merged mesh; each ribbon's distances restart at its own start.
+ */
+export declare function ribbonSurfaceFrame(ribbons: readonly Float32Array[]): Float32Array;
+/**
+ * A `MeshStandardMaterial` that shades a ground ribbon (path, road, sidewalk) with the terrain's own
+ * procedural surface functions, so a dirt track or asphalt strip matches painted ground: the
+ * authored colour varied by the surface class's grain, roughness and micro-normal, wheel ruts or tyre
+ * lanes, and (with `feather > 0`) a noise-warped edge that fades into the terrain. The geometry needs
+ * a {@link RIBBON_FRAME_ATTRIBUTE} attribute from {@link ribbonSurfaceFrame}; build it wider by
+ * {@link ribbonEdgeMargin} so the fade straddles the authored edge. The caller disposes the material.
+ */
+export declare function createSurfaceRibbonMaterial(options: SurfaceRibbonMaterialOptions): THREE.MeshStandardMaterial;
+/**
+ * {@link createSurfaceRibbonMaterial} for a React mesh: rebuilt only when an option changes and
+ * disposed on unmount. Pass `null` to get `null` (the caller falls back to a flat material).
+ */
+export declare function useSurfaceRibbonMaterial(options: SurfaceRibbonMaterialOptions | null): THREE.MeshStandardMaterial | null;

package/dist/terrain/surfaceRibbonMaterial.js

@@ -0,0 +1,227 @@
+import { useEffect, useMemo } from "react";
+import * as THREE from "three";
+import { NOISE_GLSL, SURFACE_BUMP_NORMAL_GLSL, SURFACE_FUNCTIONS_GLSL } from "./terrainSurfaceShader.js";
+import { terrainSurfaceClass, terrainSurfaceClassIndex, terrainSurfaceRoughness } from "./terrainSurfaces.js";
+/** Vertex attribute {@link ribbonSurfaceFrame} fills: metres along the ribbon, signed metres across it, metres to its far end. */
+export const RIBBON_FRAME_ATTRIBUTE = "jgRibbon";
+const SOFT_GROUND = new Set(["dirt", "mud", "sand", "gravel", "grass", "ground", "snow"]);
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+/**
+ * Default ribbon look for an authored path: the surface comes from `meta.surface`, else the path
+ * kind (`"road"` paves, `"gravel-track"` gravels), else dirt. Soft ground gets a noise-warped edge
+ * that fades into the terrain and wheel ruts; pavement keeps a near-hard edge and faint tyre lanes.
+ * `meta.surfaceDetail: false` (or `meta.surface: false`) returns `null` for the old flat ribbon;
+ * `meta.edgeSoftness` scales the fade (0 = hard) and `meta.wear` sets wear 0..1.
+ */
+export function resolvePathSurface(kind, width, meta) {
+    if (meta?.["surfaceDetail"] === false || meta?.["surface"] === false)
+        return null;
+    const id = typeof meta?.["surface"] === "string" ? meta["surface"] : kind;
+    const classified = terrainSurfaceClass(id);
+    const cls = classified === "ground" ? "dirt" : classified;
+    const surface = classified === "ground" ? "dirt" : id;
+    const soft = SOFT_GROUND.has(cls);
+    const softness = typeof meta?.["edgeSoftness"] === "number" ? Math.max(0, meta["edgeSoftness"]) : 1;
+    const feather = (soft ? clamp(width * 0.18, 0.35, 1.6) : clamp(width * 0.04, 0.08, 0.3)) * softness;
+    const warp = (soft ? clamp(width * 0.08, 0.15, 0.6) : 0.03) * softness;
+    const wear = typeof meta?.["wear"] === "number" ? clamp(meta["wear"], 0, 1) : soft ? 1 : 0.6;
+    return { surface, feather, warp, wear };
+}
+/** Extra ribbon width (metres, both sides together) a style needs so its fade straddles the authored edge. */
+export function ribbonEdgeMargin(style) {
+    return style.feather + style.warp * 2;
+}
+/**
+ * Per-vertex `(along, across, toEnd)` for a ribbon in `buildRoadRibbon`'s layout (left/right vertex
+ * pairs down the centreline). Pass several ribbons' position arrays to get one concatenated frame
+ * for a merged mesh; each ribbon's distances restart at its own start.
+ */
+export function ribbonSurfaceFrame(ribbons) {
+    const total = ribbons.reduce((sum, positions) => sum + positions.length, 0);
+    const out = new Float32Array(total);
+    let offset = 0;
+    for (const p of ribbons) {
+        const pairs = Math.floor(p.length / 6);
+        let along = 0;
+        let px = 0;
+        let pz = 0;
+        for (let i = 0; i < pairs; i++) {
+            const b = i * 6;
+            const cx = (p[b] + p[b + 3]) / 2;
+            const cz = (p[b + 2] + p[b + 5]) / 2;
+            if (i > 0)
+                along += Math.hypot(cx - px, cz - pz);
+            px = cx;
+            pz = cz;
+            const half = Math.hypot(p[b] - p[b + 3], p[b + 2] - p[b + 5]) / 2;
+            out[offset + b] = along;
+            out[offset + b + 1] = half;
+            out[offset + b + 3] = along;
+            out[offset + b + 4] = -half;
+        }
+        for (let i = 0; i < pairs; i++) {
+            const b = offset + i * 6;
+            out[b + 2] = along - out[b];
+            out[b + 5] = along - out[b + 3];
+        }
+        offset += p.length;
+    }
+    return out;
+}
+const RIBBON_FRAGMENT_GLSL = /* glsl */ `
+vec2 jgWp = vJgWorldPos.xz;
+jgFootprint = max(length(dFdx(vJgWorldPos)), length(dFdy(vJgWorldPos)));
+JgSurf jgS = jgSurface(JG_RIBBON_CLASS, diffuseColor.rgb, uJgRough, uJgScale, vJgWorldPos);
+vec3 jgCol = jgS.albedo;
+float jgRough = jgS.rough;
+float jgBumpH = jgS.bump;
+float jgAcross = vJgRibbon.y;
+jgCol *= 1.0 + (jgFbm2(jgWp / 14.0 + vec2(3.7, 61.2)) - 0.5) * 0.24;
+#if defined(JG_RIBBON_PAVED) && !defined(JG_SURFACE_LOW)
+{
+  // Weathered pavement: resurfaced patches, exposed aggregate and a partial crack network.
+  jgCol *= 1.0 + (jgFbm3o(jgWp / 5.0 + 11.0) - 0.5) * 0.34;
+  jgCol *= 1.0 + (jgVNoise(jgWp * 16.0) - 0.5) * 0.26 * jgBand(16.0);
+  vec3 jgCell = jgVoronoi(jgWp * 0.32 + 5.1);
+  float jgCrack = (1.0 - smoothstep(0.0, 0.03, jgCell.y)) * smoothstep(0.45, 0.6, jgVNoise(jgWp * 0.45 + 3.3)) * jgBand(2.0);
+  jgCol *= 1.0 - 0.4 * jgCrack;
+  jgRough += 0.05 * jgCrack;
+  jgBumpH -= jgCrack * 0.004;
+}
+#endif
+#ifdef JG_RIBBON_WEAR
+{
+  // Two wheel tracks a cart-axle apart, wandering together along the ribbon.
+  float jgWob = (jgVNoise(vec2(vJgRibbon.x * 0.09, 4.7)) - 0.5) * uJgHalfWidth * 0.35;
+  float jgRutD = abs(abs(jgAcross - jgWob) - uJgHalfWidth * 0.45);
+  float jgRutW = max(0.15, uJgHalfWidth * 0.14);
+  float jgRut = exp(-(jgRutD * jgRutD) / (jgRutW * jgRutW)) * (0.55 + 0.45 * jgVNoise(vec2(vJgRibbon.x * 0.4, 9.1))) * uJgWear;
+#ifdef JG_RIBBON_PAVED
+  jgCol *= 1.0 - 0.22 * jgRut;
+  jgRough -= 0.16 * jgRut;
+#else
+  // Trodden band: packed flat, fewer loose grains and a little dustier, so the track reads against
+  // painted dirt of the same hue; then darker ruts and loose soil heaped toward the shoulders.
+  float jgTrod = (1.0 - smoothstep(uJgHalfWidth * 0.5, uJgHalfWidth * 0.95, abs(jgAcross))) * uJgWear;
+  jgCol = mix(jgCol, diffuseColor.rgb * (0.96 + 0.12 * jgFbm2(jgWp * 0.7 + 2.9)), 0.5 * jgTrod);
+  jgCol *= 1.0 + 0.08 * jgTrod;
+  jgBumpH *= 1.0 - 0.6 * jgTrod;
+  jgCol *= 1.0 - 0.32 * jgRut;
+  jgRough -= 0.12 * jgRut;
+  jgBumpH -= jgRut * 0.03;
+  float jgShoulder = smoothstep(uJgHalfWidth * 0.6, uJgHalfWidth, abs(jgAcross)) * uJgWear;
+  jgCol *= 1.0 - 0.16 * jgShoulder;
+  jgBumpH += jgShoulder * 0.014;
+#endif
+}
+#endif
+#ifdef JG_RIBBON_EDGE
+{
+  float jgEdgeN = (jgFbm2(jgWp * 0.55 + 7.3) - 0.5) * 2.0 + (jgVNoise(jgWp * 2.3 + 1.7) - 0.5) * 0.6;
+  float jgEdge = uJgHalfWidth + jgEdgeN * uJgWarp;
+  float jgAlpha = 1.0 - smoothstep(jgEdge - uJgFeather * 0.5, jgEdge + uJgFeather * 0.5, abs(jgAcross));
+  jgAlpha *= smoothstep(0.0, uJgFeather, min(vJgRibbon.x, vJgRibbon.z) + jgEdgeN * uJgWarp);
+  // Taller grains (pebbles, clods) hold on longer, so the edge breaks up instead of fading evenly.
+  jgAlpha = clamp(jgAlpha + (jgS.height - 0.4) * 2.4 * jgAlpha * (1.0 - jgAlpha), 0.0, 1.0);
+  diffuseColor.a *= jgAlpha;
+  jgBumpH *= jgAlpha;
+}
+#endif
+#ifdef USE_COLOR_ALPHA
+{
+  // A per-vertex fade interpolated across big triangles draws straight iso-lines; warp it with noise
+  // so it breaks up like painted terrain. Fully opaque or fully clear vertices are left alone.
+  float jgA = diffuseColor.a;
+  float jgMid = min(jgA, 1.0 - jgA);
+  float jgFadeN = jgFbm2(jgWp * 0.35 + 21.7) - 0.5 + (jgVNoise(jgWp * 1.7 + 5.3) - 0.5) * 0.4;
+  diffuseColor.a = clamp(jgA + jgFadeN * min(1.0, jgMid * 4.0) * 1.1, 0.0, 1.0);
+  diffuseColor.a = smoothstep(0.08, 0.92, diffuseColor.a);
+}
+#endif
+diffuseColor.rgb = jgCol;
+`;
+/**
+ * A `MeshStandardMaterial` that shades a ground ribbon (path, road, sidewalk) with the terrain's own
+ * procedural surface functions, so a dirt track or asphalt strip matches painted ground: the
+ * authored colour varied by the surface class's grain, roughness and micro-normal, wheel ruts or tyre
+ * lanes, and (with `feather > 0`) a noise-warped edge that fades into the terrain. The geometry needs
+ * a {@link RIBBON_FRAME_ATTRIBUTE} attribute from {@link ribbonSurfaceFrame}; build it wider by
+ * {@link ribbonEdgeMargin} so the fade straddles the authored edge. The caller disposes the material.
+ */
+export function createSurfaceRibbonMaterial(options) {
+    const cls = terrainSurfaceClass(options.surface ?? "road");
+    const classIndex = terrainSurfaceClassIndex(cls);
+    const low = options.quality === "low";
+    const feather = Math.max(0, options.feather ?? 0);
+    const edge = feather > 0;
+    const wear = clamp(options.wear ?? 0, 0, 1);
+    const paved = cls === "road" || cls === "rock";
+    const roughness = options.roughness ?? terrainSurfaceRoughness(cls);
+    const material = new THREE.MeshStandardMaterial({
+        color: options.color,
+        roughness,
+        metalness: 0,
+        side: THREE.DoubleSide,
+        transparent: edge,
+        vertexColors: options.vertexColors === true,
+        ...(options.polygonOffset === true ? { polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1 } : {}),
+    });
+    const uniforms = {
+        uJgRough: { value: roughness },
+        uJgScale: { value: options.scale ?? 1 },
+        uJgHalfWidth: { value: Math.max(0.01, options.halfWidth) },
+        uJgFeather: { value: Math.max(1e-3, feather) },
+        uJgWarp: { value: Math.max(0, options.warp ?? 0) },
+        uJgWear: { value: wear },
+    };
+    material.defines = {
+        JG_RIBBON_CLASS: String(classIndex),
+        JG_SURFACE_CLASSES: String(1 << classIndex),
+        ...(low ? { JG_SURFACE_LOW: "" } : {}),
+        ...(edge ? { JG_RIBBON_EDGE: "" } : {}),
+        ...(wear > 0 ? { JG_RIBBON_WEAR: "" } : {}),
+        ...(paved ? { JG_RIBBON_PAVED: "" } : {}),
+    };
+    material.onBeforeCompile = (shader) => {
+        Object.assign(shader.uniforms, uniforms);
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <common>", `#include <common>
+attribute vec3 ${RIBBON_FRAME_ATTRIBUTE};
+varying vec3 vJgWorldPos;
+varying vec3 vJgRibbon;`)
+            .replace("#include <begin_vertex>", `#include <begin_vertex>
+vJgWorldPos = (modelMatrix * vec4(transformed, 1.0)).xyz;
+vJgRibbon = ${RIBBON_FRAME_ATTRIBUTE};`);
+        shader.fragmentShader = shader.fragmentShader
+            .replace("#include <common>", `#include <common>
+varying vec3 vJgWorldPos;
+varying vec3 vJgRibbon;
+uniform float uJgRough;
+uniform float uJgScale;
+uniform float uJgHalfWidth;
+uniform float uJgFeather;
+uniform float uJgWarp;
+uniform float uJgWear;
+${NOISE_GLSL}
+${SURFACE_FUNCTIONS_GLSL}`)
+            .replace("#include <color_fragment>", `#include <color_fragment>\n${RIBBON_FRAGMENT_GLSL}`)
+            .replace("#include <roughnessmap_fragment>", `#include <roughnessmap_fragment>
+roughnessFactor = clamp(jgRough, 0.04, 1.0);`)
+            .replace("#include <normal_fragment_maps>", `#include <normal_fragment_maps>
+${SURFACE_BUMP_NORMAL_GLSL}`);
+    };
+    material.customProgramCacheKey = () => `jgengine-surface-ribbon-${classIndex}-${low ? "low" : "full"}-${edge ? "edge" : "hard"}-${wear > 0 ? "wear" : "clean"}`;
+    return material;
+}
+/**
+ * {@link createSurfaceRibbonMaterial} for a React mesh: rebuilt only when an option changes and
+ * disposed on unmount. Pass `null` to get `null` (the caller falls back to a flat material).
+ */
+export function useSurfaceRibbonMaterial(options) {
+    const o = options;
+    const material = useMemo(() => (o === null ? null : createSurfaceRibbonMaterial(o)), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [o === null, o?.color, o?.halfWidth, o?.surface, o?.feather, o?.warp, o?.wear, o?.roughness, o?.scale, o?.quality, o?.polygonOffset, o?.vertexColors]);
+    useEffect(() => () => material?.dispose(), [material]);
+    return material;
+}