@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/input/glyphs.js

@@ -0,0 +1,216 @@
+/** The pad layout for a `Gamepad.id` (vendor words and USB vendor ids), `'generic'` when unknown. */
+export function guessPadLayout(id) {
+    if (!id)
+        return 'generic';
+    const s = id.toLowerCase();
+    if (/xbox|xinput|microsoft|045e/.test(s))
+        return 'xbox';
+    if (/playstation|dualshock|dualsense|sony|wireless controller|054c/.test(s))
+        return 'playstation';
+    if (/nintendo|switch|joy-con|pro controller|057e/.test(s))
+        return 'nintendo';
+    return 'generic';
+}
+const PAD_BUTTONS = {
+    xbox: [
+        'A',
+        'B',
+        'X',
+        'Y',
+        'LB',
+        'RB',
+        'LT',
+        'RT',
+        'View',
+        'Menu',
+        'LS',
+        'RS',
+        '↑',
+        '↓',
+        '←',
+        '→',
+        'Xbox',
+    ],
+    playstation: [
+        'Cross',
+        'Circle',
+        'Square',
+        'Triangle',
+        'L1',
+        'R1',
+        'L2',
+        'R2',
+        'Share',
+        'Options',
+        'L3',
+        'R3',
+        '↑',
+        '↓',
+        '←',
+        '→',
+        'PS',
+    ],
+    nintendo: [
+        'B',
+        'A',
+        'Y',
+        'X',
+        'L',
+        'R',
+        'ZL',
+        'ZR',
+        '-',
+        '+',
+        'LS',
+        'RS',
+        '↑',
+        '↓',
+        '←',
+        '→',
+        'Home',
+    ],
+    generic: [],
+};
+/** Standard-mapping pad button `index` in `layout` (`'Button 7'` past the table or for `'generic'`). */
+export function padButtonLabel(index, layout = 'generic') {
+    return PAD_BUTTONS[layout][index] ?? `Button ${index}`;
+}
+const AXES = ['LS', 'LS', 'RS', 'RS'];
+/** Standard-mapping pad axis `axis` pushed in `dir`: `'LS →'`, `'RS ↑'`, or `'Axis 4 +'` past the sticks. */
+export function padAxisLabel(axis, dir) {
+    const stick = AXES[axis];
+    if (!stick)
+        return `Axis ${axis} ${dir > 0 ? '+' : '-'}`;
+    const vertical = axis % 2 === 1;
+    const arrow = vertical ? (dir > 0 ? '↓' : '↑') : dir > 0 ? '→' : '←';
+    return `${stick} ${arrow}`;
+}
+const KEY_LABELS = {
+    Space: 'Space',
+    Enter: 'Enter',
+    NumpadEnter: 'Enter',
+    Escape: 'Esc',
+    Tab: 'Tab',
+    Backspace: 'Backspace',
+    Delete: 'Del',
+    Insert: 'Ins',
+    Home: 'Home',
+    End: 'End',
+    PageUp: 'PgUp',
+    PageDown: 'PgDn',
+    CapsLock: 'Caps',
+    ArrowUp: '↑',
+    ArrowDown: '↓',
+    ArrowLeft: '←',
+    ArrowRight: '→',
+    ShiftLeft: 'Shift',
+    ShiftRight: 'Shift',
+    ControlLeft: 'Ctrl',
+    ControlRight: 'Ctrl',
+    AltLeft: 'Alt',
+    AltRight: 'Alt',
+    MetaLeft: 'Meta',
+    MetaRight: 'Meta',
+    ContextMenu: 'Menu',
+    Minus: '-',
+    Equal: '=',
+    BracketLeft: '[',
+    BracketRight: ']',
+    Backslash: '\\',
+    Semicolon: ';',
+    Quote: "'",
+    Backquote: '`',
+    Comma: ',',
+    Period: '.',
+    Slash: '/',
+    NumpadAdd: 'Num +',
+    NumpadSubtract: 'Num -',
+    NumpadMultiply: 'Num *',
+    NumpadDivide: 'Num /',
+    NumpadDecimal: 'Num .',
+};
+/**
+ * Display text for a `KeyboardEvent.code`: `'KeyA'` → `'A'`, `'Digit1'` → `'1'`, `'Numpad1'` →
+ * `'Num 1'`, `'F5'` → `'F5'`, arrows as arrows, modifiers without their side; unknown codes are
+ * split at their capitals (`'AudioVolumeUp'` → `'Audio Volume Up'`).
+ */
+export function keyLabel(code) {
+    const known = KEY_LABELS[code];
+    if (known)
+        return known;
+    if (code.startsWith('Key') && code.length === 4)
+        return code.slice(3);
+    if (code.startsWith('Digit') && code.length === 6)
+        return code.slice(5);
+    if (code.startsWith('Numpad') && code.length === 7)
+        return `Num ${code.slice(6)}`;
+    if (/^F\d{1,2}$/.test(code))
+        return code;
+    return code.replace(/([a-z])([A-Z])/g, '$1 $2');
+}
+const POINTER_LABELS = { select: 'Select', secondary: 'Secondary' };
+const XR_LABELS = {
+    trigger: 'Trigger',
+    squeeze: 'Squeeze',
+    pinch: 'Pinch',
+};
+const GESTURE_LABELS = {
+    tap: 'Tap',
+    doubleTap: 'Double tap',
+    longPress: 'Hold',
+    pan: 'Drag',
+    drag: 'Drag',
+    pinch: 'Pinch',
+};
+const MOUSE_LABELS = ['Left click', 'Middle click', 'Right click', 'Back', 'Forward'];
+/**
+ * The glyph for one binding. A chord joins its members with ` + ` and takes the first member's
+ * kind; `trigger: 'hold'` prefixes `Hold `, `'doubleTap'` prefixes `Double-tap `.
+ */
+export function glyphForBinding(b, layout = 'generic') {
+    const g = sourceGlyph(b, layout);
+    if (b.trigger === 'hold')
+        g.label = `Hold ${g.label}`;
+    else if (b.trigger === 'doubleTap')
+        g.label = `Double-tap ${g.label}`;
+    return g;
+}
+function sourceGlyph(b, layout) {
+    if ('key' in b)
+        return { kind: 'key', label: keyLabel(b.key) };
+    if ('mouse' in b)
+        return { kind: 'pointer', label: MOUSE_LABELS[b.mouse] ?? `Mouse ${b.mouse}` };
+    if ('wheel' in b)
+        return { kind: 'pointer', label: b.wheel < 0 ? 'Wheel up' : 'Wheel down' };
+    if ('padButton' in b)
+        return { kind: 'button', label: padButtonLabel(b.padButton, layout) };
+    if ('padAxis' in b)
+        return { kind: 'axis', label: padAxisLabel(b.padAxis, b.dir) };
+    if ('gesture' in b)
+        return { kind: 'gesture', label: GESTURE_LABELS[b.gesture] ?? b.gesture };
+    if ('pointer' in b)
+        return { kind: 'pointer', label: POINTER_LABELS[b.pointer] };
+    if ('xr' in b)
+        return { kind: 'xr', label: XR_LABELS[b.xr] };
+    const parts = b.chord.map((m) => glyphForBinding(m, layout));
+    const first = parts[0];
+    return { kind: first?.kind ?? 'key', label: parts.map((p) => p.label).join(' + ') };
+}
+/** True when `b` is what `device` produces, so its glyph is the one to show for that device. */
+export function bindingMatchesDevice(b, device) {
+    if ('chord' in b)
+        return b.chord.some((m) => bindingMatchesDevice(m, device));
+    switch (device) {
+        case 'keyboard':
+            return 'key' in b;
+        case 'mouse':
+        case 'pen':
+            return 'mouse' in b || 'wheel' in b || 'pointer' in b;
+        case 'touch':
+            return 'gesture' in b || 'pointer' in b || 'mouse' in b;
+        case 'gamepad':
+            return 'padButton' in b || 'padAxis' in b;
+        case 'xr':
+            return 'xr' in b || 'pointer' in b;
+    }
+}

