@woosh/meep-engine 3.1.0 → 3.3.0

package/src/engine/input/devices/ManualInputDevice.js

@@ -1,152 +1,152 @@
-import { assert } from "../../../core/assert.js";
-import { InputDeviceSwitch } from "./InputDeviceSwitch.js";
-
-/**
- * An input device driven by method call rather than by hardware.
- *
- * Its switches are real {@link InputDeviceSwitch} instances, so anything reading it - the binding layer
- * included - cannot tell it from {@link KeyboardDevice} or {@link GamepadDevice}, and gets the same edge
- * detection and the same idempotence.
- *
- * Three things want this:
- *   - REPLAY. A recorded input trace is played back by pressing and releasing switches in the recorded order.
- *   - SCRIPTED INPUT. Tutorials, demos, and AI or network driven players.
- *   - TESTS. Which is a consequence of the first two rather than the reason: driving a binding through a real
- *     device is what makes an input test black-box, and it needs no DOM.
- *
- * Codes are whatever the consumer decides they are - {@link KeyCodes} to stand in for a keyboard,
- * {@link GamepadButtons} for a pad. The device attaches no meaning to them.
- *
- * @example
- *   const device = new ManualInputDevice();
- *
- *   device.getSwitch(KeyCodes.ctrl).press();
- *   device.getSwitch(KeyCodes.z).press();
- *
- *   device.defineCoordinate(GamepadCoordinates.left_stick, 2);
- *   device.setCoordinate(GamepadCoordinates.left_stick, 0, 1);
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class ManualInputDevice {
-
-    /**
-     * Switches by code. Sparse, grown on demand.
-     * @type {InputDeviceSwitch[]}
-     */
-    #switches = [];
-
-    /**
-     * Component count per defined coordinate code. Sparse.
-     * @type {number[]}
-     */
-    #dimensions = [];
-
-    /**
-     * Component values per defined coordinate code. Sparse.
-     * @type {Float64Array[]}
-     */
-    #values = [];
-
-    /**
-     * Total: a switch exists for every code, whether or not anything has touched it, and an untouched one
-     * reads up. Repeated calls for the same code return the same instance, so it is safe to hold onto.
-     *
-     * @param {number} code
-     * @returns {InputDeviceSwitch}
-     */
-    getSwitch(code) {
-        assert.isNonNegativeInteger(code, 'code');
-
-        let result = this.#switches[code];
-
-        if (result === undefined) {
-            result = new InputDeviceSwitch();
-
-            this.#switches[code] = result;
-        }
-
-        return result;
-    }
-
-    /**
-     * Declare an analog channel. Must be called before the channel is read or written.
-     *
-     * @param {number} code
-     * @param {number} dimensions component count
-     */
-    defineCoordinate(code, dimensions) {
-        assert.isNonNegativeInteger(code, 'code');
-        assert.isPositiveInteger(dimensions, 'dimensions');
-
-        this.#dimensions[code] = dimensions;
-        this.#values[code] = new Float64Array(dimensions);
-    }
-
-    /**
-     * Precondition: `code` has been passed to {@link defineCoordinate}.
-     *
-     * @param {number} code
-     * @returns {number}
-     */
-    getCoordinateDimensions(code) {
-        const result = this.#dimensions[code];
-
-        assert.defined(result, `dimensions for coordinate ${code}, coordinate was never defined`);
-
-        return result;
-    }
-
-    /**
-     * Precondition: `code` has been passed to {@link defineCoordinate}, and `components.length` matches the
-     * declared dimensionality.
-     *
-     * @param {number} code
-     * @param {...number} components
-     */
-    setCoordinate(code, ...components) {
-        const values = this.#values[code];
-
-        assert.defined(values, `coordinate ${code}, coordinate was never defined`);
-        assert.equal(components.length, values.length, `component count for coordinate ${code}`);
-
-        values.set(components);
-    }
-
-    /**
-     * Precondition: `code` has been passed to {@link defineCoordinate}.
-     *
-     * @param {number[]|Float64Array} result
-     * @param {number} offset
-     * @param {number} code
-     */
-    readCoordinate(result, offset, code) {
-        const values = this.#values[code];
-
-        assert.defined(values, `coordinate ${code}, coordinate was never defined`);
-
-        const n = values.length;
-        for (let i = 0; i < n; i++) {
-            result[offset + i] = values[i];
-        }
-    }
-
-    /**
-     * Release every switch and zero every coordinate. Used when a replay ends, or a scripted sequence is
-     * cancelled, so nothing is left stuck down.
-     */
-    reset() {
-        const switches = this.#switches;
-
-        for (let i = 0; i < switches.length; i++) {
-            switches[i]?.release();
-        }
-
-        const values = this.#values;
-
-        for (let i = 0; i < values.length; i++) {
-            values[i]?.fill(0);
-        }
-    }
-}
+import { assert } from "../../../core/assert.js";
+import { InputDeviceSwitch } from "./InputDeviceSwitch.js";
+
+/**
+ * An input device driven by method call rather than by hardware.
+ *
+ * Its switches are real {@link InputDeviceSwitch} instances, so anything reading it - the binding layer
+ * included - cannot tell it from {@link KeyboardDevice} or {@link GamepadDevice}, and gets the same edge
+ * detection and the same idempotence.
+ *
+ * Three things want this:
+ *   - REPLAY. A recorded input trace is played back by pressing and releasing switches in the recorded order.
+ *   - SCRIPTED INPUT. Tutorials, demos, and AI or network driven players.
+ *   - TESTS. Which is a consequence of the first two rather than the reason: driving a binding through a real
+ *     device is what makes an input test black-box, and it needs no DOM.
+ *
+ * Codes are whatever the consumer decides they are - {@link KeyCodes} to stand in for a keyboard,
+ * {@link GamepadButtons} for a pad. The device attaches no meaning to them.
+ *
+ * @example
+ *   const device = new ManualInputDevice();
+ *
+ *   device.getSwitch(KeyCodes.ctrl).press();
+ *   device.getSwitch(KeyCodes.z).press();
+ *
+ *   device.defineCoordinate(GamepadCoordinates.left_stick, 2);
+ *   device.setCoordinate(GamepadCoordinates.left_stick, 0, 1);
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ManualInputDevice {
+
+    /**
+     * Switches by code. Sparse, grown on demand.
+     * @type {InputDeviceSwitch[]}
+     */
+    #switches = [];
+
+    /**
+     * Component count per defined coordinate code. Sparse.
+     * @type {number[]}
+     */
+    #dimensions = [];
+
+    /**
+     * Component values per defined coordinate code. Sparse.
+     * @type {Float64Array[]}
+     */
+    #values = [];
+
+    /**
+     * Total: a switch exists for every code, whether or not anything has touched it, and an untouched one
+     * reads up. Repeated calls for the same code return the same instance, so it is safe to hold onto.
+     *
+     * @param {number} code
+     * @returns {InputDeviceSwitch}
+     */
+    getSwitch(code) {
+        assert.isNonNegativeInteger(code, 'code');
+
+        let result = this.#switches[code];
+
+        if (result === undefined) {
+            result = new InputDeviceSwitch();
+
+            this.#switches[code] = result;
+        }
+
+        return result;
+    }
+
+    /**
+     * Declare an analog channel. Must be called before the channel is read or written.
+     *
+     * @param {number} code
+     * @param {number} dimensions component count
+     */
+    defineCoordinate(code, dimensions) {
+        assert.isNonNegativeInteger(code, 'code');
+        assert.isPositiveInteger(dimensions, 'dimensions');
+
+        this.#dimensions[code] = dimensions;
+        this.#values[code] = new Float64Array(dimensions);
+    }
+
+    /**
+     * Precondition: `code` has been passed to {@link defineCoordinate}.
+     *
+     * @param {number} code
+     * @returns {number}
+     */
+    getCoordinateDimensions(code) {
+        const result = this.#dimensions[code];
+
+        assert.defined(result, `dimensions for coordinate ${code}, coordinate was never defined`);
+
+        return result;
+    }
+
+    /**
+     * Precondition: `code` has been passed to {@link defineCoordinate}, and `components.length` matches the
+     * declared dimensionality.
+     *
+     * @param {number} code
+     * @param {...number} components
+     */
+    setCoordinate(code, ...components) {
+        const values = this.#values[code];
+
+        assert.defined(values, `coordinate ${code}, coordinate was never defined`);
+        assert.equal(components.length, values.length, `component count for coordinate ${code}`);
+
+        values.set(components);
+    }
+
+    /**
+     * Precondition: `code` has been passed to {@link defineCoordinate}.
+     *
+     * @param {number[]|Float64Array} result
+     * @param {number} offset
+     * @param {number} code
+     */
+    readCoordinate(result, offset, code) {
+        const values = this.#values[code];
+
+        assert.defined(values, `coordinate ${code}, coordinate was never defined`);
+
+        const n = values.length;
+        for (let i = 0; i < n; i++) {
+            result[offset + i] = values[i];
+        }
+    }
+
+    /**
+     * Release every switch and zero every coordinate. Used when a replay ends, or a scripted sequence is
+     * cancelled, so nothing is left stuck down.
+     */
+    reset() {
+        const switches = this.#switches;
+
+        for (let i = 0; i < switches.length; i++) {
+            switches[i]?.release();
+        }
+
+        const values = this.#values;
+
+        for (let i = 0; i < values.length; i++) {
+            values[i]?.fill(0);
+        }
+    }
+}

