@driftengine/core 3.61.0

package/dist/input/gamepadMapping.js

@@ -0,0 +1,91 @@
+/**
+ * The W3C Standard Gamepad, by position rather than by anybody's lettering.
+ *
+ * **The names are positional and that is a correctness decision, not a style one.** Index 0 is the
+ * bottom button of the right cluster. It is labelled A on an Xbox pad, Cross on a PlayStation pad
+ * and **B** on a Nintendo pad, because Nintendo's physical layout swaps the two. Any lettering
+ * this file picked would therefore be a false statement about somebody's hardware. It names the
+ * position, which is true everywhere; `gamepadIdentity.ts` answers what that position is *called*
+ * on the pad actually in the player's hands.
+ *
+ * A browser sets `mapping: 'standard'` only when it is confident the device matches this table.
+ * Anything else is served by raw index and says so once — see `InputSource`'s pad view.
+ */
+export const BUTTON_INDEX = {
+    faceDown: 0,
+    faceRight: 1,
+    faceLeft: 2,
+    faceUp: 3,
+    l1: 4,
+    r1: 5,
+    /* The lower shoulders are the only members of this table that are honestly both a button and an
+       axis: they carry an analog `value` beside `pressed`, so they answer `down` and `axis` alike. */
+    l2: 6,
+    r2: 7,
+    select: 8,
+    start: 9,
+    l3: 10,
+    r3: 11,
+    dpadUp: 12,
+    dpadDown: 13,
+    dpadLeft: 14,
+    dpadRight: 15,
+    /* Optional in the specification, and a browser may withhold it entirely. A pad without one
+       simply never reports it down, which is the true answer rather than a convenient one. */
+    guide: 16,
+};
+/**
+ * **Vertical axes point up at −1**, which is the specification's choice and the opposite of most
+ * game code's expectation.
+ *
+ * It is not corrected here. An engine that silently flips a sign is one a consumer cannot reason
+ * about — the value it reads would disagree with every reference about the API it came from — so a
+ * caller that wants the other convention negates it at the one place that means something. What it
+ * costs: a caller has to know. What would make it wrong: nothing short of the specification
+ * changing, which it will not.
+ */
+export const AXIS_INDEX = {
+    leftX: 0,
+    leftY: 1,
+    rightX: 2,
+    rightY: 3,
+};
+/**
+ * How far a stick must travel before it is moving at all.
+ *
+ * A tuning constant, so it is an option rather than a rule — `AGENTS.md` forbids asserting the
+ * value of one, and `gamepadMapping.test.ts` checks only that it sits in a range a stick can
+ * leave. Sticks rest off-centre by different amounts on different pads and wear looser with age,
+ * which is the whole reason a deadzone exists.
+ */
+export const DEFAULT_DEADZONE = 0.15;
+/**
+ * Drop the dead region and rescale what is left, into a caller-owned target.
+ *
+ * **Radial rather than per-axis.** A per-axis deadzone leaves a *square* dead region, so a stick
+ * pushed diagonally clears it at a smaller displacement than one pushed straight, and the diagonal
+ * snaps out of nothing. What a player is controlling is the magnitude, so the magnitude is what
+ * the test applies to.
+ *
+ * **Rescaled from the edge**, because without it the value jumps from 0 to the deadzone the
+ * instant it is crossed — a stick that begins moving fast rather than from rest. What it costs:
+ * full deflection is reached fractionally before the hardware's own rim. What would make it wrong:
+ * a caller wanting the untouched number, which the pad view answers separately as `rawAxis`.
+ *
+ * Fills `out` rather than returning an object: this is a per-frame path and the house rule about
+ * allocation binds it.
+ */
+export function applyDeadzone(x, y, deadzone, out) {
+    const magnitude = Math.hypot(x, y);
+    if (magnitude === 0 || magnitude <= deadzone) {
+        out.x = 0;
+        out.y = 0;
+        return;
+    }
+    /* Clamped at 1: a stick can read slightly past its own rim, and a value above 1 would be a
+       speed no caller asked to be possible. */
+    const scaled = Math.min(1, (magnitude - deadzone) / (1 - deadzone));
+    const unit = scaled / magnitude;
+    out.x = x * unit;
+    out.y = y * unit;
+}

