@woosh/meep-engine 3.35.0 → 3.37.0

package/src/engine/input/devices/xr/XRHandedness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XRHandedness.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/xr/XRHandedness.js"],"names":[],"mappings":";;;2BAGU,MAAM;AAHhB;;;;GAIG;AACH;;;;GAIG"}

package/src/engine/input/devices/xr/XRHandedness.js

@@ -0,0 +1,10 @@
+/**
+ * Native XRInputSource handedness values.
+ * @readonly
+ * @enum {string}
+ */
+export const XRHandedness = Object.freeze({
+    None: 'none',
+    Left: 'left',
+    Right: 'right'
+});

package/src/engine/input/devices/xr/XRInputAction.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Observable amount of a select/squeeze action, in [0, 1]. Read {@link x} and subscribe to
+ * {@link onChanged} as with any Vector1. The device owns mutation.
+ *
+ * {@link valueSource} identifies a native button amount or an event-derived 0/1 value.
+ * {@link completed} fires on native action completion; {@link cancelled} fires when an unfinished
+ * interaction ends or is interrupted. Each interaction has at most one outcome. Amount changes alone
+ * do not complete or cancel an action.
+ */
+export class XRInputAction extends Vector1 {
+    /**
+     * Successful native action completion. Dispatches no arguments.
+     * @readonly
+     * @type {Signal}
+     */
+    readonly completed: Signal;
+    /**
+     * An unfinished interaction ended or was interrupted. Dispatches no arguments.
+     * @readonly
+     * @type {Signal}
+     */
+    readonly cancelled: Signal;
+    /**
+     * Origin of the current amount. Do not modify directly.
+     * @type {XRInputValueSource}
+     */
+    valueSource: XRInputValueSource;
+    /**
+     * Store the supplied amount and its source.
+     * @internal
+     * @param {number} [value=0]
+     * @param {XRInputValueSource} [source=XRInputValueSource.Unavailable]
+     */
+    update(value?: number, source?: XRInputValueSource): void;
+    /** @internal Called only for a native start, never inferred from the amount. */
+    begin(): void;
+    /** @internal A completion without an observed start is not replayed after a rebind/interruption. */
+    complete(): void;
+    /** @internal */
+    end(): void;
+    /** @internal Stage cancellation so the whole handle can become neutral before its notification. */
+    reset(): void;
+    /** @internal */
+    flushCancellation(): void;
+    #private;
+}
+import { Vector1 } from "../../../../core/geom/Vector1.js";
+import Signal from "../../../../core/events/signal/Signal.js";
+import { XRInputValueSource } from "./XRInputValueSource.js";
+//# sourceMappingURL=XRInputAction.d.ts.map

package/src/engine/input/devices/xr/XRInputAction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XRInputAction.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/xr/XRInputAction.js"],"names":[],"mappings":"AAgBA;;;;;;;;GAQG;AACH;IACI;;;;OAIG;IACH,oBAFU,MAAM,CAES;IAEzB;;;;OAIG;IACH,oBAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,aAFU,kBAAkB,CAEiB;IAM7C;;;;;OAKG;IACH,eAHW,MAAM,WACN,kBAAkB,QAS5B;IAED,gFAAgF;IAChF,cASC;IAED,oGAAoG;IACpG,iBAOC;IAED,gBAAgB;IAChB,YAWC;IAED,mGAAmG;IACnG,cAIC;IAED,gBAAgB;IAChB,0BAKC;;CACJ;wBAjHuB,kCAAkC;mBADvC,0CAA0C;mCAE1B,yBAAyB"}

package/src/engine/input/devices/xr/XRInputAction.js

