@woosh/meep-engine 2.165.6 → 2.165.7

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

@@ -0,0 +1,92 @@
+/**
+ * Number of consecutive samples examined as one candidate rest window.
+ * At animation-frame rate this is roughly one second.
+ * @readonly
+ * @type {number}
+ */
+export const REST_SAMPLE_COUNT: number;
+/**
+ * A window containing any sample further than this from the origin is not a plausible rest position.
+ *
+ * Deliberately tight, and tighter than the drift seen on the worst hardware. Two reasons.
+ *
+ * A large steady deflection is more likely to be a player holding the stick than a stick resting there, and
+ * the two cannot be told apart from a single window. This bound is what caps the damage when we guess wrong:
+ * a wrongly learned center can be no further out than this, which puts the resulting phantom deflection below
+ * any usable gameplay dead zone, so it stays invisible until it is superseded.
+ *
+ * And the case we would lose by being tight is the case that needs us least. Auto-calibration earns its keep
+ * on small drift, which sits under a gameplay dead zone yet still causes slow creep in anything with a tight
+ * one. Drift worse than this bound is already absorbed by any sane gameplay dead zone - XInput ships 0.24 -
+ * and is a pad heading either for replacement or for a calibration written from a settings screen.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const REST_CANDIDATE_MAX: number;
+/**
+ * A window whose per-axis spread exceeds this is the stick being moved or held, not resting.
+ *
+ * This is the main defence against learning a held position as the rest position. A held stick carries the
+ * hand's tremor, a settled one carries only sensor noise, and the two differ by roughly an order of magnitude.
+ * The bound sits between them, which costs an unusually noisy stick its calibration - an acceptable trade,
+ * since failing to calibrate leaves an exact passthrough while calibrating wrongly injects phantom deflection.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const REST_SPREAD_MAX: number;
+/**
+ * Scales the robust dispersion estimate into a radius that covers essentially all resting samples.
+ * @readonly
+ * @type {number}
+ */
+export const NOISE_RADIUS_DEVIATIONS: number;
+/**
+ * Largest noise radius that can be produced by a window that passed {@link REST_SPREAD_MAX}.
+ *
+ * Not enforced anywhere, the spread bound already constrains the result structurally. Stated so that a change
+ * to the bounds is visibly a change to how much range calibration can consume.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const NOISE_RADIUS_MAX: number;
+/**
+ * Learns where a stick rests and how much it wanders while resting.
+ *
+ * Runs continuously and unattended. Windows are only accepted while the stick is actually still, so an
+ * actively-used stick simply never produces a candidate, and no wizard or calibration screen is required.
+ *
+ * A stick cannot be told from a single window whether it is resting or being held, both look steady. The
+ * bounds are therefore biased hard towards rejection, and a wrong estimate is self-correcting: only a rest
+ * position closer to the origin than the accepted one is ever adopted, so releasing the stick supersedes it.
+ * A player parked at a small steady deflection for a full second can still poison the estimate until they let
+ * go, bounded by {@link REST_CANDIDATE_MAX}.
+ *
+ * Robust statistics throughout: the center is a median rather than a mean, because one spike shifts a
+ * 60-sample mean by 1.7% of its amplitude and shifts the median by nothing, and the dispersion is a median
+ * absolute deviation rather than a high quantile, because a quantile computed from 60 samples is dominated by
+ * the very tail we are trying not to fit.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GamepadStickCalibrator {
+    /**
+     * Feed one raw sample. Adopts a new estimate into the calibration whenever a window qualifies.
+     *
+     * @param {GamepadStickCalibration} calibration written when a window is accepted
+     * @param {number} x raw axis value
+     * @param {number} y raw axis value
+     * @returns {void}
+     */
+    sample(calibration: GamepadStickCalibration, x: number, y: number): void;
+    /**
+     * Discard the current window and the accepted estimate, learning starts over.
+     * @returns {void}
+     */
+    reset(): void;
+    #private;
+}
+//# sourceMappingURL=GamepadStickCalibrator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GamepadStickCalibrator.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/gamepad/GamepadStickCalibrator.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,gCAFU,MAAM,CAEoB;AAEpC;;;;;;;;;;;;;;;;;GAiBG;AACH,iCAFU,MAAM,CAEuB;AAEvC;;;;;;;;;;GAUG;AACH,8BAFU,MAAM,CAEqB;AAErC;;;;GAIG;AACH,sCAFU,MAAM,CAEyB;AAEzC;;;;;;;;GAQG;AACH,+BAFU,MAAM,CAE6E;AAyB7F;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAwCI;;;;;;;OAOG;IACH,gDAJW,MAAM,KACN,MAAM,GACJ,IAAI,CAiBhB;IAED;;;OAGG;IACH,SAFa,IAAI,CAKhB;;CA2EJ"}

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

