@flare-engine/input 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grzegorz Otto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @flare-engine/input
+
+Pointer / touch / gesture / virtual-control / gamepad input. `InputManager` polls per frame; `Pointer` exposes primary touch with `isDown` / `justPressed` / `delta`; `GestureDetector` emits tap / swipe / pinch / long-press; data-only `VirtualJoystick` + `VirtualButton` state (RN components live in `@flare-engine/react`); `GamepadSource` + `RemapTable` cover gamepad polling and persistent rebinds.
+
+## Install
+
+```sh
+bun add @flare-engine/input
+```
+
+## Usage
+
+```ts
+import { InputManager, GestureDetector, createWebGamepadSource } from '@flare-engine/input';
+
+const input = new InputManager();
+const gestures = new GestureDetector();
+gestures.onSwipe.add((e) => console.log(e.direction));
+
+input.pollGamepads(createWebGamepadSource(navigator));
+input.update();
+```
+
+See [API spec](../../docs/design/api-specs.md#flare-engineinput--6kb-gzip) and [skill reference](../../.github/skills/flare-input/SKILL.md).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,344 @@
+import { Vec2 } from '@flare-engine/math';
+import { Signal } from '@flare-engine/events';
+
+/** State of a single pointer (primary touch or mouse). */
+interface Pointer {
+    /** Current position in screen coordinates. */
+    position: Vec2;
+    /** Position delta since last frame. */
+    delta: Vec2;
+    /** Whether the pointer is currently held down. */
+    isDown: boolean;
+    /** True only on the frame the pointer was pressed. */
+    justPressed: boolean;
+    /** True only on the frame the pointer was released. */
+    justReleased: boolean;
+}
+/** State of a single touch point in a multitouch scenario. */
+interface TouchPoint {
+    /** Unique touch identifier. */
+    id: number;
+    /** Current position in screen coordinates. */
+    position: Vec2;
+    /** Whether this touch is currently active. */
+    isDown: boolean;
+}
+/** Create a default pointer state. */
+declare function createPointer(): Pointer;
+/**
+ * Update pointer state for a new frame.
+ * Call this at the start of each frame to clear per-frame flags.
+ */
+declare function resetPointerFrame(pointer: Pointer): void;
+/** Feed a pointer-down event into the pointer state. */
+declare function pointerDown(pointer: Pointer, x: number, y: number): void;
+/** Feed a pointer-move event into the pointer state. */
+declare function pointerMove(pointer: Pointer, x: number, y: number): void;
+/** Feed a pointer-up event into the pointer state. */
+declare function pointerUp(pointer: Pointer, x: number, y: number): void;
+
+/**
+ * Gamepad — poll-based state for a single connected controller.
+ *
+ * Buttons and axes are indexed against the W3C "Standard Gamepad" mapping by
+ * default. Callers can translate raw indices via `remap.ts` before feeding
+ * snapshots into `updateGamepadFromSnapshot`.
+ */
+/** W3C Standard Gamepad button indices. */
+declare const GamepadButton: {
+    readonly A: 0;
+    readonly B: 1;
+    readonly X: 2;
+    readonly Y: 3;
+    readonly LB: 4;
+    readonly RB: 5;
+    readonly LT: 6;
+    readonly RT: 7;
+    readonly Back: 8;
+    readonly Start: 9;
+    readonly LS: 10;
+    readonly RS: 11;
+    readonly DpadUp: 12;
+    readonly DpadDown: 13;
+    readonly DpadLeft: 14;
+    readonly DpadRight: 15;
+    readonly Home: 16;
+};
+type GamepadButtonId = (typeof GamepadButton)[keyof typeof GamepadButton];
+/** W3C Standard Gamepad axes. */
+declare const GamepadAxis: {
+    readonly LeftX: 0;
+    readonly LeftY: 1;
+    readonly RightX: 2;
+    readonly RightY: 3;
+};
+type GamepadAxisId = (typeof GamepadAxis)[keyof typeof GamepadAxis];
+interface GamepadButtonState {
+    pressed: boolean;
+    value: number;
+    /** True for exactly one frame after a press. */
+    pressedThisFrame: boolean;
+    /** True for exactly one frame after a release. */
+    releasedThisFrame: boolean;
+}
+interface GamepadState {
+    connected: boolean;
+    id: string;
+    index: number;
+    buttons: GamepadButtonState[];
+    axes: number[];
+    /** Monotonically increasing timestamp from the source (ms). */
+    timestamp: number;
+}
+/** Raw snapshot from a `GamepadSource` — values only, no derived state. */
+interface GamepadSnapshot {
+    id: string;
+    index: number;
+    buttons: {
+        pressed: boolean;
+        value: number;
+    }[];
+    axes: number[];
+    timestamp: number;
+}
+declare function createGamepadState(index?: number, buttonCount?: number, axisCount?: number): GamepadState;
+/**
+ * Apply a fresh snapshot to an existing `GamepadState` in place. Derived
+ * `pressedThisFrame` / `releasedThisFrame` flags are recomputed from the
+ * previous `pressed` value.
+ *
+ * `deadZone` in [0, 1). Values at or below are treated as 0.
+ */
+declare function updateGamepadFromSnapshot(state: GamepadState, snapshot: GamepadSnapshot | null, deadZone?: number): void;
+/** Reset just the per-frame edge flags. Call when advancing a frame without a fresh snapshot. */
+declare function resetGamepadFrame(state: GamepadState): void;
+declare function isButtonDown(state: GamepadState, button: number): boolean;
+declare function wasButtonPressed(state: GamepadState, button: number): boolean;
+declare function wasButtonReleased(state: GamepadState, button: number): boolean;
+declare function getAxis(state: GamepadState, axis: number): number;
+
+/**
+ * Platform abstraction for sampling connected gamepads.
+ *
+ * `poll()` returns one snapshot per slot (typically up to 4). Unconnected
+ * slots return `null`. Implementations:
+ *
+ * - `createWebGamepadSource()` wraps the W3C `navigator.getGamepads` API.
+ * - Native implementations (e.g., `react-native-gamepad`) inject their own
+ *   via the `GamepadSource` interface — the package itself ships no native deps.
+ */
+interface GamepadSource {
+    poll(): (GamepadSnapshot | null)[];
+}
+interface NavigatorLike {
+    getGamepads?: () => (WebGamepad | null)[];
+}
+interface WebGamepad {
+    id: string;
+    index: number;
+    connected: boolean;
+    timestamp: number;
+    buttons: readonly {
+        pressed: boolean;
+        value: number;
+    }[];
+    axes: readonly number[];
+}
+/**
+ * Wrap `navigator.getGamepads()` (W3C Gamepad API). If `nav` is not supplied,
+ * uses `globalThis.navigator`. Returns an empty array when the API is absent.
+ */
+declare function createWebGamepadSource(nav?: NavigatorLike): GamepadSource;
+
+/**
+ * Button / axis remap table.
+ *
+ * `buttons[logicalId] = physicalIndex` — to poll A, read
+ * `snapshot.buttons[table.buttons[GamepadButton.A]]`.
+ *
+ * `axes` maps logical axis id → `{ index, invert, scale }`. Most games invert
+ * Y on some controllers; `scale` supports half-range triggers.
+ */
+interface AxisMap {
+    index: number;
+    invert: boolean;
+    scale: number;
+}
+interface RemapTable {
+    buttons: number[];
+    axes: AxisMap[];
+}
+declare function createIdentityRemap(buttonCount?: number, axisCount?: number): RemapTable;
+/** Apply a remap table to a raw snapshot, returning a new snapshot with logical ordering. */
+declare function applyRemap(snapshot: GamepadSnapshot, table: RemapTable): GamepadSnapshot;
+/**
+ * Minimal storage contract — matches `@flare-engine/storage` `StorageAdapter`,
+ * but declared locally so this package does not take a hard dep on storage.
+ */
+interface RemapStore {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+}
+/** Persist a remap table under the given key. Throws on invalid table shape. */
+declare function saveRemap(store: RemapStore, key: string, table: RemapTable): Promise<void>;
+/** Load a remap table. Returns `null` if absent or malformed. */
+declare function loadRemap(store: RemapStore, key: string): Promise<RemapTable | null>;
+
+/**
+ * InputManager provides a polling-based input model.
+ *
+ * Call `update()` once per frame (before game logic) to snapshot input state.
+ * Feed events from the platform (RN touch/gesture handlers) via the on* methods.
+ */
+declare class InputManager {
+    /** Primary pointer (first touch or mouse). */
+    readonly pointer: Pointer;
+    /** All active touch points. */
+    readonly touches: TouchPoint[];
+    private _touchMap;
+    private _gamepads;
+    private _gamepadDeadZone;
+    private _gamepadRemaps;
+    /** Call once per frame to reset per-frame flags. */
+    update(): void;
+    /** Feed a touch/pointer begin event. */
+    onPointerDown(id: number, x: number, y: number): void;
+    /** Feed a touch/pointer move event. */
+    onPointerMove(id: number, x: number, y: number): void;
+    /** Feed a touch/pointer end event. */
+    onPointerUp(id: number, x: number, y: number): void;
+    /** Access the gamepad state at `index`. Allocates on first access. */
+    gamepad(index: number): GamepadState;
+    /** Dead zone in [0, 1). Axes at or below this magnitude read as 0. */
+    setGamepadDeadZone(deadZone: number): void;
+    /** Install a remap table for a specific gamepad index. Pass `null` to clear. */
+    setGamepadRemap(index: number, table: RemapTable | null): void;
+    /** Poll all gamepads from the given source, applying remap + dead zones. */
+    pollGamepads(source: GamepadSource): void;
+    private _addOrUpdateTouch;
+    private _removeTouch;
+}
+
+/** Swipe direction. */
+type SwipeDirection = 'left' | 'right' | 'up' | 'down';
+/** Gesture detection configuration. */
+interface GestureConfig {
+    /** Max time (seconds) for a tap (default 0.3). */
+    tapMaxDuration?: number;
+    /** Max distance (px) for a tap (default 20). */
+    tapMaxDistance?: number;
+    /** Min time (seconds) for a long press (default 0.5). */
+    longPressMinDuration?: number;
+    /** Min distance (px) for a swipe (default 50). */
+    swipeMinDistance?: number;
+    /** Max time (seconds) for a swipe (default 0.4). */
+    swipeMaxDuration?: number;
+}
+/** Swipe event data. */
+interface SwipeEvent {
+    direction: SwipeDirection;
+    distance: number;
+    duration: number;
+}
+/** Pinch event data. */
+interface PinchEvent {
+    /** Scale factor (>1 = spread, <1 = pinch). */
+    scale: number;
+    /** Center point between the two touches. */
+    center: Vec2;
+}
+/**
+ * GestureDetector recognizes tap, long press, swipe, and pinch gestures
+ * from raw pointer events.
+ */
+declare class GestureDetector {
+    readonly onTap: Signal<Vec2>;
+    readonly onLongPress: Signal<Vec2>;
+    readonly onSwipe: Signal<SwipeEvent>;
+    readonly onPinch: Signal<PinchEvent>;
+    private tapMaxDuration;
+    private tapMaxDistance;
+    private longPressMinDuration;
+    private swipeMinDistance;
+    private swipeMaxDuration;
+    private _startPos;
+    private _startTime;
+    private _isTracking;
+    private _longPressFired;
+    private _pinchStartDistance;
+    private _pinchTouches;
+    constructor(config?: GestureConfig);
+    /** Feed a pointer-down event. */
+    pointerDown(x: number, y: number): void;
+    /** Feed a pointer-up event. */
+    pointerUp(x: number, y: number, elapsedSinceDown: number): void;
+    /**
+     * Update gesture tracking. Call each frame with dt.
+     * @param dt Delta time in seconds.
+     * @param currentX Current pointer X.
+     * @param currentY Current pointer Y.
+     */
+    update(dt: number, currentX: number, currentY: number): void;
+    /**
+     * Feed a two-finger pinch update. Call when two touches are active.
+     * @param t1 First touch position.
+     * @param t2 Second touch position.
+     */
+    pinchUpdate(t1: Vec2, t2: Vec2): void;
+    /** Call when pinch ends (fewer than 2 touches). */
+    pinchEnd(): void;
+}
+
+/** Virtual joystick configuration. */
+interface VirtualJoystickConfig {
+    /** Dead zone radius in pixels (default 10). */
+    deadZone?: number;
+    /** Maximum radius in pixels (default 50). */
+    maxRadius?: number;
+}
+/** Virtual joystick state — pure data, no UI. */
+interface VirtualJoystickState {
+    /** Whether the joystick is currently being touched. */
+    active: boolean;
+    /** Normalized direction vector (-1 to 1 per axis). */
+    direction: Vec2;
+    /** Magnitude 0-1 (0 = center/dead zone, 1 = max radius). */
+    magnitude: number;
+    /** Raw offset from center in pixels. */
+    offset: Vec2;
+}
+/** Create a default joystick state. */
+declare function createJoystickState(): VirtualJoystickState;
+/**
+ * Update joystick state from a touch event.
+ *
+ * @param state The joystick state to update.
+ * @param centerX The joystick center X in screen pixels.
+ * @param centerY The joystick center Y in screen pixels.
+ * @param touchX The current touch X in screen pixels.
+ * @param touchY The current touch Y in screen pixels.
+ * @param config Joystick configuration.
+ */
+declare function updateJoystick(state: VirtualJoystickState, centerX: number, centerY: number, touchX: number, touchY: number, config?: VirtualJoystickConfig): void;
+/** Reset joystick state when touch is released. */
+declare function releaseJoystick(state: VirtualJoystickState): void;
+
+/** Virtual button state — pure data, no UI. */
+interface VirtualButtonState {
+    /** Whether the button is currently pressed. */
+    isPressed: boolean;
+    /** Whether the button was just pressed this frame. */
+    justPressed: boolean;
+    /** Whether the button was just released this frame. */
+    justReleased: boolean;
+}
+/** Create a default button state. */
+declare function createButtonState(): VirtualButtonState;
+/** Call at the start of each frame to reset per-frame flags. */
+declare function resetButtonFrame(state: VirtualButtonState): void;
+/** Call when the button is pressed. */
+declare function pressButton(state: VirtualButtonState): void;
+/** Call when the button is released. */
+declare function releaseButton(state: VirtualButtonState): void;
+
+export { type AxisMap, GamepadAxis, type GamepadAxisId, GamepadButton, type GamepadButtonId, type GamepadButtonState, type GamepadSnapshot, type GamepadSource, type GamepadState, type GestureConfig, GestureDetector, InputManager, type PinchEvent, type Pointer, type RemapStore, type RemapTable, type SwipeDirection, type SwipeEvent, type TouchPoint, type VirtualButtonState, type VirtualJoystickConfig, type VirtualJoystickState, applyRemap, createButtonState, createGamepadState, createIdentityRemap, createJoystickState, createPointer, createWebGamepadSource, getAxis, isButtonDown, loadRemap, pointerDown, pointerMove, pointerUp, pressButton, releaseButton, releaseJoystick, resetButtonFrame, resetGamepadFrame, resetPointerFrame, saveRemap, updateGamepadFromSnapshot, updateJoystick, wasButtonPressed, wasButtonReleased };