@@ -0,0 +1,116 @@
+import { assert } from "../../../../core/assert.js";
+import Signal from "../../../../core/events/signal/Signal.js";
+import { Vector1 } from "../../../../core/geom/Vector1.js";
+import { XRInputValueSource } from "./XRInputValueSource.js";
+
+/**
+ * Native interaction lifecycle, independent of pressure.
+ * @readonly
+ * @enum {number}
+ */
+const InteractionState = {
+    Idle: 0,
+    Started: 1,
+    Completed: 2
+};
+
+/**
+ * Observable amount of a select/squeeze action, in [0, 1]. Read {@link x} and subscribe to
+ * {@link onChanged} as with any Vector1. The device owns mutation.
+ *
+ * {@link valueSource} identifies a native button amount or an event-derived 0/1 value.
+ * {@link completed} fires on native action completion; {@link cancelled} fires when an unfinished
+ * interaction ends or is interrupted. Each interaction has at most one outcome. Amount changes alone
+ * do not complete or cancel an action.
+ */
+export class XRInputAction extends Vector1 {
+    /**
+     * Successful native action completion. Dispatches no arguments.
+     * @readonly
+     * @type {Signal}
+     */
+    completed = new Signal();
+
+    /**
+     * An unfinished interaction ended or was interrupted. Dispatches no arguments.
+     * @readonly
+     * @type {Signal}
+     */
+    cancelled = new Signal();
+
+    /**
+     * Origin of the current amount. Do not modify directly.
+     * @type {XRInputValueSource}
+     */
+    valueSource = XRInputValueSource.Unavailable;
+
+    #interaction = InteractionState.Idle;
+
+    #cancelled = false;
+
+    /**
+     * Store the supplied amount and its source.
+     * @internal
+     * @param {number} [value=0]
+     * @param {XRInputValueSource} [source=XRInputValueSource.Unavailable]
+     */
+    update(value = 0, source = XRInputValueSource.Unavailable) {
+        assert.greaterThanOrEqual(value, 0, 'value >= 0');
+        assert.lessThanOrEqual(value, 1, 'value <= 1');
+        assert.enum(source, XRInputValueSource, 'source');
+
+        this.valueSource = source;
+        this.set(value);
+    }
+
+    /** @internal Called only for a native start, never inferred from the amount. */
+    begin() {
+        if (this.#interaction !== InteractionState.Idle) {
+            return;
+        }
+
+        this.#interaction = InteractionState.Started;
+        if (this.valueSource === XRInputValueSource.Action) {
+            this.set(1);
+        }
+    }
+
+    /** @internal A completion without an observed start is not replayed after a rebind/interruption. */
+    complete() {
+        if (this.#interaction !== InteractionState.Started) {
+            return;
+        }
+
+        this.#interaction = InteractionState.Completed;
+        this.completed.send0();
+    }
+
+    /** @internal */
+    end() {
+        const cancelled = this.#interaction === InteractionState.Started;
+        this.#interaction = InteractionState.Idle;
+
+        if (this.valueSource === XRInputValueSource.Action) {
+            this.set(0);
+        }
+
+        if (cancelled) {
+            this.cancelled.send0();
+        }
+    }
+
+    /** @internal Stage cancellation so the whole handle can become neutral before its notification. */
+    reset() {
+        this.#cancelled = this.#cancelled || this.#interaction === InteractionState.Started;
+        this.#interaction = InteractionState.Idle;
+        this.update();
+    }
+
+    /** @internal */
+    flushCancellation() {
+        if (this.#cancelled) {
+            this.#cancelled = false;
+            this.cancelled.send0();
+        }
+    }
+}

package/src/engine/input/devices/xr/XRInputButton.d.ts

@@ -0,0 +1,26 @@
+/**
+ * One raw GamepadButton: its amount in [0, 1] and its native pressed/touched switches.
+ * {@link pressed} is independent of {@link x}; a partially depressed trigger need not be pressed.
+ * The device owns mutation. Switches and {@link onChanged} retain their identity across source replacement.
+ */
+export class XRInputButton extends Vector1 {
+    /** @readonly */
+    readonly pressed: InputDeviceSwitch;
+    /** @readonly */
+    readonly touched: InputDeviceSwitch;
+    /**
+     * Stage binary state while updating the scalar. All numeric channels and poses are sampled before
+     * the device calls flushSwitches, so an input-map action can read the corresponding amount.
+     * @internal
+     * @param {number} [value=0]
+     * @param {boolean} [pressed=false]
+     * @param {boolean} [touched=false]
+     */
+    update(value?: number, pressed?: boolean, touched?: boolean): void;
+    /** @internal */
+    flushSwitches(): void;
+    #private;
+}
+import { Vector1 } from "../../../../core/geom/Vector1.js";
+import { InputDeviceSwitch } from "../InputDeviceSwitch.js";
+//# sourceMappingURL=XRInputButton.d.ts.map

package/src/engine/input/devices/xr/XRInputButton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XRInputButton.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/xr/XRInputButton.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH;IACI,gBAAgB;IAChB,oCAAkC;IAElC,gBAAgB;IAChB,oCAAkC;IAKlC;;;;;;;OAOG;IACH,eAJW,MAAM,YACN,OAAO,YACP,OAAO,QAWjB;IAED,gBAAgB;IAChB,sBAYC;;CACJ;wBAnDuB,kCAAkC;kCACxB,yBAAyB"}

package/src/engine/input/devices/xr/XRInputButton.js