package/src/engine/input/devices/PointerCoordinates.js

@@ -1,26 +1,26 @@
-/**
- * Analog channels offered by {@link PointerDevice}.
- *
- * Values are written into serialized input bindings, so they are append-only once shipped.
- *
- * @readonly
- * @enum {number}
- */
-export const PointerCoordinates = {
-    /**
-     * Pointer position in the viewport. 2 components, absolute.
-     */
-    'position': 0,
-    /**
-     * Pointer movement since the last frame. 2 components, relative.
-     */
-    'move': 1,
-    /**
-     * Wheel movement since the last frame. 3 components, relative.
-     *
-     * Three because {@link WheelEvent} carries deltaX, deltaY and deltaZ, and {@link PointerDevice} surfaces
-     * all three. NOTE: the device reports the SIGN of each delta, so a component is -1, 0 or 1 and scroll
-     * magnitude is not available - accumulating this channel counts wheel ticks, not distance.
-     */
-    'wheel': 2
-};
+/**
+ * Analog channels offered by {@link PointerDevice}.
+ *
+ * Values are written into serialized input bindings, so they are append-only once shipped.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const PointerCoordinates = {
+    /**
+     * Pointer position in the viewport. 2 components, absolute.
+     */
+    'position': 0,
+    /**
+     * Pointer movement since the last frame. 2 components, relative.
+     */
+    'move': 1,
+    /**
+     * Wheel movement since the last frame. 3 components, relative.
+     *
+     * Three because {@link WheelEvent} carries deltaX, deltaY and deltaZ, and {@link PointerDevice} surfaces
+     * all three. NOTE: the device reports the SIGN of each delta, so a component is -1, 0 or 1 and scroll
+     * magnitude is not available - accumulating this channel counts wheel ticks, not distance.
+     */
+    'wheel': 2
+};

