3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Refuse grass and clutter options that build NaN geometry (#2460)
Nguyen Xuan Anf809e2fe2402
diff --git a/changes/2460.md b/changes/2460.mdnew file mode 100644index 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.mdindex 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.mdindex 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.jsindex 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.jsindex 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.jsnew file mode 100644index 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/);+});