3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Refuse NaN lean gains, negative suspension travel and drives over an hour (#2361, #2362)
Nguyen Xuan Aneafec5a2e703
diff --git a/changes/2361.md b/changes/2361.mdnew file mode 100644index 00000000..842da27c--- /dev/null+++ b/changes/2361.md@@ -0,0 +1 @@+- A drive option that is NaN, a negative suspension travel, or a drive longer than an hour now throws an error that names the field instead of returning NaN poses or failing with an allocation error (#2361, #2362).diff --git a/changes/2361.size.md b/changes/2361.size.mdnew file mode 100644index 00000000..e83bd370--- /dev/null+++ b/changes/2361.size.md@@ -0,0 +1 @@+- scene:agent-scene+lazy: three guards that turn NaN poses, an empty suspension clamp and a multi-gigabyte allocation into errors naming the field (#2361, #2362).diff --git a/docs/vehicle.md b/docs/vehicle.mdindex 9e4e39a3..41864507 100644--- a/docs/vehicle.md+++ b/docs/vehicle.md@@ -83,7 +83,7 @@ Speed is arc-length based. Give exactly one of:| `speed` | Constant metres per second, no ramp || `cruiseSpeed` | Profile with `acceleration` (3), `braking` (4), `startSpeed` (0), `endSpeed` (0) and `maxLateralAcceleration` (unlimited) |-Other options: `startTime`, `groundHeight(x, z)`, `maxSteerAngle`, `rollGain` (0.012 rad per m/s2), `pitchGain` (0.012), `bounceFrequency` (1.6 Hz), `dampingRatio` (0.45), `suspensionTravel` (0.2 m), `pathSamples` (400, for camera paths).+Other options: `startTime`, `groundHeight(x, z)`, `maxSteerAngle`, `rollGain` (0.012 rad per m/s2), `pitchGain` (0.012), `bounceFrequency` (1.6 Hz), `dampingRatio` (0.45), `suspensionTravel` (0.2 m), `pathSamples` (400, for camera paths). `rollGain` and `pitchGain` must be finite, `suspensionTravel` 0 or more, and a drive may last at most 3600 seconds including pauses and `startTime`; anything else throws an error naming the field.`sample(seconds)` returns `{ time, distance, speed, direction, position, heading, pitch, roll, steerAngle, wheels: [{ id, spinAngle, steerAngle, suspensionOffset }], lights }`.diff --git a/src/vehicle.js b/src/vehicle.jsindex 4daef1f0..3394af54 100644--- a/src/vehicle.js+++ b/src/vehicle.js@@ -15,6 +15,8 @@ const DEFAULT_MAX_STEER_ANGLE = 35 * Math.PI / 180;const MAX_BODY_ANGLE = 0.35;const SIMULATION_STEP_SECONDS = 1 / 240;const SETTLE_SECONDS = 2;+// The body-motion integrator keeps one step per 1/240 s of the drive, so a drive of hours would allocate gigabytes.+const MAX_DRIVE_SECONDS = 3600;const PATH_SPACING_METRES = 0.1;const MAX_PATH_SAMPLES = 20000;const MINIMUM_SPEED_LIMIT = 0.5;@@ -44,6 +46,10 @@ function assertFinitePositive(value, path, example = '1') {if (!Number.isFinite(value) || value <= 0) throw invalidField(path, value, `a finite number above 0, such as ${example}`);}+function assertFiniteNumber(value, path, example) {+ if (!Number.isFinite(value)) throw invalidField(path, value, `a finite number, such as ${example}`);+}+function clamp(value, minimum, maximum) {return Math.min(maximum, Math.max(minimum, value));}@@ -815,6 +821,10 @@ export function driveAlongLegs(rig, legDescriptions, options = {}, pathFieldOf =const settings = resolveDriveOptions(rig, options);const legs = buildLegs(legDescriptions, settings, pathFieldOf);const duration = legs.at(-1).endTime;+ if (!(duration <= MAX_DRIVE_SECONDS)) {+ const causes = settings.speed === undefined ? 'cruiseSpeed, acceleration, a leg pause or startTime' : 'speed, a leg pause or startTime';+ throw invalidField('duration', `${duration} seconds`, `a drive of at most ${MAX_DRIVE_SECONDS} seconds; raise ${causes} or shorten the path`);+ }const length = legs.reduce((total, leg) => total + leg.table.length, 0);const legAt = time => legs.findLast(leg => leg.startTime <= time) ?? legs[0];const timeline = {@@ -911,6 +921,11 @@ function resolveDriveOptions(rig, options) {assertFinitePositive(maxSteerAngle, 'maxSteerAngle', '0.6');assertFinitePositive(bounceFrequency, 'bounceFrequency', '1.6');assertFinitePositive(dampingRatio, 'dampingRatio', '0.45');+ assertFiniteNumber(rollGain, 'rollGain', '0.012');+ assertFiniteNumber(pitchGain, 'pitchGain', '0.012');+ if (!Number.isFinite(suspensionTravel) || suspensionTravel < 0) {+ throw invalidField('suspensionTravel', suspensionTravel, 'a distance in metres of 0 or more, such as 0.2');+ }if (!Number.isFinite(startSpeed) || startSpeed < 0 || !Number.isFinite(endSpeed) || endSpeed < 0) {const badSpeedField = !Number.isFinite(startSpeed) || startSpeed < 0 ? 'startSpeed' : 'endSpeed';throw invalidField(badSpeedField, badSpeedField === 'startSpeed' ? startSpeed : endSpeed, 'a speed of 0 or more, such as 0');diff --git a/tests/vehicle.test.js b/tests/vehicle.test.jsindex da3c7832..c2fbf586 100644--- a/tests/vehicle.test.js+++ b/tests/vehicle.test.js@@ -353,3 +353,20 @@ test('bad input produces specific errors', () => {assert.throws(() => applyVehiclePoseToSceneGraph(rig, driveAlongPath(rig, STRAIGHT_PATH, { speed: 3 }).sample(0), {}), /built from parts, not graph/);assert.throws(() => findWheelCandidates('wheel'), /array of name strings/);});++test('drive options refuse a NaN lean gain and a negative suspension travel', () => {+ const { rig } = createTestRig();+ for (const [field, value] of [['rollGain', NaN], ['pitchGain', Infinity], ['suspensionTravel', -1], ['suspensionTravel', NaN]]) {+ assert.throws(() => driveAlongPath(rig, STRAIGHT_PATH, { speed: 5, [field]: value }), new RegExp(`${field}: got`), `${field} ${value}`);+ }+ const drive = driveAlongPath(rig, STRAIGHT_PATH, { speed: 5, suspensionTravel: 0, rollGain: -0.01 });+ assert.ok(Number.isFinite(drive.sample(1).roll));+});++test('a drive too slow or paused for too long is refused with a clear error', () => {+ const { rig } = createTestRig();+ assert.throws(() => driveAlongPath(rig, STRAIGHT_PATH, { speed: 1e-9 }), /duration: got ".* seconds"; expected a drive of at most 3600 seconds/);+ assert.throws(() => driveAlongPath(rig, STRAIGHT_PATH, { cruiseSpeed: 1e-3, acceleration: 1e-3 }), /at most 3600 seconds/);+ assert.throws(() => driveAlongPath(rig, STRAIGHT_PATH, { speed: 5, startTime: 1e9 }), /at most 3600 seconds/);+ assert.ok(driveAlongPath(rig, STRAIGHT_PATH, { speed: 0.01 }).duration <= 3600);+});