Skip to content

3D engine that AI agents drive

Harden boat and float input checks (#2411)

Nguyen Xuan An1ef1936cb3ef
diff --git a/changes/2411.md b/changes/2411.md
new file mode 100644
index 00000000..489b6e47
--- /dev/null
+++ b/changes/2411.md
@@ -0,0 +1 @@
+- Boat and float input checks: a rejected `setBoatControls` call leaves the live controls as they were, a missing controls object names what to pass, sparse point, stern and keyframe arrays fail with their index, and `boat.forward` must be a string axis.
diff --git a/src/physics-boat.js b/src/physics-boat.js
index 37d0b963..7c6cc849 100644
--- a/src/physics-boat.js
+++ b/src/physics-boat.js
@@ -23,7 +23,8 @@ function normalizeControls(controls, label) {
throw new RangeError(`${label} must be an array of at most ${BOAT_LIMITS.maxControls} keyframes { time, throttle, rudder }, such as [{ "time": 0, "throttle": 1, "rudder": 0 }]`);
}
let previousTime = -Infinity;
- return controls.map((key, index) => {
+ // Array.from visits holes of a sparse array, which map would skip.
+ return Array.from(controls, (key, index) => {
const path = `${label}[${index}]`;
rejectUnknownKeys(key, ['time', 'throttle', 'rudder'], path);
const time = boundedNumber(key.time, `${path}.time`, 0, 1e6, 0);
@@ -61,12 +62,12 @@ export function normalizeBoat(input, label) {
keelDrag: boundedNumber(input.keelDrag ?? DEFAULT_KEEL_DRAG, `${label}.keelDrag`, 0, 100, DEFAULT_KEEL_DRAG),
forward: input.forward ?? '-z',
};
- if (!Object.hasOwn(FORWARD_AXES, boat.forward)) {
+ if (typeof boat.forward !== 'string' || !Object.hasOwn(FORWARD_AXES, boat.forward)) {
throw new RangeError(`${label}.forward must be one of ${Object.keys(FORWARD_AXES).join(', ')}, got ${String(input.forward)}`);
}
if (input.stern !== undefined) {
if (!Array.isArray(input.stern) || input.stern.length !== 3) throw new TypeError(`${label}.stern must be [x, y, z] in body space, such as [0, 0, 1.9]`);
- boat.stern = input.stern.map((component, axis) => boundedNumber(component, `${label}.stern[${axis}]`, -1e6, 1e6, 0));
+ boat.stern = Array.from(input.stern, (component, axis) => boundedNumber(component, `${label}.stern[${axis}]`, -1e6, 1e6, 0));
}
if (input.controls !== undefined) boat.controls = normalizeControls(input.controls, `${label}.controls`);
if (input.wake !== undefined) boat.wake = normalizeBoatWake(input.wake, `${label}.wake`);
@@ -85,9 +86,10 @@ export function resolveBoat(boat, low, high) {
/** Set the controls a live controller holds: throttle and rudder from -1 to 1. Once set they replace the keyframes. */
export function setBoatControls(boat, controls, label = 'setBoatControls') {
- boat.live.throttle = boundedNumber(controls.throttle ?? 0, `${label} throttle`, -1, 1, 1);
- boat.live.rudder = boundedNumber(controls.rudder ?? 0, `${label} rudder`, -1, 1, 0);
- boat.live.set = true;
+ if (controls === null || typeof controls !== 'object') throw new TypeError(`${label} needs controls like { throttle: 1, rudder: 0 }`);
+ const throttle = boundedNumber(controls.throttle ?? 0, `${label} throttle`, -1, 1, 1);
+ const rudder = boundedNumber(controls.rudder ?? 0, `${label} rudder`, -1, 1, 0);
+ Object.assign(boat.live, { throttle, rudder, set: true });
}
/** Throttle and rudder at a physics time: the live values when set, else the keyframes linearly, held after the last one. */
diff --git a/src/physics-buoyancy.js b/src/physics-buoyancy.js
index df14b378..78aacdef 100644
--- a/src/physics-buoyancy.js
+++ b/src/physics-buoyancy.js
@@ -57,11 +57,11 @@ export function normalizeFloat(input, label) {
if (!Array.isArray(points) || points.length < 1 || points.length > BUOYANCY_LIMITS.maxPointsPerBody) {
throw new RangeError(`${label}.points must be 1 to ${BUOYANCY_LIMITS.maxPointsPerBody} points in body space, such as [[-1, 0, -1], [1, 0, 1]]`);
}
- result.points = points.map((point, index) => {
+ result.points = Array.from(points, (point, index) => {
if (!Array.isArray(point) || point.length !== 3) {
throw new TypeError(`${label}.points[${index}] must be [x, y, z] in body space, such as [0, 0, 0]`);
}
- return point.map((component, axis) => boundedNumber(component, `${label}.points[${index}][${axis}]`, -1e6, 1e6, 0));
+ return Array.from(point, (component, axis) => boundedNumber(component, `${label}.points[${index}][${axis}]`, -1e6, 1e6, 0));
});
}
if (input.boat !== undefined) result.boat = normalizeBoat(input.boat, `${label}.boat`);
diff --git a/tests/physics-boat-validation.test.js b/tests/physics-boat-validation.test.js
new file mode 100644
index 00000000..9a1fda5b
--- /dev/null
+++ b/tests/physics-boat-validation.test.js
@@ -0,0 +1,37 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { normalizeBoat, resolveBoat, setBoatControls } from '../src/physics-boat.js';
+import { normalizeFloat } from '../src/physics-buoyancy.js';
+
+function liveBoat() {
+ return resolveBoat(normalizeBoat({}, 'boat'), [-1, -1, -1], [1, 1, 1]);
+}
+
+test('a rejected setBoatControls call leaves the live controls unchanged', () => {
+ const boat = liveBoat();
+ setBoatControls(boat, { throttle: 0.5, rudder: -0.5 });
+ assert.throws(() => setBoatControls(boat, { throttle: 1, rudder: 9 }), /setBoatControls rudder must be a number from -1 to 1/);
+ assert.deepEqual(boat.live, { throttle: 0.5, rudder: -0.5, set: true });
+ const fresh = liveBoat();
+ assert.throws(() => setBoatControls(fresh, { throttle: 1, rudder: 9 }), RangeError);
+ assert.equal(fresh.live.set, false, 'keyframes keep driving the boat after a rejected call');
+ assert.equal(fresh.live.throttle, 0);
+});
+
+test('setBoatControls names what to pass when there are no controls', () => {
+ const boat = liveBoat();
+ assert.throws(() => setBoatControls(boat), /setBoatControls needs controls like \{ throttle: 1, rudder: 0 \}/);
+ assert.throws(() => setBoatControls(boat, null, 'setBoatControls("boat")'), /setBoatControls\("boat"\) needs controls/);
+});
+
+test('sparse arrays fail with the index instead of becoming null or crashing later', () => {
+ assert.throws(() => normalizeFloat({ points: [[0, , 0]] }, 'float'), /float\.points\[0\]\[1\] must be a number/);
+ assert.throws(() => normalizeBoat({ controls: new Array(2) }, 'boat'), /boat\.controls\[0\] must be an object/);
+ assert.throws(() => normalizeBoat({ stern: [0, , 1] }, 'boat'), /boat\.stern\[1\] must be a number/);
+});
+
+test('boat.forward must be one of the axis strings', () => {
+ assert.throws(() => normalizeBoat({ forward: ['+x'] }, 'boat'), /boat\.forward must be one of \+x, -x, \+z, -z, got \+x/);
+ assert.throws(() => normalizeBoat({ forward: { toString: () => '-z' } }, 'boat'), /boat\.forward must be one of/);
+ assert.equal(normalizeBoat({ forward: '+x' }, 'boat').forward, '+x');
+});