Core guide

Input routing

Give the active scene first chance to handle raw keyboard, pointer, and gamepad input, then fall back to global handlers.

Try it: press Enter or Escape, click the button, move over the panel, or focus the text field and type.

Escape is consumed by the scene. The button and text field retain browser behavior.

checking browser support…
Action map: waiting for Confirm
  1. waiting for input…

How it works

The core router is browser-independent. Attach create_browser_input_adapter to a host element to normalize DOM events. The adapter listens in capture phase, skips editable controls by default, and applies preventDefault() only when a handler returns consume_and_prevent_default.

Scene handlers are registered automatically with scene lifecycle. The newest active scene runs first; global handlers receive events only when scenes pass them. Gamepad state is sampled when the owner calls poll().

Use create_action_map when gameplay should read named actions instead of raw device codes. Call update() once per simulation frame; rebinding and analog dead zones stay inside the action adapter.

Pass game.get_viewport() to the browser adapter when fixed-fit gameplay needs logical pointer coordinates. Raw host-relative coordinates remain available, and letterbox events are marked outside the logical content. Blur and visibility changes clear active keys and pointers.

Public types

  • InputEvent, InputDisposition, and InputRouter
  • SceneDefinition.input and Game.input
  • BrowserInputAdapter and BrowserGamepadAdapter
  • ViewportSize and optional logical pointer fields
  • GamepadState, GamepadSnapshot, and GamepadButtonSnapshot
  • create_action_map, ActionBinding, and ActionState

Minimum viable example

const router = create_input_router();
router.on_global((event) => {
  console.log(event);
  return "pass";
});

const browser_input = create_browser_input_adapter({
  host: game_host,
  router: game.input,
  viewport: game.get_viewport(),
});

const actions = create_action_map({
  router: game.input,
  bindings: {
    confirm: [{ device: "keyboard", code: "Enter" }, { device: "gamepad_button", button: 0 }],
  },
});
actions.update();
if (actions.get("confirm").just_pressed) confirm();

const gamepads = create_browser_gamepad_adapter({ router: game.input });
gamepads.poll();
console.log(gamepads.state.all());

Scope and limitations

Input routing handles raw devices, ownership, and browser default-action policy. Action mapping, rebinding, text input/IME, gesture recognition, pointer hit testing, and haptics remain separate capabilities. A physical gamepad must be connected and exposed to the browser before its state can be observed.