@woosh/meep-engine 2.158.0 → 2.160.0

package/src/engine/graphics/ecs/path/tube/build/fix_shape_normal_order.d.ts

@@ -1,8 +1,14 @@
 /**
- * Depending on the direction in which shape winds, normals of the generated geometry faces might end up flipped,
- * so we pre-process the shape to avoid that here
- * @param {number[]|Float32Array} shape
- * @returns {Float32Array}
+ * Canonicalise a profile's winding so the generated tube faces point OUTWARD
+ * regardless of the order the caller authored the shape in. The tube builder's
+ * face index pattern is fixed, so the outward/inward orientation is decided
+ * purely by the shape's winding direction; we force a single signed-area sign
+ * here. (Empirically, clockwise — negative signed area — yields outward faces
+ * for the builder's index order.)
+ *
+ * @param {number[]|Float32Array} shape  flat [x0,y0, x1,y1, ...]
+ * @returns {number[]|Float32Array} the shape wound for outward faces (input if
+ *          already correct, otherwise a reversed copy)
  */
-export function fix_shape_normal_order(shape: number[] | Float32Array): Float32Array;
+export function fix_shape_normal_order(shape: number[] | Float32Array): number[] | Float32Array;
 //# sourceMappingURL=fix_shape_normal_order.d.ts.map

package/src/engine/graphics/ecs/path/tube/build/fix_shape_normal_order.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fix_shape_normal_order.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/graphics/ecs/path/tube/build/fix_shape_normal_order.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,8CAHW,MAAM,EAAE,GAAC,YAAY,GACnB,YAAY,CAsCxB"}
+{"version":3,"file":"fix_shape_normal_order.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/graphics/ecs/path/tube/build/fix_shape_normal_order.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,8CAJW,MAAM,EAAE,GAAC,YAAY,GACnB,MAAM,EAAE,GAAC,YAAY,CA6BjC"}

package/src/engine/graphics/ecs/path/tube/build/fix_shape_normal_order.js