package/dist/input/gyro.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Gyro aim (ws/input-5): the device's rotation rate (`devicemotion`'s `rotationRate`) turned into
+ * a look delta, so a phone aims by turning it. Feature-detected; `Look` adds it to the pointer
+ * and stick delta each tick when given one (`LookOptions.gyro`). iOS asks the player first:
+ * call `requestPermission()` from a tap.
+ */
+/** `GyroSource.requestPermission` result; `'prompt'` is `permission` before it is asked. */
+export type GyroPermission = 'granted' | 'denied' | 'unavailable';
+/** The slice of `DeviceMotionEvent` the source reads. */
+export interface GyroMotionEvent {
+    /** Degrees per second about the device's z (`alpha`), x (`beta`) and y (`gamma`) axes. */
+    rotationRate?: {
+        alpha?: number | null;
+        beta?: number | null;
+        gamma?: number | null;
+    } | null;
+    /** Ms between events, as the browser reports it. */
+    interval?: number;
+    timeStamp?: number;
+}
+/** Where the source listens (tests and the harness pass a fake). Default: the page's window. */
+export interface GyroEnv {
+    /** Fires `devicemotion`. `null`: no API. */
+    target: {
+        addEventListener(type: 'devicemotion', fn: (e: GyroMotionEvent) => void): void;
+        removeEventListener(type: 'devicemotion', fn: (e: GyroMotionEvent) => void): void;
+    } | null;
+    /** `DeviceMotionEvent.requestPermission` where the platform has it (iOS 13+). */
+    requestPermission?: () => Promise<string>;
+    /** Screen rotation in degrees (`screen.orientation.angle`): 0, 90, 180 or 270. */
+    screenAngle?: () => number;
+}
+export interface GyroSourceOptions {
+    /** Look radians per radian the device turns. Default 1. */
+    sensitivity?: number;
+    /** Flip the pitch (the gyro's own; `Look.invertY` does not apply to it). Default false. */
+    invertY?: boolean;
+    /** 0..1 low-pass on each tick's delta: 0 none, 0.5 halves a jolt. Default 0. */
+    smoothing?: number;
+    /** The event source. Default the page's `window` and `DeviceMotionEvent`. */
+    env?: GyroEnv;
+}
+export interface GyroSource {
+    /** While false the rotation is dropped and `take` reads zero. Default true. */
+    enabled: boolean;
+    sensitivity: number;
+    invertY: boolean;
+    smoothing: number;
+    /** True when the platform has the motion API at all. */
+    readonly available: boolean;
+    /** True once a motion event with a rotation rate arrived (desktops have the API, no sensor). */
+    readonly receiving: boolean;
+    /** `'prompt'` until `requestPermission` settles. */
+    readonly permission: GyroPermission | 'prompt';
+    /**
+     * Ask for the sensor: `'unavailable'` without the API, the player's answer where the platform
+     * asks (iOS; call it from a tap), `'granted'` where it does not. Never rejects.
+     */
+    requestPermission(): Promise<GyroPermission>;
+    /**
+     * The turn since the last `take`, radians (`dx` > 0 turns right, `dy` > 0 looks up, as
+     * `Look.look`), smoothed; resets the accumulator. Writes `out` and returns it. `Look` calls it.
+     */
+    take(out: {
+        dx: number;
+        dy: number;
+    }): {
+        dx: number;
+        dy: number;
+    };
+    /**
+     * Add a rotation rate (degrees per second about the device's z, x and y axes, as
+     * `rotationRate.alpha/beta/gamma`) held for `ms`. The event listener calls it; tests and the
+     * harness feed it directly.
+     */
+    feed(alpha: number, beta: number, gamma: number, ms: number): void;
+    /** Stop listening. */
+    dispose(): void;
+}
+/**
+ * Build a gyro source. It listens at once (where the platform needs permission, events start
+ * after `requestPermission` is granted). Rotation about the screen's vertical axis yaws, about
+ * its horizontal axis pitches, following `screen.orientation.angle`.
+ */
+export declare function createGyroSource(opts?: GyroSourceOptions): GyroSource;

