@jgengine/core 0.9.0 → 0.10.0

package/dist/world/terrain.js

@@ -1,3 +1,4 @@
+import { nearestOnPath } from "./roads.js";
 function clamp01(value) {
     return value < 0 ? 0 : value > 1 ? 1 : value;
 }
@@ -13,6 +14,7 @@ function hash2(ix, iz, seed) {
     h ^= h >>> 12;
     return (h >>> 0) / 4294967295;
 }
+/** Smoothly interpolated 2D value noise in `[-1, 1]` for the given seed. */
 export function valueNoise(x, z, seed) {
     const x0 = Math.floor(x);
     const z0 = Math.floor(z);
@@ -28,6 +30,7 @@ export function valueNoise(x, z, seed) {
     const bottom = lerp(v01, v11, sx);
     return lerp(top, bottom, sz) * 2 - 1;
 }
+/** Layers `valueNoise` octaves per `config` into a single normalized noise sample. */
 export function fractalNoise(x, z, config) {
     let amplitude = 1;
     let frequency = config.frequency;
@@ -57,6 +60,7 @@ export function seedFrom(value, fallback) {
     }
     return fallback;
 }
+/** Derives a `TerrainField.sampleNormal` from a height sampler via finite-difference gradients. */
 export function withNormal(sampleHeight) {
     const epsilon = 0.75;
     return (x, z) => {
@@ -81,9 +85,11 @@ export const FLAT_FIELD = {
     sampleHeight: () => 0,
     sampleNormal: () => [0, 1, 0],
 };
+/** A flat, zero-height `TerrainField` for arenas with no elevation. */
 export function flatField() {
     return FLAT_FIELD;
 }
+/** Builds a `TerrainField` whose height is fractal noise shaped by `config`. */
 export function noiseField(config = {}) {
     const fractal = {
         seed: seedFrom(config.seed, 1337),
@@ -120,6 +126,7 @@ function smoothstep(edge0, edge1, value) {
     const t = clamp01((value - edge0) / (edge1 - edge0));
     return t * t * (3 - 2 * t);
 }
+/** Builds a `TerrainField` with a flat spawn plateau, rolling hills, and a basin, for combat arenas. */
 export function arenaField(config = {}) {
     const seed = seedFrom(config.seed ?? "arena", 7);
     const rolling = {
@@ -153,6 +160,10 @@ export function groundFieldFor(world) {
         return resolveEnvironmentField(world);
     return flatField();
 }
+/** Whether a world declares real terrain (base heightfield or islands) rather than a flat plane — gates terrain-floor sampling in the movement controllers. */
+export function hasEnvironmentTerrain(world) {
+    return world?.kind === "environment" && (world.terrain !== undefined || (world.islands?.length ?? 0) > 0);
+}
 /** Ground height between islands when no base terrain exists — deep enough to read as a fall into the void, finite so physics stays sane. */
 export const ISLAND_VOID_HEIGHT = -256;
 function islandContains(descriptor, x, z) {
@@ -236,6 +247,32 @@ export const TERRAIN_MATERIAL_PALETTES = {
     highland: { low: "#414f33", high: "#a3a86b", waterline: "#365f63" },
     slate: { low: "#2f3540", high: "#7d8896", waterline: "#26404f" },
 };
+const DEFAULT_TERRAIN_DETAIL = {
+    rockColor: "#6f7175",
+    sandColor: "#c2b283",
+    snowColor: "#eef3f7",
+    rockSlopeStart: 0.42,
+    snowHeight: 26,
+    detailScale: 5,
+    macroScale: 45,
+    roughness: 0.9,
+    strength: 1,
+};
+/** Fill a `TerrainDetailConfig` with defaults; `waterLevel` falls back to the terrain's own water level. */
+export function resolveTerrainDetail(config, terrainWaterLevel = 0) {
+    return {
+        rockColor: config.rockColor ?? DEFAULT_TERRAIN_DETAIL.rockColor,
+        sandColor: config.sandColor ?? DEFAULT_TERRAIN_DETAIL.sandColor,
+        snowColor: config.snowColor ?? DEFAULT_TERRAIN_DETAIL.snowColor,
+        rockSlopeStart: config.rockSlopeStart ?? DEFAULT_TERRAIN_DETAIL.rockSlopeStart,
+        snowHeight: config.snowHeight ?? DEFAULT_TERRAIN_DETAIL.snowHeight,
+        detailScale: config.detailScale ?? DEFAULT_TERRAIN_DETAIL.detailScale,
+        macroScale: config.macroScale ?? DEFAULT_TERRAIN_DETAIL.macroScale,
+        roughness: config.roughness ?? DEFAULT_TERRAIN_DETAIL.roughness,
+        strength: config.strength ?? DEFAULT_TERRAIN_DETAIL.strength,
+        waterLevel: config.waterLevel ?? terrainWaterLevel,
+    };
+}
 export function resolveTerrainPalette(descriptor = {}) {
     const material = descriptor.material ?? DEFAULT_TERRAIN_MATERIAL;
     const preset = TERRAIN_MATERIAL_PALETTES[material];
@@ -278,35 +315,108 @@ function mixPalette(from, to, t) {
     };
 }
 /**
- * Per-position palette sampler over the descriptor's base `material`/`colors` plus its
- * `materialRegions` — the multi-biome coloring seam. Regions paint fully inside `radius`
- * and blend back to the surrounding palette across `falloff`; later regions win overlaps.
+ * Per-z palette sampler over a descriptor's `biomeBands` — ordered zones that cross-fade their
+ * ground palette across a `fade`-wide window centered on the midpoint z between adjacent centers.
+ * Below the first / above the last band clamps to that band's palette. Returns `fallback` when no
+ * bands are declared. Pure math, unit-testable independent of rendering.
+ */
+export function createBiomeBandSampler(bands, fallback) {
+    if (bands.length === 0)
+        return () => fallback;
+    const resolved = bands
+        .map((band) => ({ z: band.z, fade: band.fade ?? 64, palette: resolveTerrainPalette(band) }))
+        .sort((a, b) => a.z - b.z);
+    const first = resolved[0];
+    const last = resolved[resolved.length - 1];
+    return (z) => {
+        if (z <= first.z)
+            return first.palette;
+        if (z >= last.z)
+            return last.palette;
+        for (let i = 0; i < resolved.length - 1; i += 1) {
+            const lower = resolved[i];
+            const upper = resolved[i + 1];
+            if (z < lower.z || z > upper.z)
+                continue;
+            const boundary = (lower.z + upper.z) / 2;
+            const half = Math.min(lower.fade, upper.fade) / 2;
+            if (z <= boundary - half)
+                return lower.palette;
+            if (z >= boundary + half)
+                return upper.palette;
+            return mixPalette(lower.palette, upper.palette, smoothstep(boundary - half, boundary + half, z));
+        }
+        return fallback;
+    };
+}
+/**
+ * Per-position palette sampler over the descriptor's base `material`/`colors` plus its z-ordered
+ * `biomeBands` (painted first) and radial `materialRegions` (painted over) — the multi-biome coloring
+ * seam. Regions paint fully inside `radius` and blend back across `falloff`; later regions win overlaps.
  */
 export function createTerrainPaletteSampler(descriptor) {
     const base = resolveTerrainPalette(descriptor);
+    const bandSampler = descriptor.biomeBands === undefined || descriptor.biomeBands.length === 0
+        ? null
+        : createBiomeBandSampler(descriptor.biomeBands, base);
     const regions = (descriptor.materialRegions ?? []).map((region) => ({
-        center: region.center,
-        radius: region.radius,
-        falloff: region.falloff ?? region.radius * 0.5,
+        ...resolveRegionShape(region),
         palette: resolveTerrainPalette(region),
     }));
-    if (regions.length === 0)
+    if (regions.length === 0 && bandSampler === null)
         return () => base;
     return (x, z) => {
-        let palette = base;
+        let palette = bandSampler === null ? base : bandSampler(z);
         for (const region of regions) {
-            const distance = Math.hypot(x - region.center[0], z - region.center[1]);
-            if (distance <= region.radius) {
+            const distance = region.coreDistance(x, z);
+            if (distance <= 0) {
                 palette = region.palette;
             }
-            else if (distance <= region.radius + region.falloff) {
-                const t = smoothstep(region.radius, region.radius + region.falloff, distance);
+            else if (distance <= region.falloff) {
+                const t = smoothstep(0, region.falloff, distance);
                 palette = mixPalette(region.palette, palette, t);
             }
         }
         return palette;
     };
 }
+/**
+ * Resolves a `TerrainMaterialRegion` of any shape to a `coreDistance(x, z)` — 0 inside the painted
+ * core, growing positive outward — plus its blend-ring `falloff`, so the palette sampler blends every
+ * shape through one shape-agnostic loop.
+ */
+function resolveRegionShape(region) {
+    if (region.shape === "polyline") {
+        const half = region.width * 0.5;
+        return {
+            falloff: region.falloff ?? half,
+            coreDistance: (x, z) => {
+                const sample = nearestOnPath(region.points, x, z);
+                return sample === null ? Number.POSITIVE_INFINITY : Math.max(0, sample.distance - half);
+            },
+        };
+    }
+    if (region.shape === "rect") {
+        const [hx, hz] = region.halfExtents;
+        const angle = region.rotationY ?? 0;
+        const cos = Math.cos(angle);
+        const sin = Math.sin(angle);
+        return {
+            falloff: region.falloff ?? Math.min(hx, hz) * 0.5,
+            coreDistance: (x, z) => {
+                const dx = x - region.center[0];
+                const dz = z - region.center[1];
+                const lx = dx * cos + dz * sin;
+                const lz = -dx * sin + dz * cos;
+                return Math.hypot(Math.max(0, Math.abs(lx) - hx), Math.max(0, Math.abs(lz) - hz));
+            },
+        };
+    }
+    return {
+        falloff: region.falloff ?? region.radius * 0.5,
+        coreDistance: (x, z) => Math.max(0, Math.hypot(x - region.center[0], z - region.center[1]) - region.radius),
+    };
+}
 function withFlattenMasks(sampleHeight, masks) {
     const resolved = masks.map((mask) => ({
         center: mask.center,
@@ -366,6 +476,7 @@ export function heightMapField(config) {
         ...(config.waterLevel === undefined ? {} : { waterLevel: config.waterLevel }),
     });
 }
+/** Resolves a `TerrainEnvironmentDescriptor` into a concrete `TerrainField`, applying flatten masks. */
 export function resolveTerrainField(descriptor) {
     if (descriptor === undefined)
         return flatField();
@@ -407,6 +518,7 @@ export function snapEntityToGround(entities, id, field, offset = 0) {
     return entities.setPose(id, { position: snapToGround(field, entity.position, offset) });
 }
 export const DEFAULT_MAX_WALK_SLOPE = 0.6;
+/** Zeroes out a movement step's x or z component where it would climb steeper than `maxSlope`. */
 export function resolveGroundStep(field, x, z, stepX, stepZ, maxSlope = DEFAULT_MAX_WALK_SLOPE) {
     const baseHeight = field.sampleHeight(x, z);
     const tooSteep = (dx, dz) => {