Design
Controller navigation
Which action does what on each screen, how focus moves, and why every key goes through the user's mapping.
On this page
Every key goes through the mapping engine (platform/input), so a remap applies to the loader as well as to games. The loader never reads a raw button, except for the emergency combo.
Actions per screen
| Action (default) | Library, Row / Cinematic | Library, Grid | Details | Settings | Test | Diagnostics | Menu / notice |
|---|---|---|---|---|---|---|---|
| left / right (D-pad, stick) | previous / next game | move in the grid | move between buttons | adjust a value | — | — | — |
| up / down (D-pad, stick) | — | move in the grid | scroll the facts | rows | — | — | move |
| confirm (A) | details | details | press button | assign / toggle | — | self-test | select / OK |
| back (B) | — | — | library | back (twice if unsaved) | hold 1 s | library | close |
| hide_ui (X) | game controls | game controls | — | reset to default | — | — | — |
| history (Y) | — | — | — | next preset | — | — | — |
| game_menu (+) | menu | menu | — | save | — | — | close menu |
On the picture page: left/right the newer/older screenshot, L/R (rollback/roll forward) move the cover’s frame by 80 px, confirm opens the choice, back returns to the details.
Focus rules
- Every screen opens with its first item focused.
- The library keeps the focused game when you come back from a game’s details.
- The row and the grid stop at their edges; lists wrap around, as in the console’s own UI.
- Moving the focus scrolls every list it is in. On a list’s first line it scrolls all the way up, so the heading shows.
- Held directions repeat with the user’s own repeat delay and interval.
Why there is no LVGL keypad device
The mapping engine already turns buttons into actions, with the repeat timing from the user’s settings. An LVGL keypad device would add LVGL’s own key repeat on top, and it has no keys for hide_ui, history or game_menu. So the logic moves the selection on each action event, and the UI shows that as focus. Either way, no key reaches the UI without passing through the user’s mapping.
Touch
The touchscreen is an LVGL pointer:
- dragging scrolls every list and row, and moves the cover’s frame on the picture page;
- a tap on an item focuses and confirms it, like A (a How to play card is only focused);
- a tap on a footer hint does that hint’s action; on a two-button hint (← →), the second icon does the second one;
- a tap beside the + menu or a notice closes it;
- the controller test is left by holding B, so a tap on its hint leaves at once.