Skip to content

3D engine that AI agents drive

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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.js
index 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.js
index 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);
+});