@threenative/terrain 0.0.0-stage → 0.1.1

package/starter/coastal/world.ts

@@ -0,0 +1,386 @@
+// The coastal 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 fir.
+// 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";
+import { type ICoastalSea, type ICoastalSeaData, addCoastalSea } from "./sea.js";
+
+/** Where the game's asset source holds the baked `world/` folder. */
+export const COASTAL_URL = "terrain/coastal/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>> = {
+  fir: { sphere: 0.6 },
+};
+
+/** How strongly the sky lights the props. The sun stays the dominant light on a fir. */
+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 ICoastalWorld {
+  readonly world: WorldCells;
+  /** One heightfield for the whole world, in place before `addCoastal` 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"];
+  /** The sea's level in metres, as the bake wrote it. The scene keeps its spawn and its walk above it. */
+  readonly seaLevel: number;
+  /** The sea in the scene. `dispose` removes its mesh and releases its water surface. */
+  readonly sea: ICoastalSea;
+}
+
+/** What `water.json` holds for the coastal kit: the sea, as one lake with a level. */
+interface ICoastalWaterFile {
+  readonly lakes: readonly {
+    readonly id: string;
+    readonly radius: number;
+    readonly level: number;
+  }[];
+  readonly rivers: readonly unknown[];
+}
+
+/**
+ * Stream the coastal 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 addCoastal(
+  ctx: ICtx<Record<string, unknown>, IPhysicsContext>,
+  follow: Object3D,
+  url = COASTAL_URL,
+  whileCurrent: () => boolean = () => true,
+): Promise<ICoastalWorld> {
+  const assertCurrent = () => {
+    if (whileCurrent()) return;
+    const error = new Error("Coastal 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 sea: ICoastalSea | undefined;
+  let released = false;
+  const dispose = () => {
+    if (released) return;
+    released = true;
+    colliders?.detach();
+    colliders?.removeFromParent();
+    ground?.dispose();
+    ground?.object?.removeFromParent();
+    sea?.dispose();
+    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("Coastal 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 = coastalField(manifest, heightmap);
+    ground = groundCollider(ctx, manifest, field);
+    const waterFile = (await (
+      await fetchAsset(ctx, `${base}water.json`, assertCurrent)
+    ).json()) as ICoastalWaterFile;
+    assertCurrent();
+    const seaLevel = waterFile.lakes[0]?.level;
+    if (seaLevel === undefined) throw new Error("Coastal world: water.json names no sea level.");
+    const ocean = addCoastalSea(ctx, coastalSeaData(manifest, heightmap, seaLevel));
+    sea = ocean;
+    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(`coastal-world.${world.uuid}`, { dispose });
+    return {
+      world,
+      ground,
+      colliders,
+      field,
+      placements: props,
+      extent: manifest.extent,
+      seaLevel,
+      sea: ocean,
+    };
+  } catch (error) {
+    dispose();
+    throw error;
+  }
+}
+
+// Every prop gets the sky as its own envMap before WorldCells adopts the shared cached models.
+// Without it, a fir 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("Coastal 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 coastalField(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 = "coastal-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);
+      }
+  }
+}
+
+/**
+ * The bake's heights on the world's grid, in metres, row-major by Z then X. The sea's shoreline, surf and
+ * depth tint are read from these, so they match the terrain the player stands on.
+ */
+function coastalSeaData(
+  manifest: IWorldPackage,
+  heightmap: Uint16Array,
+  seaLevel: number,
+): ICoastalSeaData {
+  const { terrain, extent } = manifest;
+  const heights = Float32Array.from(
+    heightmap,
+    (value) => terrain.heightMin + (value / 65535) * (terrain.heightMax - terrain.heightMin),
+  );
+  return { heights, resolution: terrain.columns, size: extent.sizeX, waterLevel: seaLevel };
+}
+
+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(`Coastal world: '${url}' is not served.`);
+  const response = await fetch(resolved);
+  assertCurrent();
+  if (!response.ok) throw new Error(`Coastal world: '${url}' answered ${String(response.status)}.`);
+  return response;
+}

package/starter/desert/README.md

@@ -0,0 +1,35 @@
+# Desert starter kit (placeholder scatter)
+
+A 512 m desert on a real survey (USGS 1 m DEM, Colorado), with hydraulic and thermal erosion, sand
+on the low ground, dirt patches, rock on the steep ground and a scatter of 140 props. 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 sand, dirt and rock surfaces, and the scatter. |
+| `assets.json` | The boulder model, its LOD distance and draw distance, and its bounds. |
+| `surface.json` | The ground: the sand base, the dirt and rock layers, 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 boulders near the player, and the sky as the props' light. |
+| `sky.ts` | The daylight: the sun, sky, fill, haze, exposure and tone curve. |
+
+Art is CC0 (Poly Haven); provenance is in `@threenative/terrain/starter-assets/credits.json`.
+
+## Placeholder
+
+The preview's desert scrub is drawn from generated cards, and the starter assets do not ship a CC0
+shrub model. Until one is added, this kit scatters the CC0 boulder in the scrub's place, with the
+same count, spacing and slope limits. The result does not look like the preview's desert. Replace the
+`scrub` entry in `recipe.json` and the boulder row in `assets.json` with a CC0 shrub model to fix it.
+
+## Status
+
+The kit bakes and streams. The kit ships no scene: the game writes one. The placeholder boulders are
+colliders like any other prop, and the scene picks its spawn from the loaded heightfield.
+
+## Steps
+
+1. Copy `node_modules/@threenative/terrain/starter/desert` to `src/terrain/desert`.
+2. Run `node src/terrain/desert/bake.mjs --out assets/terrain/desert` (needs `@threenative/terrain`
+   as a devDependency). The same recipe always writes the same bytes.
+3. In the scene, call `addDesert(ctx, follow)` for the world and `desertDaylight(follow)` for the light.

package/starter/desert/assets.json

@@ -0,0 +1,12 @@
+{
+  "boulder": {
+    "near": "boulder_01/boulder-near.glb",
+    "mid": "boulder_01/boulder-mid.glb",
+    "midDistance": 35,
+    "maxDistance": 300,
+    "bounds": {
+      "min": [-0.716, 0, -0.991],
+      "max": [0.557, 1.004, 0.841]
+    }
+  }
+}

package/starter/desert/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/desert/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`,
+);