@threenative/terrain 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,89 @@
 {
   "name": "@threenative/terrain",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "license": "MIT",
+  "description": "Headless terrain authoring — noise, erosion, sculpting, roads, rivers, material splats and scatter — evaluated into ordinary typed arrays and indexed Three.js geometry.",
+  "keywords": [
+    "threenative",
+    "terrain",
+    "heightfield",
+    "three",
+    "threejs",
+    "procedural",
+    "webgpu"
+  ],
+  "homepage": "https://github.com/ThreeNativeHQ/threenative#readme",
+  "bugs": {
+    "url": "https://github.com/ThreeNativeHQ/threenative/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ThreeNativeHQ/threenative.git",
+    "directory": "packages/terrain"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "starter",
+    "starter-assets",
+    "README.md",
+    "AGENT_GUIDE.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./three": {
+      "types": "./dist/three.d.ts",
+      "import": "./dist/three.js"
+    },
+    "./export": {
+      "types": "./dist/export.d.ts",
+      "import": "./dist/export.js"
+    },
+    "./package.json": "./package.json",
+    "./editor/server": {
+      "types": "./dist/editor/server.d.ts",
+      "import": "./dist/editor/server.js"
+    },
+    "./editor": {
+      "types": "./dist/editor/index.d.ts",
+      "import": "./dist/editor/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "@types/node": "20.19.43",
+    "@types/three": "0.185.3",
+    "publint": "0.3.22",
+    "three": "0.185.1",
+    "tsup": "8.5.1",
+    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "@typescript/native": "npm:typescript@7.0.2",
+    "vite": "8.2.0",
+    "@threenative/core": "0.3.5",
+    "@threenative/physics": "0.3.5"
+  },
+  "peerDependencies": {
+    "three": ">=0.185.0 <0.186.0",
+    "vite": ">=7.0.0 <9.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup --config tsup.config.ts && publint",
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm run build && vitest run --root ../.. terrain/__tests__ && publint --strict"
+  }
 }

package/starter/alpine/README.md

@@ -0,0 +1,29 @@
+# Alpine starter kit
+
+A 512 m alpine headwall on a real survey (USGS 1 m DEM, Longs Peak, Colorado), with hydraulic and
+thermal erosion, rock base, dirt on slopes, snow on the high steep ground and boulder scree. 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, dirt and snow surfaces, and the scree. |
+| `assets.json` | The boulder model, its LOD distance and draw distance, and its bounds. |
+| `surface.json` | The ground: the rock base, the dirt and snow layers, tiles, tints and blend thresholds. |
+| `bake.mjs` | Writes the world package 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`.
+
+## Status
+
+The kit bakes and streams. The kit ships no scene: the game writes one. The terrain is too steep to
+stand on near its centre, so a scene picks its spawn from the loaded heightfield. The proof's scene
+rings the nearest boulder with gentle ground and a clear walk.
+
+## Steps
+
+1. Copy `node_modules/@threenative/terrain/starter/alpine` to `src/terrain/alpine`.
+2. Run `node src/terrain/alpine/bake.mjs --out assets/terrain/alpine` (needs `@threenative/terrain`
+   as a devDependency). The same recipe always writes the same bytes.
+3. In the scene, call `addAlpine(ctx, follow)` for the world and `alpineDaylight(follow)` for the light.

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