---
name: ferret-input-ui
description: Use to bind input and build the HUD in a Ferret game: actions and bindings per device kind (console, keyboard, gamepad, touch), touch controls, prompts, toasts, loading screen and the cursor/A/B menu with UIService and MenuModel.
---

# Input actions and UI

## When to use
Adding controls, showing a prompt or HUD line, building a menu, testing input.

## The model
A game declares **actions** (`button` or `axis2`) and per-kind **bindings** (`keyboard`, `console`, `gamepad`, `touch`). `InputService` samples every fixed step: `down`, `pressed`, `released`, `axis`, `lookDelta`; `prompt(a)` returns the label of the current binding for UI text. On OS Beroun the cursor, A and B reach the page as keys, so `console` is an ordinary key map.

## Steps
1. Declare `actions` and `bindings`; pass both to `createGame`.
2. Use `input.pressed('use')` in `onFixedUpdate`, never raw key codes.
3. Phones and tablets get `TouchControls` from the touch bindings automatically (`touchControls: false` to opt out).
4. UI: `setHud(key, text|null)`, `setPrompt(text)`, `toast(text)` (at most three at once), `openMenu(def)` with `MenuModel` (up/down/accept/back), `pauseMenu`.
5. In tests: `inject(action, value)`; `enabled = false` while a menu or cutscene is up.

## Check afterwards
Play every action with each binding kind; open the menu with only cursor, A and B; the prompt text matches the active kind.

## What usually goes wrong
- Binding extra console buttons: apps use the cursor, A (Enter) and B (Exit) only unless the owner allows more.
- Writing menu code that needs a mouse: use `MenuModel` so D-pad, A, B, mouse and touch all work.
- HUD sizes in pixels instead of `em`.
- Forgetting to disable input while a menu is open.

## Files

- `reference/input-ui.md` — Actions over every device, on-screen controls for touch, and the HTML overlay for HUD, prompts, toasts and menus.
- `reference/api-input.md` — every export of `@ferret/input` with signature and doc comment
- `reference/api-ui.md` — every export of `@ferret/ui` with signature and doc comment