package/dist/input/gyro.js

@@ -0,0 +1,140 @@
+/**
+ * Gyro aim (ws/input-5): the device's rotation rate (`devicemotion`'s `rotationRate`) turned into
+ * a look delta, so a phone aims by turning it. Feature-detected; `Look` adds it to the pointer
+ * and stick delta each tick when given one (`LookOptions.gyro`). iOS asks the player first:
+ * call `requestPermission()` from a tap.
+ */
+/** Longest gap one event integrates over, ms (a stalled sensor must not jump the view). */
+const MAX_EVENT_MS = 100;
+const DEG = Math.PI / 180;
+function defaultEnv() {
+    if (typeof window === 'undefined' || typeof DeviceMotionEvent === 'undefined') {
+        return { target: null };
+    }
+    const ctor = DeviceMotionEvent;
+    return {
+        target: window,
+        requestPermission: typeof ctor.requestPermission === 'function' ? () => ctor.requestPermission() : undefined,
+        screenAngle: () => (typeof screen !== 'undefined' && screen.orientation?.angle) ||
+            // Old iOS Safari.
+            Number(window.orientation ?? 0),
+    };
+}
+/**
+ * Build a gyro source. It listens at once (where the platform needs permission, events start
+ * after `requestPermission` is granted). Rotation about the screen's vertical axis yaws, about
+ * its horizontal axis pitches, following `screen.orientation.angle`.
+ */
+export function createGyroSource(opts = {}) {
+    const env = opts.env ?? defaultEnv();
+    const target = env.target;
+    let yaw = 0;
+    let pitch = 0;
+    let sx = 0;
+    let sy = 0;
+    let lastStamp = Number.NaN;
+    let receiving = false;
+    let permission = target ? 'prompt' : 'unavailable';
+    const onMotion = (e) => {
+        const r = e.rotationRate;
+        if (!r)
+            return;
+        receiving = true;
+        let ms;
+        const stamp = e.timeStamp;
+        if (stamp !== undefined && !Number.isNaN(lastStamp))
+            ms = stamp - lastStamp;
+        else {
+            // Some browsers have reported `interval` in seconds.
+            const iv = e.interval ?? 16;
+            ms = iv > 0 && iv < 1 ? iv * 1000 : iv;
+        }
+        if (stamp !== undefined)
+            lastStamp = stamp;
+        src.feed(r.alpha ?? 0, r.beta ?? 0, r.gamma ?? 0, ms);
+    };
+    const src = {
+        enabled: true,
+        sensitivity: opts.sensitivity ?? 1,
+        invertY: opts.invertY ?? false,
+        smoothing: opts.smoothing ?? 0,
+        get available() {
+            return target !== null;
+        },
+        get receiving() {
+            return receiving;
+        },
+        get permission() {
+            return permission;
+        },
+        async requestPermission() {
+            if (!target) {
+                permission = 'unavailable';
+                return permission;
+            }
+            if (!env.requestPermission) {
+                permission = 'granted';
+                return permission;
+            }
+            try {
+                const r = await env.requestPermission();
+                permission = r === 'granted' ? 'granted' : 'denied';
+            }
+            catch {
+                // Not inside a user gesture, or refused.
+                permission = 'denied';
+            }
+            return permission;
+        },
+        feed(_alpha, beta, gamma, ms) {
+            if (!src.enabled)
+                return;
+            const s = Math.min(MAX_EVENT_MS, Math.max(0, ms)) / 1000;
+            // Device axes: x right, y up, z out of the screen. Turning to aim right is a negative turn
+            // about the screen's up axis; tilting the top away (aim up) a positive one about its right.
+            const angle = (((env.screenAngle?.() ?? 0) % 360) + 360) % 360;
+            let up;
+            let right;
+            if (angle === 90) {
+                up = beta;
+                right = -gamma;
+            }
+            else if (angle === 180) {
+                up = -gamma;
+                right = -beta;
+            }
+            else if (angle === 270) {
+                up = -beta;
+                right = gamma;
+            }
+            else {
+                up = gamma;
+                right = beta;
+            }
+            yaw += 0 - up * s * DEG;
+            pitch += right * s * DEG;
+        },
+        take(out) {
+            const k = src.sensitivity;
+            let dx = src.enabled ? yaw * k : 0;
+            let dy = src.enabled ? pitch * k * (src.invertY ? -1 : 1) : 0;
+            yaw = pitch = 0;
+            const a = Math.min(1, Math.max(0, src.smoothing));
+            if (a > 0) {
+                dx = sx * a + dx * (1 - a);
+                dy = sy * a + dy * (1 - a);
+            }
+            sx = dx;
+            sy = dy;
+            // `+ 0` keeps a still gyro at +0 under invertY.
+            out.dx = dx + 0;
+            out.dy = dy + 0;
+            return out;
+        },
+        dispose() {
+            target?.removeEventListener('devicemotion', onMotion);
+        },
+    };
+    target?.addEventListener('devicemotion', onMotion);
+    return src;
+}