package/dist/input/input.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Low-level, device-agnostic input capture: raw keys, relative mouse motion,
+ * live touch points. Interpretation (bindings, gestures, virtual stick) is the
+ * game's job — this module never decides what an input *means*.
+ */
+import { type InputDevice } from './activeDevice.ts';
+import { type GamepadFamily } from './gamepadIdentity.ts';
+import { type GamepadAxis, type GamepadButton } from './gamepadMapping.ts';
+/**
+ * Ask for the pointer lock, and deal with being told no.
+ *
+ * Split out from the caller below so the rule can be tested without a DOM, the
+ * same way `isTypingTarget` is.
+ *
+ * **The refusal is expected and it is not an error.** Chrome returns a promise here
+ * (113 and up) and rejects it when it will not grant the lock — most often for the
+ * second or so after the user has left one with Escape, which is precisely when the
+ * next click arrives asking for it back. Dropping that promise makes an ordinary
+ * refusal an `unhandledrejection`, and in a game that watches for those it becomes a
+ * bug report about nothing: see report `G94666`, 2026-08-08.
+ *
+ * `requestFullscreen` next door has always caught its own for the same reason.
+ */
+export declare function askForPointerLock(request: (options?: {
+    unadjustedMovement: boolean;
+}) => Promise<void> | void): void;
+export interface TouchPoint {
+    readonly id: number;
+    x: number;
+    y: number;
+    readonly startX: number;
+    readonly startY: number;
+    readonly startTime: number;
+}
+/** The devices this source watches, and the granularity a consumer may switch off. */
+export type InputSourceName = 'keyboard' | 'mouse' | 'touch' | 'gamepad';
+export interface InputOptions {
+    /**
+     * Turn a device off. Absent means on.
+     *
+     * A disabled source is **inert, not absent**: its state stops updating, it never takes the
+     * prompts, and — for the gamepad — the poll stops outright, so an application that does not want
+     * controllers pays for no snapshot at all.
+     */
+    readonly sources?: Partial<Record<InputSourceName, boolean>>;
+    /**
+     * Whether to poll the gamepad on an animation frame of this source's own. Defaults to true.
+     *
+     * **True is what makes support seamless**: a consumer that wired nothing still gets a working
+     * controller. Pass `false` and call `poll()` where you want the sample taken — which is what a
+     * recorded replay needs, since a sample pinned to the fixed tick is reproducible and one taken
+     * on a frame callback is not.
+     */
+    readonly autoPoll?: boolean;
+    /** How far a stick travels before it is moving. See `DEFAULT_DEADZONE`. */
+    readonly deadzone?: number;
+}
+/** What a pad is, as opposed to where its buttons are. See `gamepadIdentity.ts`. */
+export interface GamepadIdentity {
+    readonly family: GamepadFamily;
+    /** What this pad calls that position: `faceDown` is `A`, `Cross` or `B`. */
+    label(button: GamepadButton): string;
+    /** A stable key for a consumer's own icon set, such as `xbox.a`. The engine ships no art. */
+    glyph(button: GamepadButton): string;
+}
+/**
+ * One connected pad, as a consumer holds it.
+ *
+ * A view per pad rather than flat accessors on the source, for two reasons: identity belongs to a
+ * device and would otherwise be passed alongside every call, and local multiplayer falls out of it
+ * instead of needing a second design later.
+ */
+export interface GamepadView {
+    /** The browser's own slot, so a consumer can keep a player on the pad they picked up. */
+    readonly index: number;
+    readonly identity: GamepadIdentity;
+    /**
+     * `'standard'` when the browser vouches for the layout, `'unknown'` when it will not.
+     *
+     * The named accessors still answer on an unknown pad — they read the standard indices — but they
+     * are reading a guess, and this is how a consumer can tell.
+     */
+    readonly mapping: 'standard' | 'unknown';
+    /** Held right now. */
+    down(button: GamepadButton): boolean;
+    /**
+     * Went down since the last poll, readable by anything.
+     *
+     * Clears at the next poll rather than at the read, so a menu and a heads-up display may both see
+     * one press. Use `consumePress` where acting twice would be a bug.
+     */
+    pressed(button: GamepadButton): boolean;
+    /**
+     * The same edge, claimed — true for exactly one caller, then gone for everybody.
+     *
+     * **The hazard is a slow frame.** The fixed-step loop runs more than once, and a `pressed` that
+     * stayed true across both ticks is a double jump from a single press. Anything acting inside
+     * `simulate` claims; anything drawing reads `pressed`.
+     */
+    consumePress(button: GamepadButton): boolean;
+    /** A stick axis with the deadzone applied, in [-1, 1]. Vertical points **up at −1**. */
+    axis(axis: GamepadAxis): number;
+    /** A lower shoulder's analog travel, in [0, 1]. It is a button and an axis, honestly both. */
+    trigger(button: 'l2' | 'r2'): number;
+    /** Any button by raw index, for a pad whose layout the browser will not vouch for. */
+    button(index: number): boolean;
+    /** Any axis by raw index, untouched by the deadzone. */
+    rawAxis(index: number): number;
+    /**
+     * Whether this pad has motors this browser can drive.
+     *
+     * **Read it and grey the control out.** Most pads on most browsers cannot rumble, and a settings
+     * screen offering a slider the player's hardware ignores is worse than one that says so. Re-read
+     * it after a poll rather than caching: a pad unplugged and plugged back in is a different device
+     * behind the same slot.
+     */
+    readonly canRumble: boolean;
+    /**
+     * Play a rumble for `durationMs`, at two magnitudes in [0, 1]. Answers whether it was taken.
+     *
+     * `strong` is the low-frequency motor and `weak` the high-frequency one, which is what a standard
+     * pad has two of. Magnitudes are clamped into range and a duration past the platform's ceiling of
+     * five seconds is clamped to it; a duration at or below zero is nothing to play and answers
+     * `false`.
+     *
+     * **`false` is a real answer and not an error**: no actuator, a browser that cannot drive one, or
+     * nothing to play. It never throws, and a failure after the fact — the pad unplugged mid-effect —
+     * is reported once per pad on the console rather than as an unhandled rejection.
+     */
+    rumble(durationMs: number, strong: number, weak: number): boolean;
+    /** Stop whatever is playing. Answers whether the platform took it. */
+    stopRumble(): boolean;
+}
+export interface InputCallbacks {
+    onKeyDown?: (code: string) => void;
+    onTouchStart?: (touch: TouchPoint) => void;
+    onTouchMove?: (touch: TouchPoint) => void;
+    onTouchEnd?: (touch: TouchPoint, durationMs: number) => void;
+}
+export declare class InputSource {
+    readonly isCoarse: boolean;
+    readonly touches: Map<number, TouchPoint>;
+    readonly target: HTMLElement;
+    private readonly keys;
+    private readonly preventDefaultCodes;
+    private readonly subscribers;
+    private mouseDx;
+    private mouseDy;
+    private mouseButtonDown;
+    private readonly disposers;
+    /** Which device the player last actually used, and who wants telling when that changes. */
+    private readonly active;
+    private readonly enabled;
+    /** Preallocated: a poll must not build a pad per frame. */
+    private readonly padStates;
+    /** The live subset, as a stable array whose length is set rather than rebuilt. */
+    private readonly padViews;
+    private deadzone;
+    private autoPoll;
+    private frameHandle;
+    /** Devices already refused in words, so a refusal is once a pad rather than once a frame. */
+    private readonly refusedPads;
+    /**
+     * Keys that went down since the last poll, and the ones a caller has claimed.
+     *
+     * `isDown` is a level and `onKeyDown` is a callback; neither is an edge a simulation tick can
+     * take. These give the keyboard the two verbs a pad already had, latched at the same moment and
+     * cleared at the same one, which is what lets one action answer for both devices without either
+     * being a special case.
+     */
+    private keysPressed;
+    private keysPressedNext;
+    private readonly keysClaimed;
+    /**
+     * Presses waiting for somebody to act on them.
+     *
+     * **Separate from `keysPressed`, because the two edges have different lifetimes and conflating
+     * them lost inputs.** `keysPressed` is for *drawing* — a highlight that outlived its frame would
+     * be wrong — so it rotates every poll. This one is for *acting*, and a claimant does not run
+     * every frame: `poll` is on an animation frame and a fixed-step simulation is not, so at 120 Hz
+     * against a 60 Hz tick about half the display frames run no tick at all. A press that landed in
+     * one of those was rotated away before anything could claim it, and the player's jump did not
+     * happen — intermittently, in proportion to their refresh rate. A consumer found it by replacing
+     * a hand-rolled `onKeyDown` latch, which cleared only when the simulation ran, with
+     * `ActionMap.consumePress`.
+     *
+     * So a claim lives until it is claimed or until the key comes back up. **Releasing is what makes
+     * it stale**: a press nobody wanted, whose key is no longer down, describes nothing anybody can
+     * still act on. What this costs is a press held across a screen that does not read it, which
+     * then lands on the screen that does — which is the same thing the hand-rolled latch did.
+     */
+    private readonly keysUnclaimed;
+    /**
+     * `options` is a **third** parameter rather than a widened second, so every existing call site
+     * keeps compiling. A consumer that passes only a target and its prevent-default codes gets the
+     * behaviour it always had, plus a working controller it did not ask for.
+     */
+    constructor(target: HTMLElement, preventDefaultCodes?: Iterable<string>, options?: InputOptions);
+    isDown(code: string): boolean;
+    /**
+     * The pads currently connected and seen, most recently sampled.
+     *
+     * **A pad is invisible until the player uses it**, and that is the browser's rule rather than
+     * this engine's: reporting a connected gamepad before a button has been pressed is a
+     * fingerprinting surface, so none does. It happens to be the rule this design wanted anyway.
+     *
+     * The array is stable and its length is set rather than rebuilt, so reading it allocates
+     * nothing.
+     */
+    get pads(): readonly GamepadView[];
+    /**
+     * One pad by position in `pads`, or null.
+     *
+     * **Position in the list, not the browser's slot** — `GamepadView.index` answers that, and is
+     * what a consumer pins a player to. The distinction shows itself when a pad is unplugged: the
+     * list closes up, and a caller holding a slot wants `index`.
+     */
+    pad(at: number): GamepadView | null;
+    /** Which device the player last actually used. See `activeDevice.ts` for what counts as use. */
+    get lastDevice(): InputDevice;
+    /** Told when that changes, and only when it changes. Returns the unsubscribe. */
+    onDeviceChange(listener: (device: InputDevice) => void): () => void;
+    /**
+     * Turn a device on or off at runtime, for a settings screen.
+     *
+     * A disabled source is inert rather than absent, and disabling the gamepad stops the poll
+     * outright — so an application that does not want controllers pays for no snapshot a frame.
+     */
+    setSourceEnabled(source: InputSourceName, enabled: boolean): void;
+    /**
+     * Sample the pads now.
+     *
+     * **Called once an animation frame by this source's own loop unless `autoPoll` is false**, and
+     * public so a consumer can pin the sample to its own fixed tick instead — which is what a
+     * recorded replay needs, since a sample taken on a frame callback is not reproducible.
+     *
+     * **`getGamepads()` allocates**, an array and the objects behind it, and that cost is the
+     * browser's rather than something this engine can pool. So it is called exactly once here and
+     * never from a read: every accessor on a view is a lookup on numbers already copied out. A frame
+     * that runs three simulation ticks polls once, which is also the correct semantics — the
+     * hardware cannot have changed between two ticks of one frame.
+     */
+    poll(): void;
+    /**
+     * Say once, per device, that a pad's layout is not one the browser will vouch for.
+     *
+     * **Served rather than refused**, so a consumer that knows the device can still reach it by
+     * index — but said out loud, because silence would leave a player whose arcade stick does
+     * nothing with no way to discover why, which is the silent no-op the house rules forbid. Once
+     * per device rather than once per frame, exactly as `registerCompute` refuses: a line every
+     * frame floods a console somebody needs to read.
+     */
+    private refuseIfUnvouched;
+    private startPolling;
+    private stopPolling;
+    /**
+     * Whether a key went down since the last poll. Readable by anything, cleared at the next poll.
+     *
+     * The keyboard's half of the pair `GamepadView.pressed` documents: use this to draw, and
+     * `consumeKeyPress` to act, so a slow frame running the fixed-step loop twice cannot act twice.
+     */
+    keyPressed(code: string): boolean;
+    /** The same edge, claimed: true for exactly one caller, then gone for everybody. */
+    consumeKeyPress(code: string): boolean;
+    /**
+     * Add a device-event subscriber. Multiple reusable control layers may listen
+     * without overwriting one another; interpretation still happens outside the
+     * raw source. Subscription and removal are initialization-time operations.
+     */
+    subscribe(callbacks: InputCallbacks): () => void;
+    /** Drain accumulated relative mouse motion into `out` (allocation-free). */
+    consumeMouseDelta(out: {
+        dx: number;
+        dy: number;
+    }): void;
+    get hasPointerLock(): boolean;
+    requestPointerLock(): void;
+    dispose(): void;
+    private onTouches;
+    private listen;
+}