@threenative/terrain 0.0.0-stage → 0.1.1

package/starter/tundra/sky.ts

@@ -0,0 +1,27 @@
+// The tundra world's daylight: the engine's sun, sky, fill, haze and tone curve, every value this world's.
+// Edit any number here to change the look. Nothing in a package decides it.
+import { Daylight } from "@threenative/core";
+import { ACESFilmicToneMapping, Color, type Object3D, Vector3 } from "three";
+import { SKY_REFLECTION_LAYER } from "./water.js";
+
+export function tundraDaylight(follow: Object3D): Daylight {
+  const daylight = new Daylight({
+    follow,
+    // Mid-morning sun from the south-east, high enough for short readable shadows under the boulders.
+    sunDirection: new Vector3(0.55, 0.62, 0.56),
+    sunColor: new Color(0xfff1dc),
+    sunIntensity: 3.2,
+    shadowExtents: [24, 96, 320],
+    sky: { turbidity: 2, rayleigh: 3, mieCoefficient: 0.003, mieDirectionalG: 0.82 },
+    fill: { sky: new Color(0xa8c8e8), ground: new Color(0x464937), intensity: 0.62 },
+    // Enough air that the 512 m world's far edge fades instead of ending on a hard line.
+    haze: { color: new Color(0x9fb4c2), density: 0.0016 },
+    exposure: 2 ** -0.38,
+    toneMapping: ACESFilmicToneMapping,
+    // The box's corners must stay inside the camera's far plane (5000 m in the kit's example scene).
+    skySize: 5000,
+  });
+  // The kettles' mirror shows the sky only on this layer (see `water.ts`), so the sky joins it.
+  daylight.sky.layers.enable(SKY_REFLECTION_LAYER);
+  return daylight;
+}

package/starter/tundra/surface.json

@@ -0,0 +1,54 @@
+{
+  "base": {
+    "id": "moss",
+    "tile": 3.6,
+    "tint": [1, 1, 1],
+    "normal": true,
+    "triplanar": true
+  },
+  "breakup": {
+    "scale": 0.05,
+    "push": 0.12
+  },
+  "macro": {
+    "scale": 0.006,
+    "min": 0.75,
+    "max": 1.1
+  },
+  "layers": [
+    {
+      "id": "snow",
+      "tile": 4.5,
+      "tint": [1, 1, 1],
+      "normal": true,
+      "mask": "snow",
+      "lo": 0.3,
+      "hi": 0.7
+    },
+    {
+      "id": "rock",
+      "tile": 3.8,
+      "tint": [1, 1, 1],
+      "normal": true,
+      "triplanar": true,
+      "mask": "rock",
+      "lo": 0.25,
+      "hi": 0.75
+    }
+  ],
+  "textures": "textures",
+  "sources": {
+    "moss": {
+      "diff": "mossy_rock/mossy_rock_diff_1k.jpg",
+      "nrm": "mossy_rock/mossy_rock_nor_gl_1k.jpg"
+    },
+    "snow": {
+      "diff": "snow_02/snow_02_diff_1k.jpg",
+      "nrm": "snow_02/snow_02_nor_gl_1k.jpg"
+    },
+    "rock": {
+      "diff": "rock_boulder_dry/rock_boulder_dry_diff_512.jpg",
+      "nrm": "rock_boulder_dry/rock_boulder_dry_nor_gl_512.jpg"
+    }
+  }
+}

package/starter/tundra/water.ts