@@ -0,0 +1,250 @@
+/**
+ * Number of consecutive samples examined as one candidate rest window.
+ * At animation-frame rate this is roughly one second.
+ * @readonly
+ * @type {number}
+ */
+export const REST_SAMPLE_COUNT = 60;
+
+/**
+ * A window containing any sample further than this from the origin is not a plausible rest position.
+ *
+ * Deliberately tight, and tighter than the drift seen on the worst hardware. Two reasons.
+ *
+ * A large steady deflection is more likely to be a player holding the stick than a stick resting there, and
+ * the two cannot be told apart from a single window. This bound is what caps the damage when we guess wrong:
+ * a wrongly learned center can be no further out than this, which puts the resulting phantom deflection below
+ * any usable gameplay dead zone, so it stays invisible until it is superseded.
+ *
+ * And the case we would lose by being tight is the case that needs us least. Auto-calibration earns its keep
+ * on small drift, which sits under a gameplay dead zone yet still causes slow creep in anything with a tight
+ * one. Drift worse than this bound is already absorbed by any sane gameplay dead zone - XInput ships 0.24 -
+ * and is a pad heading either for replacement or for a calibration written from a settings screen.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const REST_CANDIDATE_MAX = 0.08;
+
+/**
+ * A window whose per-axis spread exceeds this is the stick being moved or held, not resting.
+ *
+ * This is the main defence against learning a held position as the rest position. A held stick carries the
+ * hand's tremor, a settled one carries only sensor noise, and the two differ by roughly an order of magnitude.
+ * The bound sits between them, which costs an unusually noisy stick its calibration - an acceptable trade,
+ * since failing to calibrate leaves an exact passthrough while calibrating wrongly injects phantom deflection.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const REST_SPREAD_MAX = 0.015;
+
+/**
+ * Scales the robust dispersion estimate into a radius that covers essentially all resting samples.
+ * @readonly
+ * @type {number}
+ */
+export const NOISE_RADIUS_DEVIATIONS = 4;
+
+/**
+ * Largest noise radius that can be produced by a window that passed {@link REST_SPREAD_MAX}.
+ *
+ * Not enforced anywhere, the spread bound already constrains the result structurally. Stated so that a change
+ * to the bounds is visibly a change to how much range calibration can consume.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const NOISE_RADIUS_MAX = REST_SPREAD_MAX * Math.SQRT2 * (1 + NOISE_RADIUS_DEVIATIONS);
+
+/**
+ * Median of a full sample window, computed via {@link scratch} so the input is left untouched and nothing is
+ * allocated.
+ *
+ * @param {Float64Array} values exactly {@link REST_SAMPLE_COUNT} long
+ * @param {Float64Array} scratch exactly {@link REST_SAMPLE_COUNT} long
+ * @returns {number}
+ */
+function median(values, scratch) {
+    scratch.set(values);
+
+    // typed array sort is numeric ascending
+    scratch.sort();
+
+    const middle = REST_SAMPLE_COUNT >> 1;
+
+    if ((REST_SAMPLE_COUNT & 1) === 1) {
+        return scratch[middle];
+    }
+
+    return (scratch[middle - 1] + scratch[middle]) * 0.5;
+}
+
+/**
+ * Learns where a stick rests and how much it wanders while resting.
+ *
+ * Runs continuously and unattended. Windows are only accepted while the stick is actually still, so an
+ * actively-used stick simply never produces a candidate, and no wizard or calibration screen is required.
+ *
+ * A stick cannot be told from a single window whether it is resting or being held, both look steady. The
+ * bounds are therefore biased hard towards rejection, and a wrong estimate is self-correcting: only a rest
+ * position closer to the origin than the accepted one is ever adopted, so releasing the stick supersedes it.
+ * A player parked at a small steady deflection for a full second can still poison the estimate until they let
+ * go, bounded by {@link REST_CANDIDATE_MAX}.
+ *
+ * Robust statistics throughout: the center is a median rather than a mean, because one spike shifts a
+ * 60-sample mean by 1.7% of its amplitude and shifts the median by nothing, and the dispersion is a median
+ * absolute deviation rather than a high quantile, because a quantile computed from 60 samples is dominated by
+ * the very tail we are trying not to fit.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GamepadStickCalibrator {
+
+    /**
+     * @type {Float64Array}
+     */
+    #samplesX = new Float64Array(REST_SAMPLE_COUNT);
+
+    /**
+     * @type {Float64Array}
+     */
+    #samplesY = new Float64Array(REST_SAMPLE_COUNT);
+
+    /**
+     * Scratch space for distances of the current window from its own center
+     * @type {Float64Array}
+     */
+    #distances = new Float64Array(REST_SAMPLE_COUNT);
+
+    /**
+     * Scratch space for median computation
+     * @type {Float64Array}
+     */
+    #scratch = new Float64Array(REST_SAMPLE_COUNT);
+
+    /**
+     * @type {number}
+     */
+    #count = 0;
+
+    /**
+     * Magnitude of the accepted center, or -1 when nothing has been accepted yet.
+     * A window is only adopted if it rests closer to the origin than what we already have, which makes a bad
+     * estimate self-correcting: a stick that was being held when sampling started is superseded the moment it
+     * is released. The trade is that drift growing within a single session is not followed, which is fine -
+     * that is a wear process measured in weeks, and calibration restarts whenever the pad reconnects.
+     *
+     * @type {number}
+     */
+    #acceptedMagnitude = -1;
+
+    /**
+     * Feed one raw sample. Adopts a new estimate into the calibration whenever a window qualifies.
+     *
+     * @param {GamepadStickCalibration} calibration written when a window is accepted
+     * @param {number} x raw axis value
+     * @param {number} y raw axis value
+     * @returns {void}
+     */
+    sample(calibration, x, y) {
+        const i = this.#count;
+
+        this.#samplesX[i] = x;
+        this.#samplesY[i] = y;
+
+        this.#count = i + 1;
+
+        if (this.#count < REST_SAMPLE_COUNT) {
+            return;
+        }
+
+        this.#count = 0;
+
+        this.#evaluateWindow(calibration);
+    }
+
+    /**
+     * Discard the current window and the accepted estimate, learning starts over.
+     * @returns {void}
+     */
+    reset() {
+        this.#count = 0;
+        this.#acceptedMagnitude = -1;
+    }
+
+    /**
+     *
+     * @param {GamepadStickCalibration} calibration
+     */
+    #evaluateWindow(calibration) {
+        const samplesX = this.#samplesX;
+        const samplesY = this.#samplesY;
+
+        let minX = samplesX[0];
+        let maxX = minX;
+        let minY = samplesY[0];
+        let maxY = minY;
+
+        for (let i = 0; i < REST_SAMPLE_COUNT; i++) {
+            const x = samplesX[i];
+            const y = samplesY[i];
+
+            if (x * x + y * y > REST_CANDIDATE_MAX * REST_CANDIDATE_MAX) {
+                // too far out to be a rest position
+                return;
+            }
+
+            if (x < minX) {
+                minX = x;
+            } else if (x > maxX) {
+                maxX = x;
+            }
+
+            if (y < minY) {
+                minY = y;
+            } else if (y > maxY) {
+                maxY = y;
+            }
+        }
+
+        if (maxX - minX > REST_SPREAD_MAX || maxY - minY > REST_SPREAD_MAX) {
+            // the stick is being moved, this is not a rest window
+            return;
+        }
+
+        const scratch = this.#scratch;
+
+        const centerX = median(samplesX, scratch);
+        const centerY = median(samplesY, scratch);
+
+        const magnitude = Math.sqrt(centerX * centerX + centerY * centerY);
+
+        if (this.#acceptedMagnitude !== -1 && magnitude >= this.#acceptedMagnitude) {
+            // we already know of a rest position closer to the origin
+            return;
+        }
+
+        const distances = this.#distances;
+
+        for (let i = 0; i < REST_SAMPLE_COUNT; i++) {
+            const dx = samplesX[i] - centerX;
+            const dy = samplesY[i] - centerY;
+
+            distances[i] = Math.sqrt(dx * dx + dy * dy);
+        }
+
+        const medianDistance = median(distances, scratch);
+
+        for (let i = 0; i < REST_SAMPLE_COUNT; i++) {
+            distances[i] = Math.abs(distances[i] - medianDistance);
+        }
+
+        const absoluteDeviation = median(distances, scratch);
+
+        calibration.set(centerX, centerY, medianDistance + NOISE_RADIUS_DEVIATIONS * absoluteDeviation);
+
+        this.#acceptedMagnitude = magnitude;
+    }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Analog view of the D-pad, for consumers that drive the same thing from a stick and a D-pad.
+ *
+ * Written in the hardware frame ({@link GamepadAxes}: +x is right, +y is down), matching
+ * {@link GamepadStick#value}, so the two compose without the caller tracking which of them is flipped.
+ * Components are exactly -1, 0 or 1, a full diagonal is (1,1) and has magnitude sqrt(2) - normalize at the call
+ * site if unit length is wanted.
+ *
+ * How the two views combine is game policy and stays with the caller: whether the stick wins, whether they sum,
+ * whether a held D-pad suppresses stick drift.
+ *
+ * @param {Vector2} result
+ * @param {GamepadHandle} pad
+ * @returns {void}
+ */
+export function gamepad_write_dpad_vector(result: Vector2, pad: GamepadHandle): void;
+//# sourceMappingURL=gamepad_write_dpad_vector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gamepad_write_dpad_vector.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/gamepad/gamepad_write_dpad_vector.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,gFAFa,IAAI,CAchB"}

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

@@ -0,0 +1,30 @@
+import { GamepadButtons } from "./GamepadButtons.js";
+
+/**
+ * Analog view of the D-pad, for consumers that drive the same thing from a stick and a D-pad.
+ *
+ * Written in the hardware frame ({@link GamepadAxes}: +x is right, +y is down), matching
+ * {@link GamepadStick#value}, so the two compose without the caller tracking which of them is flipped.
+ * Components are exactly -1, 0 or 1, a full diagonal is (1,1) and has magnitude sqrt(2) - normalize at the call
+ * site if unit length is wanted.
+ *
+ * How the two views combine is game policy and stays with the caller: whether the stick wins, whether they sum,
+ * whether a held D-pad suppresses stick drift.
+ *
+ * @param {Vector2} result
+ * @param {GamepadHandle} pad
+ * @returns {void}
+ */
+export function gamepad_write_dpad_vector(result, pad) {
+    const buttons = pad.buttons;
+
+    const up = buttons[GamepadButtons.dpad_up].is_down;
+    const down = buttons[GamepadButtons.dpad_down].is_down;
+    const left = buttons[GamepadButtons.dpad_left].is_down;
+    const right = buttons[GamepadButtons.dpad_right].is_down;
+
+    result.set(
+        (right ? 1 : 0) - (left ? 1 : 0),
+        (down ? 1 : 0) - (up ? 1 : 0)
+    );
+}

package/src/engine/input/devices/touch/TouchDevice.d.ts

@@ -9,9 +9,9 @@ export class TouchDevice {
      * @readonly
      */
     readonly on: {
-        pinch: Signal<any, any, any, any, any, any, any, any>;
-        pinchStart: Signal<any, any, any, any, any, any, any, any>;
-        pinchEnd: Signal<any, any, any, any, any, any, any, any>;
+        pinch: Signal;
+        pinchStart: Signal;
+        pinchEnd: Signal;
     };
     #private;
 }

package/src/engine/input/ecs/components/Input.d.ts

@@ -1,6 +1,49 @@
-import {InputBinding} from "../ism/InputBinding";
-import List from "../../../../core/collection/list/List";
-
-export class Input {
-    bindings: List<InputBinding>
-}
+export class Input {
+    /**
+     * @readonly
+     * @type {List<InputBinding>}
+     */
+    readonly bindings: List<InputBinding>;
+    /**
+     *
+     * @param {Input} other
+     * @returns {boolean}
+     */
+    equals(other: Input): boolean;
+    /**
+     *
+     * @return {number}
+     */
+    hash(): number;
+    /**
+     *
+     * @param {string} path
+     * @param {string} event
+     * @returns {boolean}
+     */
+    exists(path: string, event: string): boolean;
+    /**
+     *
+     * @param {string} path
+     * @param {string} event
+     * @returns {boolean}
+     */
+    bind(path: string, event: string): boolean;
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     */
+    toBinaryBuffer(buffer: BinaryBuffer): void;
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     */
+    fromBinaryBuffer(buffer: BinaryBuffer): void;
+}
+export namespace Input {
+    let typeName: string;
+    let serializable: boolean;
+}
+import List from "../../../../core/collection/list/List.js";
+import { InputBinding } from "../ism/InputBinding.js";
+//# sourceMappingURL=Input.d.ts.map

package/src/engine/input/ecs/components/InputController.d.ts

@@ -1,3 +1,33 @@
-export default class InputController {
-
-}
+export default InputController;
+declare class InputController {
+    /**
+     *
+     * @param {Array} bindings
+     */
+    static from(bindings: any[]): InputController;
+    /**
+     *
+     * @param {Array} [bindings]
+     * @constructor
+     */
+    constructor(bindings?: any[]);
+    mapping: List<any>;
+    on: {
+        unlinked: Signal;
+    };
+    /**
+     *
+     * @param {string} path
+     * @param {function} action
+     * @returns {InputBinding}
+     */
+    bind(path: string, action: Function): InputBinding;
+}
+declare namespace InputController {
+    let typeName: string;
+    let serializable: boolean;
+}
+import List from '../../../../core/collection/list/List.js';
+import Signal from "../../../../core/events/signal/Signal.js";
+import { InputBinding } from "./InputBinding.js";
+//# sourceMappingURL=InputController.d.ts.map

package/src/engine/input/ecs/ism/InputBinding.d.ts

@@ -1,4 +1,40 @@
-export class InputBinding {
-    path: string
-    event: string
-}
+export class InputBinding {
+    /**
+     *
+     * @type {string}
+     */
+    path: string;
+    /**
+     *
+     * @type {string}
+     */
+    event: string;
+    /**
+     *
+     * @param {string} path
+     * @param {string} event
+     */
+    set(path: string, event: string): void;
+    /**
+     *
+     * @param {InputBinding} other
+     * @returns {boolean}
+     */
+    equals(other: InputBinding): boolean;
+    /**
+     *
+     * @return {number}
+     */
+    hash(): number;
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     */
+    toBinaryBuffer(buffer: BinaryBuffer): void;
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     */
+    fromBinaryBuffer(buffer: BinaryBuffer): void;
+}
+//# sourceMappingURL=InputBinding.d.ts.map

package/src/engine/input/ecs/systems/InputControllerSystem.d.ts

@@ -1,6 +1,28 @@
-import {System} from "../../../ecs/System";
-import {InputController} from "../components/InputController";
-
-export default class InputControllerSystem extends System<InputController> {
-    constructor(devices: any)
-}
+export default InputControllerSystem;
+/**
+ * Prefer to use {@link InputSystem} instead
+ */
+declare class InputControllerSystem extends System<any> {
+    constructor(devices: any);
+    enabled: ObservedValue;
+    dependencies: (typeof InputController)[];
+    devices: any;
+    startup(entityManager: any): Promise<void>;
+    proxies: {};
+    /**
+     *
+     * @param {InputController} component
+     * @param entity
+     */
+    link(component: InputController, entity: any): void;
+    /**
+     *
+     * @param {InputController} component
+     * @param entity
+     */
+    unlink(component: InputController, entity: any): void;
+}
+import { System } from "../../../ecs/System.js";
+import ObservedValue from "../../../../core/model/ObservedValue.js";
+import InputController from "../components/InputController.js";
+//# sourceMappingURL=InputControllerSystem.d.ts.map

package/src/engine/input/ecs/systems/InputSystem.d.ts

@@ -1,6 +1,59 @@
-import {System} from "../../../ecs/System";
-import {Input} from "../components/Input";
-
-export class InputSystem extends System<Input> {
-    constructor(devices: any)
-}
+export class InputSystem extends System<any> {
+    constructor(devices: any);
+    dependencies: (typeof Input)[];
+    devices: any;
+    /**
+     *
+     * @type {Map<number,BindingLink[]>}
+     */
+    links: Map<number, BindingLink[]>;
+    /**
+     *
+     * @param {Input} component
+     * @param entity
+     */
+    link(component: Input, entity: any): void;
+    /**
+     *
+     * @param {Input} component
+     * @param entity
+     */
+    unlink(component: Input, entity: any): void;
+}
+import { System } from "../../../ecs/System.js";
+import { Input } from "../components/Input.js";
+declare class BindingLink {
+    /**
+     *
+     * @param {InputBinding} binding
+     * @param {EntityComponentDataset} dataset
+     * @param {number} entity
+     * @param {object} devices
+     */
+    constructor(binding: InputBinding, dataset: EntityComponentDataset, entity: number, devices: object);
+    /**
+     *
+     * @type {InputBinding}
+     */
+    binding: InputBinding;
+    /**
+     *
+     * @type {EntityComponentDataset}
+     */
+    dataset: EntityComponentDataset;
+    /**
+     *
+     * @type {number}
+     */
+    entity: number;
+    devices: any;
+    /**
+     *
+     * @param {*} eventData
+     */
+    emit(eventData: any): void;
+    link(): void;
+    unlink(): void;
+}
+export {};
+//# sourceMappingURL=InputSystem.d.ts.map