package/src/engine/input/devices/events/GamepadEvents.js

@@ -1,10 +1,10 @@
-/**
- * DOM event names for the Gamepad API
- * see https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API
- *
- * @enum {string}
- */
-export const GamepadEvents = {
-    Connected: "gamepadconnected",
-    Disconnected: "gamepaddisconnected"
-};
+/**
+ * DOM event names for the Gamepad API
+ * see https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API
+ *
+ * @enum {string}
+ */
+export const GamepadEvents = {
+    Connected: "gamepadconnected",
+    Disconnected: "gamepaddisconnected"
+};

package/src/engine/input/devices/gamepad/GamepadAxes.js

@@ -1,19 +1,19 @@
-/**
- * Axis indices for the "standard" gamepad mapping
- * see https://w3c.github.io/gamepad/#remapping
- *
- * Hardware frame: +x is right, +y is down. Negative values are left/up.
- *
- * That frame is kept all the way through {@link GamepadStick#value} and {@link gamepad_write_dpad_vector}.
- * Converting it into a game frame depends on the camera, so it belongs in a controller - see
- * {@link KeyboardCameraController} for the equivalent on the keyboard side.
- *
- * @readonly
- * @enum {number}
- */
-export const GamepadAxes = {
-    'left_stick_x': 0,
-    'left_stick_y': 1,
-    'right_stick_x': 2,
-    'right_stick_y': 3
-};
+/**
+ * Axis indices for the "standard" gamepad mapping
+ * see https://w3c.github.io/gamepad/#remapping
+ *
+ * Hardware frame: +x is right, +y is down. Negative values are left/up.
+ *
+ * That frame is kept all the way through {@link GamepadStick#value} and {@link gamepad_write_dpad_vector}.
+ * Converting it into a game frame depends on the camera, so it belongs in a controller - see
+ * {@link KeyboardCameraController} for the equivalent on the keyboard side.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const GamepadAxes = {
+    'left_stick_x': 0,
+    'left_stick_y': 1,
+    'right_stick_x': 2,
+    'right_stick_y': 3
+};

package/src/engine/input/devices/gamepad/GamepadButtons.js

@@ -1,29 +1,29 @@
-/**
- * Button indices for the "standard" gamepad mapping
- * see https://w3c.github.io/gamepad/#remapping
- *
- * Names of face buttons (a/b/x/y) follow the Xbox controller layout:
- *      a = bottom, b = right, x = left, y = top
- *
- * @readonly
- * @enum {number}
- */
-export const GamepadButtons = {
-    'a': 0,
-    'b': 1,
-    'x': 2,
-    'y': 3,
-    'left_bumper': 4,
-    'right_bumper': 5,
-    'left_trigger': 6,
-    'right_trigger': 7,
-    'back': 8,
-    'start': 9,
-    'left_stick': 10,
-    'right_stick': 11,
-    'dpad_up': 12,
-    'dpad_down': 13,
-    'dpad_left': 14,
-    'dpad_right': 15,
-    'home': 16
-};
+/**
+ * Button indices for the "standard" gamepad mapping
+ * see https://w3c.github.io/gamepad/#remapping
+ *
+ * Names of face buttons (a/b/x/y) follow the Xbox controller layout:
+ *      a = bottom, b = right, x = left, y = top
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const GamepadButtons = {
+    'a': 0,
+    'b': 1,
+    'x': 2,
+    'y': 3,
+    'left_bumper': 4,
+    'right_bumper': 5,
+    'left_trigger': 6,
+    'right_trigger': 7,
+    'back': 8,
+    'start': 9,
+    'left_stick': 10,
+    'right_stick': 11,
+    'dpad_up': 12,
+    'dpad_down': 13,
+    'dpad_left': 14,
+    'dpad_right': 15,
+    'home': 16
+};

package/src/engine/input/devices/gamepad/GamepadCoordinates.js

@@ -1,17 +1,17 @@
-/**
- * Analog channels offered by {@link GamepadHandle}, each of 2 components in the hardware frame
- * (+x right, +y down - see {@link GamepadAxes}).
- *
- * The D-pad is a coordinate as well as four buttons: {@link gamepad_write_dpad_vector} is the existing
- * analog view of it, and treating it as a channel lets one binding serve a stick and a D-pad.
- *
- * Values are written into serialized input bindings, so they are append-only once shipped.
- *
- * @readonly
- * @enum {number}
- */
-export const GamepadCoordinates = {
-    'left_stick': 0,
-    'right_stick': 1,
-    'dpad': 2
-};
+/**
+ * Analog channels offered by {@link GamepadHandle}, each of 2 components in the hardware frame
+ * (+x right, +y down - see {@link GamepadAxes}).
+ *
+ * The D-pad is a coordinate as well as four buttons: {@link gamepad_write_dpad_vector} is the existing
+ * analog view of it, and treating it as a channel lets one binding serve a stick and a D-pad.
+ *
+ * Values are written into serialized input bindings, so they are append-only once shipped.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const GamepadCoordinates = {
+    'left_stick': 0,
+    'right_stick': 1,
+    'dpad': 2
+};