@@ -1,45 +1,39 @@
-import { v2_bearing_angle_towards } from "../../../../../../core/geom/vec2/v2_bearing_angle_towards.js";
-
 /**
- * Depending on the direction in which shape winds, normals of the generated geometry faces might end up flipped,
- * so we pre-process the shape to avoid that here
- * @param {number[]|Float32Array} shape
- * @returns {Float32Array}
+ * Canonicalise a profile's winding so the generated tube faces point OUTWARD
+ * regardless of the order the caller authored the shape in. The tube builder's
+ * face index pattern is fixed, so the outward/inward orientation is decided
+ * purely by the shape's winding direction; we force a single signed-area sign
+ * here. (Empirically, clockwise — negative signed area — yields outward faces
+ * for the builder's index order.)
+ *
+ * @param {number[]|Float32Array} shape  flat [x0,y0, x1,y1, ...]
+ * @returns {number[]|Float32Array} the shape wound for outward faces (input if
+ *          already correct, otherwise a reversed copy)
  */
 export function fix_shape_normal_order(shape) {
-    const shape_array_length = shape.length;
-
-    if (shape_array_length <= 2) {
-        // less than 2 points in the shape
+    const n = shape.length / 2;
+    if (n < 3) {
         return shape;
     }
 
-    // compute initial direction
-    const x0 = shape[0];
-    const y0 = shape[1];
-    const x1 = shape[2];
-    const y1 = shape[3];
-
-    const angle = v2_bearing_angle_towards(x0, y0, x1, y1);
+    // signed area (shoelace); > 0 is counter-clockwise
+    let area2 = 0;
+    for (let i = 0; i < n; i++) {
+        const j = (i + 1) % n;
+        area2 += shape[i * 2] * shape[j * 2 + 1] - shape[j * 2] * shape[i * 2 + 1];
+    }
 
-    if (angle > Math.PI) {
-        // order is fine
+    if (area2 <= 0) {
+        // already clockwise — the orientation the builder wants
         return shape;
     }
 
-    // reverse order
-    const reversed = new Float32Array(shape_array_length);
-
-    const n = shape_array_length / 2;
-
+    // reverse to clockwise
+    const reversed = new Float32Array(shape.length);
     for (let i = 0; i < n; i++) {
-        const i2 = i * 2;
-
-        const j2 = (n - (i + 1)) * 2;
-
-        reversed[i2] = shape[j2];
-        reversed[i2 + 1] = shape[j2 + 1];
+        const j = n - 1 - i;
+        reversed[i * 2] = shape[j * 2];
+        reversed[i * 2 + 1] = shape[j * 2 + 1];
     }
-
     return reversed;
 }

package/src/engine/input/devices/GamepadDevice.d.ts

@@ -0,0 +1,26 @@
+import Signal from "../../../core/events/signal/Signal";
+import {GamepadHandle} from "./gamepad/GamepadHandle";
+
+export class GamepadDevice {
+    constructor()
+
+    start(): void
+
+    stop(): void
+
+    poll(): void
+
+    deadZone: number
+
+    readonly pads: GamepadHandle[]
+
+    readonly main: GamepadHandle | undefined
+
+    readonly on: {
+        connected: Signal<GamepadHandle>,
+        disconnected: Signal<GamepadHandle>,
+        down: Signal<number /*buttonIndex*/, GamepadHandle>,
+        up: Signal<number /*buttonIndex*/, GamepadHandle>,
+        axis: Signal<number /*axisIndex*/, number /*value*/, GamepadHandle>
+    }
+}

package/src/engine/input/devices/GamepadDevice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GamepadDevice.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/GamepadDevice.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH;IAEI;;OAEG;IACH;QACI;;;WAGG;mBADO,OAAO,aAAa,CAAC;QAG/B;;;WAGG;sBADO,OAAO,aAAa,CAAC;QAG/B;;;WAGG;cADO,OAAO,MAAM,EAAE,aAAa,CAAC;QAGvC;;;WAGG;YADO,OAAO,MAAM,EAAE,aAAa,CAAC;QAGvC;;;WAGG;cADO,OAAO,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC;MAGjD;IAEF;;;;;;OAMG;IACH,eAFU,aAAa,EAAE,CAEf;IAEV;;;;OAIG;IACH,UAFU,MAAM,CAED;IAEf;;;OAGG;IACH,kBAAkB;IAQlB;;;;;OAKG;IACH,0BAaC;IAmFD;;;OAGG;IACH,aA+BC;IAQD;;;OAGG;IACH,SAFa,IAAI,CAmBhB;IAED;;;OAGG;IACH,QAFa,IAAI,CA6BhB;;CACJ;mBAvRkB,uCAAuC;8BAE5B,4BAA4B"}

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

@@ -0,0 +1,280 @@
+import Signal from "../../../core/events/signal/Signal.js";
+import { GamepadEvents } from "./events/GamepadEvents.js";
+import { GamepadHandle } from "./gamepad/GamepadHandle.js";
+
+/**
+ * Provides gamepad input on top of the Gamepad API.
+ * see https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API
+ *
+ * Unlike mouse/keyboard, the Gamepad API offers no events for button/axis state changes, state must be polled instead.
+ * While running, the device polls automatically once per animation frame. {@link GamepadDevice#poll} can also be
+ * invoked manually for finer control (e.g. from a fixed-rate simulation loop).
+ *
+ * NOTE: when a gamepad disconnects, any "pressed" buttons will be automatically released with appropriate signals,
+ * preventing inputs from getting "stuck".
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GamepadDevice {
+
+    /**
+     * @readonly
+     */
+    on = {
+        /**
+         * Fires when a gamepad is connected
+         * @type {Signal<GamepadHandle>}
+         */
+        connected: new Signal(),
+        /**
+         * Fires when a gamepad is disconnected
+         * @type {Signal<GamepadHandle>}
+         */
+        disconnected: new Signal(),
+        /**
+         * Fires when any button on any gamepad is pressed, dispatches (buttonIndex, pad)
+         * @type {Signal<number, GamepadHandle>}
+         */
+        down: new Signal(),
+        /**
+         * Fires when any button on any gamepad is released, dispatches (buttonIndex, pad)
+         * @type {Signal<number, GamepadHandle>}
+         */
+        up: new Signal(),
+        /**
+         * Fires when any axis on any gamepad changes, dispatches (axisIndex, value, pad)
+         * @type {Signal<number, number, GamepadHandle>}
+         */
+        axis: new Signal()
+    };
+
+    /**
+     * Known gamepads, indexed by {@link Gamepad.index}. May be sparse.
+     * Handles are retained after disconnection and re-used on re-connection, so they are safe to hold references to.
+     *
+     * @readonly
+     * @type {GamepadHandle[]}
+     */
+    pads = [];
+
+    /**
+     * Axis values with magnitude below this threshold are treated as 0.
+     * Compensates for analog stick noise/drift around the neutral position.
+     * @type {number}
+     */
+    deadZone = 0.1;
+
+    /**
+     * @private
+     * @type {boolean}
+     */
+    isRunning = false;
+
+    /**
+     *
+     * @type {number}
+     */
+    #animationFrameId = -1;
+
+    /**
+     * First connected gamepad, or undefined if none are connected.
+     * Convenience accessor for the common single-player case.
+     *
+     * @returns {GamepadHandle|undefined}
+     */
+    get main() {
+        const pads = this.pads;
+        const n = pads.length;
+
+        for (let i = 0; i < n; i++) {
+            const pad = pads[i];
+
+            if (pad !== undefined && pad.connected) {
+                return pad;
+            }
+        }
+
+        return undefined;
+    }
+
+    /**
+     * Returns handle for a given pad index, creating it if it doesn't exist yet
+     *
+     * @param {number} index
+     * @returns {GamepadHandle}
+     */
+    #obtainHandle(index) {
+        let pad = this.pads[index];
+
+        if (pad === undefined) {
+            pad = new GamepadHandle();
+            pad.index = index;
+
+            // forward pad signals to device-level signals
+            pad.on.down.add(buttonIndex => this.on.down.send2(buttonIndex, pad));
+            pad.on.up.add(buttonIndex => this.on.up.send2(buttonIndex, pad));
+            pad.on.axis.add((axisIndex, value) => this.on.axis.send3(axisIndex, value, pad));
+
+            this.pads[index] = pad;
+        }
+
+        return pad;
+    }
+
+    /**
+     *
+     * @param {Gamepad} gamepad native gamepad object
+     * @returns {GamepadHandle}
+     */
+    #connect(gamepad) {
+        const pad = this.#obtainHandle(gamepad.index);
+
+        pad.update(gamepad, this.deadZone);
+
+        if (!pad.connected) {
+            pad.connected = true;
+
+            this.on.connected.send1(pad);
+        }
+
+        return pad;
+    }
+
+    /**
+     *
+     * @param {GamepadHandle} pad
+     */
+    #disconnect(pad) {
+        if (!pad.connected) {
+            // already disconnected
+            return;
+        }
+
+        pad.connected = false;
+
+        // release everything to avoid stuck inputs
+        pad.reset();
+
+        this.on.disconnected.send1(pad);
+    }
+
+    /**
+     *
+     * @param {GamepadEvent} event
+     */
+    #handleConnectedEvent = (event) => {
+        this.#connect(event.gamepad);
+    }
+
+    /**
+     *
+     * @param {GamepadEvent} event
+     */
+    #handleDisconnectedEvent = (event) => {
+        const pad = this.pads[event.gamepad.index];
+
+        if (pad !== undefined) {
+            this.#disconnect(pad);
+        }
+    }
+
+    /**
+     * Read current state of all gamepads and dispatch signals for any changes.
+     * Invoked automatically once per animation frame while the device is running.
+     */
+    poll() {
+        if (typeof navigator === "undefined" || typeof navigator.getGamepads !== "function") {
+            // Gamepad API is not supported in this environment
+            return;
+        }
+
+        const gamepads = navigator.getGamepads();
+        const n = gamepads.length;
+
+        for (let i = 0; i < n; i++) {
+            const gamepad = gamepads[i];
+
+            if (gamepad === null || gamepad === undefined) {
+                // empty slot, disconnect matching handle if there is one
+                const pad = this.pads[i];
+
+                if (pad !== undefined) {
+                    this.#disconnect(pad);
+                }
+
+                continue;
+            }
+
+            /*
+            Some browsers only dispatch "gamepadconnected" after a button is pressed,
+            so connection is detected during polling as well
+             */
+            const pad = this.#connect(gamepad);
+
+            pad.update(gamepad, this.deadZone);
+        }
+    }
+
+    #update = () => {
+        this.poll();
+
+        this.#animationFrameId = requestAnimationFrame(this.#update);
+    }
+
+    /**
+     * Starts listening for gamepad connections and polling gamepad state.
+     * @returns {void}
+     */
+    start() {
+        if (this.isRunning) {
+            //already running
+            return;
+        }
+
+        this.isRunning = true;
+
+        window.addEventListener(GamepadEvents.Connected, this.#handleConnectedEvent);
+        window.addEventListener(GamepadEvents.Disconnected, this.#handleDisconnectedEvent);
+
+        // pick up gamepads that were connected before start
+        this.poll();
+
+        if (typeof requestAnimationFrame === "function") {
+            this.#animationFrameId = requestAnimationFrame(this.#update);
+        }
+    }
+
+    /**
+     * Stops listening for gamepad connections and polling gamepad state.
+     * @returns {void}
+     */
+    stop() {
+        if (!this.isRunning) {
+            //not running
+            return;
+        }
+
+        this.isRunning = false;
+
+        window.removeEventListener(GamepadEvents.Connected, this.#handleConnectedEvent);
+        window.removeEventListener(GamepadEvents.Disconnected, this.#handleDisconnectedEvent);
+
+        if (this.#animationFrameId !== -1) {
+            cancelAnimationFrame(this.#animationFrameId);
+            this.#animationFrameId = -1;
+        }
+
+        // release all buttons, as we will not be able to observe release while stopped
+        const pads = this.pads;
+        const n = pads.length;
+
+        for (let i = 0; i < n; i++) {
+            const pad = pads[i];
+
+            if (pad !== undefined) {
+                pad.reset();
+            }
+        }
+    }
+}

package/src/engine/input/devices/events/GamepadEvents.d.ts

@@ -0,0 +1,10 @@
+/**
+ * DOM event names for the Gamepad API
+ * see https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API
+ */
+export type GamepadEvents = string;
+export namespace GamepadEvents {
+    let Connected: string;
+    let Disconnected: string;
+}
+//# sourceMappingURL=GamepadEvents.d.ts.map

package/src/engine/input/devices/events/GamepadEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GamepadEvents.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/events/GamepadEvents.js"],"names":[],"mappings":";;;;4BAIU,MAAM"}

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

@@ -0,0 +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"
+};

package/src/engine/input/devices/gamepad/GamepadAxes.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Axis indices for the "standard" gamepad mapping
+ * see https://w3c.github.io/gamepad/#remapping
+ *
+ * Negative values are left/up, positive values are right/down
+ */
+export type GamepadAxes = number;
+export namespace GamepadAxes {
+    let left_stick_x: number;
+    let left_stick_y: number;
+    let right_stick_x: number;
+    let right_stick_y: number;
+}
+//# sourceMappingURL=GamepadAxes.d.ts.map

package/src/engine/input/devices/gamepad/GamepadAxes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GamepadAxes.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/gamepad/GamepadAxes.js"],"names":[],"mappings":";;;;;;0BAOU,MAAM"}

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

@@ -0,0 +1,15 @@
+/**
+ * Axis indices for the "standard" gamepad mapping
+ * see https://w3c.github.io/gamepad/#remapping
+ *
+ * Negative values are left/up, positive values are right/down
+ *
+ * @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.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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
+ */
+export type GamepadButtons = number;
+export namespace GamepadButtons {
+    let a: number;
+    let b: number;
+    let x: number;
+    let y: number;
+    let left_bumper: number;
+    let right_bumper: number;
+    let left_trigger: number;
+    let right_trigger: number;
+    let back: number;
+    let start: number;
+    let left_stick: number;
+    let right_stick: number;
+    let dpad_up: number;
+    let dpad_down: number;
+    let dpad_left: number;
+    let dpad_right: number;
+    let home: number;
+}
+//# sourceMappingURL=GamepadButtons.d.ts.map

package/src/engine/input/devices/gamepad/GamepadButtons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GamepadButtons.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/gamepad/GamepadButtons.js"],"names":[],"mappings":";;;;;;;6BAQU,MAAM"}

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

@@ -0,0 +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
+};

package/src/engine/input/devices/gamepad/GamepadHandle.d.ts

@@ -0,0 +1,29 @@
+import Signal from "../../../../core/events/signal/Signal";
+import Vector2 from "../../../../core/geom/Vector2";
+import {InputDeviceSwitch} from "../InputDeviceSwitch";
+
+export class GamepadHandle {
+    readonly index: number
+    readonly id: string
+    readonly mapping: string
+    readonly connected: boolean
+
+    readonly buttons: InputDeviceSwitch[]
+    readonly buttonValues: number[]
+    readonly axes: number[]
+
+    readonly stickLeft: Vector2
+    readonly stickRight: Vector2
+
+    getButton(index: number): InputDeviceSwitch
+
+    update(source: Gamepad, deadZone?: number): void
+
+    reset(): void
+
+    readonly on: {
+        down: Signal<number /*buttonIndex*/>,
+        up: Signal<number /*buttonIndex*/>,
+        axis: Signal<number /*axisIndex*/, number /*value*/, number /*previousValue*/>
+    }
+}

package/src/engine/input/devices/gamepad/GamepadHandle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GamepadHandle.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/gamepad/GamepadHandle.js"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH;IAEI;;;OAGG;IACH,OAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,IAFU,MAAM,CAER;IAER;;;;OAIG;IACH,SAFU,MAAM,CAEH;IAEb;;;;OAIG;IACH,WAFU,OAAO,CAEC;IAElB;;OAEG;IACH;QACI;;;WAGG;cADO,OAAO,MAAM,CAAC;QAGxB;;;WAGG;YADO,OAAO,MAAM,CAAC;QAGxB;;;WAGG;cADO,OAAO,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;MAG1C;IAEF;;;;;;;;;;OAUG;IACH,kBALU,iBAAiB,EAAE,CAKhB;IAEb;;;;;OAKG;IACH,uBAFU,MAAM,EAAE,CAEA;IAElB;;;;;OAKG;IACH,eAFU,MAAM,EAAE,CAER;IAEV;;;;OAIG;IACH,oBAFU,OAAO,CAES;IAE1B;;;;OAIG;IACH,qBAFU,OAAO,CAEU;IAE3B;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,iBAAiB,CAa7B;IAED;;;;;OAKG;IACH,eAHW,OAAO,aACP,MAAM,QAkEhB;IAED;;;OAGG;IACH,cA+BE;CACL;mBAvOkB,0CAA0C;kCAE3B,yBAAyB;oBADvC,kCAAkC"}