Input

BLIT386 provides DOM-backed input: pointer (mouse, touch, pen), keyboard (KeyboardEvent.code tracking and virtual face buttons), gamepad (up to four players via navigator.getGamepads()), and text accumulation for UI entry (BT.inputString).

All pointer coordinates are returned in logical display space (the displaySize from configure() or defaultConfig()), independent of the canvas's CSS or backing-buffer size.

Pointer slot model

The engine tracks up to four simultaneous pointers:

The engine tracks four pointer slots (indices 0-3). Overflow contacts beyond slot 3 are dropped silently.

Mouse slot (slot 0)

• Becomes valid on the first pointermove inside the canvas.
• Stays valid while the mouse remains over the canvas; cleared on pointerleave.
• Tracks all four buttons (A, B, C, D).
• Position is preserved after the mouse leaves; a new pointermove re-syncs it.
• A pointer event with an empty pointerType counts as the mouse, so synthetic events from test scripts work without it. Synthetic touch or pen events must set pointerType to 'touch' or 'pen'.

Touch / pen slots (slots 1-3)

• Allocated on pointerdown in the first free slot; freed on pointerup, pointercancel, or pointerleave.
• Only BTN_POINTER_A reports true while the contact is down; B, C, D always return false.
• Position and delta are preserved on release so release-frame code can read the final position and flick velocity.
• The engine calls setPointerCapture so off-canvas drags continue delivering events.

Position and delta

// Current position in display coordinates
const pos = BT.pointerPos(); // slot 0 (mouse)
const touch = BT.pointerPos(1); // slot 1 (first touch)

// Movement since the last frame
const delta = BT.pointerDelta(); // slot 0 (mouse)
const td = BT.pointerDelta(1); // slot 1

// Validity check - false means no live pointer in this slot
if (BT.isPointerActive()) {
  // Mouse is over the canvas
}

if (BT.isPointerActive(1)) {
  // Touch slot 1 is active
}

BT.pointerPos() returns Vector2i.zero() when the slot index is out of [0, 3] or the engine is not initialized. BT.pointerDelta() similarly returns Vector2i.zero() for invalid slots.

Zero-allocation reads

BT.pointerPos() and BT.pointerDelta() allocate a new Vector2i on every call. A demo reading pointer position or delta more than once per frame should reuse a scratch vector with the *To(out) counterparts instead:

BT.pointerPosTo(posScratch); // slot 0 (mouse)
BT.pointerDeltaTo(deltaScratch); // slot 0 (mouse)

// Same slot argument as pointerPos()/pointerDelta(), now trailing the out param.
BT.pointerPosTo(posScratch, 1); // slot 1 (first touch)

Both write (0, 0) into out under the same conditions pointerPos()/pointerDelta() return Vector2i.zero() for (invalid slot, engine not initialized), and return out itself so the call can be chained.

Buttons

Use BT.isDown(), BT.isPressed(), and BT.isReleased() with the BTN_POINTER_* constants. The second parameter is the pointer slot (defaults to 0):

// Hold detection
BT.isDown(BT.BTN_POINTER_A); // left mouse button held
BT.isDown(BT.BTN_POINTER_B); // right mouse button held
BT.isDown(BT.BTN_POINTER_C); // middle mouse button held
BT.isDown(BT.BTN_POINTER_D); // back / forward button held
BT.isDown(BT.BTN_POINTER_A, 1); // touch slot 1 in contact

// Edge detection (true only on the transition frame)
BT.isPressed(BT.BTN_POINTER_A); // left button just pressed
BT.isReleased(BT.BTN_POINTER_A); // left button just released
BT.isPressed(BT.BTN_POINTER_A, 2); // touch slot 2 just touched down

// Composite pointer mask (ANY-match semantics)
BT.isDown(BT.BTN_POINTER_ANY); // any pointer button on slot 0
BT.isDown(BT.BTN_POINTER_A | BT.BTN_POINTER_B); // left or right mouse button held

Mouse button mapping

The mapping follows the RetroBlit canonical order, not the DOM PointerEvent.button index:

Keyboard

Listeners attach to the canvas during BT.init(). For reliable delivery, ensure the canvas can receive focus (for example canvas.tabIndex = 0 and canvas.focus()). The library follows KeyboardEvent.code (physical-key semantics), not event.key layout text.

Raw key queries

Use these for direct key checks:

// Held state
if (BT.isKeyDown('KeyW')) {
  // W key held
}

// Edge and optional tick-based repeat (repeat interval in fixed-update ticks)
if (BT.isKeyPressed('ArrowUp', 10)) {
  // first press or repeat every 10 ticks while held
}

// Release edge
if (BT.isKeyReleased('Escape')) {
  // Escape released this frame
}

Any key and any button

For "press any key to start" screens and idle checks, ask about the whole keyboard (or one player's gamepad) instead of a named key:

if (BT.isAnyKeyPressed()) {
  // any key went down this tick, even if another key was already held
}

if (BT.isAnyKeyPressed(10)) {
  // same, then again every 10 ticks while keys stay held
}

if (BT.isAnyKeyReleased()) {
  // the last held key came up: nothing is held now, something was held before
}

if (BT.isAnyButtonPressed(0)) {
  // any button on player 0's gamepad went down
}

• isAnyKeyPressed fires on every new key, so holding A and then tapping B fires it for B. With a repeat rate, the cadence is counted from the earliest key still held.
• isAnyKeyReleased and isAnyButtonReleased mean "everything is up now". Letting go of one key while another stays down does not fire them; use BT.isKeyReleased(code) for per-key release edges. A gamepad disconnecting while buttons were held counts as the release.
• isAnyButton* covers the BTN_UP to BTN_SELECT buttons of that player's gamepad, and nothing else: no sticks, no triggers (neither the analog pull nor BTN_L2 / BTN_R2), no keyboard, no pointers. Use isAnyKey* for the keyboard. player defaults to 0.
• Call the pressed and released checks from update(), not render(). The held checks (isAnyKeyDown, isAnyButtonDown) are safe anywhere.
• The keyboard edges clear once per fixed-update tick, and are buffered so a fast tap is never dropped. The gamepad edges follow BT.isPressed and BT.isReleased instead: they roll over once per rendered frame, so on a display faster than targetFPS a gamepad edge can be missed by a frame that runs no update, and a frame that runs several updates reports the same edge to each of them. See Frame-timing semantics.

Face buttons (BTN_UP through BTN_SELECT)

Face button constants are bit flags. You can pass a single button or a combined mask; matching uses ANY semantics: BT.isDown(BT.BTN_A | BT.BTN_B) is true when either A or B is down.

For player 0 and player 1, face-button reads merge keyboard maps and gamepad state (logical OR). For player 2 and player 3, face-button reads use gamepad only.

BT.isPressed supports optional tick-based repeat via repeatRate (0 or omitted = edge only), matching BT.isKeyPressed semantics. For players 0 and 1, the keyboard-mapped half of isPressed / isReleased shares the same update()-only edge timing as BT.isKeyPressed above.

// Player 0 (default: WASD-style + Space / KeyB for A, etc.)
BT.isDown(BT.BTN_UP, 0);
BT.isPressed(BT.BTN_A, 0, 6); // edge + repeat every 6 ticks while held

// Player 1 (default: arrow keys + alternate bindings)
BT.isDown(BT.BTN_LEFT, 1);

// Composite face-button masks (ANY-match semantics)
BT.isDown(BT.BTN_ABXY, 0); // A, B, X, or Y for player 0
BT.isDown(BT.BTN_SHOULDER, 1); // L or R shoulder for player 1

Triggers: analog or digital

Each trigger is available two ways. BT.getAxis(BT.AXIS_TRIGGER_L) / AXIS_TRIGGER_R return the pull from 0 to 1. BT.BTN_L2 and BT.BTN_R2 (mask BT.BTN_TRIGGER) work with BT.isDown, BT.isPressed and BT.isReleased and turn on at 50% pull or more, judged from the analog value alone (the browser's own pressed flag is ignored). The threshold is fixed. BTN_L and BTN_R are still the shoulder buttons, not the triggers.

Trigger buttons are gamepad only. Keyboard players never trigger them and BT.inputMap ignores them, so give keyboard players an explicit fallback if your game needs one:

// Either trigger on player 0 (gamepad only, ANY-match like other masks)
BT.isDown(BT.BTN_TRIGGER, 0);

// Same action with a keyboard fallback
const fire = BT.isPressed(BT.BTN_R2, 0) || BT.isPressed(BT.BTN_A, 0);

Keyboard layouts

HardwareSettings.keyboardLayout picks which built-in map the two keyboard players start with:

Face and system buttons are the same in both layouts (player 0: Space / B for A, N for B, 5 for Start, Escape for Select; player 1: ; / Numpad 1, ' / Numpad 2, Backspace / Numpad /). 'single' also turns on isCapturingKeyboardScroll so the arrows stop scrolling the host page, unless configure() sets that flag itself.

import { type HardwareSettings } from 'blit386';

function configure(): Partial<HardwareSettings> {
  return {
    keyboardLayout: 'single', // one player: WASD and the arrows both steer player 0
  };
}

The layout is applied before your init() runs, so BT.inputMap calls in init() still override single buttons, and BT.inputMapReset() restores the active layout's defaults. Changing it during a hot reload triggers a full reload.

Built-in defaults are exposed as read-only tables (same values the engine starts with):

• BT.DEFAULT_KEYBOARD_PLAYER1 / BT.DEFAULT_KEYBOARD_PLAYER2 - 'versus'
• BT.DEFAULT_KEYBOARD_SINGLE_PLAYER1 / BT.DEFAULT_KEYBOARD_SINGLE_PLAYER2 - 'single'

Remapping (BT.inputMap / BT.inputMapReset)

Override bindings at runtime. The first argument is the zero-based player index (0 or 1 only; other values are ignored). The second is the face button constant. Remaining arguments are KeyboardEvent.code strings.

BT.inputMap(0, BT.BTN_A, 'Space');
BT.inputMap(0, BT.BTN_UP, 'ArrowUp', 'KeyW'); // either key triggers UP for player 0
BT.inputMap(1, BT.BTN_START, 'Enter', 'NumpadEnter');

// Restore the active keyboardLayout's defaults for both keyboard players (does not affect pointer or gamepad state)
BT.inputMapReset();

Pass no key codes to clear keyboard bindings for that player and button until you map again:

BT.inputMap(0, BT.BTN_X); // player 0 X has no keyboard keys until remapped

Gamepad API

BT.isGamepadConnected(0); // true when player 0 has a connected gamepad
BT.gamepadCount; // number of connected gamepads (0..4)

BT.getAxis(BT.AXIS_LEFT_X, 0); // -1.0 .. 1.0 (dead-zone filtered)
BT.getAxis(BT.AXIS_TRIGGER_L, 0); // 0.0 .. 1.0

Axis constants:

• AXIS_LEFT_X, AXIS_LEFT_Y
• AXIS_RIGHT_X, AXIS_RIGHT_Y
• AXIS_TRIGGER_L, AXIS_TRIGGER_R

Player constants:

• PLAYER_ONE (0)
• PLAYER_TWO (1)
• PLAYER_THREE (2)
• PLAYER_FOUR (3)

Text input buffer

BT.inputString returns characters accumulated from filtered beforeinput (and Tab / Escape where needed). The buffer clears at the end of each fixed update step (read it during update()). See public JSDoc on BT.inputString for details.

Scroll delta

// Accumulated vertical scroll for the current frame, in pixels
const scroll = BT.pointerScrollDelta;

if (scroll > 0) {
  // Scrolled down
}
if (scroll < 0) {
  // Scrolled up
}

The value aggregates all WheelEvent.deltaY values received since the last frame, normalizing line and page delta modes to pixels. It resets to zero each frame.

Wheel capture is opt-in. Set isCapturingPointerScroll: true in configure() so the engine calls preventDefault() on canvas wheel events and fills BT.pointerScrollDelta. When the flag is omitted (the default), the host page scrolls normally while the pointer is over the canvas and BT.pointerScrollDelta stays 0.

The same flag also gates canvas.style.touch-action. When enabled, touch-action is none so the canvas does not compete with the wheel capture above. When the flag is omitted (the default) and no other capture source is active, touch-action is pan-y, so touch devices can still tap-hold-scroll the host page past the canvas.

The overlay palette grid still captures wheel while the pointer is over its band, even without the configure flag, so scrolling palette rows does not move the page. The same palette-band capture also forces touch-action to none for as long as a pointer is over the band, independent of the configure flag.

import { type HardwareSettings } from 'blit386';

function configure(): Partial<HardwareSettings> {
  return {
    isCapturingPointerScroll: true,
  };
}

Keyboard scroll capture is also opt-in. Set isCapturingKeyboardScroll: true in configure() so the engine calls preventDefault() on canvas keydown for keys that scroll the host page by default (arrow keys, Space, PageUp/PageDown, Home, End). When the flag is omitted (the default), those keys still scroll the page while the canvas is focused - except under keyboardLayout: 'single', which turns capture on unless you set the flag to false.

import { type HardwareSettings } from 'blit386';

function configure(): Partial<HardwareSettings> {
  return {
    isCapturingKeyboardScroll: true,
  };
}

Cursor control

// In init(): hide the OS cursor and draw your own crosshair / sprite
BT.hideCursor();

// Restore at any time
BT.showCursor();

hideCursor() sets canvas.style.cursor = 'none'. showCursor() restores whatever the cursor was at attach() time. Both are no-ops before the engine is initialized. The cursor is restored automatically when the engine stops.

Frame-timing semantics

Pointer and gamepad previous-state rollover happens at the end of each animation frame, after demo.update() and demo.render() have run. Keyboard press/release edges and BT.inputString align with the fixed update rate (targetFPS), not the display refresh rate:

• On a 120 Hz monitor with targetFPS: 60, render() may run twice per update(). Keyboard edges are buffered on DOM events and consumed on the next fixed update so fast taps are not dropped between render-only frames.
• pointerDelta() reflects movement between the last update() and the current one.
• Gamepad current state is polled from the Gamepad API once per render frame, immediately after that frame's previous-state rollover. Button/axis queries read that cached snapshot and never trigger a poll themselves.
• Read BT.inputString during update(); the buffer clears at the end of each fixed update step.

Pointer transitions:

• Any pointer event that fires between two animation frames is visible as a transition on the next update() call.
• A pointer button press that lands in a frame that runs no update (a display faster than targetFPS) is carried to the next frame that does, so BT.isPressed never misses a click. Only update() sees the carried press; the engine overlay and other render-side readers still see each press once.

Page-interaction guards

attach() installs guards on the canvas to prevent browser defaults from interfering:

• wheel with { passive: false } - when isCapturingPointerScroll is true (or the overlay forces capture over the palette band), preventDefault() stops page scroll and the delta feeds BT.pointerScrollDelta. When capture is off, the page scrolls normally.
• keydown - when isCapturingKeyboardScroll is true, preventDefault() stops page scroll for arrow keys, Space, PageUp/PageDown, Home, and End while the canvas is focused. When capture is off, those keys keep their browser defaults.
• canvas.style.touchAction - when isCapturingPointerScroll is true (or the overlay forces capture over the palette band), touch-action is 'none', preventing iOS Safari pinch-zoom, double-tap-zoom, and touch scroll from competing with capture. When capture is off, touch-action is 'pan-y', so the host page still scrolls vertically past the canvas on touch devices.
• contextmenu with preventDefault() - prevents the OS context menu on right-click so BTN_POINTER_B works.

detach() reverses the pointer and keyboard guards and removes all event listeners. This happens automatically when the engine stops or when demo.init() throws.

Coordinate conversion

Client coordinates from DOM events are converted to display space using the canvas bounding rect:

display_x = floor((clientX - rect.left) / rect.width  * displaySize.x)
display_y = floor((clientY - rect.top)  / rect.height * displaySize.y)

Coordinates are clamped to [0, displaySize - 1] on each axis. The conversion is skipped when the canvas has zero size (no layout yet) to avoid NaN coordinates.

Converting your own DOM events

BT.nativeScreenToDisplayPos(clientX, clientY) runs the same conversion for coordinates the engine does not track itself, such as a file dropped onto the canvas. It returns a new Vector2i, or null when there is no valid position to report:

• the engine is not initialized;
• the canvas has zero width or height (no layout yet);
• a coordinate is not finite.

A point outside the canvas is not an error: it clamps to the nearest edge pixel, exactly as pointer input does. The canvas rect is read on every call, so the result stays correct after a resize or page scroll. It does not depend on pointer state, so it works before the first pointer event and for events the pointer subsystem never sees.

canvas?.addEventListener('dragover', (event) => event.preventDefault());
canvas?.addEventListener('drop', (event) => {
  event.preventDefault();

  const pos = BT.nativeScreenToDisplayPos(event.clientX, event.clientY);

  if (pos !== null) {
    console.log(`dropped at display (${pos.x}, ${pos.y})`);
  }
});

Implementation notes

API history

See also

Last updated on October 18, 2026