@@ -0,0 +1,53 @@
+import { assert } from "../../../../core/assert.js";
+import { Vector1 } from "../../../../core/geom/Vector1.js";
+import { InputDeviceSwitch } from "../InputDeviceSwitch.js";
+
+/**
+ * One raw GamepadButton: its amount in [0, 1] and its native pressed/touched switches.
+ * {@link pressed} is independent of {@link x}; a partially depressed trigger need not be pressed.
+ * The device owns mutation. Switches and {@link onChanged} retain their identity across source replacement.
+ */
+export class XRInputButton extends Vector1 {
+    /** @readonly */
+    pressed = new InputDeviceSwitch();
+
+    /** @readonly */
+    touched = new InputDeviceSwitch();
+
+    #pressed = false;
+    #touched = false;
+
+    /**
+     * Stage binary state while updating the scalar. All numeric channels and poses are sampled before
+     * the device calls flushSwitches, so an input-map action can read the corresponding amount.
+     * @internal
+     * @param {number} [value=0]
+     * @param {boolean} [pressed=false]
+     * @param {boolean} [touched=false]
+     */
+    update(value = 0, pressed = false, touched = false) {
+        assert.greaterThanOrEqual(value, 0, 'value >= 0');
+        assert.lessThanOrEqual(value, 1, 'value <= 1');
+        assert.isBoolean(pressed, 'pressed');
+        assert.isBoolean(touched, 'touched');
+
+        this.#pressed = pressed;
+        this.#touched = touched;
+        this.set(value);
+    }
+
+    /** @internal */
+    flushSwitches() {
+        if (this.#pressed) {
+            this.pressed.press();
+        } else {
+            this.pressed.release();
+        }
+
+        if (this.#touched) {
+            this.touched.press();
+        } else {
+            this.touched.release();
+        }
+    }
+}

package/src/engine/input/devices/xr/XRInputCoordinates.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Code for a raw button's scalar amount. Use InputTriggerXRButton for pressed/touched switches.
+ * @param {number} index Native button index.
+ * @returns {number}
+ */
+export function xr_input_button_coordinate(index: number): number;
+/**
+ * Code for a raw axis, without stick calibration.
+ * @param {number} index Native axis index.
+ * @returns {number}
+ */
+export function xr_input_axis_coordinate(index: number): number;
+/**
+ * Stable coordinate codes used in serialized input maps.
+ */
+export type XRInputCoordinates = number;
+export namespace XRInputCoordinates {
+    let select: number;
+    let squeeze: number;
+    let thumbstick: number;
+    let touchpad: number;
+}
+//# sourceMappingURL=XRInputCoordinates.d.ts.map

package/src/engine/input/devices/xr/XRInputCoordinates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XRInputCoordinates.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/xr/XRInputCoordinates.js"],"names":[],"mappings":"AAcA;;;;GAIG;AACH,kDAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;;GAIG;AACH,gDAHW,MAAM,GACJ,MAAM,CAMlB;;;;iCA7BS,MAAM"}

package/src/engine/input/devices/xr/XRInputCoordinates.js

@@ -0,0 +1,35 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Stable coordinate codes used in serialized input maps.
+ * @readonly
+ * @enum {number}
+ */
+export const XRInputCoordinates = {
+    select: 0,
+    squeeze: 1,
+    thumbstick: 2,
+    touchpad: 3
+};
+
+/**
+ * Code for a raw button's scalar amount. Use InputTriggerXRButton for pressed/touched switches.
+ * @param {number} index Native button index.
+ * @returns {number}
+ */
+export function xr_input_button_coordinate(index) {
+    assert.isNonNegativeInteger(index, 'index');
+
+    return 4 + index * 2;
+}
+
+/**
+ * Code for a raw axis, without stick calibration.
+ * @param {number} index Native axis index.
+ * @returns {number}
+ */
+export function xr_input_axis_coordinate(index) {
+    assert.isNonNegativeInteger(index, 'index');
+
+    return 5 + index * 2;
+}

package/src/engine/input/devices/xr/XRInputHandle.d.ts

