Input Documentation
Input Methods
b8.Input.consumeTap()
Consumes the pending tap, if any, so that it does not trigger multiple UI interactions.
This should be called after handling a tap to ensure that the same tap does not trigger multiple buttons or regions.
b8.Input.getKeys(key)
Gets an array of keys that correspond to a given key. For example, pressing “W” also maps to “ArrowUp”.
Parameters
- key (string): The key to get aliases for.
Returns
- (string[]): An array of key names.
b8.Input.hasTap()
Checks if there is a pending tap (pointer down and up) that has not yet been consumed.
This is used for immediate-mode UI interactions, where a tap should trigger a button or region only once.
Returns
- (boolean): True if there is a pending tap, false otherwise.
b8.Input.init()
Initializes the input system.
b8.Input.keyHeld(keyName)
Checks if a key is currently held down.
Parameters
- keyName (string): The name of the key to check.
Returns
- (boolean): Whether the key is currently held down.
b8.Input.keyJustPressed(keyName)
Checks if a key was just pressed in the current frame.
Parameters
- keyName (string): The name of the key to check.
Returns
- (boolean): Whether the key was just pressed.
b8.Input.onEndFrame()
Clears the list of keys that were just pressed. Should be called at the end of each frame.
b8.Input.onKeyDown(e)
Handles keydown events, adding the key to the just pressed and held sets. Resolves any pending asynchronous key events.
Parameters
- e (KeyboardEvent): The event object.
b8.Input.onKeyUp(e)
Handles keyup events, removing the key from the held set.
Parameters
- e (KeyboardEvent): The event object.
b8.Input.onPointerCancel()
Resets the game input state. This is useful when restarting a level or resetting the game.
This clears all held keys, just pressed keys, and pointer state.
b8.Input.onPointerDown()
Handles pointer down events.
Marks the pointer as pressed and updates position.
b8.Input.onPointerMove()
Handles pointer move events, updating the pointer position.
This is used for hover states and dragging, but does not trigger any immediate-mode UI interactions on its own.
b8.Input.onPointerUp()
Handles pointer up events.
Marks the pointer as released.
b8.Input.pointerHeld()
Checks if the pointer is currently held down.
Returns
- (boolean): True if the pointer is held down, false otherwise.
b8.Input.pointerJustPressed()
Checks if the pointer was pressed this frame.
b8.Input.pointerJustReleased()
Checks if the pointer was released this frame.
b8.Input.pointerTile()
Gets the pointer position in tile coordinates.
Returns
- ({col: number, row: number): }
b8.Input.pointerX()
Gets the pointer X position in canvas pixels.
b8.Input.pointerY()
Gets the pointer Y position in canvas pixels.
b8.Input.pushContext(name [,opts])
Pushes a new input context onto the stack.
Parameters
- name (string): The name of the context.
- [opts] (Object): Options for the context. (default: {})
b8.Input.readKeyAsync()
Reads a key asynchronously. Returns a promise that resolves to the key that was pressed.
Async key reads always pull from the active context. This prevents async input from racing gameplay polling.
Resolves with the full logical key list for the next key event.
Returns
- (Promise<string[]>): A promise that resolves to the pressed key aliases.
b8.Input.readLine([prompt] [,initString] [,maxLen] [,maxWidth]) async
Reads a line of text asynchronously. Handles user input to build a string until the Enter key is pressed.
readLine runs inside a capture context so that gameplay input is fully suspended while typing.
Parameters
- [prompt] (string): text:’] Prompt text to display. (default: ‘Enter)
- [initString] (string): Initial input value. (default: ‘’)
- [maxLen] (number): Maximum allowed length. (default: 100)
- [maxWidth] (number): Maximum width before wrapping. (default: -1)
Returns
- (Promise<string>): A promise that resolves to the entered text.
b8.Input.readPointerAsync()
Reads a pointer asynchronously. Returns a promise that resolves to the pointer position.
Returns
- (Promise<{x: number, y: number): >} A promise that resolves to the pointer position.
b8.Input.reset()
Resets the input state, clearing all held and just pressed keys. This is useful when restarting a game or resetting input state.
b8.Input.tapTile()
Gets the tile coordinates of the pending tap, if any. Returns null if there is no pending tap.
This is used for immediate-mode UI interactions, where a tap should trigger a button or region only once.
Returns
- ({col: number, row: number): | null} The tile coordinates of the tap, or null if there is no tap.
b8.Input.withContext(name, opts, fn) async
Executes a function within a temporary input context.
Pushes a new context, runs the provided function, and then pops the context.
Parameters
- name (string): The name of the temporary context.
- opts (Object): Options for the context.
- fn (Function): The function to execute within the context.
Returns
- (Promise<any>): The result of the executed function.
