124 lines
3.8 KiB
Markdown
124 lines
3.8 KiB
Markdown
# UI System
|
|
|
|
Source: `src/dusk/ui/`
|
|
|
|
The UI system is an immediate-mode layer drawn on top of the game scene each frame. Elements register themselves; `uiUpdate()` ticks all elements and `uiRender()` draws them. All coordinates are in screen pixels.
|
|
|
|
---
|
|
|
|
## Lifecycle
|
|
|
|
```
|
|
uiInit() → uiTextboxInit() // init order matters — textbox depends on display being ready
|
|
uiUpdate() // each frame, before rendering
|
|
uiRender() // each frame, after scene render
|
|
uiDispose()
|
|
uiTextboxDispose()
|
|
```
|
|
|
|
---
|
|
|
|
## Element registration (`ui/uielement.h`)
|
|
|
|
Elements are stored in `UI_ELEMENTS[]`. Each has a type and a `draw` callback:
|
|
|
|
```c
|
|
typedef struct {
|
|
uielementtype_t type;
|
|
errorret_t (*draw)();
|
|
} uielement_t;
|
|
```
|
|
|
|
Currently `UI_ELEMENT_TYPE_NATIVE` elements call their `draw` function directly. New debug/HUD elements are registered by adding to this array.
|
|
|
|
---
|
|
|
|
## Textbox (`ui/uitextbox.h`)
|
|
|
|
`UI_TEXTBOX` is the global dialogue box. It word-wraps text, paginates it, and plays a typewriter scroll effect.
|
|
|
|
```c
|
|
uiTextboxSetText("Long dialogue string..."); // wraps to charsPerLine, paginates
|
|
uiTextboxUpdate(); // each frame: advance scroll, check input
|
|
uiTextboxDraw(); // draw box + text
|
|
|
|
// Pagination:
|
|
uiTextboxPageIsComplete() // true when all chars of current page are visible
|
|
uiTextboxHasNextPage()
|
|
uiTextboxNextPage()
|
|
|
|
// Subscibe to page events:
|
|
eventSubscribe(&UI_TEXTBOX.onPageComplete, cb, user);
|
|
eventSubscribe(&UI_TEXTBOX.onLastPage, cb, user);
|
|
```
|
|
|
|
`UI_TEXTBOX.advanceAction` defaults to the input action that advances dialogue — set it before calling `uiTextboxInit()` if the default doesn't suit.
|
|
|
|
Layout constants:
|
|
- `UI_TEXTBOX_TEXT_MAX` — 1024 chars
|
|
- `UI_TEXTBOX_LINES_MAX` — 64 lines
|
|
- `UI_TEXTBOX_LINES_PER_PAGE_MAX` — 3 lines visible at once
|
|
- `UI_TEXTBOX_SCROLL_CHARS_PER_TICK` — 1 char per tick (typewriter speed)
|
|
|
|
The textbox uses `UI_TEXTBOX.frame` (a `uiframe_t`) for its border rendering and `UI_TEXTBOX.font` for text.
|
|
|
|
---
|
|
|
|
## UI Frame (`ui/uiframe.h`)
|
|
|
|
9-slice bordered box rendered with a tileset:
|
|
|
|
```c
|
|
uiFrameInit(&frame);
|
|
uiFrameDraw(&frame, x, y, width, height);
|
|
uiFrameDispose(&frame);
|
|
```
|
|
|
|
The tileset is loaded from the asset system during `uiFrameInit()`. The 9 slices are arranged in the tileset grid as: top-left corner, top edge, top-right corner, left edge, fill, right edge, bottom-left, bottom edge, bottom-right.
|
|
|
|
---
|
|
|
|
## Loading overlay (`ui/uiloading.h`)
|
|
|
|
`UI_LOADING` is a full-screen loading indicator with fade-in/fade-out transitions:
|
|
|
|
```c
|
|
uiLoadingShow(onShownCallback, user); // fade in; calls callback when fully opaque
|
|
uiLoadingHide(onHiddenCallback, user); // fade out; calls callback when fully transparent
|
|
uiLoadingUpdate(delta); // each frame
|
|
uiLoadingDraw(); // each frame, over everything
|
|
```
|
|
|
|
`UI_LOADING_FADE_DURATION` is `FIXED(0.5f)` seconds. Subscribe to `UI_LOADING.onTransitionEnd` for completion events.
|
|
|
|
---
|
|
|
|
## Full-box overlay (`ui/uifullbox.h`)
|
|
|
|
Two global full-screen color overlays: `UI_FULLBOX_UNDER` (drawn before game content) and `UI_FULLBOX_OVER` (drawn after). Used for scene transitions (fade to black, etc.):
|
|
|
|
```c
|
|
uiFullboxTransition(
|
|
&UI_FULLBOX_OVER,
|
|
COLOR_TRANSPARENT, COLOR_BLACK,
|
|
FIXED(0.5f),
|
|
EASING_IN_OUT_CUBIC
|
|
);
|
|
eventSubscribe(&UI_FULLBOX_OVER.onTransitionEnd, myCallback, NULL);
|
|
|
|
uiFullboxUnderDraw(); // draw under layer
|
|
uiFullboxOverDraw(); // draw over layer
|
|
```
|
|
|
|
---
|
|
|
|
## FPS counter (`ui/uifps.h`)
|
|
|
|
`UIFPS` tracks a rolling average FPS. `uiFPSDraw()` renders it in the corner. Currently drawn as part of the debug HUD (not wired to an element slot).
|
|
|
|
---
|
|
|
|
## Player position HUD (`ui/uiplayerpos.h`)
|
|
|
|
`uiplayerpos.c` draws the player's current world tile coordinates. Debug overlay, currently drawn directly in the scene render.
|