Docs

.claude/ui.md

@@ -0,0 +1,123 @@
+# 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.