Skip to content

3D engine that AI agents drive

Refuse grass and clutter options that build NaN geometry (#2460)

Nguyen Xuan Anf809e2fe2402
diff --git a/changes/2460.md b/changes/2460.md
new file mode 100644
index 00000000..d0ada3e7
--- /dev/null
+++ b/changes/2460.md
@@ -0,0 +1 @@
+- `createGrass` and `createClutter` throw an error that says what to pass for a zero or NaN `clumpSize`, a `clumpStrength` outside 0 to 1, a `bend` that is not a finite pair, and an infinite height, width, rock or pebble size or tile size, instead of building NaN blades or nothing (#2460, #2461, #2463)
diff --git a/docs/clutter.md b/docs/clutter.md
index 3248b2f3..52ac065d 100644
--- a/docs/clutter.md
+++ b/docs/clutter.md
@@ -47,7 +47,7 @@ Clutter shows best on paths, clearings, riverbanks and forest floor. Under a den
| `stoneColor`, `mossColor`, `soilColor`, `twigColor` | earth tones | Linear RGB. |
| `leafColors` | four dry browns | A list of linear RGB colours. Each leaf picks one. |
| `castShadow` | `true` | Stones cast shadows. Twigs and leaves never do. |
-| `tileSize`, `levels`, `cullDistance` | `4`, `CLUTTER_LEVELS`, last level | Tiling and level of detail. An area needing over 262144 tiles throws. |
+| `tileSize`, `levels`, `cullDistance` | `4`, `CLUTTER_LEVELS`, last level | Tiling and level of detail; `tileSize` must be finite. An area needing over 262144 tiles throws. |
| `eye`, `seed` | area centre, `1` | Initial camera position and random seed. |
`createClutter` returns `{ parts, update(eye), stats(), materials, settings }`.
diff --git a/docs/grass.md b/docs/grass.md
index 17ab4ddf..da2a3be2 100644
--- a/docs/grass.md
+++ b/docs/grass.md
@@ -55,7 +55,7 @@ The technique follows the grass of Ghost of Tsushima (GDC 2021) and the open por
| `patchiness` | from preset | Field-scale variation of height, density and shade (0 to 1). Zero gives an even field. |
| `stalks` | from preset | Share of seed stalks (0 to 1). `lawn` has none. |
| `base`, `tip`, `dry` | from preset | Linear RGB colours for the root, the green tip and the dry tip. |
-| `tileSize` | `4` | Tile edge in metres. Each tile is one part and one draw. An area needing over 262144 tiles throws. |
+| `tileSize` | `4` | Tile edge in metres, finite. Each tile is one part and one draw. An area needing over 262144 tiles throws. |
| `levels` | `GRASS_LEVELS` | Distance, kept share, segments and width scale per level of detail. |
| `cullDistance` | last level's distance | Tiles farther than this are dropped. |
| `castShadow` | `false` | Blade shadows cost a full extra pass of every blade. Blades still receive shadows. |
diff --git a/src/clutter.js b/src/clutter.js
index 3abbeddc..b7afcef5 100644
--- a/src/clutter.js
+++ b/src/clutter.js
@@ -10,6 +10,7 @@ import {
} from './vegetation-geometry.js';
import { createTileField, hashTile, tileMatrix } from './tile-field.js';
import { requireSeed } from './seeded-random.js';
+import { requireFiniteInRange } from './modeling-limits.js';
// Rocks draw their keep key below this value and everything else above it, so the farthest level keeps only rocks.
const ROCK_KEY_LIMIT = 0.04;
@@ -269,7 +270,7 @@ function addLeaf(builder, item, tileOrigin, settings, detail) {
}
function requireRange(value, name) {
- if (!Array.isArray(value) || value.length !== 2 || !(value[0] > 0) || !(value[1] >= value[0])) throw new RangeError(`Clutter ${name} must be [minimum, maximum] in metres.`);
+ if (!Array.isArray(value) || value.length !== 2 || !(value[0] > 0) || !(value[1] >= value[0]) || !(value[1] < Infinity)) throw new RangeError(`Clutter ${name} must be finite [minimum, maximum] in metres, such as [0.01, 0.05].`);
}
function requireColor(value, name) {
@@ -291,7 +292,7 @@ function resolveSettings(options) {
for (const name of ['moss', 'clumping']) {
if (!(settings[name] >= 0 && settings[name] <= 1)) throw new RangeError(`Clutter ${name} must be between 0 and 1.`);
}
- if (!(settings.tileSize > 0)) throw new RangeError('Clutter tileSize must be positive.');
+ requireFiniteInRange('createClutter', 'tileSize', settings.tileSize, 1e-3, 1e6);
requireSeed(settings.seed, 'Clutter seed');
requireRange(settings.pebbleSize, 'pebbleSize');
requireRange(settings.rockSize, 'rockSize');
diff --git a/src/grass.js b/src/grass.js
index 92c60dfb..de01ff4b 100644
--- a/src/grass.js
+++ b/src/grass.js
@@ -9,6 +9,7 @@ import {
} from './vegetation-geometry.js';
import { createTileField, hashTile, tileMatrix } from './tile-field.js';
import { requireSeed } from './seeded-random.js';
+import { requireFiniteInRange } from './modeling-limits.js';
export const GRASS_LEVELS = Object.freeze([
Object.freeze({ distance: 10, keep: 1, segments: 4, widthScale: 1 }),
@@ -215,10 +216,13 @@ function resolveSettings(options) {
throw new TypeError('Grass area needs finite minX < maxX and minZ < maxZ.');
}
if (!(settings.density > 0)) throw new RangeError('Grass density must be a positive number of blades per square metre.');
- if (!(settings.tileSize > 0)) throw new RangeError('Grass tileSize must be positive.');
- if (!Array.isArray(settings.height) || !(settings.height[0] > 0) || !(settings.height[1] >= settings.height[0])) throw new RangeError('Grass height must be [minimum, maximum] in metres.');
- if (!(settings.width > 0)) throw new RangeError('Grass width must be positive.');
- for (const name of ['patchiness', 'stalks', 'dryness']) {
+ requireFiniteInRange('createGrass', 'tileSize', settings.tileSize, 1e-3, 1e6);
+ if (!Array.isArray(settings.height) || !(settings.height[0] > 0) || !(settings.height[1] >= settings.height[0]) || !(settings.height[1] < Infinity)) throw new RangeError('Grass height must be finite [minimum, maximum] in metres, such as [0.25, 0.6].');
+ requireFiniteInRange('createGrass', 'width', settings.width, 1e-6, 1e3);
+ requireFiniteInRange('createGrass', 'clumpSize', settings.clumpSize, 1e-3, 1e6);
+ if (!Array.isArray(settings.bend) || settings.bend.length !== 2 || !(settings.bend[1] >= settings.bend[0])) throw new RangeError('Grass bend must be [minimum, maximum], such as [0.18, 0.6].');
+ requireFiniteInRange('createGrass', 'bend', settings.bend, 0, 10);
+ for (const name of ['patchiness', 'stalks', 'dryness', 'clumpStrength']) {
if (!(settings[name] >= 0 && settings[name] <= 1)) throw new RangeError(`Grass ${name} must be between 0 and 1.`);
}
if (settings.mask !== undefined && typeof settings.mask !== 'function') throw new TypeError('Grass mask must be a function (x, z) => 0..1.');
diff --git a/tests/scatter-finite-options.test.js b/tests/scatter-finite-options.test.js
new file mode 100644
index 00000000..2dd846c7
--- /dev/null
+++ b/tests/scatter-finite-options.test.js
@@ -0,0 +1,32 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createGrass } from '../src/grass.js';
+import { createClutter } from '../src/clutter.js';
+
+const area = { minX: 0, maxX: 8, minZ: 0, maxZ: 8 };
+
+function allFinite(parts) {
+ return parts.every(part => Array.from(part.geometry.positions).every(Number.isFinite));
+}
+
+test('grass refuses a clump size, clump strength or bend that would build NaN blades (#2460)', () => {
+ assert.throws(() => createGrass({ area, clumpSize: 0 }), /createGrass: clumpSize was 0; pass a number/);
+ assert.throws(() => createGrass({ area, clumpSize: -1 }), /clumpSize/);
+ assert.throws(() => createGrass({ area, clumpStrength: NaN }), /clumpStrength must be between 0 and 1/);
+ assert.throws(() => createGrass({ area, clumpStrength: 2 }), /clumpStrength/);
+ assert.throws(() => createGrass({ area, bend: 3 }), /Grass bend must be \[minimum, maximum\]/);
+ assert.throws(() => createGrass({ area, bend: [0.6, 0.2] }), /bend/);
+ assert.ok(allFinite(createGrass({ area, density: 40 }).parts));
+});
+
+test('grass and clutter refuse infinite sizes (#2461)', () => {
+ assert.throws(() => createGrass({ area, height: [0.2, Infinity] }), /Grass height must be finite/);
+ assert.throws(() => createGrass({ area, width: Infinity }), /createGrass: width was Infinity/);
+ assert.throws(() => createClutter({ area, rockSize: [0.1, Infinity], rocks: 1 }), /Clutter rockSize must be finite/);
+ assert.throws(() => createClutter({ area, pebbleSize: [Infinity, Infinity] }), /pebbleSize/);
+});
+
+test('grass and clutter refuse an infinite tile size instead of building nothing (#2463)', () => {
+ assert.throws(() => createGrass({ area, tileSize: Infinity }), /createGrass: tileSize was Infinity/);
+ assert.throws(() => createClutter({ area, tileSize: Infinity }), /createClutter: tileSize was Infinity/);
+});