package/dist/input/index.d.ts

@@ -0,0 +1,19 @@
+export { type BindingConflict, findConflicts, isBinding, parseBindings, serializeBindings, } from './bindings.js';
+export { createTickClock, type InputClock, type TickClock, wallClock, } from './clock.js';
+export { Follow, type FollowCamera, type FollowMode, type FollowObstacle, type FollowOptions, type FollowSubject, } from './follow.js';
+export { createGestures, type DragGesture, type GestureAttachOptions, type GestureDevice, type GestureListener, type GestureOptions, type GesturePhase, type GesturePoint, Gestures, type PanGesture, type PinchGesture, type TapGesture, } from './gestures.js';
+export { bindingMatchesDevice, type Glyph, type GlyphKind, glyphForBinding, guessPadLayout, keyLabel, type PadLayout, padAxisLabel, padButtonLabel, } from './glyphs.js';
+export { createGyroSource, type GyroEnv, type GyroMotionEvent, type GyroPermission, type GyroSource, type GyroSourceOptions, } from './gyro.js';
+export { type ActionSource, type AttachOptions, type ContextOptions, type ContextPass, DEFAULT_DOUBLE_TAP_MS, DEFAULT_HOLD_MS, Input, type InputEvents, type InputFeedHook, type InputOptions, type InputPointerPhase, isButtonTarget, isInteractiveTarget, isTextEntryTarget, type ListenOptions, type RumbleOptions, type StickOptions, type StickShape, shapeStick, } from './input.js';
+export type { LookTapListener, LookTapOptions } from './look.js';
+export { createLook, Look, type LookEvents, type LookKeys, type LookMode, type LookOptions, type LookStick, type LookTouchOptions, type LookZoomOptions, type LookZoomPad, type MoveZone, PAD_ZOOM_PER_S, } from './look.js';
+export { type Aim, type Edges, MAGNIFY_DEFAULTS, type MagnifyOptions, type MagnifyTarget, type SnapGrid, snapToGrid, } from './magnify.js';
+export { createPointerDispatcher, POINTER_PRIORITY, type PointerConsumer, type PointerDispatcher, type PointerDispatcherOptions, type PointerRecord, type PointerRecordDevice, } from './pointer-dispatch.js';
+export { createPointerRouter, type PointerActions, type PointerHitEvent, PointerRouter, type PointerRouterEvents, type PointerRouterOptions, type RoutedPointer, } from './pointer-router.js';
+export { createSample, PadCursor, type PadCursorOptions, type PointerDevice, type PointerSample, type PointerSource, ScreenPointers, type XrButtons, } from './pointer-sources.js';
+export { aabbTester, createHit, createRay, type HitTester, type MeshTesterOptions, meshTester, obbTester, type PickHit, planeTester, type Ray, type RayBounds, type RayBox, type RayCamera, type RayPlane, type RayTransform, rayAt, rayTriangle, screenRay, sphereTester, transformRayInto, type Vec3, } from './rays.js';
+export type { InputPointerEntry } from './record.js';
+export { createInputPlayback, createInputRecorder, type InputPlayback, type InputPlaybackOptions, type InputRecorder, type InputRecorderOptions, type InputRecording, InputRecordingError, type InputTick, type InputTickEvents, type InputTickRun, type PadSnapshot, parseRecording, recordingLength, serializeRecording, } from './record.js';
+export { type ButtonsZone, type ButtonsZoneOptions, createTouchZones, type StickZone, type StickZoneOptions, type SwipeDirection, type SwipeZone, type SwipeZoneOptions, type TouchZoneBinding, type TouchZoneKind, type TouchZoneOptions, type TouchZoneReading, type TouchZones, type TouchZonesOptions, type ZoneRect, type ZoneRectFn, } from './touch-zones.js';
+export type { ActionState, Binding, BindingSource, Bindings, GamepadActuatorLike, GamepadLike, GestureKind, Hand, InputDevice, PointerButton, PointerState, PointerTransform, Trigger, TriggerOptions, XrButton, } from './types.js';
+export { XrPointerSource, type XrPointerSourceOptions } from './xr-source.js';