@@ -0,0 +1,93 @@
+/**
+ * One XR input source, or a persistent handedness slot owned by XRInputDevice.
+ * All control objects survive disconnection. Consumers read them; the device owns mutation.
+ * With xr-standard, select/squeeze read native button amounts. Other mappings remain available through
+ * buttons/axes, while select/squeeze report 0/1 from native events; check their valueSource.
+ *
+ * Button indices 0/1 are select/squeeze; axes 0/1 are touchpad and 2/3 thumbstick in xr-standard.
+ * Placeholder entries are allowed by WebXR: a zero entry does not prove that a control exists.
+ */
+export class XRInputHandle {
+    /** @readonly */
+    readonly select: XRInputAction;
+    /** @readonly */
+    readonly squeeze: XRInputAction;
+    /**
+     * Raw native buttons. Use {@link getButton} for an index that may not exist yet.
+     * @readonly
+     * @type {XRInputButton[]}
+     */
+    readonly buttons: XRInputButton[];
+    /**
+     * Raw native axes in [-1, 1]. Use {@link getAxis} for an index that may not exist yet.
+     * @readonly
+     * @type {Vector1[]}
+     */
+    readonly axes: Vector1[];
+    /**
+     * Calibrated xr-standard thumbstick, +x right and +y down.
+     * @readonly
+     */
+    readonly thumbstick: GamepadStick;
+    /**
+     * Uncalibrated xr-standard touchpad coordinates, +x right and +y down.
+     * @readonly
+     */
+    readonly touchpad: Vector2;
+    /** @readonly */
+    readonly targetRay: XRInputPose;
+    /** @readonly */
+    readonly grip: XRInputPose;
+    /**
+     * Native source, or null while disconnected. Set by the device.
+     * @readonly
+     * @type {import('./XRInputTypes.js').XRInputSource|null}
+     */
+    readonly nativeSource: import('./XRInputTypes.js').XRInputSource | null;
+    /** Number of native buttons, excluding controls materialised for bindings. Do not modify directly. */
+    buttonCount: number;
+    /** Number of native axes, excluding controls materialised for bindings. Do not modify directly. */
+    axisCount: number;
+    get connected(): boolean;
+    get handedness(): string;
+    get targetRayMode(): string;
+    /** @returns {ReadonlyArray<string>} */
+    get profiles(): readonly string[];
+    /**
+     * Return a stable button, creating neutral entries up to this index if needed.
+     * @param {number} index
+     * @returns {XRInputButton}
+     */
+    getButton(index: number): XRInputButton;
+    /**
+     * Return a stable axis, creating neutral entries up to this index if needed.
+     * @param {number} index
+     * @returns {Vector1}
+     */
+    getAxis(index: number): Vector1;
+    /**
+     * @internal
+     * @param {import('./XRInputTypes.js').XRInputSource|null} source
+     */
+    bind(source: import('./XRInputTypes.js').XRInputSource | null): void;
+    /**
+     * @internal Sample values and poses before publishing raw switch edges.
+     * @param {import('./XRInputTypes.js').XRFrame|null} frame
+     * @param {EventTarget|null} referenceSpace
+     */
+    sample(frame: import('./XRInputTypes.js').XRFrame | null, referenceSpace: EventTarget | null): void;
+    /** @internal Tracking loss does not imply release or cancellation. */
+    invalidatePoses(): void;
+    /** @internal Neutralise everything before switch releases and cancellation callbacks. */
+    clear(): void;
+    /** @internal */
+    flush(): void;
+    #private;
+}
+import { XRInputAction } from "./XRInputAction.js";
+import { XRInputButton } from "./XRInputButton.js";
+import { Vector1 } from "../../../../core/geom/Vector1.js";
+import { GamepadStick } from "../gamepad/GamepadStick.js";
+import Vector2 from "../../../../core/geom/Vector2.js";
+import { XRInputPose } from "./XRInputPose.js";
+//# sourceMappingURL=XRInputHandle.d.ts.map

package/src/engine/input/devices/xr/XRInputHandle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XRInputHandle.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/input/devices/xr/XRInputHandle.js"],"names":[],"mappings":"AA2BA;;;;;;;;GAQG;AACH;IACI,gBAAgB;IAChB,+BAA6B;IAE7B,gBAAgB;IAChB,gCAA8B;IAE9B;;;;OAIG;IACH,kBAFU,aAAa,EAAE,CAEZ;IAEb;;;;OAIG;IACH,eAFU,OAAO,EAAE,CAET;IAEV;;;OAGG;IACH,kCAAoC;IAEpC;;;OAGG;IACH,2BAAyB;IAEzB,gBAAgB;IAChB,gCAA8B;IAE9B,gBAAgB;IAChB,2BAAyB;IAEzB;;;;OAIG;IACH,uBAFU,OAAO,mBAAmB,EAAE,aAAa,GAAC,IAAI,CAEpC;IAQpB,sGAAsG;IACtG,oBAAgB;IAEhB,mGAAmG;IACnG,kBAAc;IAOd,yBAEC;IAED,yBAEC;IAED,4BAEC;IAED,uCAAuC;IACvC,kCAEC;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,aAAa,CAUzB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,OAAO,CAUnB;IAED;;;OAGG;IACH,aAFW,OAAO,mBAAmB,EAAE,aAAa,GAAC,IAAI,QAgBxD;IAED;;;;OAIG;IACH,cAHW,OAAO,mBAAmB,EAAE,OAAO,GAAC,IAAI,kBACxC,WAAW,GAAC,IAAI,QA+C1B;IAmBD,sEAAsE;IACtE,wBAGC;IAED,yFAAyF;IACzF,cAeC;IAED,gBAAgB;IAChB,cAMC;;CACJ;8BAvQ6B,oBAAoB;8BACpB,oBAAoB;wBAJ1B,kCAAkC;6BAE7B,4BAA4B;oBADrC,kCAAkC;4BAIN,kBAAkB"}