3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Refuse bad previousCamera, part matrix and mesh indices with clear errors (#2446)
Nguyen Xuan Ana91fec2e2f06
diff --git a/changes/2446.md b/changes/2446.mdnew file mode 100644index 00000000..63d5bd5e--- /dev/null+++ b/changes/2446.md@@ -0,0 +1 @@+- A motion blur `previousCamera` with a non-finite eye, an eye on its target or a parallel up now throws an error that says what to pass (#2446)diff --git a/changes/2446.size.md b/changes/2446.size.mdnew file mode 100644index 00000000..0211b45d--- /dev/null+++ b/changes/2446.size.md@@ -0,0 +1,4 @@+- entry:camera-effects: previousCamera now refuses a NaN, zero-length or parallel-up view instead of building a garbage motion blur matrix (about 280 bytes gzip).+- scene:agent-scene: three input checks (previousCamera, part matrix, mesh indices) whose messages say what to pass (about 280 bytes gzip).+- scene:agent-scene+lazy: the same three checks.+- goal:agent-scene: the checks stop silent NaN boxes, garbage blur and an open-mesh error that blames the wrong field; the growth is about 0.2 percent.diff --git a/changes/2447.md b/changes/2447.mdnew file mode 100644index 00000000..d64df44d--- /dev/null+++ b/changes/2447.md@@ -0,0 +1 @@+- A mesh volume part with a non-finite or short matrix now throws an error that names the part (#2447)diff --git a/changes/2448.md b/changes/2448.mdnew file mode 100644index 00000000..289f00c4--- /dev/null+++ b/changes/2448.md@@ -0,0 +1 @@+- A mesh volume part with out-of-range or partial-triangle indices now says so instead of reporting an open mesh (#2448)diff --git a/src/camera-effects.js b/src/camera-effects.jsindex ea9465f7..01f6e798 100644--- a/src/camera-effects.js+++ b/src/camera-effects.js@@ -1,5 +1,5 @@import { mat4 } from 'gl-matrix';-import { applyProjection, requirePositiveFinite } from './camera.js';+import { applyProjection, requireNonDegenerateView, requirePositiveFinite } from './camera.js';import { compileProgram, fullscreenVertex } from './gl-program.js';// Depth of field and camera motion blur as optional full-frame stages. The core renderer carries no shader text for@@ -197,7 +197,9 @@ export function previousViewProjectionOf(renderer, frame) {const previous = { ...frame, ...frame.previousCamera };const aspect = renderer.canvas.width / renderer.canvas.height;const projection = applyProjection(mat4.create(), previous, aspect, { world: renderer.world });- const view = mat4.lookAt(mat4.create(), previous.eye, previous.target ?? [0, 1.2, 0], previous.up ?? [0, 1, 0]);+ const lookView = { eye: previous.eye, target: previous.target ?? [0, 1.2, 0], up: previous.up ?? [0, 1, 0] };+ requireNonDegenerateView(lookView, 'previousCamera');+ const view = mat4.lookAt(mat4.create(), lookView.eye, lookView.target, lookView.up);return mat4.multiply(mat4.create(), projection, view);}diff --git a/src/camera.js b/src/camera.jsindex 0b58a12e..2baf0290 100644--- a/src/camera.js+++ b/src/camera.js@@ -130,20 +130,22 @@ export function cameraView(name = 'front', { target = [0, 1.5, 0], height = 3.8,return { eye, target: [...target], up: name === 'top' ? [0, 0, -1] : [0, 1, 0], projection: name === 'perspective' ? 'perspective' : 'orthographic', orthographicHeight: height, fov: 45 };}-function requireNonDegenerateView(view) {+/** Throws unless the eye, target and up of `view` are finite, the eye differs from the target and up is not parallel to the view; `subject` starts each message. */+export function requireNonDegenerateView(view, subject = 'Fit') {const up = view?.up ?? [0, 1, 0];const isFiniteVector = vector => vector?.length === 3 && Array.from(vector).every(value => typeof value === 'number' && Number.isFinite(value));if (!isFiniteVector(view?.eye) || !isFiniteVector(view?.target) || !isFiniteVector(up)) {- throw new RangeError('Fit camera eye, target and up must be three finite numbers each.');+ throw new RangeError(`${subject} camera eye, target and up must be three finite numbers each.`);}- const forward = vec3.subtract(vec3.create(), view.target, view.eye);- const upDirection = vec3.normalize(vec3.create(), up);- if (vec3.length(forward) === 0 || vec3.length(upDirection) === 0) {- throw new RangeError('Fit eye and target must differ and up must be nonzero.');+ const forward = [0, 1, 2].map(axis => view.target[axis] - view.eye[axis]);+ const forwardLength = Math.hypot(...forward);+ const upLength = Math.hypot(...up);+ if (forwardLength === 0 || upLength === 0) {+ throw new RangeError(`${subject} eye and target must differ and up must be nonzero.`);}- vec3.normalize(forward, forward);- if (Math.abs(vec3.dot(forward, upDirection)) >= 1 - 1e-10) {- throw new RangeError('Fit up must not be parallel to the view direction; pass another up, such as [0, 0, -1] for a top view.');+ const alignment = forward.reduce((sum, component, axis) => sum + component * up[axis], 0) / (forwardLength * upLength);+ if (Math.abs(alignment) >= 1 - 1e-10) {+ throw new RangeError(`${subject} up must not be parallel to the view direction; pass another up, such as [0, 0, -1] for a top view.`);}}diff --git a/src/local-volume-parts.js b/src/local-volume-parts.jsindex ae8c54df..a998ca30 100644--- a/src/local-volume-parts.js+++ b/src/local-volume-parts.js@@ -76,6 +76,9 @@ function localBounds(geometry, label, partName) {function orientedBounds(part, label) {const { minimum, maximum } = localBounds(part.geometry, label, part.name);const matrix = part.matrix ?? [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];+ if (matrix.length !== 16 || !Array.from(matrix).every(Number.isFinite)) {+ throw new RangeError(`${label}.part "${part.name}" needs a matrix of 16 finite numbers, got ${matrix.length} values; pass the part's world matrix`);+ }const localCenter = minimum.map((low, axis) => (low + maximum[axis]) / 2);const center = [0, 1, 2].map(row => matrix[row] * localCenter[0] + matrix[4 + row] * localCenter[1] + matrix[8 + row] * localCenter[2] + matrix[12 + row]);const size = [];@@ -95,9 +98,16 @@ function orientedBounds(part, label) {const edgeProblemsByPositions = new WeakMap();+function requireValidIndices(indices, vertexCount, subject) {+ if (indices.length % 3 !== 0) throw new RangeError(`${subject} has ${indices.length} indices; a triangle list needs a multiple of 3`);+ const outOfRange = indices.findIndex(index => !(index >= 0 && index < vertexCount));+ if (outOfRange >= 0) throw new RangeError(`${subject} index ${outOfRange} is ${indices[outOfRange]}, but the part has ${vertexCount} vertices; pass indices from 0 to ${vertexCount - 1}`);+}+/** Throws unless the part's mesh is closed and its faces wind the same way, which the rasterizer's front and back faces rely on. */export function assertClosedMesh(part, label) {const { positions, indices } = part.geometry;+ requireValidIndices(indices, positions.length / 3, `${label}.part "${part.name}"`);let cached = edgeProblemsByPositions.get(positions);if (cached?.indices !== indices) {const { minimum, maximum } = localBounds(part.geometry, label, part.name);diff --git a/tests/volume-camera-input.test.js b/tests/volume-camera-input.test.jsnew file mode 100644index 00000000..a432c3bd--- /dev/null+++ b/tests/volume-camera-input.test.js@@ -0,0 +1,40 @@+// Bad camera and mesh-volume input fails with a message that names the field (issues 2446, 2447, 2448).+import test from 'node:test';+import assert from 'node:assert/strict';+import { previousViewProjectionOf } from '../src/camera-effects.js';+import { assertClosedMesh, bindLocalVolumeParts } from '../src/local-volume-parts.js';++const renderer = { canvas: { width: 100, height: 50 }, world: false };+const frame = { eye: [0, 1, 5], target: [0, 1, 0] };++const positions = new Float32Array([0, 0, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 0, 0, 1, 1, 0, 1, 1, 1, 1, 0, 1, 1]);+const indices = new Uint32Array([0, 2, 1, 0, 3, 2, 4, 5, 6, 4, 6, 7, 0, 1, 5, 0, 5, 4, 3, 7, 6, 3, 6, 2, 0, 4, 7, 0, 7, 3, 1, 2, 6, 1, 6, 5]);+const meshVolume = [{ shape: 'mesh', part: 'room', fit: 'bounds' }];++test('previousViewProjectionOf refuses a previous camera it cannot aim', () => {+ assert.throws(() => previousViewProjectionOf(renderer, { ...frame, previousCamera: { eye: [Number.NaN, 0, 0] } }), /previousCamera camera eye, target and up must be three finite numbers/);+ assert.throws(() => previousViewProjectionOf(renderer, { ...frame, previousCamera: { eye: [0, 1, 0] } }), /previousCamera eye and target must differ/);+ assert.throws(() => previousViewProjectionOf(renderer, { ...frame, previousCamera: { up: [0, 0, 1] } }), /previousCamera up must not be parallel/);+});++test('previousViewProjectionOf still builds a finite matrix for a partial previous camera', () => {+ const matrix = previousViewProjectionOf(renderer, { ...frame, previousCamera: { eye: [1, 1, 5] } });+ assert.ok(Array.from(matrix).every(Number.isFinite));+});++test('a mesh volume part needs a matrix of 16 finite numbers', () => {+ const bind = matrix => bindLocalVolumeParts(meshVolume, [{ name: 'room', geometry: { positions, indices }, matrix }]);+ assert.throws(() => bind([Infinity, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]), /part "room" needs a matrix of 16 finite numbers/);+ assert.throws(() => bind([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, Number.NaN, 0, 0, 1]), /16 finite numbers/);+ assert.throws(() => bind([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]), /got 11 values/);+ assert.deepEqual(bind([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 2, 0, 0, 1])[0].center, [2.5, 0.5, 0.5]);+});++test('assertClosedMesh names a bad index list instead of reporting open edges', () => {+ const check = list => assertClosedMesh({ name: 'room', geometry: { positions, indices: list } }, 'localVolumes[0]');+ check(indices);+ const outOfRange = indices.slice();+ outOfRange[5] = 99;+ assert.throws(() => check(outOfRange), /index 5 is 99, but the part has 8 vertices/);+ assert.throws(() => check(new Uint32Array([...indices, 0, 1])), /38 indices; a triangle list needs a multiple of 3/);+});