package/dist/input/index.js

@@ -0,0 +1,16 @@
+export { findConflicts, isBinding, parseBindings, serializeBindings, } from './bindings.js';
+export { createTickClock, wallClock, } from './clock.js';
+export { Follow, } from './follow.js';
+export { createGestures, Gestures, } from './gestures.js';
+export { bindingMatchesDevice, glyphForBinding, guessPadLayout, keyLabel, padAxisLabel, padButtonLabel, } from './glyphs.js';
+export { createGyroSource, } from './gyro.js';
+export { DEFAULT_DOUBLE_TAP_MS, DEFAULT_HOLD_MS, Input, isButtonTarget, isInteractiveTarget, isTextEntryTarget, shapeStick, } from './input.js';
+export { createLook, Look, PAD_ZOOM_PER_S, } from './look.js';
+export { MAGNIFY_DEFAULTS, snapToGrid, } from './magnify.js';
+export { createPointerDispatcher, POINTER_PRIORITY, } from './pointer-dispatch.js';
+export { createPointerRouter, PointerRouter, } from './pointer-router.js';
+export { createSample, PadCursor, ScreenPointers, } from './pointer-sources.js';
+export { aabbTester, createHit, createRay, meshTester, obbTester, planeTester, rayAt, rayTriangle, screenRay, sphereTester, transformRayInto, } from './rays.js';
+export { createInputPlayback, createInputRecorder, InputRecordingError, parseRecording, recordingLength, serializeRecording, } from './record.js';
+export { createTouchZones, } from './touch-zones.js';
+export { XrPointerSource } from './xr-source.js';