@threenative/terrain 0.0.0-stage → 0.1.1

package/starter/alpine/sky.ts

@@ -0,0 +1,23 @@
+// The alpine 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";
+
+export function alpineDaylight(follow: Object3D): Daylight {
+  return 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,
+  });
+}

package/starter/alpine/surface.json

@@ -0,0 +1,53 @@
+{
+  "base": {
+    "id": "rock",
+    "tile": 3.8,
+    "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": "dirt",
+      "tile": 3.4,
+      "tint": [0.8, 0.72, 0.62],
+      "normal": true,
+      "mask": "dirt",
+      "lo": 0.45,
+      "hi": 0.85
+    },
+    {
+      "id": "snow",
+      "tile": 4.5,
+      "tint": [1, 1, 1],
+      "normal": true,
+      "mask": "snow",
+      "lo": 0.3,
+      "hi": 0.7
+    }
+  ],
+  "textures": "textures",
+  "sources": {
+    "rock": {
+      "diff": "rock_boulder_dry/rock_boulder_dry_diff_512.jpg",
+      "nrm": "rock_boulder_dry/rock_boulder_dry_nor_gl_512.jpg"
+    },
+    "dirt": {
+      "diff": "forest_ground_04/forest_ground_04_diff_1k.jpg",
+      "nrm": "forest_ground_04/forest_ground_04_nor_gl_1k.jpg"
+    },
+    "snow": {
+      "diff": "snow_02/snow_02_diff_1k.jpg",
+      "nrm": "snow_02/snow_02_nor_gl_1k.jpg"
+    }
+  }
+}

package/starter/alpine/world.ts