@@ -0,0 +1,313 @@
+// The tundra's lake and river, drawn from the water the bake wrote to `world/water.json`. The lake covers
+// the ground that its level floods from the lake's centre, read from the same heightfield the physics
+// stands on, so the water sits where the bake floods it. WaterSurface3D mirrors the sky in the lake and
+// shows the bed through it, and the water thins to nothing where the ground rises through the level: that
+// is the shore. A river follows the ground, so it is a ribbon the game shades itself. Colours, depths and
+// the shore are this file's to change: the kit owns its look.
+import type { ICtx } from "@threenative/core";
+import { WaterSurface3D } from "@threenative/core";
+import type { Heightfield } from "@threenative/core/world";
+import type { IPhysicsContext } from "@threenative/physics";
+import {
+  BufferAttribute,
+  BufferGeometry,
+  Color,
+  DoubleSide,
+  type Material,
+  Mesh,
+  MeshStandardMaterial,
+} from "three";
+import {
+  attribute,
+  cameraPosition,
+  clamp,
+  dot,
+  float,
+  mix,
+  normalize,
+  positionWorld,
+  pow,
+  smoothstep,
+  vec3,
+} from "three/tsl";
+import { MeshBasicNodeMaterial } from "three/webgpu";
+
+/** The generator's own water, written beside the world by `bake.mjs`. */
+export interface ITundraWaterFile {
+  readonly lakes: readonly ILake[];
+  readonly rivers: readonly IRiver[];
+}
+
+interface ILake {
+  readonly id: string;
+  readonly at: readonly [number, number];
+  readonly radius: number;
+  readonly level: number;
+}
+
+interface IRiver {
+  readonly id: string;
+  readonly width: number;
+  readonly points: readonly (readonly [number, number, number])[];
+}
+
+export interface ITundraWater {
+  readonly lakes: number;
+  readonly rivers: number;
+  dispose(): void;
+}
+
+/** The layer the sky sits on, so the lake's mirror can show it (see `sky.ts`). */
+export const SKY_REFLECTION_LAYER = 3;
+/** The ribbon sits this far above its profile, clear of the carved bed. */
+const RIVER_LIFT = 0.05;
+/**
+ * Metres of water over the bed at which the lake is fully opaque. The shore is wide enough to hide the
+ * flood grid's stepped outline, which reads as a jagged edge when the fade is narrow.
+ */
+const SHORE_DEPTH = 0.8;
+/**
+ * The colour the mirrored sky takes at grazing angles, in linear light. The kettles are frozen, so the tint
+ * is pale ice; the mirror keeps the sky's gradient.
+ */
+const SHEEN = new Color(0xeaf4f8);
+/** The ice's own colour: a pale, milky blue-white. The bed is hidden under it, as frozen water hides it. */
+const BODY = new Color(0xbcd6e0);
+/** Meltwater: a blue-grey that reads as running water rather than a dark road. */
+const RIVER = new Color(0x9fb9c4);
+
+/** The heightfield's sample grid in world metres: one node per column and row, the first at (x0, z0). */
+function gridOf(field: Heightfield): { stepX: number; stepZ: number; x0: number; z0: number } {
+  return {
+    stepX: field.width / (field.columns - 1),
+    stepZ: field.depth / (field.rows - 1),
+    x0: field.origin.x - field.width / 2,
+    z0: field.origin.z - field.depth / 2,
+  };
+}
+
+/**
+ * The grid nodes the lake covers: the nodes below its level that a flood from its centre reaches inside
+ * its radius. This reproduces the generator's own flood on the heightfield the physics stands on.
+ */
+function floodedNodes(field: Heightfield, lake: ILake): Uint8Array {
+  const { columns, rows } = field;
+  const { stepX, stepZ, x0, z0 } = gridOf(field);
+  const [cx, cz] = lake.at;
+  const worldX = (node: number): number => x0 + (node % columns) * stepX;
+  const worldZ = (node: number): number => z0 + Math.floor(node / columns) * stepZ;
+  const below = (node: number): boolean => field.heightAt(worldX(node), worldZ(node)) < lake.level;
+  const within = (node: number): boolean =>
+    Math.hypot(worldX(node) - cx, worldZ(node) - cz) <= lake.radius;
+  const start = Math.round((cz - z0) / stepZ) * columns + Math.round((cx - x0) / stepX);
+  const flooded = new Uint8Array(columns * rows);
+  const seen = new Uint8Array(columns * rows);
+  const queue: number[] = [start];
+  seen[start] = 1;
+  for (let head = 0; head < queue.length; head += 1) {
+    const node = queue[head];
+    if (node === undefined || !below(node)) continue;
+    flooded[node] = 1;
+    const i = node % columns;
+    const j = Math.floor(node / columns);
+    const neighbours = [
+      i > 0 ? node - 1 : -1,
+      i < columns - 1 ? node + 1 : -1,
+      j > 0 ? node - columns : -1,
+      j < rows - 1 ? node + columns : -1,
+    ];
+    for (const next of neighbours) {
+      if (next < 0 || seen[next] === 1 || !within(next)) continue;
+      seen[next] = 1;
+      queue.push(next);
+    }
+  }
+  return flooded;
+}
+
+/**
+ * The lake's surface: a level sheet over every grid cell that touches a flooded node. The sheet runs a
+ * cell past the flood, so the shore is where `lakeMaterial` thins the water, not the sheet's edge.
+ */
+/**
+ * The lake's surface, cut where the water level crosses the ground. Each flooded grid cell is two triangles,
+ * and each triangle keeps only the part where the ground is under the level. The shoreline therefore follows
+ * the terrain's contour, not the grid's steps.
+ */
+function lakeGeometry(field: Heightfield, lake: ILake, flooded: Uint8Array): BufferGeometry {
+  const { columns, rows } = field;
+  const { stepX, stepZ, x0, z0 } = gridOf(field);
+  const positions: number[] = [];
+  const indices: number[] = [];
+  // Each vertex's distance from the kettle's centre, in radii: the sheet fades out toward its circular edge.
+  const radial: number[] = [];
+  const corner = (node: number): ICorner => {
+    const x = x0 + (node % columns) * stepX;
+    const z = z0 + Math.floor(node / columns) * stepZ;
+    return { x, z, h: field.heightAt(x, z) };
+  };
+  const emit = (polygon: readonly { readonly x: number; readonly z: number }[]): void => {
+    const first = positions.length / 3;
+    for (const point of polygon) {
+      positions.push(point.x, lake.level, point.z);
+      radial.push(Math.hypot(point.x - lake.at[0], point.z - lake.at[1]) / lake.radius);
+    }
+    for (let k = 1; k + 1 < polygon.length; k += 1) indices.push(first, first + k, first + k + 1);
+  };
+  for (let j = 0; j < rows - 1; j += 1)
+    for (let i = 0; i < columns - 1; i += 1) {
+      const a = j * columns + i;
+      const b = a + 1;
+      const c = a + columns;
+      const d = c + 1;
+      if (!(flooded[a] || flooded[b] || flooded[c] || flooded[d])) continue;
+      for (const triangle of [
+        [a, c, b],
+        [b, c, d],
+      ]) {
+        const clipped = clipBelow(triangle.map(corner), lake.level);
+        if (clipped.length >= 3) emit(clipped);
+      }
+    }
+  const geometry = new BufferGeometry();
+  geometry.setAttribute("position", new BufferAttribute(new Float32Array(positions), 3));
+  geometry.setAttribute("radial", new BufferAttribute(new Float32Array(radial), 1));
+  geometry.setIndex(indices);
+  return geometry;
+}
+
+/** A grid corner: its place on the ground and the terrain height there. */
+interface ICorner {
+  readonly x: number;
+  readonly z: number;
+  readonly h: number;
+}
+
+/**
+ * The part of a triangle where the ground is under `level`, by Sutherland–Hodgman on the height difference.
+ * The ground is linear across a triangle, so the crossing points lie on the level's contour.
+ */
+function clipBelow(
+  corners: readonly ICorner[],
+  level: number,
+): readonly { readonly x: number; readonly z: number }[] {
+  const out: { x: number; z: number }[] = [];
+  for (let k = 0; k < corners.length; k += 1) {
+    const p = corners[k];
+    const q = corners[(k + 1) % corners.length];
+    if (p === undefined || q === undefined) continue;
+    const fp = level - p.h;
+    const fq = level - q.h;
+    if (fp >= 0) out.push({ x: p.x, z: p.z });
+    if (fp * fq < 0) {
+      const t = fp / (fp - fq);
+      out.push({ x: p.x + (q.x - p.x) * t, z: p.z + (q.z - p.z) * t });
+    }
+  }
+  return out;
+}
+
+/**
+ * The lake's surface: the sky mirrored in it at grazing angles, the bed seen through it where it is
+ * shallow, and the body's own colour where it is deep. Schlick at water's 1.333 index, so the water at
+ * your feet is clear and the far bank is a mirror. Where the water is thinner than SHORE_DEPTH it fades
+ * to nothing, because the ground has risen through the level there.
+ */
+function lakeMaterial(surface: WaterSurface3D): MeshBasicNodeMaterial {
+  const view = normalize(cameraPosition.sub(positionWorld));
+  const facing = clamp(dot(vec3(0, 1, 0), view), float(0), float(1));
+  const fresnel = float(0.02).add(pow(float(1).sub(facing), 5).mul(0.98));
+  const thickness = surface.thicknessAt();
+  const body = vec3(BODY.r, BODY.g, BODY.b);
+  // Ice hides the bed: the body colour takes over from the refraction within a fraction of a metre.
+  const submerged = mix(
+    surface.refractionAt(),
+    body,
+    smoothstep(float(0.1), float(0.6), thickness),
+  );
+  const material = new MeshBasicNodeMaterial({ transparent: true, side: DoubleSide });
+  // The HDR mirror is compressed, then tinted: its horizon is neutral, the water should not be.
+  const mirror = surface.reflectionAt();
+  const compressed = mirror.div(mirror.add(vec3(1, 1, 1)));
+  material.colorNode = mix(submerged, compressed.mul(vec3(SHEEN.r, SHEEN.g, SHEEN.b)), fresnel);
+  // The sheet ends at the kettle's circle, where the ground beyond is still under the level. It fades there.
+  const edge = float(1).sub(smoothstep(float(0.8), float(1), attribute("radial", "float")));
+  material.opacityNode = smoothstep(float(0), float(SHORE_DEPTH), thickness).mul(edge);
+  return material;
+}
+
+/** A ribbon along the river's profile: each point's left and right edge across the course. */
+function riverGeometry(river: IRiver): BufferGeometry {
+  const half = river.width / 2;
+  const positions: number[] = [];
+  const indices: number[] = [];
+  river.points.forEach(([x, y, z], i) => {
+    const before = river.points[Math.max(0, i - 1)] ?? [x, y, z];
+    const after = river.points[Math.min(river.points.length - 1, i + 1)] ?? [x, y, z];
+    const tx = after[0] - before[0];
+    const tz = after[2] - before[2];
+    const length = Math.hypot(tx, tz) || 1;
+    const sx = (-tz / length) * half;
+    const sz = (tx / length) * half;
+    positions.push(x + sx, y + RIVER_LIFT, z + sz, x - sx, y + RIVER_LIFT, z - sz);
+    if (i > 0) {
+      const a = 2 * (i - 1);
+      const b = 2 * i;
+      indices.push(a, b, a + 1, b, b + 1, a + 1);
+    }
+  });
+  const geometry = new BufferGeometry();
+  geometry.setAttribute("position", new BufferAttribute(new Float32Array(positions), 3));
+  geometry.setIndex(indices);
+  return geometry;
+}
+
+/**
+ * Adds the lake and river the bake wrote. `field` is the ground the props and the colliders stand on.
+ * The caller owns the returned handle: its `dispose` removes both meshes and releases each surface.
+ */
+export function addTundraWater(
+  ctx: ICtx<Record<string, unknown>, IPhysicsContext>,
+  water: ITundraWaterFile,
+  field: Heightfield,
+): ITundraWater {
+  const surfaces: WaterSurface3D[] = [];
+  const meshes: Mesh[] = [];
+  for (const lake of water.lakes) {
+    const surface = new WaterSurface3D({
+      level: lake.level,
+      maxThickness: 4,
+      // The mirror holds only the sky, which barely changes: redrawing it every fourth frame keeps the
+      // water's look and takes the second world draw off most frames (the lake's cost in the ground view).
+      reflection: { resolutionScale: 0.5, layers: 1 << SKY_REFLECTION_LAYER, refreshInterval: 4 },
+    });
+    surfaces.push(surface);
+    meshes.push(
+      new Mesh(lakeGeometry(field, lake, floodedNodes(field, lake)), lakeMaterial(surface)),
+    );
+  }
+  for (const river of water.rivers) {
+    const material = new MeshStandardMaterial({
+      color: RIVER,
+      roughness: 0.18,
+      metalness: 0,
+      transparent: true,
+      opacity: 0.9,
+      side: DoubleSide,
+    });
+    meshes.push(new Mesh(riverGeometry(river), material));
+  }
+  for (const mesh of meshes) ctx.add(mesh);
+  return {
+    lakes: water.lakes.length,
+    rivers: water.rivers.length,
+    dispose() {
+      for (const mesh of meshes) {
+        mesh.removeFromParent();
+        mesh.geometry.dispose();
+        (mesh.material as Material).dispose();
+      }
+      for (const surface of surfaces) surface.dispose();
+    },
+  };
+}