# Key prompts that follow the controls (ui.prompts)

Part of the [menus and screens guide](guide:ui-screens).

## What it is for

`ui.prompts` decides which key hints are on screen, and writes them: "[E] Open door" on a keyboard, "[A] Continue" on a gamepad.
No key is written in the kit. Every label comes from `input.actions` (`labelFor`, `promptFor`), so it follows the project
bindings, the player's remapping and the device used last. The kit draws nothing itself: `view()` gives what an interface
draws, and the web player shows it as a `ui.webui` fragment.

**No key is shown by default.** The help bar and the context row are off, and the controls live in the options menu. Turn one
on for a tutorial or for a game that relies on contextual prompts. A prompt pushed with `show()` is always shown.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "ui.prompts" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "ui.prompts",
                              config: { "bar": true, "context": true, "maxItems": 4 } }
```

The kit needs `input.actions` and `game.engine`.

## First example

<!-- test: kits/game_engine/host/tests/ui_prompts.rs::the_help_bar_lists_the_buttons_of_the_moment_and_a_pushed_prompt_leads_the_context -->
With `bar` and `context` on and `maxItems: 2`, the bar lists the button actions of the moment ("[Left Shift] Sprint",
"[Space] Jump"). A tutorial step pushes a prompt, which leads the context row and leaves the bar:

```json
{ "op": "call", "service": "ui.prompts", "method": "show",
  "args": ["tutorial.jump", "jump", { "en": "Leap", "fr": "Bondir" }] }
```

The context row now reads "[Space] Leap" (in French "[Espace] Bondir"); `hide("tutorial.jump")` removes it.

## Settings and defaults

| Setting | Type | Default | Meaning |
|---|---|---|---|
| `bar` | boolean | `false` | show the help bar of the controls of the moment |
| `context` | boolean | `false` | show the context row: the interaction target and the `contexts` rows |
| `barActions` | list | `[]` | actions of the bar in order; empty = automatic (the button actions of the current group: on foot, or `vehicle.*` while driving) |
| `exclude` | list | `[]` | actions never shown in the bar |
| `maxItems` | integer | `6` | most prompts in the bar (1 to 12) |
| `interaction` | boolean | `true` | with `context` on, show the `interaction.system` target ("[E] Open door"); left to `interaction.feedback` while it draws the prompt on the object |
| `contexts` | list | dialogue, vehicle | rows `{ id, action, text: { en, fr }, var, tag }` shown while the state variable `var` is truthy or the player has the tag `tag`; an unregistered action is skipped |
| `position` | text | `bottom` | where the prompts are drawn |
| `device` | text | `auto` | `auto` follows the last device; `keyboard` or `gamepad` forces a style |
| `language` | text | `auto` | `auto` follows the `ui.menu` language; or `en`, `fr` |
| `hideInMenus` | boolean | `true` | hide the prompts while a menu or the end screen is open |

The default `contexts` are "Continue" while `dialogue.active` is true and "Exit vehicle" while the player has the tag `driving`.

## Services, events, variables

- `ui.prompts` (service): `view(lang)`, `context(lang)`, `bar(lang)`, `show(id, action, text)` (false if the id or the action is
  invalid; `text` is a string or `{ en, fr }`, empty means the action name), `hide(id)`, `shown()`, `labelFor(action, lang?,
  device?)`, `promptFor(action, text?, lang?, device?)`, `device()`, `setDevice(d)` (`keyboard`, `gamepad`, else `auto`),
  `visible()`, `setVisible(on)`, `refresh()`.
- `prompts.changed` (event): the first context prompt or the device changed, payload `{ context, device }`.
- Variables: `prompts.context` (the first context prompt as text) and `prompts.device`, refreshed every tick and after each call.
- Listens to: `input.device`, `remap.changed`, `remap.reset`, `menu.language`, `i18n.language`, `ui.theme.changed`,
  `interaction.available`, `interaction.hidden`.

## Hooks and modding

The kit decides nothing of the game, so a mod may set every setting above. It declares no hook of its own.

## Engines

Web, native, Godot, Unity and Unreal share the same model. Each engine draws keycaps in the `ui.menu` theme (a `CanvasLayer` in
Godot, UI Toolkit in Unity, a UMG widget in Unreal). On a touch device, a prompt whose action has a control on screen is its text
alone, without a key.

## When it does not do what you expect

- No key on screen: `bar` and `context` are off by default; turn one on, or push a prompt with `show()`.
- A prompt shows the wrong key: it follows the live binding, so check the project bindings and the player's remapping, or force
  a style with `device`.
- A context row is missing: its action is not registered in `input.actions`, or its `var` is not truthy.
- Prompts vanish: `hideInMenus` is on and a menu is open.

## Limits

The kit does not bind keys and does not own the controls screen; those belong to `input.actions` and `ui.menu`.

## Versions

Kit 1.5.0 (no key on screen by default; adds `context`). Service `ui.prompts` 1.0.0.