@threedog/terrain-noise 0.5.0 → 0.8.0

package/README.md

@@ -1,12 +1,12 @@
 # @threedog/terrain-noise
 
-Optional terrain generator for [threedog](https://www.npmjs.com/package/threedog): noise hills, `island`, `canyon` or `plain` shapes, rivers and a biome rule table. It decides the shape of the world only; ground colors belong to the game's style (keyed by the biome names). Without it the engine's ground is flat.
+Optional terrain generator for [threedog](https://www.npmjs.com/package/threedog): noise hills, `island`, `canyon` or `flat` shapes, rivers and a biome rule table. It decides the shape of the world only; ground colors belong to the game's style (keyed by the biome names). Without it the engine's ground is flat.
 
 ```sh
-npm install @threedog/terrain-noise@0.5
+npm install @threedog/terrain-noise@0.8
 ```
 
-This describes 0.5.0: `npm install @threedog/terrain-noise@0.5` (games made in the [repository](https://github.com/penstic123-code/ThreeDog.js-Game-Engine) already have it).
+This describes 0.8.0: `npm install @threedog/terrain-noise@0.8` (games made in the [repository](https://github.com/penstic123-code/Threedog.js-Game-Engine) already have it).
 
 ```js
 import { openWorld } from 'threedog';

package/index.d.ts

@@ -21,7 +21,7 @@ export interface BiomeRule extends BiomeCondition { name: string; any?: BiomeCon
 export interface TerrainPresetOptions {
   /** Landform, default 'hills' */
   shape?: 'hills' | 'island' | 'canyon' | 'flat';
-  /** Overall relief multiplier */
+  /** Multiplies the base land and hills around sea level (lows get deeper as highs rise); the mountain part (`mountains`) is separate and not scaled by it */
   heightScale?: number;
   /** Mountain strength */
   mountains?: number;
@@ -29,6 +29,8 @@ export interface TerrainPresetOptions {
   rivers?: boolean;
   /** River width (0.02 narrow, 0.05 wide) */
   riverWidth?: number;
+  /** Where rivers run and how their banks fall: noise scale and offset, bank width in river widths, the depth share outside the river itself */
+  river?: { scale?: number; offset?: number[]; bank?: number; edge?: number };
   /** Biome rule table (default BIOMES) */
   biomes?: BiomeRule[];
   tempScale?: number; moistScale?: number;
@@ -41,13 +43,15 @@ export interface TerrainPresetOptions {
 /** The default biome rule table: beach, snow, rock, riverbank, wetland, savanna, forest, highland, meadow */
 export const BIOMES: BiomeRule[];
 /**
- * Noise terrain generator for terrain() / openWorld({ terrain }) / createTerrain(): noise hills (or island, canyon, plain), rivers, biomes.
+ * Noise terrain generator for terrain() / openWorld({ terrain }) / createTerrain(): noise hills (or island, canyon, flat), rivers, biomes.
  * @example engine.use(openWorld({ seed: 7, camera: 'follow', terrain: terrainPreset({ shape: 'island' }) }))
  */
 export function terrainPreset(opts?: TerrainPresetOptions): {
   height: (x: number, z: number, n: TerrainNoise) => number;
   groundType: (x: number, z: number, h: number, slope: number, n: TerrainNoise) => string;
   params: Record<string, any>;
+  /** Sea level this generator carves rivers and coasts toward */
+  waterLevel: number;
 };
 /** Display names of the preset's ground types ('ground.<type>' keys in zh-CN and en): engine.i18n.add(terrainStrings) */
 export const terrainStrings: Record<string, Record<string, string>>;

package/index.js

@@ -4,9 +4,10 @@
 //   import { terrainPreset } from '@threedog/terrain-noise';
 //   engine.use(openWorld({ seed: 7, camera: 'follow', terrain: terrainPreset({ shape: 'island' }) }));
 // Why its own package and not part of a style: the shape of the world (where hills, rivers and forests are) is gameplay, and a style
-// pack holds looks only (packages/engine/docs/recipes/09-style.md). Swapping the look must never move a river. The colors of these ground types belong
+// pack holds looks only (packages/engine/docs/recipes/09-materials-lights-models.md). Swapping the picture must never move a river. The colors of these ground types belong
 // to whichever style the game uses (e.g. style.terrain.biomeColors, keyed by the names below).
 // height and groundType run in terrain workers, so they are pure: they read only their parameters (n.params is the options below) and Math.
+// That is also why the river formula is written out in each of them (core/threads/threadPure.js recompiles a function in an empty scope, so a shared helper is out of reach): the numbers live once, in `river`.
 // The ground type names are plain strings that vegetation rules, style colors and a game's footstep map match by name.
 
 // Biome rules: checked top to bottom, the first match is the biome there (the last has no condition and is the default).
@@ -34,10 +35,11 @@ export const terrainStrings = {
 
 const DEFAULTS = {
   shape: 'hills',      // 'hills' | 'island' | 'canyon' (mesas) | 'flat' (gentle plain)
-  heightScale: 1,      // overall relief multiplier
+  heightScale: 1,      // multiplies the base land and hills around sea level (lows get deeper too, not only highs); `mountains` is a separate amount that heightScale does not scale, so the highest point may not rise with it
   mountains: 1,        // mountain strength
   rivers: true,        // carve rivers
   riverWidth: 0.03,    // river width (noise threshold, 0.02 narrow, 0.05 wide)
+  river: { scale: 0.0022, offset: [40, -70], bank: 2.2, edge: 0.85 },   // noise behind the rivers; bank width in river widths; the share of depth outside the river itself
   biomes: BIOMES,
   tempScale: 0.0011, moistScale: 0.0014, tempLapse: 0.006,   // temperature / moisture noise scale; temperature drop per meter of altitude
   noise: { baseScale: 0.0035, baseAmp: 46, hillScale: 0.016, hillAmp: 10, mountainScale: 0.0018, mountainAmp: 900, mountainThreshold: 0.52, seaBias: 0.42 },
@@ -66,8 +68,8 @@ function height(x, z, n) {
   } else h = hills();
   // rivers: thin bands where noise is near 0.5 are dug below the water surface
   if (P.rivers) {
-    const r = Math.abs(fbm(x * 0.0022 + 40, z * 0.0022 - 70, 3) - 0.5), w = P.riverWidth, bank = w * 2.2;
-    if (r < bank) h = h + (n.waterLevel - 1.6 - h) * Math.min(1, smooth(1 - r / bank) * (r < w ? 1 : 0.85) * 1.25);
+    const R = P.river, r = Math.abs(fbm(x * R.scale + R.offset[0], z * R.scale + R.offset[1], 3) - 0.5), w = P.riverWidth, bank = w * R.bank;
+    if (r < bank) h = h + (n.waterLevel - 1.6 - h) * Math.min(1, smooth(1 - r / bank) * (r < w ? 1 : R.edge) * 1.25);
   }
   return h;
 }
@@ -80,8 +82,8 @@ function groundType(x, z, h, sl, n) {
   const moist = () => ms ??= fbm(x * P.moistScale - 200, z * P.moistScale + 100, 3);
   const river = () => rv ??= (() => {
     if (!P.rivers) return 0;
-    const r = Math.abs(fbm(x * 0.0022 + 40, z * 0.0022 - 70, 3) - 0.5), w = P.riverWidth, bank = w * 2.2, t = 1 - r / bank;
-    return r >= bank ? 0 : t * t * (3 - 2 * t) * (r < w ? 1 : 0.85);
+    const R = P.river, r = Math.abs(fbm(x * R.scale + R.offset[0], z * R.scale + R.offset[1], 3) - 0.5), w = P.riverWidth, bank = w * R.bank, t = 1 - r / bank;
+    return r >= bank ? 0 : t * t * (3 - 2 * t) * (r < w ? 1 : R.edge);
   })();
   const test = c => c.any ? c.any.some(test) : !((c.minHeight != null && h < c.minHeight) || (c.maxHeight != null && h > c.maxHeight) ||
     (c.maxAboveWater != null && h >= W + c.maxAboveWater) || (c.minSlope != null && sl < c.minSlope) ||
@@ -102,18 +104,18 @@ function groundType(x, z, h, sl, n) {
 export function riverAt(x, z, n) {
   const P = n.params;
   if (!P?.rivers) return 0;
-  const r = Math.abs(n.fbm(x * 0.0022 + 40, z * 0.0022 - 70, 3) - 0.5), w = P.riverWidth, bank = w * 2.2, t = 1 - r / bank;
-  return r >= bank ? 0 : t * t * (3 - 2 * t) * (r < w ? 1 : 0.85);
+  const R = P.river, r = Math.abs(n.fbm(x * R.scale + R.offset[0], z * R.scale + R.offset[1], 3) - 0.5), w = P.riverWidth, bank = w * R.bank, t = 1 - r / bank;
+  return r >= bank ? 0 : t * t * (3 - 2 * t) * (r < w ? 1 : R.edge);
 }
 
 /**
- * Noise terrain preset: spread it into terrain() (or openWorld({ terrain })). Options override the defaults above; noise, island and
- * canyon merge field by field.
+ * Noise terrain preset: spread it into terrain() (or openWorld({ terrain })). Options override the defaults above; noise, island,
+ * canyon and river merge field by field.
  * @example engine.use(terrain({ seed: 7, ...terrainPreset({ shape: 'island', rivers: false }) }))
  * @param {Partial<typeof DEFAULTS>} [opts]
  */
 export function terrainPreset(opts = {}) {
   const params = { ...DEFAULTS, ...opts };
-  for (const k of ['noise', 'island', 'canyon']) params[k] = { ...DEFAULTS[k], ...(opts[k] || {}) };
+  for (const k of ['noise', 'island', 'canyon', 'river']) params[k] = { ...DEFAULTS[k], ...(opts[k] || {}) };
   return { waterLevel: 0, height, groundType, params };   // this generator's rivers and coasts are carved toward sea level 0
 }

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@threedog/terrain-noise",
-  "version": "0.5.0",
-  "description": "Optional terrain generator for threedog: noise hills, island, canyon or plain shapes, rivers and a biome rule table (world shape only, no colors)",
+  "version": "0.8.0",
+  "description": "Optional terrain generator for threedog: noise hills, island, canyon or flat shapes, rivers and a biome rule table (world shape only, no colors)",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/penstic123-code/ThreeDog.js-Game-Engine.git",
+    "url": "git+https://github.com/penstic123-code/Threedog.js-Game-Engine.git",
     "directory": "packages/terrain-noise"
   },
-  "homepage": "https://github.com/penstic123-code/ThreeDog.js-Game-Engine#readme",
+  "homepage": "https://github.com/penstic123-code/Threedog.js-Game-Engine#readme",
   "type": "module",
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
@@ -27,6 +27,6 @@
     "*.d.ts"
   ],
   "peerDependencies": {
-    "threedog": "^0.5.0"
+    "threedog": "^0.8.0"
   }
 }