@@ -0,0 +1,335 @@
+// The alpine starter world, as the game that copied it draws and collides with it.
+//
+// `bake.mjs` wrote a world package into `world/`: heightmap, splat masks, placements and the CC0 boulder.
+// The engine's `WorldCells` streams it. `loadTerrainSplat` textures its ground.
+// Everything that decides how the world looks, or what stops the player, is in this folder for the game to edit.
+import type { IComputeDriven, ICtx } from "@threenative/core";
+import {
+  Heightfield,
+  type IWorldCellsLoadOptions,
+  type IWorldPackage,
+  WorldCells,
+  heightSamplerFromHeightmap,
+  loadTerrainSplat,
+  loadWorldHeightmap,
+} from "@threenative/core/world";
+import { CollisionShape3D, type IPhysicsContext, RigidBody3D } from "@threenative/physics";
+import {
+  EquirectangularReflectionMapping,
+  type Material,
+  type Mesh,
+  type MeshStandardMaterial,
+  Object3D,
+  type Texture,
+  Vector3,
+} from "three";
+import { HDRLoader } from "three/addons/loaders/HDRLoader.js";
+
+/** Where the game's asset source holds the baked `world/` folder. */
+export const ALPINE_URL = "terrain/alpine/world.json";
+
+/**
+ * What stops the player, per placed asset, in metres at the placement's scale 1. `null` walks
+ * through. A sphere sits on the placement's origin. Change a row to change every copy.
+ */
+export const COLLIDERS: Readonly<Record<string, { sphere: number } | null>> = {
+  boulder: { sphere: 0.9 },
+};
+
+/** How strongly the sky lights the props. The sun stays the dominant light on a boulder. */
+export const PROP_SKY_LIGHT = 0.5;
+
+/** Metres around `follow` within which props collide. Beyond that, props only draw. */
+export const PROP_COLLIDER_REACH = 60;
+
+export interface IAlpineWorld {
+  readonly world: WorldCells;
+  /** One heightfield for the whole world, in place before `addAlpine` resolves. */
+  readonly ground: RigidBody3D;
+  /** The prop colliders near `follow`. They stream with it (see `PROP_COLLIDER_REACH`). */
+  readonly colliders: PropColliders;
+  /** The heightfield the ground stands on: `heightAt(x, z)` reads the terrain under any point. */
+  readonly field: Heightfield;
+  /** Every placed prop's record, eight floats each, as the bake wrote it. */
+  readonly placements: Float32Array;
+  /** The world's extent in metres, as the bake wrote it. */
+  readonly extent: IWorldPackage["extent"];
+}
+
+/**
+ * Stream the alpine world around `follow` (usually the player or the camera) and give it collision.
+ * `whileCurrent` stops a departed scene's async load from attaching anything. Its resources are
+ * released on cancellation, failure and when the game's entity registry ends this scene.
+ */
+export async function addAlpine(
+  ctx: ICtx<Record<string, unknown>, IPhysicsContext>,
+  follow: Object3D,
+  url = ALPINE_URL,
+  whileCurrent: () => boolean = () => true,
+): Promise<IAlpineWorld> {
+  const assertCurrent = () => {
+    if (whileCurrent()) return;
+    const error = new Error("Alpine world: its scene is no longer current.");
+    error.name = "AbortError";
+    throw error;
+  };
+  let surface: Material | undefined;
+  let releaseLighting: (() => void) | undefined;
+  let world: WorldCells | undefined;
+  let ground: RigidBody3D | undefined;
+  let colliders: PropColliders | undefined;
+  let released = false;
+  const dispose = () => {
+    if (released) return;
+    released = true;
+    colliders?.detach();
+    colliders?.removeFromParent();
+    ground?.dispose();
+    ground?.object?.removeFromParent();
+    world?.dispose();
+    surface?.dispose();
+    releaseLighting?.();
+  };
+  try {
+    assertCurrent();
+    const manifest = (await (await fetchAsset(ctx, url, assertCurrent)).json()) as IWorldPackage;
+    assertCurrent();
+    const base = url.slice(0, url.lastIndexOf("/") + 1);
+    const records = await (
+      await fetchAsset(ctx, base + manifest.placements, assertCurrent)
+    ).arrayBuffer();
+    assertCurrent();
+    const [heightmapUrl] = await ctx.assets.resolve(base + manifest.terrain.heightmap);
+    assertCurrent();
+    if (heightmapUrl === undefined) throw new Error("Alpine world: its heightmap is not served.");
+    const heightmap = await loadWorldHeightmap(heightmapUrl);
+    assertCurrent();
+    surface = await loadTerrainSplat({ assets: ctx.assets, url });
+    assertCurrent();
+    releaseLighting = await lightProps(ctx, url, manifest, assertCurrent);
+    assertCurrent();
+    const options: IWorldCellsLoadOptions = {
+      url,
+      assets: ctx.assets,
+      data: { manifest, placements: records, heightmap },
+      surface,
+      follow,
+      ring: 5,
+      impostors: false,
+      gpuScene: false,
+      shadows: { cast: true, receive: true },
+      budgets: { residentCells: 64, instances: 40_000, bytes: 64_000_000 },
+      terrain: { streamRadius: 6 },
+    };
+    world = await WorldCells.load(options);
+    assertCurrent();
+    const field = alpineField(manifest, heightmap);
+    ground = groundCollider(ctx, manifest, field);
+    const props = new Float32Array(records);
+    colliders = new PropColliders(ctx, follow, manifest, props);
+    ctx.add(world);
+    if (ground.object !== undefined) ctx.add(ground.object);
+    ctx.add(colliders);
+    ctx.entities.add(`alpine-world.${world.uuid}`, { dispose });
+    return { world, ground, colliders, field, placements: props, extent: manifest.extent };
+  } catch (error) {
+    dispose();
+    throw error;
+  }
+}
+
+// Every prop gets the sky as its own envMap before WorldCells adopts the shared cached models.
+// Without it, a boulder lit by the sun alone draws flat.
+async function lightProps(
+  ctx: ICtx<Record<string, unknown>, IPhysicsContext>,
+  url: string,
+  manifest: IWorldPackage,
+  assertCurrent: () => void,
+): Promise<() => void> {
+  const base = url.slice(0, url.lastIndexOf("/") + 1);
+  const [skyUrl] = await ctx.assets.resolve(`${base}sky.hdr`);
+  assertCurrent();
+  if (skyUrl === undefined) throw new Error("Alpine world: 'sky.hdr' is not served.");
+  const sky = await new HDRLoader().loadAsync(skyUrl);
+  const originals = new Map<MeshStandardMaterial, { envMap: Texture | null; intensity: number }>();
+  const dispose = () => {
+    for (const [material, original] of originals) {
+      if (material.envMap !== sky) continue;
+      material.envMap = original.envMap;
+      material.envMapIntensity = original.intensity;
+    }
+    sky.dispose();
+  };
+  try {
+    assertCurrent();
+    sky.mapping = EquirectangularReflectionMapping;
+    for (const asset of Object.values(manifest.assets)) {
+      const model = await ctx.assets.model<{ scene: Object3D }>(base + asset.glb);
+      assertCurrent();
+      model.scene.traverse((object) => {
+        const mesh = object as Mesh;
+        for (const material of [mesh.material ?? []].flat() as MeshStandardMaterial[])
+          if (!originals.has(material))
+            originals.set(material, {
+              envMap: material.envMap,
+              intensity: material.envMapIntensity,
+            });
+        dressProp(mesh, sky);
+      });
+    }
+    return dispose;
+  } catch (error) {
+    dispose();
+    throw error;
+  }
+}
+
+/** One prop mesh: the sky as its envMap. */
+function dressProp(mesh: Mesh, sky: Texture): void {
+  for (const material of [mesh.material ?? []].flat() as MeshStandardMaterial[]) {
+    material.envMap = sky;
+    material.envMapIntensity = PROP_SKY_LIGHT;
+  }
+}
+
+// The streamed terrain tiles arrive over several frames. A player spawned before its tile would
+// fall through. One heightfield for the whole package avoids that, at a few hundred kilobytes.
+/** The kit's one heightfield: the collider stands on it. */
+function alpineField(manifest: IWorldPackage, heightmap: Uint16Array): Heightfield {
+  const { extent, terrain } = manifest;
+  return Heightfield.fromSampler({
+    columns: terrain.columns,
+    rows: terrain.rows,
+    width: extent.sizeX,
+    depth: extent.sizeZ,
+    origin: { x: extent.minX + extent.sizeX / 2, z: extent.minZ + extent.sizeZ / 2 },
+    sampleHeight: heightSamplerFromHeightmap(terrain, extent, heightmap),
+  });
+}
+
+function groundCollider(
+  ctx: ICtx<Record<string, unknown>, IPhysicsContext>,
+  manifest: IWorldPackage,
+  field: Heightfield,
+): RigidBody3D {
+  const { extent } = manifest;
+  const anchor = new Object3D();
+  anchor.position.set(extent.minX + extent.sizeX / 2, 0, extent.minZ + extent.sizeZ / 2);
+  return new RigidBody3D({
+    object: anchor,
+    physics: ctx.physics,
+    type: "fixed",
+    entity: "terrain",
+    shape: CollisionShape3D.heightfield(field.rows, field.columns, field.toColliderHeights(), {
+      x: extent.sizeX,
+      y: 1,
+      z: extent.sizeZ,
+    }),
+  });
+}
+
+/**
+ * Fixed bodies for the props within `PROP_COLLIDER_REACH` of `follow`, rebuilt when it has moved a few
+ * metres. Thousands of resident bodies cost Rapier about 0.5 s per 8 s (measured). A hundred do not.
+ */
+export class PropColliders extends Object3D implements IComputeDriven {
+  readonly warmupNodes: readonly unknown[] = [];
+  readonly processCadence = "render" as const;
+  readonly #live = new Map<number, RigidBody3D>();
+  readonly #runs: { asset: string; offset: number; count: number }[] = [];
+  readonly #at = { x: Number.NaN, z: Number.NaN };
+  readonly #followPosition = new Vector3();
+  #released = false;
+
+  constructor(
+    private readonly ctx: ICtx<Record<string, unknown>, IPhysicsContext>,
+    private readonly follow: Object3D,
+    manifest: IWorldPackage,
+    private readonly records: Float32Array,
+  ) {
+    super();
+    this.name = "alpine-prop-colliders";
+    for (const cell of manifest.cells)
+      for (const run of cell.runs) if (COLLIDERS[run.asset]) this.#runs.push(run);
+    try {
+      this.#rebuild();
+    } catch (error) {
+      this.detach();
+      throw error;
+    }
+  }
+
+  /** How many prop bodies exist right now. */
+  get active(): number {
+    return this.#live.size;
+  }
+
+  get released(): boolean {
+    return this.#released;
+  }
+
+  attachRenderer(): void {}
+
+  process(): void {
+    if (this.#released) return;
+    const p = this.follow.getWorldPosition(this.#followPosition);
+    if (Math.hypot(p.x - this.#at.x, p.z - this.#at.z) > 4 || Number.isNaN(this.#at.x))
+      this.#rebuild();
+  }
+
+  detach(): void {
+    for (const body of this.#live.values()) body.dispose();
+    this.#live.clear();
+    this.#released = true;
+  }
+
+  #rebuild(): void {
+    const { x: fx, z: fz } = this.follow.getWorldPosition(this.#followPosition);
+    this.#at.x = fx;
+    this.#at.z = fz;
+    const keep = new Set<number>();
+    for (const run of this.#runs) {
+      const shape = COLLIDERS[run.asset];
+      if (!shape) continue;
+      for (let i = run.offset; i < run.offset + run.count; i++) {
+        const x = this.records[i * 8] as number;
+        const z = this.records[i * 8 + 2] as number;
+        if (Math.hypot(x - fx, z - fz) > PROP_COLLIDER_REACH) continue;
+        keep.add(i);
+        if (this.#live.has(i)) continue;
+        const collider = CollisionShape3D.sphere(
+          shape.sphere * (this.records[i * 8 + 7] as number),
+        );
+        this.#live.set(
+          i,
+          new RigidBody3D({
+            physics: this.ctx.physics,
+            type: "fixed",
+            entity: `${run.asset}.${String(i)}`,
+            position: { x, y: this.records[i * 8 + 1] as number, z },
+            shape: collider,
+          }),
+        );
+      }
+    }
+    for (const [i, body] of this.#live)
+      if (!keep.has(i)) {
+        body.dispose();
+        this.#live.delete(i);
+      }
+  }
+}
+
+async function fetchAsset(
+  ctx: ICtx<Record<string, unknown>, IPhysicsContext>,
+  url: string,
+  assertCurrent: () => void,
+): Promise<Response> {
+  const [resolved] = await ctx.assets.resolve(url);
+  assertCurrent();
+  if (resolved === undefined) throw new Error(`Alpine world: '${url}' is not served.`);
+  const response = await fetch(resolved);
+  assertCurrent();
+  if (!response.ok) throw new Error(`Alpine world: '${url}' answered ${String(response.status)}.`);
+  return response;
+}

package/starter/coastal/README.md

@@ -0,0 +1,37 @@
+# Coastal starter kit
+
+A 512 m coastline on a real survey (USGS 1 m DEM, Colorado), with hydraulic and thermal erosion,
+rock on the steep ground, sand on the low ground, an ocean at 1.5 m and fir stands kept out of the
+water. It is game source: once copied, every file is yours to edit.
+
+| File | What it decides |
+| --- | --- |
+| `recipe.json` | The terrain: the survey heightmap, erosion, the rock and sand surfaces, the ocean and the stands. |
+| `assets.json` | The fir model, its LOD distance and draw distance, and its bounds. |
+| `surface.json` | The ground: the sand base, the rock layer, tiles, tints and blend thresholds. |
+| `bake.mjs` | Writes the world package and `world/water.json` from the three files above. |
+| `world.ts` | The runtime: streams the baked world, one heightfield for the ground, sphere colliders for the firs near the player, and the sky as the props' light. |
+| `sky.ts` | The daylight: the sun, sky, fill, haze, exposure and tone curve. |
+| `sea.ts` | The sea: the installed spectral simulation drives a lit water surface at the level the bake wrote. |
+
+Art is CC0 (Poly Haven); provenance is in `@threenative/terrain/starter-assets/credits.json`.
+
+## Substitution
+
+The preview's coastal stands use its licensed spruce models, which cannot ship in a kit. This kit
+plants the CC0 fir from the forest kit in their place, with the same count and spacing. The
+ocean is written to `water.json` as the one entry in `lakes`, with no `at`: the game draws it.
+
+## Status
+
+The kit bakes, streams and draws its sea. The kit ships no scene: the game writes one. The sea is a
+lit surface at the baked level: the simulation's waves, the surf from the bake's shoreline, and the depth
+tint. Its colours and sea state are in `sea.ts`. The close-up view is named `boulders` in the shared captures, although
+it frames a fir.
+
+## Steps
+
+1. Copy `node_modules/@threenative/terrain/starter/coastal` to `src/terrain/coastal`.
+2. Run `node src/terrain/coastal/bake.mjs --out assets/terrain/coastal` (needs `@threenative/terrain`
+   as a devDependency). The same recipe always writes the same bytes.
+3. In the scene, call `addCoastal(ctx, follow)` for the world and `coastalDaylight(follow)` for the light.

package/starter/coastal/assets.json

@@ -0,0 +1,10 @@
+{
+  "fir": {
+    "near": "fir_tree_01/fir-b-lod2.glb",
+    "maxDistance": 600,
+    "bounds": {
+      "min": [-2.869, 0, -3.619],
+      "max": [2.763, 14.078, 2.465]
+    }
+  }
+}

package/starter/coastal/bake.mjs

@@ -0,0 +1,118 @@
+// Bakes this folder's recipe into a self-contained world package. Run it once from your game
+// project, then serve the folder it writes:
+//   node src/terrain/coastal/bake.mjs [--assets <dir>] [--out <dir>]
+// The engine's `WorldCells` streams `world/world.json` and `loadTerrainSplat` textures its ground;
+// the game never evaluates terrain at runtime.
+import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Terrain, applyPlacementOverrides, bakeWorldPackage } from "@threenative/terrain";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** `--key value` after the script; `--assets` and `--out` default as noted below. */
+function flag(name, fallback) {
+  const at = process.argv.indexOf(`--${name}`);
+  return at === -1 ? fallback : resolve(process.argv[at + 1] ?? "");
+}
+
+// The installed kit ships its models and textures beside the package manifest, so a copied kit
+// finds them without asking the game for a path. `--assets` overrides that for a local checkout.
+const installed = dirname(fileURLToPath(import.meta.resolve("@threenative/terrain/package.json")));
+const assetsDir = flag("assets", join(installed, "starter-assets"));
+const outDir = flag("out", join(here, "world"));
+
+const recipe = JSON.parse(await readFile(join(here, "recipe.json"), "utf8"));
+const assetTable = JSON.parse(await readFile(join(here, "assets.json"), "utf8"));
+const surface = JSON.parse(await readFile(join(here, "surface.json"), "utf8"));
+
+const state = applyPlacementOverrides(
+  Terrain.fromJSON(recipe.recipe).evaluate(),
+  recipe.placementOverrides ?? {},
+);
+
+const assets = Object.fromEntries(
+  Object.entries(assetTable).map(([id, spec]) => [
+    id,
+    {
+      bounds: spec.bounds,
+      glb: `models/${spec.near.split("/").at(-1)}`,
+      ...(spec.mid
+        ? { lods: [{ distance: spec.midDistance, glb: `models/${spec.mid.split("/").at(-1)}` }] }
+        : {}),
+      maxDistance: spec.maxDistance,
+    },
+  ]),
+);
+
+const started = performance.now();
+const { manifest, splat, files } = bakeWorldPackage(state, {
+  assets,
+  layers: { table: "terrain-table.json" },
+});
+const written = new Map();
+
+async function write(relative, bytes) {
+  await mkdir(join(outDir, dirname(relative)), { recursive: true });
+  await writeFile(join(outDir, relative), bytes);
+  written.set(relative, bytes.length ?? bytes.byteLength);
+}
+
+async function copy(from, to) {
+  await mkdir(join(outDir, dirname(to)), { recursive: true });
+  await copyFile(join(assetsDir, from), join(outDir, to));
+  written.set(to, (await readFile(join(outDir, to))).byteLength);
+}
+
+await write("world.json", `${JSON.stringify(manifest, null, 2)}\n`);
+// The lake and river the generator evaluated, so the game draws the water the bake shaped.
+const round = (value) => Math.round(value * 1_000) / 1_000;
+await write(
+  "water.json",
+  `${JSON.stringify(
+    {
+      lakes: state.waters.map((lake) => ({
+        id: lake.id,
+        at: lake.at,
+        radius: lake.radius,
+        level: lake.level,
+      })),
+      rivers: state.rivers.map((river) => ({
+        id: river.id,
+        width: round(river.width),
+        points: river.points.map((point) => point.map(round)),
+      })),
+    },
+    null,
+    2,
+  )}\n`,
+);
+for (const [name, bytes] of Object.entries(files)) await write(name, bytes);
+for (const spec of Object.values(assetTable)) {
+  await copy(spec.near, `models/${spec.near.split("/").at(-1)}`);
+  if (spec.mid) await copy(spec.mid, `models/${spec.mid.split("/").at(-1)}`);
+}
+// The sky the props are lit by (CC0 Poly Haven Kloofendal); world.ts gives it to their materials.
+await copy("hdri/kloofendal_48d_partly_cloudy_1k.hdr", "sky.hdr");
+for (const layer of [surface.base, ...surface.layers]) {
+  const source = surface.sources[layer.id];
+  await copy(source.diff, `${surface.textures}/${layer.id}_diff.jpg`);
+  await copy(source.nrm, `${surface.textures}/${layer.id}_nrm.jpg`);
+}
+// `sources` is the bake's own lookup: the runtime reads only base/layers/splat/textures.
+await write(
+  "terrain-table.json",
+  `${JSON.stringify({ ...surface, splat, textures: "textures" }, null, 2)}\n`,
+);
+
+const perAsset = {};
+for (const cell of manifest.cells)
+  for (const run of cell.runs) perAsset[run.asset] = (perAsset[run.asset] ?? 0) + run.count;
+const total = [...written.values()].reduce((sum, bytes) => sum + bytes, 0);
+console.log(
+  `${Object.entries(perAsset)
+    .map(([asset, count]) => `${asset} ${String(count)}`)
+    .join(", ")} placements; ${[...written]
+    .map(([name, bytes]) => `${name} ${String(bytes)} B`)
+    .join(", ")}; ${String(total)} B total; ${Math.round(performance.now() - started)} ms`,
+);