116 lines
3.6 KiB
TypeScript
116 lines
3.6 KiB
TypeScript
/**
|
||
* Copyright (c) 2026 Dominic Masters
|
||
*
|
||
* This software is released under the MIT License.
|
||
* https://opensource.org/licenses/MIT
|
||
*/
|
||
|
||
/**
|
||
* Opaque type alias for input action identifiers.
|
||
* Use the `INPUT_ACTION_*` constants rather than raw numbers.
|
||
*/
|
||
type InputAction = number;
|
||
|
||
/**
|
||
* Polling-based input queries and button rebinding.
|
||
*/
|
||
interface InputNamespace {
|
||
/**
|
||
* Returns `true` while the given action is held down this frame.
|
||
*
|
||
* @param action - An `INPUT_ACTION_*` constant.
|
||
*
|
||
* @example
|
||
* if (Input.isDown(INPUT_ACTION_UP)) { player.moveUp(); }
|
||
*/
|
||
isDown(action: InputAction): boolean;
|
||
|
||
/**
|
||
* Returns `true` if the given action was held down in the previous frame.
|
||
*
|
||
* @param action - An `INPUT_ACTION_*` constant.
|
||
*/
|
||
wasDown(action: InputAction): boolean;
|
||
|
||
/**
|
||
* Returns `true` on the first frame the action transitions from up → down.
|
||
*
|
||
* @param action - An `INPUT_ACTION_*` constant.
|
||
*
|
||
* @example
|
||
* if (Input.pressed(INPUT_ACTION_ACCEPT)) { confirmSelection(); }
|
||
*/
|
||
pressed(action: InputAction): boolean;
|
||
|
||
/**
|
||
* Returns `true` on the first frame the action transitions from down → up.
|
||
*
|
||
* @param action - An `INPUT_ACTION_*` constant.
|
||
*/
|
||
released(action: InputAction): boolean;
|
||
|
||
/**
|
||
* Returns the continuous (analog) value of an action in the range `0.0–1.0`.
|
||
* Digital buttons return either `0` or `1`.
|
||
*
|
||
* @param action - An `INPUT_ACTION_*` constant.
|
||
*
|
||
* @example
|
||
* const speed = Input.getValue(INPUT_ACTION_UP) * MAX_SPEED;
|
||
*/
|
||
getValue(action: InputAction): number;
|
||
|
||
/**
|
||
* Returns a signed axis value in the range `-1.0–1.0`, derived from two
|
||
* opposing actions: `getValue(pos) - getValue(neg)`.
|
||
*
|
||
* @param neg - Action mapped to the negative direction.
|
||
* @param pos - Action mapped to the positive direction.
|
||
*
|
||
* @example
|
||
* const moveX = Input.axis(INPUT_ACTION_LEFT, INPUT_ACTION_RIGHT);
|
||
*/
|
||
axis(neg: InputAction, pos: InputAction): number;
|
||
|
||
/**
|
||
* Rebinds a physical button (by name) to a logical input action at runtime.
|
||
* Throws if `buttonName` is unknown or `action` is out of range.
|
||
*
|
||
* @param buttonName - Platform-specific button identifier string (e.g. `"A"`, `"START"`).
|
||
* @param action - Target `INPUT_ACTION_*` constant.
|
||
*
|
||
* @example
|
||
* Input.bind("A", INPUT_ACTION_ACCEPT);
|
||
*/
|
||
bind(buttonName: string, action: InputAction): void;
|
||
}
|
||
|
||
/** Polling-based input system. */
|
||
declare var Input: InputNamespace;
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// Input action constants.
|
||
// Injected as plain global variables by the engine at startup.
|
||
// ---------------------------------------------------------------------------
|
||
|
||
/** Move / navigate upward. */
|
||
declare var INPUT_ACTION_UP: InputAction;
|
||
/** Move / navigate downward. */
|
||
declare var INPUT_ACTION_DOWN: InputAction;
|
||
/** Move / navigate left. */
|
||
declare var INPUT_ACTION_LEFT: InputAction;
|
||
/** Move / navigate right. */
|
||
declare var INPUT_ACTION_RIGHT: InputAction;
|
||
/** Confirm / accept the current selection. */
|
||
declare var INPUT_ACTION_ACCEPT: InputAction;
|
||
/** Cancel / go back. */
|
||
declare var INPUT_ACTION_CANCEL: InputAction;
|
||
/** Emergency quit (e.g. hold-to-exit on embedded platforms). */
|
||
declare var INPUT_ACTION_RAGEQUIT: InputAction;
|
||
/** Toggle the developer console overlay. */
|
||
declare var INPUT_ACTION_CONSOLE: InputAction;
|
||
/** Pointer / cursor horizontal position (analog). */
|
||
declare var INPUT_ACTION_POINTERX: InputAction;
|
||
/** Pointer / cursor vertical position (analog). */
|
||
declare var INPUT_ACTION_POINTERY: InputAction;
|