Add some UI
This commit is contained in:
@@ -0,0 +1,150 @@
|
||||
# UI System
|
||||
|
||||
## Scene structure
|
||||
|
||||
```
|
||||
RootUI (Control, fullscreen, always visible)
|
||||
├── DebugMenu
|
||||
├── PauseMenu
|
||||
│ ├── PauseSettings
|
||||
│ └── PauseMain
|
||||
├── GameMenu
|
||||
│ ├── GameMenuPartyTab
|
||||
│ └── GameMenuItemsTab
|
||||
└── VNTextbox
|
||||
```
|
||||
|
||||
`RootUI` is a permanent child of `RootScene` and registers itself with the `UI` singleton on `_enter_tree`. Access its children via `UI.TEXTBOX`, `UI.DEBUG_MENU`, and `UI.GAME_MENU`.
|
||||
|
||||
## UI singleton
|
||||
|
||||
`UI` (autoload) is the global access point.
|
||||
|
||||
| Accessor | Returns | Notes |
|
||||
|---|---|---|
|
||||
| `UI.TEXTBOX` | `VNTextbox` | Bottom-screen dialogue box |
|
||||
| `UI.DEBUG_MENU` | `DebugMenu` | Dev scene-jump overlay |
|
||||
| `UI.GAME_MENU` | `GameMenu` | JRPG-style in-game menu |
|
||||
| `UI.dialogueActive` | `bool` | `true` for the entire duration of a `DialogueAction`, including line transitions |
|
||||
|
||||
`dialogueActive` is set by `DialogueAction` — it is broader than just "textbox visible." Movement blocks on both flags: `UI.dialogueActive` prevents movement even while the textbox is briefly hidden between lines.
|
||||
|
||||
## VNTextbox
|
||||
|
||||
Bottom-anchored `PanelContainer` that reveals text character-by-character and paginates when content overflows 4 lines.
|
||||
|
||||
**Showing text from code:**
|
||||
|
||||
```gdscript
|
||||
# Fire-and-forget
|
||||
UI.TEXTBOX.setText("Hello world.")
|
||||
|
||||
# Await player dismiss — use this in cutscene callables
|
||||
await UI.TEXTBOX.setTextAndWait("Hello world.")
|
||||
```
|
||||
|
||||
**Flow:**
|
||||
1. `setText` resets reveal state and sets new text; textbox becomes visible automatically
|
||||
2. Player holds `interact` to speed up reveal; press again after reveal completes to advance page or close
|
||||
3. `textboxClosing` signal fires when the last page is dismissed
|
||||
4. `setTextAndWait` awaits that signal before returning
|
||||
|
||||
**Input guard:** `EntityMovement._canMove()` returns `false` while `!UI.TEXTBOX.isClosed`. Don't set text without also expecting movement to be blocked.
|
||||
|
||||
**Signal:** `textboxClosing` — emitted once per `setTextAndWait` call when player dismisses.
|
||||
|
||||
## AdvancedRichText
|
||||
|
||||
`RichTextLabel` subclass (`@tool`) used inside `VNTextbox`. Handles:
|
||||
|
||||
- Smart word-wrap (`TextServer.AUTOWRAP_WORD_SMART`)
|
||||
- Pagination via `maxLines` / `startLine` exports
|
||||
- Inline input icons: `[input action=interact]text[/input]` → replaced with the icon image from `res://ui/input/{action}.tres`
|
||||
- Optional auto-translation via Godot's `tr()`
|
||||
|
||||
Supported icon actions: `interact`, `pause`, `debug`, `up`, `down`, `left`, `right`.
|
||||
|
||||
## ClosableMenu
|
||||
|
||||
Base class for any togglable panel. Extends `Control`; `isOpen` drives `visible`.
|
||||
|
||||
```gdscript
|
||||
menu.open() # shows, emits opened
|
||||
menu.close() # hides, emits closed
|
||||
menu.toggle()
|
||||
```
|
||||
|
||||
Signals: `opened`, `closed`.
|
||||
|
||||
All new menus that need standard show/hide behaviour should extend `ClosableMenu`.
|
||||
|
||||
## Game menu
|
||||
|
||||
JRPG-style in-game menu at `res://ui/gamemenu/`. Open with the `menu` input (**Tab** on keyboard, **Y** on controller). Blocks player movement while open via `EntityMovement._canMove()`.
|
||||
|
||||
**Structure:**
|
||||
- Left sidebar: `ItemList` tab selector (Party, Items)
|
||||
- Right panel: active tab content
|
||||
|
||||
| Tab | Content |
|
||||
|---|---|
|
||||
| Party | One card per `PartyMember` — name, status, HP/MP, ATK/DEF/SPD/MAG/LCK |
|
||||
| Items | One row per `ItemStack` in `PARTY.BACKPACK` — item name + quantity |
|
||||
|
||||
Both tabs are populated dynamically on open; call `refresh()` on the active tab directly if data changes while the menu is already open.
|
||||
|
||||
**Key methods on `GameMenu`:**
|
||||
|
||||
| Method | Effect |
|
||||
|---|---|
|
||||
| `open()` | Shows menu, refreshes active tab, grabs sidebar focus |
|
||||
| `close()` | Hides menu |
|
||||
| `isOpen() -> bool` | Visibility state |
|
||||
|
||||
`ui_cancel` or `menu` closes the menu. The `menu` input opens it only when `UI.dialogueActive` is false and the textbox is closed.
|
||||
|
||||
To add a new tab: add a value to `GameMenu.Tab`, create a tab scene/script under `ui/gamemenu/`, instance it in `GameMenu.tscn` as a sibling of the other tabs, add an `@export` for it in `GameMenu.gd`, and add the `match` branch in `_selectTab()`.
|
||||
|
||||
## Pause menu
|
||||
|
||||
`PauseMenu` wraps `PauseMain` (item list) and `PauseSettings` (settings tabs).
|
||||
|
||||
| Method | Effect |
|
||||
|---|---|
|
||||
| `PauseMenu.open()` | Shows container, opens PauseMain |
|
||||
| `PauseMenu.close()` | Hides everything |
|
||||
| `PauseMenu.isOpen() -> bool` | Visibility state |
|
||||
|
||||
`ui_cancel` inside the pause menu: if PauseSettings is open, closes it and reopens PauseMain; otherwise closes the whole menu.
|
||||
|
||||
> **Stub:** `Pause.gd` (the singleton) has its logic commented out. Pause menu is not yet wired to actual game-pause state.
|
||||
|
||||
## Settings menu
|
||||
|
||||
`SettingsMenu` is a shared tabbed component instanced in both `MainMenuSettings` and `PauseSettings`. Three tabs: **Gameplay**, **Sound**, **Graphics** — currently contain placeholder labels only.
|
||||
|
||||
## Debug menu
|
||||
|
||||
`DebugMenu` (toggle via `debug` input — **F1**) provides four scene-jump buttons:
|
||||
|
||||
| Button | Action |
|
||||
|---|---|
|
||||
| Overworld | `SCENE.setScene(OVERWORLD)` |
|
||||
| Battle | `SCENE.setScene(BATTLE)` |
|
||||
| Cooking | `SCENE.setScene(COOKING)` |
|
||||
| Initial | `SCENE.setScene(INITIAL)` |
|
||||
|
||||
Access via `UI.DEBUG_MENU`. Starts hidden; `isClosed` getter/setter controls visibility.
|
||||
|
||||
## Theme & assets
|
||||
|
||||
- Global theme: `res://ui/UI Theme.tres` — applied to all UI nodes
|
||||
- Input icons: `res://ui/input/{action}.tres` — one file per action name
|
||||
- Font: configured globally in project settings
|
||||
|
||||
## Adding a new menu
|
||||
|
||||
1. Create a scene whose root extends `ClosableMenu` (or `Control` if open/close isn't needed)
|
||||
2. Add it as a child of `RootUI.tscn`
|
||||
3. Export a typed reference on `RootUI.gd` and wire it in the Inspector
|
||||
4. Expose via a getter on `UISingleton.gd` if other systems need access (follow the `TEXTBOX` / `DEBUG_MENU` pattern)
|
||||
Reference in New Issue
Block a user