Reimplement the archived UI widget stack on the new element-tree system

The old widget system (archive/dusk/ui/) depended on infrastructure this rewrite deleted -- a static X-macro element list, a 9-slice UI_FRAME, and a global gamepad/keyboard focus stack -- so everything below is rebuilt on top of the new native uielement_t pool + parent/child tree instead, gamepad/keyboard-only (no mouse support exists in the input system). New JS widgets (assets/scripts/), all pure composites of Label/Rectangle following the Button.js pattern: Checkbox, Tab, Slider, Dropdown. Slider/ Dropdown expose a directionInput(dx, dy) hook so a menu can hand them LEFT/RIGHT before falling back to cursor movement. New Menu.js replaces the old global uifocus_t stack: a small push/pop stack of Menu instances where only the topmost consumes CANCEL/ACCEPT/ direction input each tick (needed for nested modals -- a Settings sub-page menu plus a "discard changes?" Confirm can be open at once). Held-direction repeat timing matches the old 0.5s delay / 0.1s repeat. New overlay composites (added via a new UI.addOverlay()/UI.removeOverlay(), always drawn/updated after normal roots): FpsCounter, ConsoleOverlay (one Label per console history line, driven directly rather than via add() since History (16) exceeds the 8-children-per-element cap), Crop (letterbox/pillarbox bars), and Fullbox (a reusable tweened full-screen fade covering both the old fullbox and transition effects -- reuses shared instances rather than allocate-and-dispose, since disposing an element from inside its own render() callback risks the same JerryScript refcount corruption hit earlier in this rewrite). New Confirm.js (Yes/No dialog) and Settings.js (+ SettingsGeneral/ SettingsInput sub-pages) built on Menu. Display/Audio settings pages are intentionally not ported -- neither had a real backing engine system even in the old code. Frame is a flat Rectangle for now, not real 9-slice (a genuinely bigger native lift, deliberately deferred). Small native binding additions needed by the above, each with its own unit test: Time.renderDelta, Console.lineCount/getLine/visible/ consumeDirty, a new Screen module, a new Locale module, Input.deadzone, a new Save module, and Label.color (was missing entirely). Also fixes a real gap from the UI.addOverlay() work: uiElementDispose() wasn't removing disposed elements from the new overlay root array, which would have left dangling ids behind. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Rebuild UI as a scriptable element tree, archive the old system
2026-08-14 09:05:11 -05:00 · 2026-08-13 11:13:23 -05:00 · 2026-08-11 23:33:29 -05:00 · 2026-08-11 16:03:32 -05:00 · 2026-08-11 14:34:51 -05:00 · 2026-08-11 13:11:22 -05:00
1069 changed files with 46313 additions and 24827 deletions
@@ -1,74 +0,0 @@
 # Animation System
 Source: `src/dusk/animation/`
 Lightweight keyframe-based value interpolation using fixed-point math throughout.
 ---
 ## Easing (`animation/easing.h`)
 `easingApply(type, t)` applies an easing function to a normalized time value `t ∈ [0, FIXED_ONE]` and returns the eased value in the same range.
 All functions are also callable directly:
 ```c
 fixed_t t = FIXED(0.5f);
 fixed_t out = easingApply(EASING_IN_OUT_CUBIC, t);
 ```
 Available easing types (all in `easingtype_t`):
 | Enum value | Curve |
 |---|---|
 | `EASING_LINEAR` | straight line |
 | `EASING_IN_SINE` / `OUT` / `IN_OUT` | sinusoidal |
 | `EASING_IN_QUAD` / `OUT` / `IN_OUT` | quadratic |
 | `EASING_IN_CUBIC` / `OUT` / `IN_OUT` | cubic |
 | `EASING_IN_QUART` / `OUT` / `IN_OUT` | quartic |
 | `EASING_IN_BACK` / `OUT` / `IN_OUT` | overshoots slightly |
 `EASING_FUNCTIONS[EASING_COUNT]` is a table of `easingfn_t` function pointers for when you need to pick an easing at runtime without a switch.
 ---
 ## Keyframes (`animation/keyframe.h`)
 ```c
 typedef struct {
  fixed_t time;          // time point this keyframe is at
  fixed_t value;         // output value at this time
  easingtype_t easing;   // easing to apply when interpolating toward the NEXT keyframe
 } keyframe_t;
 ```
 Keyframe arrays should be sorted ascending by `time`.
 ---
 ## Animation (`animation/animation.h`)
 `animation_t` wraps a keyframe array and provides value lookup:
 ```c
 keyframe_t frames[] = {
  { FIXED(0.0f), FIXED(0.0f), EASING_LINEAR },
  { FIXED(1.0f), FIXED(1.0f), EASING_IN_OUT_CUBIC },
  { FIXED(2.0f), FIXED(0.0f), EASING_LINEAR },
 };
 animation_t anim;
 animationInit(&anim, frames, 3);
 fixed_t value = animationGetValue(&anim, FIXED(0.75f));   // interpolated
 ```
 `animationGetValue` finds the surrounding keyframes for the given `time`, computes the local `t` within that segment, applies the keyframe's easing, and linearly interpolates between the two keyframe values.
 The animation does not own the keyframe array — it holds a pointer. Pass a static or long-lived array.
 ---
 ## Usage in the engine
 Entity animations (`entityanim_t`) do NOT use this system — they use a simple countdown timer (`animTime`) and a state enum. The `animation_t` system is intended for property animation: UI transitions, camera easing, visual effects, anything that needs a time → value curve.
@@ -1,81 +0,0 @@
 # Architecture
 ## Platform abstraction
 Every subsystem that differs across platforms (display, input, asset loading, save, time, network, log) follows the same pattern:
 1. `src/dusk/<subsystem>/<subsystem>platform.h` — included by the public header. Contains `#include "path/to/platform-specific-header.h"` resolved by the build system include path.
 2. `src/dusk{platform}/<subsystem>/<subsystem>platform.h` — the actual platform-specific header included above (e.g. `src/duskgl/display/framebuffer/framebufferplatform.h`).
 3. The shared header (`src/dusk/<subsystem>/<subsystem>.h`) `#error`s at compile time if the platform doesn't define the expected macros/types.
 The active platform backends are selected by `DUSK_TARGET_SYSTEM` in CMake, which includes `cmake/targets/<system>.cmake`. That file sets compile definitions (`DUSK_LINUX`, `DUSK_SDL2`, `DUSK_OPENGL`, …) and links platform libraries.
 Platform source directories:
 - `src/duskgl/` — OpenGL rendering (used on Linux and as the GL layer for SDL2)
 - `src/dusksdl2/` — SDL2 window/input/time (Linux desktop)
 - `src/dusklinux/` — Linux filesystem/save/network
 - `src/duskdolphin/` — GameCube & Wii (GX renderer, libogc)
 - `src/duskpsp/` — PSP (GU renderer, PSPSDK)
 - `src/duskvita/` — PS Vita
 ## Subsystem lifecycle
 All subsystems follow `init → update (per frame) → dispose`. Engine initialization order matters and is centralized in `engine.c`:
 ```
 systemInit → timeInit → consoleInit → inputInit → assetInit →
 localeManagerInit → displayInit → uiInit → uiTextboxInit →
 cutsceneInit → rpgInit → networkInit → sceneInit
 ```
 Dispose runs in reverse. Each call uses `errorChain()` to propagate failures.
 ## Error handling
 Functions that can fail return `errorret_t` (a code + pointer to thread-local error state). Three core macros:
 ```c
 errorThrow("message %s", arg);        // sets error, returns from current function
 errorChain(someCall());               // if someCall() fails, propagates and returns
 errorOk();                            // returns success
 ```
 Check with `errorIsOk(ret)` / `errorIsNotOk(ret)`. The error state carries file/function/line info for a stack-like trace.
 ## Fixed-point math
 `fixed_t` is `int32_t` with Q24.8 format (8 fractional bits, ~0.004 resolution). Use it for all world/game values:
 ```c
 fixed_t x = FIXED(1.5);              // compile-time literal
 fixed_t y = fixedFromI32(3);         // runtime conversion
 fixed_t z = fixedMul(x, y);          // arithmetic
 float_t f = fixedToFloat(z);         // only where float is needed (e.g. GL uniforms)
 ```
 ## Code generation from CSV
 Several subsystems define their data in CSV files and have corresponding Python tools that generate C headers at build time (via CMake `add_custom_command`):
 | CSV | Tool | Output |
 |-----|------|--------|
 | `src/dusk/input/input.csv` | `tools/input/csv/` | input action enum + names |
 | `src/dusk/display/color.csv` | `tools/color/csv/` | color constants |
 | `src/dusk/rpg/item/item.csv` | `tools/item/csv/` | item enum + metadata |
 | `src/dusk/rpg/story/storyflag.csv` | `tools/story/csv/` | story flag enum + initial values |
 Generated headers are written to `build-<target>/generated/` and included via `target_include_directories`.
 ## Asset system
 Assets are packed into `dusk.dsk` (a zip archive) at build time from the `assets/` directory. At runtime `asset.c` opens the archive and serves files from it.
 Loading is asynchronous: `assetLock()` registers a load request; the background thread calls the appropriate loader; call `assetRequireLoaded()` to block until ready. `assetUnlock()` / `assetUnlockEntry()` releases the entry so it can be reclaimed.
 Loaders are registered per type (`assetloadertype_t`) and live under `src/dusk/asset/loader/`. Platform-specific asset init (finding the .dsk file) is in `src/dusk{platform}/asset/`.
 ## Display subsystem
 The display system is currently organized around immediate GPU-style rendering: `mesh_t` (vertex buffers), `shader_t` (GLSL on GL / TEV state on Dolphin), `texture_t`, and `framebuffer_t`. See [display-refactor.md](display-refactor.md) for the planned move to a render-queue model (needed for a future Saturn port).
 The `spritebatch_t` (`display/spritebatch/`) accumulates 2D quads and flushes in batches — the primary 2D drawing primitive used by the RPG layer.
@@ -1,115 +0,0 @@
 # Asset System
 Source: `src/dusk/asset/`
 All game assets are packed into `dusk.dsk` (a zip archive) at build time and served from it at runtime. The asset system manages async loading, reference counting, and platform-specific archive location.
 See [architecture.md](architecture.md#asset-system) for the high-level overview.
 ---
 ## Asset archive
 The archive is opened at `assetInit()`. `assetFileExists(filename)` checks for a file without loading it. The file path format inside the archive matches the layout of the `assets/` source directory.
 On each platform, `assetInitPlatform()` locates the `.dsk` file (e.g. adjacent to the binary on Linux, on the SD card on PSP).
 ---
 ## Entry lifecycle
 An `assetentry_t` represents one file being managed by the system. States:
 ```
 NOT_STARTED → PENDING_ASYNC → LOADING_ASYNC → PENDING_SYNC → LOADING_SYNC → LOADED
                                                                           └→ ERROR
 ```
 - **PENDING_ASYNC / LOADING_ASYNC**: the background thread is handling I/O (file reads, decompression).
 - **PENDING_SYNC / LOADING_SYNC**: the main thread needs to finish loading (e.g. uploading to GPU), triggered during `assetUpdate()`.
 The async/sync split exists because GPU operations must happen on the main thread.
 ---
 ## Using assets
 ```c
 // Acquire a loaded entry (blocks until loaded):
 assetentry_t *entry = assetLock(filename, ASSET_LOADER_TYPE_TEXTURE, &input);
 errorChain(assetRequireLoaded(entry));
 // Use the loaded data:
 texture_t *tex = &entry->data.texture.texture;
 // Release when done:
 assetUnlockEntry(entry);
 ```
 `assetLock` finds-or-creates an entry and increments its reference count. `assetUnlock` / `assetUnlockEntry` decrements it; when it reaches zero the entry is reclaimed at the next `assetUpdate()`.
 To subscribe to async completion instead of blocking:
 ```c
 eventSubscribe(&entry->onLoaded, myCallback, myUser);
 ```
 ---
 ## Loader types
 | Type constant | File | Output struct accessed via |
 |---|---|---|
 | `ASSET_LOADER_TYPE_TEXTURE` | `.png` etc. | `entry->data.texture.texture` |
 | `ASSET_LOADER_TYPE_TILESET` | tileset descriptor | `entry->data.tileset.tileset` |
 | `ASSET_LOADER_TYPE_MESH` | mesh data | `entry->data.mesh.mesh` |
 | `ASSET_LOADER_TYPE_LOCALE` | `.po` file | internal to locale manager |
 | `ASSET_LOADER_TYPE_JSON` | `.json` | `entry->data.json.*` |
 Each loader type registers `loadAsync`, `loadSync`, and `dispose` callbacks in `ASSET_LOADER_CALLBACKS[]`.
 The async callback runs on the loader thread; the sync callback runs on the main thread during `assetUpdate()`. Most loaders do file I/O async and GPU upload sync.
 ### Error handling inside loaders
 Use these macros instead of `errorThrow` / `errorChain` inside loader callbacks — they also set the entry state to ERROR:
 ```c
 assetLoaderErrorChain(loading, someCall());
 assetLoaderErrorThrow(loading, "Descriptive message");
 ```
 ---
 ## Low-level file I/O (`asset/assetfile.h`)
 `assetfile_t` wraps a `zip_file_t` handle and provides streaming reads:
 ```c
 assetFileInit(&file, "textures/player.png", NULL, NULL);
 assetFileOpen(&file);
 assetFileRead(&file, buffer, size);
 assetFileClose(&file);
 assetFileDispose(&file);
 // Read entire file into a malloc'd buffer:
 uint8_t *buf; size_t size;
 assetFileReadEntire(&file, &buf, &size);   // caller frees buf
 ```
 For line-by-line text parsing (`assetfilelinereader_t`):
 ```c
 assetFileLineReaderInit(&reader, &file, readBuf, readBufSize, outBuf, outBufSize);
 while(!reader.eof) {
  errorChain(assetFileLineReaderNext(&reader));
  // reader.outBuffer contains the line, reader.lineLength its length
 }
 ```
 ---
 ## Background loader thread
 `assetUpdateAsync(thread)` is the thread entry point. It calls `assetUpdate()` in a loop, sleeping briefly between iterations, until `threadShouldStop()` returns true. The main thread also calls `assetUpdate()` once per frame to process the sync phase.
 Up to `ASSET_LOADING_COUNT_MAX` (4) entries can be loading concurrently.
 Up to `ASSET_ENTRY_COUNT_MAX` (128) entries can exist at once.
@@ -1,92 +0,0 @@
 # Display Refactor Progress
 ## Immediate Goal
 Render a 32x32 white square through the new render opcode stack on Linux.
 ## Architecture (summary)
 See `.claude/display-refactor.md` for the full design.
 - `src/dusk/render/` -- opcode format + buffer + submission API (the *contract*).
 - Platform backends (e.g. `src/duskgl/`) consume the buffer and translate to native API calls.
 - `src/dusk/display/` -- orchestration shell only: `displayInit`, `displayUpdate`, `displayDispose`.
 - Scenes call `renderSprite(...)`, `renderClear(...)`. The backend executes the intent.
 ## Opcode format (32 bytes)
 Every command starts with a 4-byte `ropheader_t` (opcode, flags, depth). Two commands defined:
 - `ROP_CLEAR` (32 bytes) -- clear with a color.
 - `ROP_DRAW_SPRITE` (32 bytes) -- screen-space int16 x/y/w/h + tint color.
 ## Milestone 1 -- Archive + strip existing display deps ✓
 - [x] Old `src/dusk/display/` archived (now deleted from working tree via git).
 - [x] Old `src/duskgl/display/` removed (new GL renderer replaces it).
 - [x] `engine.c` stripped to minimal subsystems, set to `SCENE_TYPE_TEST`.
 - [x] `scene.c` stripped of old display/shader/screen references.
 - [x] `console.c` stripped of display deps.
 - [x] `ui/CMakeLists.txt` gutted (re-implementation deferred).
 - [x] `asset/loader/CMakeLists.txt` -- display loaders disabled.
 - [x] `asset/loader/assetloader.h` -- display loader types removed.
 - [x] `rpg/overworld/chunk.h` -- mesh_t / meshvertex_t removed.
 - [x] `rpg/overworld/map.c` -- mesh/spritebatch calls removed.
 - [x] `scene/overworld/sceneoverworld.c` -- stubbed to empty callbacks.
 - [x] Test suite display tests disabled.
 ## Milestone 2 -- Render opcode system ✓
 - [x] `src/dusk/render/rop.h` -- `ropheader_t`, `ropclear_t`, `ropsprite_t`.
 - [x] `src/dusk/render/ropbuffer.h/.c` -- `ROPBUFFER` global, reset, alloc.
 - [x] `src/dusk/render/render.h/.c` -- `renderClear()`, `renderSprite()`.
 - [x] `src/dusk/render/CMakeLists.txt`.
 ## Milestone 3 -- New minimal display shell ✓
 - [x] `src/dusk/display/display.h/.c` -- init/update/dispose, calls platform hooks.
 - [x] `src/dusk/display/displaystate.h` -- cull/depth/blend flags.
 - [x] `src/dusk/display/color.csv` + `CMakeLists.txt` -- color generation kept.
 ## Milestone 4 -- GL backend ✓
 - [x] `src/duskgl/render/rendergl.h/.c`:
  - GL 3.3 core shader (ortho projection, solid color, no texture yet).
  - `renderGLInit` -- creates VAO/VBO/shader.
  - `renderGLFlush(buf, w, h)` -- walks ROPBUFFER, GL calls per opcode.
  - `ROP_CLEAR` → `glClearColor` + `glClear`.
  - `ROP_DRAW_SPRITE` → 6-vertex quad, `glDrawArrays`.
 - [x] `src/duskgl/error/errorgl.h/.c` -- `errorGLCheck`.
 - [x] `src/duskgl/CMakeLists.txt`.
 - [x] `src/dusksdl2/display/displaysdl2.h/.c` updated:
  - `displaySDL2Init` -- SDL2 window + GL 3.3 context + `renderGLInit`.
  - `displaySDL2Flush(ropbuffer_t *)` -- MakeCurrent + `renderGLFlush`.
  - `displaySDL2Swap` -- SDL_GL_SwapWindow.
 - [x] `src/dusklinux/display/displayplatform.h` updated with new macros.
 ## Milestone 5 -- Test scene ✓
 - [x] `SCENE_TYPE_TEST` added to `scenetype.h/.c`.
 - [x] `src/dusk/scene/test/scenetest.h/.c`:
  - `renderClear(color(32, 32, 48, 255))` -- dark blue-grey background.
  - `renderSprite(100, 100, 32, 32, COLOR_WHITE)` -- 32x32 white square.
 - [x] `engine.c` starts with `SCENE_TYPE_TEST`.
 ## Milestone 6 -- Verified ✓
 - [x] Build succeeds with no errors (2026-06-18).
 - [x] Engine initializes: SDL window + GL context + shader + test scene.
 - [x] No crashes running for 5+ seconds.
 - [ ] 32x32 white square visually confirmed on screen.
 ---
 ## Status: BUILD PASSING -- awaiting visual confirmation
 ---
 ## Decisions log
 **2026-06-18** -- `color_t = color4b_t` (from generated `display/color.h`). The color generation pipeline (color.csv + Python tool) is kept in the new minimal `src/dusk/display/CMakeLists.txt`.
 **2026-06-18** -- `ROP_SIZE = 32`. All opcodes fixed 32 bytes. 3D quads will be 64 bytes when added later.
 **2026-06-18** -- Depth sort deferred. Buffer stores unsorted commands; painter platforms sort on flush. GL uses Z-buffer.
 **2026-06-18** -- Texture system not yet wired into the opcode pipeline. `ROP_DRAW_SPRITE` with `texture=0` uses solid tint color only (no sampler). Texture handle system comes next.
 **2026-06-18** -- GL backend uses GL 3.3 Core profile. Shader takes screen-space pixel coordinates and converts to clip space using window size queried from SDL each frame.
 **2026-06-18** -- `ROPBUFFER` is a global (4096 slots × 32 bytes = 128 KB). Reset at start of each frame in `displayUpdate`.
 **2026-06-18** -- `ui/`, `rpg/overworld` display code, asset display loaders all temporarily stubbed/disabled. Will be rewritten against the new render API.
@@ -1,352 +0,0 @@
 # Display System
 Source: `src/dusk/display/`
 The display system is the rendering pipeline. It is abstracted across platforms via `displayplatform.h` — see [architecture.md](architecture.md) for the abstraction pattern. The current concrete backends are OpenGL (`src/duskgl/`) and GX/Dolphin (`src/duskdolphin/`).
 For the planned render-queue refactor (required for Saturn), see [display-refactor.md](display-refactor.md).
 ---
 ## Render / ROP system (`display/render/`)
 The ROP (Render OPcode) system is the low-level, backend-agnostic drawing API. All game drawing goes through this layer; backends (`rendergl.c`, `renderpsp.c`, `renderdolphin.c`) execute the commands at display flush time.
 ### API (`display/render/render.h`)
 ```c
 /* Clear the framebuffer */
 void renderClear(color_t color);
 /* 2D textured quad at pixel coordinates */
 void renderSprite(
  int16_t x, int16_t y, int16_t w, int16_t h,
  int16_t depth,                       /* 0=front … 32767=back */
  rtexture_t texture, color_t tint
 );
 /* Set perspective projection for subsequent 3D draws */
 void renderSetProjection(
  fixed_t fovY, fixed_t aspect, fixed_t nearZ, fixed_t farZ
 );
 /* Set camera position/target for subsequent 3D draws */
 void renderSetView(
  int16_t eyeX, int16_t eyeY, int16_t eyeZ,
  int16_t tgtX, int16_t tgtY, int16_t tgtZ
 );
 /* World-space quad: center point + right half-extent + up half-extent */
 void renderQuad3D(
  int16_t cx, int16_t cy, int16_t cz,
  int16_t rx, int16_t ry, int16_t rz,
  int16_t ux, int16_t uy, int16_t uz,
  int16_t depth,
  rtexture_t texture, color_t tint
 );
 /* Create / dispose an 8-bit indexed palette texture */
 rtexture_t renderTextureCreate(
  uint16_t w, uint16_t h,
  const uint8_t *indices,    /* w×h pixel indices (0-255) */
  const color_t *palette     /* 256 RGBA colour entries */
 );
 void renderTextureDispose(rtexture_t tex);
 /* Mutable pointers to the texture's CPU-side data.
 * Write directly to these; the next draw call picks up the changes.
 *   GL:      dirty flag set on getter call; glTexSubImage2D at next bind.
 *   PSP:     re-pads indices and converts palette → ABGR at bind time.
 *   Dolphin: re-tiles CI8 and converts palette → RGB5A3 at bind time. */
 color_t *renderTextureGetPalette(rtexture_t tex);  /* color_t[256]  */
 uint8_t *renderTextureGetIndices(rtexture_t tex);  /* uint8_t[w*h]  */
 ```
 ### Coordinate conventions
 | Domain | Type | Scale | Notes |
 |---|---|---|---|
 | 3D world positions | `int16_t` | 1 unit = 1 cm | Matches PS1 GTE / N64 RSP native format |
 | Camera/projection params | `fixed_t` | Q24.8 | `FIXED(x)` for literals |
 | 2D screen positions | `int16_t` | pixels | Origin top-left |
 | UV coords | `uint8_t` | 0–255 → 0.0–1.0 | Stored in ROP structs |
 ### Palettized textures
 All textures are 8-bit indexed. `renderTextureCreate` takes:
 - `indices`: one `uint8_t` per pixel (0–255), row-major
 - `palette`: exactly **256** `color_t` RGBA entries
 **Per-platform storage:**
 | Platform | CPU source of truth | GPU/native format | When derived |
 |---|---|---|---|
 | GL (Linux/Vita) | `color_t palette[256]` + `uint8_t *cpuIndices` in slot | `GL_R8` index tex + `GL_RGBA` 256×1 palette tex | Lazy: dirty flag set by getter, `glTexSubImage2D` at next bind |
 | PSP | `color_t palette[256]` + unpadded `uint8_t *cpuIndices` | Stride-padded indices (POT ≥ 8) + ABGR8888 CLUT in shared `pspAbgrBuf` | Every `bindTexture` call; dcache-flushed before GU reads |
 | Dolphin/GC/Wii | `color_t palette[256]` + unpadded `uint8_t *cpuIndices` | CI8 tiled (8×4 tiles, 32 B/tile) + RGB5A3 TLUT in `tlutData` | Every `bindTexture` call; `DCFlushRange` before GX load |
 **GL palette shader detail**: The fragment shader samples the R8 index texture, converts the normalised float back to an exact texel centre with `raw*(255/256) + 0.5/256`, then looks up the 256×1 palette texture. This gives pixel-exact results for all 256 index values and allows independent real-time updates to indices or palette.
 **Dolphin RGB5A3 encoding**:
 - Opaque (`a == 255`): bit 15 = 1, RGB555
 - Transparent: bit 15 = 0, A3RGB4 (alpha quantised to 3 bits — dithered transparency is planned for a future pass)
 ### ROP buffer (`display/render/ropbuffer.h` / `rop.h`)
 Commands are written into `ROPBUFFER` (a static byte array) then replayed by the backend at flush time. All ops are fixed-size aligned structs:
 | Op | Struct | Size |
 |---|---|---|
 | `ROP_CLEAR` | `ropclear_t` | 32 bytes |
 | `ROP_DRAW_SPRITE` | `ropsprite_t` | 32 bytes |
 | `ROP_SET_PROJECTION` | `ropprojection_t` | 32 bytes |
 | `ROP_SET_VIEW` | `ropview_t` | 32 bytes |
 | `ROP_DRAW_QUAD_3D` | `ropquad3d_t` | 64 bytes |
 | `ROP_DRAW_TILEMAP_CHUNK` | `roptilemapc_t` | 32 bytes |
 `ropOpSize(op)` returns the byte size for any op. Backends iterate with `offset += ropOpSize(op)`.
 ### Texture handles (`display/render/rtexture.h`)
 `rtexture_t` is a `uint16_t` index into the platform's texture table. `RTEXTURE_NONE` (0 or a sentinel) means "white fallback". Tables are platform-static; handles are valid until `renderTextureDispose` is called.
 ### Tilemap chunk handles (`display/render/rtilemapchunk.h`)
 `rtilemapchunk_t` is a `uint16_t` index into the platform's chunk table. `RTILEMAPCHUNK_INVALID` (0) means no-op. Chunks are pre-built at map load time; each backend constructs its native draw structure once (VAO+VBO on GL, display list on PSP/GX/N64) and the ROP entry costs only a handle lookup + single native draw call per frame.
 ```c
 /* Build once at map load */
 rtilemapchunk_t chunk = renderTilemapChunkCreate(
  chunkW, chunkH,     /* size in tiles */
  tileW, tileH,       /* pixels per tile */
  tileset,            /* rtexture_t of the packed tileset */
  tileIndices         /* uint8_t[chunkW*chunkH], row-major tile indices */
 );
 /* Each frame for visible chunks */
 renderTilemapChunk(screenX, screenY, depth, chunk);
 /* At map unload */
 renderTilemapChunkDispose(chunk);
 ```
 Animated tiles should be drawn on top as separate `renderSprite()` calls; the chunk itself is treated as static geometry and never rebuilt at runtime.
 **Per-platform build:**
 | Platform | What's built at create time | Draw cost per frame |
 |---|---|---|
 | GL (Linux/Vita) | VAO + VBO (`GL_STATIC_DRAW`), `uOffset` uniform translates to screen pos | 1 `glDrawArrays` |
 | PSP | GU display list in uncached EDRAM | 1 `sceGuCallList` |
 | GC/Wii | Compiled GX display list | 1 `GX_CallDispList` |
 | PS1 | Pre-linked POLY_FT4/SPRT chain | Linked into OT at one slot |
 | N64 | RDP display list with pre-scheduled `LOAD_TILE` batches (TMEM-aware) | 1 `gSPDisplayList` |
 | Saturn | VDP2 plane config + VRAM tilemap data | Scroll register write only |
 ---
 ## Initialization order
 Within the display system, init must follow this order (enforced in `engine.c`):
 ```
 displayInit → uiInit → uiTextboxInit
 ```
 Within `displayInit`, the platform typically initialises: framebuffer → screen → shader list → textures → spritebatch → text system.
 ---
 ## `display_t` / `displaystate_t`
 `display_t DISPLAY` is the global display instance (type alias for `displayplatform_t`).
 `displaystate_t` carries per-draw-call render state flags:
 ```c
 DISPLAY_STATE_FLAG_CULL       // face culling
 DISPLAY_STATE_FLAG_DEPTH_TEST // depth testing
 DISPLAY_STATE_FLAG_BLEND      // alpha blending
 ```
 Set state before drawing with `displaySetState(state)`.
 ---
 ## Screen (`display/screen/`)
 `screen_t SCREEN` manages the logical viewport that game content renders into. On dynamic-size platforms (Linux/SDL2) the screen can differ from the native window/framebuffer resolution.
 Screen modes:
 ```
 SCREEN_MODE_BACKBUFFER           — maps 1:1 to backbuffer
 SCREEN_MODE_FIXED_SIZE           — fixed pixel dimensions
 SCREEN_MODE_ASPECT_RATIO         — fixed aspect, scale to fit
 SCREEN_MODE_FIXED_HEIGHT         — fixed height, width scales
 SCREEN_MODE_FIXED_WIDTH          — fixed width, height scales
 SCREEN_MODE_FIXED_VIEWPORT_HEIGHT — fixed viewport height
 ```
 The linux target defines `DUSK_DISPLAY_SCREEN_HEIGHT=240`, producing a 240p fixed-height viewport.
 Render loop usage:
 ```c
 screenBind();       // set up viewport, projection
 // ... draw game content ...
 screenUnbind();
 screenRender();     // blit to backbuffer / current framebuffer
 ```
 `SCREEN.width` / `SCREEN.height` are the logical dimensions used for world-to-screen math — always prefer these over the framebuffer dimensions.
 ---
 ## Framebuffer (`display/framebuffer/`)
 `framebuffer_t FRAMEBUFFER_BACKBUFFER` is the platform backbuffer. `FRAMEBUFFER_BOUND` points to the currently-bound framebuffer (or `NULL` for backbuffer).
 ```c
 frameBufferInitBackBuffer();                        // called once at startup
 frameBufferBind(fb);                                // NULL → backbuffer
 frameBufferClear(FRAMEBUFFER_CLEAR_COLOR | FRAMEBUFFER_CLEAR_DEPTH, COLOR_BLACK);
 frameBufferGetWidth(fb) / frameBufferGetHeight(fb) / frameBufferGetAspect(fb);
 ```
 On platforms with `DUSK_DISPLAY_SIZE_DYNAMIC`, off-screen framebuffers can be created with `frameBufferInit(fb, w, h)` and disposed with `frameBufferDispose(fb)`. Fixed-resolution platforms (PSP, GameCube) only ever use the backbuffer.
 ---
 ## Mesh (`display/mesh/`)
 `mesh_t` is a vertex buffer. The type is `meshplatform_t` (e.g. a VAO+VBO on GL, a GX display list on Dolphin).
 ```c
 meshInit(&mesh, MESH_PRIMITIVE_TYPE_TRIANGLES, vertexCount, verticesPtr);
 meshFlush(&mesh, offset, count);  // upload CPU vertices → GPU
 meshDraw(&mesh, offset, count);   // draw; pass -1 for count to draw all
 meshDispose(&mesh);
 ```
 **Key distinction**: `meshFlush` uploads data to GPU memory; `meshDraw` issues the draw call. For static geometry (chunk meshes) you call `meshFlush` once on load, then `meshDraw` every frame. For dynamic geometry (spritebatch) you `meshFlush` + `meshDraw` each frame.
 `meshvertex_t` (`display/mesh/meshvertex.h`) contains:
 - `float_t uv[2]` — texture coordinates
 - `float_t pos[3]` — position
 - Optionally `color_t color` if `MESH_ENABLE_COLOR` is defined (off by default)
 Primitive mesh generators live alongside `mesh.h`: `quad.h`, `plane.h`, `cube.h`, `sphere.h`, `capsule.h`, `triprism.h`.
 ---
 ## Shader (`display/shader/`)
 `shader_t` is `shaderplatform_t` (GLSL program on GL, TEV state block on Dolphin).
 ```c
 shaderInit(&shader, &definition);
 shaderBind(&shader);
 shaderSetMatrix(&shader, "uModel", modelMat);
 shaderSetTexture(&shader, "uTexture", &texture);
 shaderSetColor(&shader, "uColor", COLOR_WHITE);
 shaderSetMaterial(&shader, &material);
 shaderDispose(&shader);
 ```
 ### Shader list (`display/shader/shaderlist.h`)
 The engine maintains a small set of built-in shaders in `SHADER_LIST_DEFS[]`. Currently only one is defined:
 - `SHADER_LIST_SHADER_UNLIT` → `SHADER_UNLIT` — unlit textured/colored rendering, used for all world and entity drawing.
 `shaderListInit()` compiles/uploads all built-in shaders and sets shared projection/view matrices. Call once after display init.
 ### Materials (`display/shader/shadermaterial.h`)
 `shadermaterial_t` is a union of all shader-specific material structs. Currently only `shaderunlitmaterial_t`:
 ```c
 shadermaterial_t mat = {
  .unlit = {
    .color = COLOR_WHITE,
    .texture = &myTexture,   // NULL for solid color
  }
 };
 shaderSetMaterial(&SHADER_UNLIT, &mat);
 ```
 ---
 ## Texture (`display/texture/`)
 ```c
 textureInit(&texture, width, height, format, data);
 textureDispose(&texture);
 ```
 Width and height **must be powers of two** (asserted at init time).
 `textureformat_t` is `textureformatplatform_t`. Supported formats vary by platform; the common ones are `TEXTURE_FORMAT_RGBA` and `TEXTURE_FORMAT_PALETTE`.
 `texturedata_t` is a union:
 ```c
 // RGBA:
 data.rgbaColors = colorArray;
 // Paletted:
 data.paletted.indices = indexArray;
 data.paletted.palette = &palette;   // palette color count must be power of two
 ```
 **Built-in textures** (defined in `texture.c`, no asset loading needed):
 - `TEXTURE_WHITE` — 4×4 solid white
 - `TEXTURE_TEST` — 4×4 black/magenta checkerboard
 ### Palette (`display/texture/palette.h`)
 Up to `PALETTE_COUNT` (6) global palettes in `PALETTES[]`, each holding up to `PALETTE_COLOR_COUNT` (255) `color_t` entries.
 ### Tileset (`display/texture/tileset.h`)
 A tileset slices a texture into a grid of equal-sized tiles. Used by fonts and UI frames. The tileset does not own the texture — it references a `texture_t *`.
 ---
 ## SpriteBatch (`display/spritebatch/`)
 The primary 2D/billboard drawing primitive. Accumulates `spritebatchsprite_t` quads and flushes them in batches of `SPRITEBATCH_FLUSH_COUNT` (16) sprites at a time.
 ```c
 // Per frame:
 spriteBatchClear();
 spriteBatchBuffer(sprites, count, &SHADER_UNLIT, material);  // auto-flushes when batch full
 spriteBatchFlush();  // flush remaining
 // Low-level: write directly to an external mesh (for baking static geometry):
 spriteBatchBufferToMesh(sprites, count, vertices, verticesSize);
 ```
 `spritebatchsprite_t`:
 ```c
 typedef struct {
  vec3 min, max;     // 3D bounding box
  vec2 uvMin, uvMax; // texture region
 } spritebatchsprite_t;
 ```
 The global `SPRITEBATCH` and its vertex backing array `SPRITEBATCH_VERTICES[]` are defined externally to the struct to satisfy alignment requirements on certain platforms.
 ---
 ## Text (`display/text/`)
 Text rendering uses `FONT_DEFAULT` (loaded during `textInit()`), which references a texture and a tileset. Characters start at ASCII `!` (`TEXT_CHAR_START`).
 ```c
 textDraw(x, y, "Hello", COLOR_WHITE, &FONT_DEFAULT);
 textMeasure("Hello", &FONT_DEFAULT, &outWidth, &outHeight);
 // Single-char sprite for manual layout:
 spritebatchsprite_t s = textGetSprite(pos, 'A', &FONT_DEFAULT);
 ```
 `font_t` holds a `texture_t *` and a `tileset_t *` — both are owned by the asset system, not the font struct.
@@ -1,93 +0,0 @@
 # Input System
 Source: `src/dusk/input/`
 The input system decouples physical hardware buttons from logical game actions via a binding layer. Actions are defined in `src/dusk/input/input.csv` and code-generated into `inputaction_t` enum values — see [architecture.md](architecture.md#code-generation-from-csv).
 ---
 ## Concepts
 **Button** (`inputbutton_t`) — a physical input source: a keyboard scancode, gamepad button, gamepad axis, or pointer axis. The available button types depend on which `DUSK_INPUT_*` defines are active for the target platform.
 **Action** (`inputaction_t`) — a logical game input (e.g. `INPUT_ACTION_UP`, `INPUT_ACTION_CONFIRM`, `INPUT_ACTION_RAGEQUIT`). Each action accumulates a float value `[0.0, 1.0]` from all buttons bound to it.
 **Binding** — a many-to-one mapping from buttons to actions. Bindings are registered at runtime with `inputBind(button, action)`.
 ---
 ## Querying actions
 ```c
 // Boolean helpers (current frame):
 inputIsDown(action)        // value > 0 this frame
 inputPressed(action)       // down this frame but not last
 inputReleased(action)      // down last frame but not this
 // Last frame state:
 inputWasDown(action)
 // Raw float value:
 inputGetCurrentValue(action)   // [0.0, 1.0]
 inputGetLastValue(action)
 // Axis helpers — combine two opposing actions into a signed float:
 float_t h = inputAxis(INPUT_ACTION_LEFT, INPUT_ACTION_RIGHT);  // -1.0 to 1.0
 inputAxis2D(negX, posX, negY, posY, result);   // fills vec2
 inputAngle2D(negX, posX, negY, posY, result);  // atan2-based normalized direction
 // Deadzone:
 float_t clean = inputDeadzone(rawValue, 0.1f);
 ```
 ---
 ## Dynamic values (`DUSK_TIME_DYNAMIC`)
 On platforms with variable frame rates, each action also tracks `dynamicDelta`-scaled values:
 ```c
 inputGetCurrentValueDynamic(action)
 inputGetLastValueDynamic(action)
 ```
 These account for the actual time elapsed since the last frame, so movement calculated from them is frame-rate independent.
 ---
 ## Events on actions
 Each `inputactiondata_t` exposes `onPressed` and `onReleased` events:
 ```c
 eventSubscribe(&INPUT.actions[INPUT_ACTION_CONFIRM].onPressed, myCallback, myUser);
 ```
 The callback signature is `void cb(void *params, void *user)`. `params` is always `NULL` for input events.
 ---
 ## Buttons and bindings
 Physical buttons are typed via `inputbuttontype_t`:
 | Constant | When available | Payload |
 |---|---|---|
 | `INPUT_BUTTON_TYPE_KEYBOARD` | `DUSK_INPUT_KEYBOARD` | `inputscancode_t` |
 | `INPUT_BUTTON_TYPE_GAMEPAD` | `DUSK_INPUT_GAMEPAD` | `inputgamepadbutton_t` |
 | `INPUT_BUTTON_TYPE_GAMEPAD_AXIS` | `DUSK_INPUT_GAMEPAD` | axis + positive direction flag |
 | `INPUT_BUTTON_TYPE_POINTER` | `DUSK_INPUT_POINTER` | `inputpointeraxis_t` |
 Button names and default bindings are defined in `input.csv`. Look up a button by name:
 ```c
 inputbutton_t btn = inputButtonGetByName("keyboard_w");
 inputBind(btn, INPUT_ACTION_UP);
 ```
 `INPUT_BUTTON_DATA[]` holds runtime state (current/last raw values) for every physical button.
 ---
 ## Platform platform-specific reads
 `inputButtonGetValuePlatform(button)` is the one required platform function — it returns the current raw `[0.0, 1.0]` value for a button. The platform implementations live in `src/dusk{platform}/input/`.
@@ -1,149 +0,0 @@
 # Cutscenes
 Two distinct layers: a low-level engine sequencer (`src/dusk/cutscene/`) and a higher-level RPG wrapper (`src/dusk/rpg/cutscene/`). Almost all game code works with the RPG layer.
 ---
 ## Engine sequencer (`src/dusk/cutscene/`)
 `cutscene_t CUTSCENE` is a minimal event runner with up to `CUTSCENE_EVENT_COUNT_MAX` (16) `cutsceneevent_t` slots. Each event has three callbacks:
 ```c
 typedef struct {
  errorret_t (*onStart)(void);
  errorret_t (*onUpdate)(void);
  errorret_t (*onEnd)(void);
 } cutsceneevent_t;
 ```
 API:
 ```c
 cutscenePlay(events, count);   // copy events array and start from index 0
 cutsceneAdvance();             // end current event, start next (deactivates after last)
 cutsceneStop();                // abort immediately
 cutsceneIsActive();            // bool
 ```
 This layer is primarily used by the RPG cutscene system — game code doesn't normally touch it directly.
 ---
 ## RPG cutscene layer (`src/dusk/rpg/cutscene/`)
 ### Data structures
 A `cutscene_t` is just a pointer to an item array and a count:
 ```c
 typedef struct cutscene_s {
  const cutsceneitem_t *items;
  uint8_t itemCount;
 } cutscene_t;
 ```
 A `cutsceneitem_t` is a tagged union of all item types:
 ```c
 typedef struct cutsceneitem_s {
  cutsceneitemtype_t type;
  union {
    cutscenetext_t    text;      // display text in textbox
    cutscenecallback_t callback; // call a void(*)(void) function
    cutscenewait_t    wait;      // pause for a fixed_t duration (seconds)
    const cutscene_t *cutscene;  // nest another cutscene
  };
 } cutsceneitem_t;
 ```
 ### Item types
 | Type constant | Payload | Behaviour |
 |---|---|---|
 | `CUTSCENE_ITEM_TYPE_TEXT` | `cutscenetext_t` — `text[256]` + `rpgtextboxpos_t position` | Shows textbox; advances on player confirm input |
 | `CUTSCENE_ITEM_TYPE_CALLBACK` | `cutscenecallback_t` (function pointer) | Calls the function once, then immediately advances |
 | `CUTSCENE_ITEM_TYPE_WAIT` | `cutscenewait_t` (a `fixed_t` in seconds) | Counts down `animTime` each frame, then advances |
 | `CUTSCENE_ITEM_TYPE_CUTSCENE` | `const cutscene_t *` | Plays the nested cutscene before continuing |
 ### Runtime state
 `cutscenesystem_t CUTSCENE_SYSTEM` tracks:
 - `scene` — pointer to the active `cutscene_t`
 - `currentItem` — index into `scene->items[]`
 - `data` — per-item runtime data (`cutsceneitemdata_t`, currently just `cutscenewaitdata_t`)
 - `mode` — the current `cutscenemode_t`
 API:
 ```c
 cutsceneSystemStartCutscene(cutscene);   // begin playing a cutscene
 cutsceneSystemNext();                    // advance to next item
 cutsceneSystemUpdate();                  // called each frame from rpgUpdate
 cutsceneSystemGetCurrentItem();          // inspect active item
 ```
 ### Cutscene mode (`cutscenemode.h`)
 Each item can run in one of three modes:
 ```c
 CUTSCENE_MODE_NONE           // no cutscene active
 CUTSCENE_MODE_FULL_FREEZE    // pause everything (not yet used)
 CUTSCENE_MODE_INPUT_FREEZE   // player input blocked (default: CUTSCENE_MODE_INITIAL)
 CUTSCENE_MODE_GAMEPLAY       // player can still move during cutscene
 ```
 `cutsceneModeIsInputAllowed()` is checked by `entityUpdate()` before invoking the movement callback — the player cannot walk when in INPUT_FREEZE mode.
 ### Defining a cutscene
 Cutscenes are defined as `static const` arrays in header files under `rpg/cutscene/scene/`. Example (`testcutscene.h`):
 ```c
 static const cutsceneitem_t MY_CUTSCENE_ITEMS[] = {
  {
    .type = CUTSCENE_ITEM_TYPE_TEXT,
    .text = { .text = "Hello!", .position = RPG_TEXTBOX_POS_BOTTOM }
  },
  {
    .type = CUTSCENE_ITEM_TYPE_WAIT,
    .wait = FIXED(1.5f)
  },
  {
    .type = CUTSCENE_ITEM_TYPE_CUTSCENE,
    .cutscene = &ANOTHER_CUTSCENE
  },
 };
 static const cutscene_t MY_CUTSCENE = {
  .items = MY_CUTSCENE_ITEMS,
  .itemCount = sizeof(MY_CUTSCENE_ITEMS) / sizeof(cutsceneitem_t)
 };
 ```
 Attach to an NPC via its interact component:
 ```c
 entity->interact.type = ENTITY_INTERACT_CUTSCENE;
 entity->interact.data.cutscene = &MY_CUTSCENE;
 ```
 ---
 ## Textbox (`src/dusk/rpg/rpgtextbox.h`)
 `rpgtextbox_t RPG_TEXTBOX` is the global textbox state:
 ```c
 typedef struct {
  rpgtextboxpos_t position;      // RPG_TEXTBOX_POS_TOP or RPG_TEXTBOX_POS_BOTTOM
  bool_t visible;
  char_t text[RPG_TEXTBOX_MAX_CHARS];   // 256 chars
 } rpgtextbox_t;
 ```
 API:
 ```c
 rpgTextboxShow(position, text);   // copies text, sets visible = true
 rpgTextboxHide();                 // sets visible = false
 rpgTextboxIsVisible();            // bool
 ```
 The textbox state is read by `ui/uitextbox.c` during the UI render pass to draw the dialogue box on screen. `rpgtextbox.c` itself does no rendering.
@@ -1,140 +0,0 @@
 # Entities
 Source: `src/dusk/rpg/entity/`
 ---
 ## Storage
 Entities live in a single fixed global array:
 ```c
 entity_t ENTITIES[ENTITY_COUNT];   // ENTITY_COUNT = 64
 ```
 A slot is "empty" when `entity->type == ENTITY_TYPE_NULL`. Never allocate entity memory dynamically — always find a free slot with `entityGetAvailable()`, which returns its index (`0xFF` if none free).
 ---
 ## `entity_t` structure
 ```c
 typedef struct entity_s {
  uint8_t id;                  // index in ENTITIES[]
  entitytype_t type;           // ENTITY_TYPE_NULL / PLAYER / NPC
  entitytypedata_t data;       // union: player_t | npc_t
  entitydir_t direction;       // facing direction (N/S/E/W)
  fixed_t position[3];         // current sub-tile position (x, y, z)
  fixed_t lastPosition[3];     // position before last move (for interpolation)
  entityanim_t animation;      // IDLE / TURN / WALK
  fixed_t animTime;            // countdown timer for current animation
  entityinteract_t interact;   // optional interact component
 } entity_t;
 ```
 ---
 ## Type system
 Entity types are defined in `entitytype.h` using the enum+integer-typedef pattern:
 ```c
 typedef enum { ENTITY_TYPE_NULL, ENTITY_TYPE_PLAYER, ENTITY_TYPE_NPC, ENTITY_TYPE_COUNT } entitytype_enum_t;
 typedef uint8_t entitytype_t;
 ```
 Each type has a `entitycallback_t` entry in the `ENTITY_CALLBACKS[ENTITY_TYPE_COUNT]` static table:
 ```c
 typedef struct {
  void (*init)(entity_t *entity);
  void (*movement)(entity_t *entity);
  bool_t (*interact)(entity_t *player, entity_t *entity);
 } entitycallback_t;
 ```
 Callbacks not applicable to a type are `NULL`; `entityUpdate()` guards against this before calling.
 Type-specific data sits in `entitytypedata_t` (a union of `player_t` and `npc_t`). Currently both are stubs (`void *nothing`).
 ---
 ## Direction (`entitydir.h`)
 ```c
 ENTITY_DIR_NORTH / EAST / SOUTH / WEST
 ```
 Aliases: `UP = NORTH`, `DOWN = SOUTH`, `LEFT = WEST`, `RIGHT = EAST`.
 Utilities:
 - `entityDirGetOpposite(dir)` — returns the opposite direction.
 - `entityDirGetRelative(dir, &relX, &relY)` — fills in the ±1 XY delta for that direction.
 - `assertValidEntityDir(dir, msg)` — assertion macro.
 ---
 ## Animation (`entityanim.h`)
 ```c
 ENTITY_ANIM_IDLE   // standing still
 ENTITY_ANIM_TURN   // turning to a new direction (ENTITY_ANIM_TURN_DURATION = FIXED(0.06))
 ENTITY_ANIM_WALK   // mid-step (ENTITY_ANIM_WALK_DURATION = FIXED(0.1))
 ```
 `entityAnimUpdate(entity)` decrements `animTime` each frame and transitions back to `IDLE` when it reaches zero.
 `entityCanWalk(entity)` / `entityCanTurn(entity)` both return true only when `animation == ENTITY_ANIM_IDLE`.
 The renderer interpolates between `lastPosition` and `position` using `animTime / WALK_DURATION` to produce smooth motion even at low frame rates.
 ---
 ## Movement
 `entityWalk(entity, direction)`:
 1. Converts `entity->position` to a `worldpos_t` (truncates fractional part).
 2. Applies the directional delta to get `newPos`.
 3. Checks the current and target tiles for ramp raise/fall logic (see [world.md](world.md)).
 4. Checks `ENTITIES[]` for another entity occupying `newPos` — blocks if found.
 5. On success: copies `position` to `lastPosition`, updates `position` to `newPos` (via `worldPosToFixed`), sets `animation = ENTITY_ANIM_WALK`.
 `entityTurn(entity, direction)`: sets `direction` and starts a brief turn animation.
 ---
 ## Interaction (`entityinteract.h`)
 The `entityinteract_t` component is embedded in every entity. It is optional — set `type = ENTITY_INTERACT_NULL` for non-interactable entities.
 ```c
 typedef enum {
  ENTITY_INTERACT_NULL,
  ENTITY_INTERACT_CUTSCENE,   // plays a cutscene_t *
  ENTITY_INTERACT_PRINT,      // prints a short message[32]
 } entityinteracttype_t;
 ```
 `entityInteractWith(player, target)` dispatches:
 1. If the interact component's `type != NULL`, handles it (starts the cutscene or prints the message).
 2. Otherwise falls back to `ENTITY_CALLBACKS[type].interact` if set.
 ---
 ## Player (`player.h` / `player.c`)
 `playerInit()` is called via `ENTITY_CALLBACKS[ENTITY_TYPE_PLAYER].init`.
 `playerInput(entity)` is the movement callback. It reads `PLAYER_INPUT_DIR_MAP[]` — a static table mapping input actions (`INPUT_ACTION_UP/DOWN/LEFT/RIGHT`) to entity directions — and calls `entityWalk` or `entityTurn` accordingly.
 The player entity is normally `ENTITIES[0]` but there is no hardcoded assumption about its index beyond being initialized with `ENTITY_TYPE_PLAYER`.
 ---
 ## NPC (`npc.h` / `npc.c`)
 `npcInit()`, `npcMovement()`, and `npcInteract()` provide the NPC type callbacks. Currently stubs; movement does nothing, interact returns false.
@@ -1,18 +0,0 @@
 # RPG Layer
 The RPG layer lives in `src/dusk/rpg/` and is the game-logic tier above the engine. It is initialized and ticked by `engine.c` via `rpgInit` / `rpgUpdate` / `rpgDispose`. The `rpg_t` struct is currently a stub; all meaningful state lives in the subsystems below.
 ## Contents
 - [world.md](world.md) — scene manager, overworld map, chunks, tiles, coordinate system, camera
 - [entity.md](entity.md) — entity pool, types, direction, animation, interaction, player, NPC
 - [cutscene.md](cutscene.md) — cutscene system, item types, mode control, textbox
 - [story.md](story.md) — story flags, items, inventory, backpack, save system
 ## Scene system
 The scene manager (`src/dusk/scene/`) sits above the RPG layer and owns the single active scene. Scenes are identified by `scenetype_t` and registered in `SCENE_TYPES[]` (`scene/scenetype.c`) as `scenecallbacks_t` (init / update / render / dispose).
 `scenedata_t` is a union so all scene structs share memory. `sceneSet(type)` defers the transition — the old scene disposes before the new one inits.
 Currently the only scene is `SCENE_TYPE_OVERWORLD` → `src/dusk/scene/overworld/sceneoverworld.c`.
@@ -1,124 +0,0 @@
 # Story, Items & Save
 ---
 ## Story flags (`src/dusk/rpg/story/`)
 Story flags are the primary mechanism for tracking game-world state (quest progress, one-time events, unlocks). Each flag is a `uint8_t` value (`storyflagvalue_t`), so they can hold booleans or small counts.
 ### Defining flags
 Flags are defined in `src/dusk/rpg/story/storyflag.csv`:
 ```
 id,description,initial
 test,"Test flag for debugging purposes",1
 ```
 The build tool generates:
 - A `storyflag_t` enum (e.g. `STORY_FLAG_TEST`) in the generated header.
 - `STORY_FLAG_VALUES[]` — the runtime array, pre-populated with the `initial` column values.
 To add a flag: add a row to the CSV. The build re-runs the Python tool automatically on the next CMake build.
 ### Access
 ```c
 storyflagvalue_t v = storyFlagGet(STORY_FLAG_TEST);   // macro: array read
 storyFlagSet(STORY_FLAG_TEST, 1);                      // function: also marks save dirty
 ```
 `storyFlagGet` is a macro that directly indexes `STORY_FLAG_VALUES[]` — no function call overhead.
 ---
 ## Items (`src/dusk/rpg/item/`)
 ### Item definitions
 Items are defined in `src/dusk/rpg/item/item.csv`. The build tool generates `itemid_t` enum values and item metadata. `itemid_t` is a generated `uint8_t` typedef.
 ### Inventory (`inventory.h`)
 `inventory_t` is a generic container backed by a caller-supplied `inventorystack_t` array:
 ```c
 typedef struct {
  itemid_t item;
  uint8_t quantity;        // max ITEM_STACK_QUANTITY_MAX (255)
 } inventorystack_t;
 typedef struct {
  inventorystack_t *storage;
  uint8_t storageSize;
 } inventory_t;
 ```
 Key operations:
 ```c
 inventoryInit(&inv, storageArray, size);
 inventoryAdd(&inv, ITEM_POTION, 3);
 inventoryRemove(&inv, ITEM_POTION);
 inventorySet(&inv, ITEM_POTION, 10);
 inventoryGetCount(&inv, ITEM_POTION);   // returns 0 if not present
 inventoryItemExists(&inv, ITEM_POTION);
 inventoryIsFull(&inv);
 inventorySort(&inv, INVENTORY_SORT_BY_ID, false);
 ```
 `inventory_t` itself holds no data — the backing array is always external. This avoids fixed-size struct limits and lets different inventories (backpack, shop, chest) share the same logic.
 ### Backpack (`backpack.h`)
 The player's inventory is the global `BACKPACK` instance:
 ```c
 extern inventorystack_t BACKPACK_STORAGE[BACKPACK_STORAGE_SIZE_MAX];  // 20 slots
 extern inventory_t BACKPACK;
 backpackInit();   // wires BACKPACK_STORAGE into BACKPACK
 ```
 ---
 ## Save system (`src/dusk/save/`)
 The save system is stubbed out — it exists and compiles but is commented out of engine init (`engine.c`). What follows describes the design as implemented.
 ### Slots
 `save_t SAVE` holds `SAVE_FILE_COUNT_MAX` slots:
 ```c
 typedef struct {
  savefile_t files[SAVE_FILE_COUNT_MAX];
  saveplatform_t platform;   // platform-specific state (paths, card handles)
 } save_t;
 ```
 ### Streams
 `savestream_t` (`save/savestream.h`) is a raw byte cursor used to serialize/deserialize `savefile_t`. Platform backends in `src/dusk{platform}/save/` implement the actual I/O:
 - Linux: filesystem files in a save directory.
 - GameCube/Wii: memory card via libogc.
 ### API
 ```c
 saveInit();
 saveLoad(slot);     // reads platform storage → savefile_t
 saveWrite(slot);    // writes savefile_t → platform storage
 saveDelete(slot);
 saveExists(slot);   // bool
 saveGet(slot);      // returns savefile_t *
 saveDispose();
 ```
 ---
 ## Locale / i18n (`src/dusk/locale/`)
 Translations are loaded from `.po` files in `assets/locale/` (e.g. `en_US.po`). `localemanager.c` manages the active locale and exposes a key→string lookup. `assetlocaleloader.c` parses the PO format via the asset system.
 All player-visible strings must go through the locale system rather than being hardcoded. The locale is loaded asynchronously via the asset system so it is available before the first scene renders.
@@ -1,114 +0,0 @@
 # World
 Source: `src/dusk/rpg/overworld/`
 ---
 ## Coordinate system
 Three nested coordinate spaces, each defined in `worldpos.h`:
 | Type | Description | Unit |
 |---|---|---|
 | `worldpos_t` | Tile-level absolute position `{x, y, z}` | `worldunit_t` (int16) |
 | `chunkpos_t` | Chunk-grid position `{x, y, z}` | `chunkunit_t` (int16) |
 | `fixed_t[3]` | Smooth sub-tile position used by entities | Q24.8 fixed-point |
 One chunk = `CHUNK_WIDTH × CHUNK_HEIGHT × CHUNK_DEPTH` tiles (16 × 16 × 8).
 The loaded world window = `MAP_CHUNK_WIDTH × MAP_CHUNK_HEIGHT × MAP_CHUNK_DEPTH` chunks (5 × 5 × 3).
 Conversion helpers (all in `worldpos.c`):
 ```c
 worldPosToChunkPos(&worldPos, &chunkPos);   // tile → chunk grid
 chunkPosToWorldPos(&chunkPos, &worldPos);   // chunk grid → tile origin
 worldPosToChunkTileIndex(&worldPos);        // tile → index within its chunk
 chunkPosToIndex(&chunkPos);                 // chunk grid → linear index in MAP.chunks[]
 worldPosToFixed(&worldPos, fixedOut);       // tile → entity fixed position
 fixedToWorldPos(fixedPos);                  // entity fixed → tile (truncates frac)
 ```
 ---
 ## Tiles
 Defined in `tile.h` as a plain `tile_t` enum:
 ```
 TILE_SHAPE_NULL    — empty / unloaded
 TILE_SHAPE_GROUND  — solid flat tile
 TILE_SHAPE_RAMP_*  — directional ramps (N/S/E/W + diagonals NE/NW/SE/SW)
 ```
 Key predicates:
 - `tileIsWalkable(tile)` — true for GROUND and all ramp shapes.
 - `tileIsRamp(tile)` — true only for ramp shapes.
 Entity walk code (`entity.c`) checks both the current tile and the target tile to decide whether the entity steps forward flat, raises one Z level (walking up a ramp), or falls one Z level (stepping onto a downward ramp from above).
 ---
 ## Chunks
 `chunk_t` (`chunk.h`) holds:
 - `position` — its `chunkpos_t` in the world grid
 - `tiles[CHUNK_TILE_COUNT]` — flat array of `tile_t`, indexed by `chunkGetTileIndex()`
 - `vertices[CHUNK_VERTEX_COUNT]` / `mesh` — pre-baked mesh uploaded to GPU on load
 - `entities[CHUNK_ENTITY_COUNT_MAX]` — indices into `ENTITIES[]` currently in this chunk (sentinel `0xFF`)
 - `testColor` — temporary debug color (checkerboard), will be replaced by real tileset data
 Tile layout within a chunk is `z * W*H + y * W + x` (Z-major, row-major in XY).
 ---
 ## Map
 `map_t MAP` (`map.h`) is the single global map instance.
 ```c
 chunk_t chunks[MAP_CHUNK_COUNT];         // flat storage — index is NOT world position
 chunk_t *chunkOrder[MAP_CHUNK_COUNT];    // draw-order sorted pointers into chunks[]
 chunkpos_t chunkPosition;               // world-grid origin of the loaded window
 bool_t loaded;
 ```
 ### Load / unload
 `mapInit()` allocates chunk meshes and performs the initial load of all chunks in the starting window.
 `mapPositionSet(newPos)` shifts the window:
 1. Determines which of the `MAP_CHUNK_COUNT` slots remain within the new window vs. fall outside it.
 2. Calls `mapChunkUnload()` on every chunk that falls outside (nulls its entity slots, zeroes `vertCount`).
 3. Reuses freed slots for newly-in-range chunks; calls `mapChunkLoad()` on each.
 4. Rebuilds `chunkOrder[]` in XYZ order for the new position.
 ### Chunk load (current stub)
 `mapChunkLoad()` currently:
 - Fills all tiles with `TILE_SHAPE_GROUND`
 - Assigns a checkerboard debug color based on chunk XY parity
 - Bakes a flat sprite-batch quad mesh for the z=0 layer and uploads it via `meshFlush()`
 - Skips mesh generation for z > 0 chunks (they're empty)
 ### Tile lookup
 ```c
 tile_t mapGetTile(const worldpos_t position);
 ```
 Converts `position` to its chunk, looks up the chunk in `chunkOrder`, then indexes into `chunk->tiles[]`. Returns `TILE_SHAPE_NULL` for any out-of-bounds position or when the map is not loaded.
 ---
 ## Camera
 `rpgcamera_t RPG_CAMERA` (`rpgcamera.h`) has two modes:
 ```c
 RPG_CAMERA_MODE_FREE            // free worldpos; camera.free holds the position
 RPG_CAMERA_MODE_FOLLOW_ENTITY   // tracks ENTITIES[followEntityId]
 ```
 `rpgCameraGetPosition()` returns the active world tile position in either mode.
 The scene renderer (`sceneoverworld.c`) uses `rpgCameraGetPosition()` to build the `glm_lookat` view matrix. When following an entity, it sub-tile interpolates between `entity->lastPosition` and `entity->position` using `entity->animTime / ENTITY_ANIM_WALK_DURATION` to smooth movement.
@@ -1,96 +0,0 @@
 # Save & Locale
 ---
 ## Save system (`src/dusk/save/`)
 Slot-based persistent storage. Currently disabled in engine init (commented out in `engine.c`) — the system is fully implemented but not yet wired up.
 ### Slots
 Up to `SAVE_FILE_COUNT_MAX` (3) save slots. The global `SAVE` holds all slots:
 ```c
 saveInit();
 saveExists(slot);          // bool_t — check before load
 saveLoad(slot);            // read from platform storage → SAVE.files[slot]
 saveWrite(slot);           // write SAVE.files[slot] → platform storage
 saveDelete(slot);
 savefile_t *f = saveGet(slot);
 saveDispose();
 ```
 ### Save file format
 `savefile_t` is the serialized struct stored per slot. Currently minimal:
 ```c
 typedef struct {
  char_t header[3];    // "DSK"
  uint32_t version;    // SAVE_FILE_VERSION = 1
  bool_t exists;
 } savefile_t;
 ```
 Extend this struct to add game-specific save data (player position, story flags, etc.).
 ### Stream serialization (`save/savestream.h`)
 `savestream_t` is a cursor used to read/write a save slot's bytes. It CRC32-checksums all data written through it and verifies the checksum on read.
 Write a save:
 ```c
 savestream_t stream;
 // (platform opens stream for slot)
 saveFileWriteHeader(&stream, SAVE_FILE_HEADER);
 saveFileWriteVersion(&stream, SAVE_FILE_VERSION);
 saveFileWriteBool(&stream, myFlag);
 saveFileWriteInt32(&stream, myInt);
 saveFileWriteString(&stream, myString, sizeof(myString));
 saveStreamFinalizeWriteImpl(&stream);   // writes CRC
 ```
 Read a save:
 ```c
 saveFileReadHeader(&stream, headerBuf);
 saveFileReadVersion(&stream, &version);
 saveFileReadBool(&stream, &myFlag);
 saveFileReadInt32(&stream, &myInt);
 saveFileReadString(&stream, myString, sizeof(myString));
 saveStreamVerifyChecksumImpl(&stream, slot);   // returns error if CRC mismatch
 ```
 All multi-byte values are stored in little-endian byte order. The `saveFile*` macros are thin wrappers over the `*Impl` functions that integrate `errorChain` — always use the macros.
 ### Platform backends
 Each `src/dusk{platform}/save/` provides `saveplatform_t` (e.g. a file path on Linux, a memory-card handle on GameCube). The stream implementations (`savestream{platform}.c`) do the actual I/O.
 ---
 ## Locale / i18n (`src/dusk/locale/`)
 Translations are stored as GNU `.po` files in `assets/locale/`. Only `en_US.po` currently exists.
 ### Loading
 `localemanager_t LOCALE` tracks the active locale and its in-progress asset entry:
 ```c
 localeManagerInit();                         // loads en_US by default
 localeManagerSetLocale(&LOCALE_EN_US);       // switch locale (async load)
 localeManagerDispose();
 ```
 `LOCALE_EN_US` is a predefined `localeinfo_t` constant (`name = "en-US"`, `file = "locale/en_US.po"`).
 ### Looking up strings
 ```c
 char_t buf[128];
 localeManagerGetText("my.key", buf, sizeof(buf), 1, /* format args */ );
 ```
 The macro handles plural forms and `printf`-style format arguments. Pass plural `1` for singular, any other value for plural.
 `assetlocaleloader.c` parses the `.po` format (msgid / msgstr pairs) into a key→string table during the async asset load phase.
@@ -1,403 +0,0 @@
 # Coding Style
 All source is C11. Everything below is derived from the existing codebase — match it exactly.
 ---
 ## File structure
 ### Headers (`.h`)
 ```c
 /**
 * Copyright (c) 2026 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "direct/dependency.h"
 ```
 - `#pragma once` always, never `#ifndef` guards.
 - No blank line between the license block and `#pragma once`.
 - One blank line between `#pragma once` and the first `#include`.
 ### Sources (`.c`)
 ```c
 /**
 * Copyright (c) 2026 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "thisfile.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 ```
 - First include is always the matching `.h` for this `.c` file.
 - Remaining includes follow with no separator unless logically grouped (then one blank line between groups — see [Include order](#include-order)).
 ---
 ## Include order
 In `.c` files, include in this order with a blank line between each group:
 1. The matching header (e.g. `#include "entity.h"`)
 2. Core utilities (`assert/assert.h`, `util/memory.h`, `util/math.h`, etc.)
 3. Engine subsystems (`display/...`, `input/...`, etc.)
 4. Domain subsystems (`rpg/...`, `scene/...`, etc.)
 In `.h` files, only include what the header directly requires. Never include more than necessary to make the type definitions in that header compile.
 All include paths are relative to `src/dusk/` (the root include directory). Use the full path:
 ```c
 #include "rpg/overworld/map.h"   // correct
 #include "map.h"                  // wrong
 ```
 ---
 ## Line length
 80-character limit. Break before it, not after.
 Multi-parameter function signatures break one param per line, with 2-space indent, closing `)` on its own line before `{`:
 ```c
 errorret_t textureInit(
  texture_t *texture,
  const int32_t width,
  const int32_t height,
  const textureformat_t format,
  const texturedata_t data
 ) {
 ```
 Same rule for calls that don't fit on one line:
 ```c
 assertTrue(
  data.paletted.palette->count ==
  mathNextPowTwo(data.paletted.palette->count),
  "Palette color count must be a power of 2"
 );
 ```
 ---
 ## Indentation and spacing
 - **2 spaces** per indent level. No tabs.
 - No space between a control keyword and its `(`:
  ```c
  if(x) {        // correct
  if (x) {       // wrong
  ```
 - No space between a function name and its `(` in either declarations or calls.
 - Opening brace on the same line:
  ```c
  void entityUpdate(entity_t *entity) {
  if(x) {
  for(int i = 0; i < n; i++) {
  ```
 - Closing brace always on its own line, except `} else {` and `} while(...)`.
 - One blank line between function definitions in `.c` files.
 - No trailing whitespace.
 ---
 ## Naming
 | Kind | Convention | Example |
 |---|---|---|
 | Types (struct/union/typedef) | `snake_case_t` | `entity_t`, `worldpos_t` |
 | Struct tags | `struct name_s` | `struct entity_s` |
 | Union tags | `union name_u` | `union texturedata_u` |
 | Enum tags (when typedef'd separately) | `name_enum_t` | `entitytype_enum_t` |
 | Functions | `subsystemVerb` (camelCase, noun-first) | `entityInit`, `mapGetTile` |
 | Macro constants | `UPPER_SNAKE_CASE` | `CHUNK_WIDTH`, `FIXED_ONE` |
 | Function-like macros | `camelCase` (same as functions) | `errorThrow`, `assertNotNull` |
 | Global subsystem instances | `UPPER_SNAKE_CASE` | `ENGINE`, `MAP`, `ENTITIES` |
 | Local variables | `camelCase` | `tileNew`, `spriteCount` |
 | Parameters | `camelCase` | `texture`, `worldPos` |
 Subsystem prefix always comes first in function names: `textureInit`, `shaderBind`, `spriteBatchFlush`. The verb describes the action: `Init`, `Update`, `Dispose`, `Get`, `Set`, `Is`, etc.
 ---
 ## Typedefs
 ### Structs
 ```c
 typedef struct {
  uint8_t id;
  entitytype_t type;
 } entity_t;
 ```
 Use a named tag (`struct entity_s`) only when forward declaration is required:
 ```c
 typedef struct entity_s {
  // ...
 } entity_t;
 ```
 ### Unions
 ```c
 typedef union texturedata_u {
  struct {
    uint8_t *indices;
    palette_t *palette;
  } paletted;
  color_t *rgbaColors;
 } texturedata_t;
 ```
 ### Enums
 When the enum values need to be a compact integer (common for arrays and flags), declare the enum separately and typedef an integer type:
 ```c
 typedef enum {
  ENTITY_TYPE_NULL,
  ENTITY_TYPE_PLAYER,
  ENTITY_TYPE_NPC,
  ENTITY_TYPE_COUNT
 } entitytype_enum_t;
 typedef uint8_t entitytype_t;  // actual type used everywhere
 ```
 Always include `_NULL` as the first value (zero) and `_COUNT` as the last value.
 ---
 ## `#define` constants
 All-caps, underscores. Wrap multi-token expressions in parentheses:
 ```c
 #define CHUNK_WIDTH 16
 #define CHUNK_HEIGHT CHUNK_WIDTH
 #define CHUNK_TILE_COUNT (CHUNK_WIDTH * CHUNK_HEIGHT * CHUNK_DEPTH)
 ```
 Multi-line macros: backslash continuation, body indented 2 spaces, closing line has no backslash:
 ```c
 #define errorThrow(message, ...) \
  return errorThrowImpl(\
    &ERROR_STATE, ERROR_NOT_OK, __FILE__, __func__, __LINE__, (message), \
    ##__VA_ARGS__ \
  )
 ```
 ---
 ## `const` usage
 Mark every pointer and value parameter `const` unless the function modifies it:
 ```c
 void entityTurn(entity_t *entity, const entitydir_t direction);
 errorret_t textureInit(texture_t *texture, const int32_t width, ...);
 ```
 `entity_t *entity` is non-const because the function writes to it; `direction` is const because it is read-only.
 ---
 ## `void` in no-argument functions
 Use `(void)` in definitions and declarations of zero-parameter functions:
 ```c
 errorret_t engineUpdate(void);
 errorret_t spriteBatchFlush(void);
 ```
 ---
 ## Unused parameters
 Do **not** use `(void)param;` casts to suppress unused-parameter warnings. They are
 redundant noise. If a callback signature is fixed by a function-pointer type and the
 parameter is genuinely unused, just leave it — do not suppress:
 ```c
 // correct — parameter unused, no cast
 errorret_t sceneTestUpdate(scenedata_t *data) {
  errorOk();
 }
 // wrong
 errorret_t sceneTestUpdate(scenedata_t *data) {
  (void)data;
  errorOk();
 }
 ```
 ---
 ## Global subsystem state
 Each subsystem exposes a single global instance declared `extern` in the header and defined (once) in the `.c` file:
 ```c
 // entity.h
 extern entity_t ENTITIES[ENTITY_COUNT];
 // entity.c
 entity_t ENTITIES[ENTITY_COUNT];
 ```
 Never define a subsystem global as `static` in a header.
 ---
 ## Assertions
 Place assertions at the very top of a function, before any logic:
 ```c
 void entityInit(entity_t *entity, const entitytype_t type) {
  assertNotNull(entity, "Entity pointer cannot be NULL");
  assertTrue(type < ENTITY_TYPE_COUNT, "Invalid entity type");
  // ... actual logic
 }
 ```
 Available assertion macros (from `assert/assert.h`):
 - `assertNotNull(ptr, msg)`
 - `assertNull(ptr, msg)`
 - `assertTrue(expr, msg)`
 - `assertFalse(expr, msg)`
 - `assertUnreachable(msg)`
 - `assertStringEqual(a, b, msg)`
 - `assertIsMainThread(msg)` / `assertNotMainThread(msg)`
 ---
 ## Error handling style
 Functions that can fail return `errorret_t`. Three patterns:
 ```c
 // Propagate a child call's failure and return from this function:
 errorChain(someCall());
 // Return success:
 errorOk();
 // Return failure:
 errorThrow("Descriptive message %s", variable);
 ```
 `errorChain` is used inline — do not capture the result first:
 ```c
 errorChain(textureInitPlatform(texture, width, height, format, data));  // correct
 errorret_t r = textureInitPlatform(...); errorChain(r);                 // wrong
 ```
 ---
 ## Struct initialization
 Use C99 designated initializers for any struct literal with more than one field:
 ```c
 static const entitycallback_t ENTITY_CALLBACKS[ENTITY_TYPE_COUNT] = {
  [ENTITY_TYPE_NULL] = { NULL },
  [ENTITY_TYPE_PLAYER] = {
    .init = playerInit,
    .movement = playerInput
  },
 };
 ```
 ```c
 shadermaterial_t material = {
  .unlit = {
    .color = COLOR_WHITE,
    .texture = NULL
  }
 };
 ```
 ---
 ## Fixed-size array iteration
 Prefer pointer arithmetic with `do/while` over index loops for iterating through fixed global arrays:
 ```c
 entity_t *ent = ENTITIES;
 do {
  if(ent->type == ENTITY_TYPE_NULL) continue;
  // ...
 } while(++ent, ent < &ENTITIES[ENTITY_COUNT]);
 ```
 Use `for` loops when an index variable is actually needed.
 ---
 ## Comments
 Comments explain *why*, not *what*. One short inline comment is fine; multi-line block comments for non-obvious invariants only.
 ```c
 // Walking up a ramp — only the direction the ramp faces is valid.
 if(tileIsRamp(tileCurrent) && ...) {
 ```
 Section labels inside long functions are acceptable:
 ```c
 // Chunks
 {
  ...
 }
 // Entities
 {
  ...
 }
 ```
 Doc comments on public functions use Javadoc style with `@param` / `@return`:
 ```c
 /**
 * Gets the tile at the given world position.
 *
 * @param position The world position.
 * @return The tile at that position, or TILE_NULL if the chunk is unloaded.
 */
 tile_t mapGetTile(const worldpos_t position);
 ```
 ---
 ## Platform-conditional code
 Use the `DUSK_*` compile-definition macros set by `cmake/targets/<target>.cmake`:
 ```c
 #ifdef DUSK_THREAD_PTHREAD
  #include "thread/thread.h"
  extern pthread_t ASSERT_MAIN_THREAD_ID;
 #endif
 ```
 Never use `#ifdef __linux__`, `#ifdef _WIN32`, etc. directly — go through the engine macros.
@@ -1,177 +0,0 @@
 # Engine Systems
 Smaller systems that support the engine but don't warrant their own file each.
 ---
 ## Time (`src/dusk/time/`)
 `dusktime_t TIME` tracks fixed and dynamic delta time.
 ```c
 TIME.delta         // fixed_t: always DUSK_TIME_STEP (16ms default) on fixed-rate platforms
 TIME.time          // fixed_t: total elapsed time in seconds
 ```
 On platforms with `DUSK_TIME_DYNAMIC` (Linux/SDL2):
 ```c
 TIME.dynamicDelta  // fixed_t: actual time since last frame
 TIME.dynamicTime   // fixed_t: total elapsed (dynamic)
 TIME.dynamicUpdate // bool_t: true when a real tick occurred
 ```
 Call `timeUpdate()` once per frame (before input/logic). `timeGetEpoch()` returns the current wall-clock time as a `dusktimeepoch_t`.
 ### Epoch time (`time/timeepoch.h`)
 `dusktimeepoch_t` stores a Unix timestamp (double) with timezone offset. Utilities:
 ```c
 dusktimeepoch_t e = timeGetEpoch();
 timeEpochGetHours(e)      // 0–23
 timeEpochGetMinutes(e)    // 0–59
 timeEpochGetSeconds(e)    // 0–59
 timeEpochGetDayOfMonth(e) // 0–30
 timeEpochGetMonth(e)      // 0–11
 timeEpochGetYear(e)
 // Format: %Y year, %m month, %d day, %H hour, %M minute, %S second
 timeEpochFormat(e, "%Y-%m-%d %H:%M:%S", buf, sizeof(buf));
 // Compare: returns -1, 0, 1
 timeEpochCompare(a, b);
 // Timezone shift:
 dusktimeepoch_t local = timeEpochSwitchTimeZone(e, offsetHours);
 ```
 ---
 ## Thread (`src/dusk/thread/`)
 Currently only the pthread backend (`DUSK_THREAD_PTHREAD`) exists. Thread objects are `thread_t` — used primarily by the asset loader.
 ```c
 threadInit(&thread, myCallback);   // myCallback: void (*)(thread_t *)
 threadStart(&thread);              // blocks until thread is RUNNING
 threadStop(&thread);               // requests stop, blocks until STOPPED
 // Inside the thread callback:
 while(!threadShouldStop(&thread)) { /* work */ }
 ```
 State flow: `STOPPED → STARTING → RUNNING → (STOP_REQUESTED) → STOPPED`.
 ### Mutex (`thread/threadmutex.h`)
 ```c
 threadMutexInit(&lock);
 threadMutexLock(&lock);
 threadMutexUnlock(&lock);
 threadMutexTryLock(&lock);       // non-blocking; returns false if already held
 threadMutexWaitLock(&lock);      // release lock and sleep until signalled
 threadMutexSignal(&lock);        // wake a thread waiting on this mutex
 threadMutexDispose(&lock);
 ```
 ### Thread-local storage
 `THREAD_LOCAL` expands to `__thread` (GCC) on pthread platforms. Used for the per-thread error state (`ERROR_STATE` in `error/error.h`).
 ---
 ## Event (`src/dusk/event/`)
 A fixed-capacity multicast callback list.
 ```c
 // Declare backing arrays (choose a size):
 eventcallback_t cbs[4];
 void *users[4];
 event_t myEvent;
 eventInit(&myEvent, cbs, users, 4);
 eventSubscribe(&myEvent, myCallback, myUser);
 eventUnsubscribe(&myEvent, myCallback);
 eventInvoke(&myEvent, params);   // calls all subscribers; params passed as-is
 ```
 Callback signature: `void cb(void *params, void *user)`.
 `event_t` does not own its callback/user arrays. Always declare them alongside the event in the same struct or as static arrays.
 ---
 ## Console (`src/dusk/console/`)
 `CONSOLE` is a scrolling in-game terminal for debug output. On POSIX platforms (`DUSK_CONSOLE_POSIX`) it also polls stdin in a thread so commands can be typed during a running session.
 ```c
 consolePrint("Value is %d", x);   // printf-style; thread-safe
 consoleDraw();                     // renders visible history lines to screen
 ```
 Configuration constants (`consoledefs.h`):
 - `CONSOLE_LINE_MAX` — 512 chars per line
 - `CONSOLE_HISTORY_MAX` — 16 lines of scrollback
 - `CONSOLE_EXEC_BUFFER_MAX` — 32 pending exec commands
 `CONSOLE.visible` controls whether `consoleDraw()` actually renders anything.
 ---
 ## Log (`src/dusk/log/`)
 Two simple output functions, implemented per-platform:
 ```c
 logDebug("format %s", arg);   // debug output (stdout on Linux, debug channel on consoles)
 logError("format %s", arg);   // error output; may pause execution on some platforms
 ```
 These go directly to the platform's native output and are not buffered by the console history.
 ---
 ## System / Platform (`src/dusk/system/`)
 `systemInit()` runs platform-specific startup (e.g. Wii PAD init, PSP kernel setup). Must be the first call in `engineInit()`.
 ```c
 systemplatform_t p = systemGetPlatform();   // SYSTEM_PLATFORM_LINUX, _PSP, etc.
 systemdialogtype_t d = systemGetActiveDialogType();
 // SYSTEM_DIALOG_TYPE_NONE / RENDER_BLOCKING / TICK_BLOCKING
 ```
 The full platform list is defined via X-macro in `system/systemplatformlist.h`:
 | Constant | Value |
 |---|---|
 | `SYSTEM_PLATFORM_LINUX` | 0 |
 | `SYSTEM_PLATFORM_KNULLI` | 1 |
 | `SYSTEM_PLATFORM_PSP` | 2 |
 | `SYSTEM_PLATFORM_GAMECUBE` | 3 |
 | `SYSTEM_PLATFORM_WII` | 4 |
 ---
 ## Network (`src/dusk/network/`)
 `network_t NETWORK` manages platform connection state. The engine calls `networkInit` / `networkUpdate` / `networkDispose`; game code uses the request API:
 ```c
 networkRequestConnection(onConnected, onFailed, onDisconnect, user);
 networkRequestDisconnection(onComplete, user);
 networkIsConnected();   // bool_t
 ```
 State machine: `DISCONNECTED → CONNECTING → CONNECTED → DISCONNECTING → DISCONNECTED`.
 Network address info (after connection):
 ```c
 networkinfo_t info = networkGetInfo();
 // info.type = NETWORK_TYPE_IPV4 / IPV6
 // info.ipv4.ip[4] or info.ipv6.ip[16]
 ```
 Platform backends implement `networkPlatformInit/Update/Dispose/IsConnected`. Currently only Linux (socket-based) and PSP/Vita are implemented.
@@ -1,123 +0,0 @@
 # 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.
@@ -1,162 +0,0 @@
 # Utilities
 Source: `src/dusk/util/`
 ---
 ## String (`util/string.h`)
 **Always use these instead of stdlib equivalents** (`strcmp`, `strcpy`, `sprintf`, etc.).
 ```c
 stringCopy(dest, src, destSize);           // safe strncpy; always null-terminates
 stringCompare(a, b);                       // -1 / 0 / 1
 stringEquals(a, b);                        // bool_t
 stringCompareInsensitive(a, b);            // case-insensitive -1 / 0 / 1
 stringTrim(str);                           // in-place strip leading/trailing whitespace
 stringFindLastChar(str, c);                // last occurrence pointer or NULL
 stringFormat(dest, destSize, fmt, ...);    // snprintf wrapper; pass NULL dest to get length
 stringFormatVA(dest, destSize, fmt, args); // va_list version
 stringIsWhitespace(c);                     // bool_t
 // Parse:
 stringToI32(str, &out)   → bool_t
 stringToI64(str, &out)   → bool_t
 stringToI16(str, &out)   → bool_t
 stringToU16(str, &out)   → bool_t
 stringToF32(str, &out)   → bool_t
 // Suffix checks:
 stringEndsWith(str, suffix)                 → bool_t
 stringEndsWithCaseInsensitive(str, suffix)  → bool_t
 stringIncludesString(haystack, needle)      → bool_t
 ```
 ---
 ## Memory (`util/memory.h`)
 **Always use these instead of `malloc`/`free`/`memcpy`/`memset` directly.**
 ```c
 memoryAllocate(size)          → void *      // malloc + tracks pointer count
 memoryAlign(alignment, size)  → void *      // aligned malloc
 memoryFree(ptr)                             // free + decrements count
 memoryReallocate(&ptr, size)               // realloc
 memoryResize(&ptr, oldSize, newSize)       // realloc + copy (safe reshape)
 memoryTrack(ptr)                           // track externally-malloc'd pointer
 memoryCopy(dest, src, size)                // memcpy
 memoryMove(dest, src, size)                // memmove
 memorySet(dest, value, size)               // memset
 memoryZero(dest, size)                     // memset 0
 memoryCompare(a, b, size)     → int_t      // memcmp
 // Useful for uploading vertex data with different source/dest layouts:
 memoryCopyInterleaved(dest, destStride, src, srcStride, elementSize, count);
 memoryCopyRangeSafe(dest, start, end, sizeMax);  // copy with bounds check
 memoryGetAllocatedCount()     → size_t     // current malloc'd block count
 ```
 ---
 ## Math (`util/math.h`)
 ```c
 mathNextPowTwo(value)    → uint32_t   // next power of two >= value
 mathMax(a, b)                         // macro
 mathMin(a, b)                         // macro
 mathClamp(x, lower, upper)            // macro
 mathAbs(amt)                          // macro
 mathModFloat(x, y)       → float_t    // always non-negative modulo
 mathLerp(a, b, t)        → float_t    // linear interpolation (floats)
 ```
 For fixed-point lerp use `fixedLerp(a, b, t)` from `util/fixed.h`.
 `MATH_PI` is defined as `M_PI`.
 ---
 ## Fixed-point (`util/fixed.h`)
 Q24.8 format: 24-bit integer part, 8-bit fractional part (`int32_t`). See [architecture.md](architecture.md#fixed-point-math) for the full API.
 Quick reference:
 ```c
 FIXED(1.5f)               // compile-time literal
 fixedFromI32(3)           // runtime int → fixed
 fixedToFloat(f)           // fixed → float (only for GL/platform APIs)
 fixedMul(a, b)            // multiplication (not just addition)
 fixedDiv(a, b)            // division
 fixedLerp(a, b, t)        // lerp where t ∈ [0, FIXED_ONE]
 ```
 ---
 ## Array (`util/array.h`)
 ```c
 arrayReverse(array, count, size);   // in-place reverse; size = sizeof(element)
 ```
 ---
 ## Sort (`util/sort.h`)
 ```c
 sortQuick(array, count, size, compare);   // quicksort
 sortBubble(array, count, size, compare);  // bubble sort (small arrays)
 sort(array, count, size, compare);        // macro alias for sortQuick
 // Convenience uint8_t sorter:
 sortArrayU8(array, count);
 int sortArrayU8Compare(const void *a, const void *b);   // comparator
 ```
 `sortcompare_t` matches `qsort` comparator signature: `int (*)(const void *, const void *)`.
 ---
 ## Reference counting (`util/ref.h`)
 ```c
 refInit(&ref, dataPtr, onLock, onUnlock, onAllUnlocked);
 refLock(&ref);              // increments count, calls onLock
 bool_t hit_zero = refUnlock(&ref);   // decrements; calls onAllUnlocked when 0
 ```
 Used internally by the asset entry system to track how many callers hold a reference to a loaded asset entry.
 ---
 ## CRC32 (`util/crypt.h`)
 ```c
 // One-shot:
 uint32_t crc = cryptCRC32(data, size);
 // Streaming:
 uint32_t acc = cryptCRC32Begin();
 cryptCRC32Update(&acc, chunk1, len1);
 cryptCRC32Update(&acc, chunk2, len2);
 uint32_t final = cryptCRC32End(acc);
 ```
 Used by the save stream to checksum save files.
 ---
 ## Endian (`util/endian.h`)
 All serialized data (save files, asset headers) is little-endian. Convert to/from host byte order:
 ```c
 uint32_t val = endianLittleToHost32(rawU32);
 uint16_t val = endianLittleToHost16(rawU16);
 float_t  val = endianLittleToHostFloat(rawFloat);
 ```
 `isHostLittleEndian()` returns a bool at runtime. The compile-time defines `DUSK_PLATFORM_ENDIAN_LITTLE` / `DUSK_PLATFORM_ENDIAN_BIG` are set by `cmake/targets/<target>.cmake`.
@@ -0,0 +1,49 @@
 name: Setup devkitPro
 description: Install devkitPro with GameCube/Wii packages on an Ubuntu runner
 runs:
  using: composite
  steps:
    - name: Install apt dependencies
      shell: bash
      run: |
        sudo apt-get update
        sudo apt-get install -y \
          cmake \
          python3 \
          python3-pip \
          python3-polib \
          python3-pil \
          python3-dotenv \
          python3-pyqt5 \
          python3-opengl \
          xorriso
    - name: Install devkitPro pacman
      shell: bash
      run: |
        sudo ln -sf /proc/self/mounts /etc/mtab
        wget https://apt.devkitpro.org/install-devkitpro-pacman \
          -O /tmp/install-devkitpro-pacman
        echo "=== installer script contents ==="
        cat /tmp/install-devkitpro-pacman
        echo "================================="
        chmod +x /tmp/install-devkitpro-pacman
        sudo /tmp/install-devkitpro-pacman
        echo "DEVKITPRO=/opt/devkitpro" >> $GITHUB_ENV
        echo "DEVKITPPC=/opt/devkitpro/devkitPPC" >> $GITHUB_ENV
        echo "/opt/devkitpro/tools/bin" >> $GITHUB_PATH
        echo "/opt/devkitpro/devkitPPC/bin" >> $GITHUB_PATH
    - name: Install devkitPro GameCube/Wii packages
      shell: bash
      run: |
        sudo dkp-pacman -S --needed --noconfirm \
          gamecube-dev \
          gamecube-sdl2 \
          ppc-liblzma \
          ppc-libzip \
          libogc2 \
          gamecube-tools \
          ppc-libmad \
          ppc-zlib-ng \
          ppc-bzip2 \
          ppc-zstd
@@ -0,0 +1,20 @@
 name: Setup pspdev
 description: Install the pspdev PSP toolchain on an Ubuntu runner
 runs:
  using: composite
  steps:
    - name: Install dependencies
      shell: bash
      run: |
        sudo apt-get update
        sudo apt-get install -y cmake python3 python3-pip python3-dotenv
    - name: Install pspdev toolchain
      shell: bash
      run: |
        wget -q \
          https://github.com/pspdev/pspdev/releases/latest/download/pspdev-ubuntu-latest-x86_64.tar.gz \
          -O /tmp/pspdev.tar.gz
        sudo tar -xzf /tmp/pspdev.tar.gz -C /usr/local
        echo "PSPDEV=/usr/local/pspdev" >> $GITHUB_ENV
        echo "/usr/local/pspdev/bin" >> $GITHUB_PATH
@@ -4,27 +4,37 @@ on:
    tags:
      - '*'
 jobs:
  run-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6
      - name: Set up Docker
        uses: docker/setup-docker-action@v5
      - name: Run tests in Docker
        run: ./scripts/test-linux-docker.sh
  build-linux:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v4
-      - name: Set up Docker
+      - name: Install dependencies
-        uses: docker/setup-docker-action@v5
+        run: |
          sudo apt-get update
          sudo apt-get install -y \
            build-essential \
            cmake \
            python3 \
            python3-pip \
            python3-polib \
            python3-pil \
            libsdl2-dev \
            libgl1-mesa-dev \
            libzip-dev \
            python3-dotenv \
            python3-pyqt5 \
            python3-opengl \
            xz-utils \
            liblzma-dev \
            libbz2-dev \
            zlib1g-dev \
            git \
            libssl-dev
      - name: Build Linux
-        run: ./scripts/build-linux-docker.sh
+        run: ./scripts/build-linux.sh
      - name: Upload Linux binary
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v3
        with:
          name: dusk-linux
          path: build-linux/Dusk
@@ -34,53 +44,72 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v4
-      - name: Set up Docker
+      - name: Setup pspdev
-        uses: docker/setup-docker-action@v5
+        uses: ./.github/actions/setup-pspdev
-      - name: Build psp
+      - name: Build PSP
-        run: ./scripts/build-psp-docker.sh
+        run: ./scripts/build-psp.sh
      - name: Move EBOOT.PBP to Dusk subfolder
        run: |
          mkdir -p ./git-artifcats/Dusk/PSP/GAME/Dusk
          cp build-psp/EBOOT.PBP ./git-artifcats/Dusk/PSP/GAME/Dusk/EBOOT.PBP
-      - name: Upload psp binary
+      - name: Upload PSP binary
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v3
        with:
          name: dusk-psp
          path: ./git-artifcats/Dusk
          if-no-files-found: error
  # build-vita:
  #   runs-on: ubuntu-latest
  #   steps:
  #     - name: Checkout repository
  #       uses: actions/checkout@v6
  #     - name: Set up Docker
  #       uses: docker/setup-docker-action@v5
  #     - name: Build Vita
  #       run: ./scripts/build-vita-docker.sh
  #     - name: Upload Vita binary
  #       uses: actions/upload-artifact@v6
  #       with:
  #         name: dusk-vita
  #         path: build-vita/Dusk.vpk
  #         if-no-files-found: error
  build-knulli:
    runs-on: ubuntu-latest
    container:
      image: debian:trixie
    steps:
      - name: Install Node.js
        run: apt-get update && apt-get install -y nodejs
      - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v4
-      - name: Set up Docker
+      - name: Install dependencies
-        uses: docker/setup-docker-action@v5
+        run: |
-      - name: Build knulli
+          dpkg --add-architecture arm64
-        run: ./scripts/build-knulli-docker.sh
+          apt-get update
          apt-get install -y --no-install-recommends \
            crossbuild-essential-arm64 \
            ca-certificates \
            pkg-config \
            cmake \
            make \
            ninja-build \
            git \
            file \
            python3 \
            python3-pip \
            python3-polib \
            python3-pil \
            python3-dotenv \
            python3-pyqt5 \
            python3-opengl \
            liblua5.4-dev:arm64 \
            xz-utils:arm64 \
            libbz2-dev:arm64 \
            zlib1g-dev:arm64 \
            libzip-dev:arm64 \
            libssl-dev:arm64 \
            libsdl2-dev:arm64 \
            liblzma-dev:arm64 \
            libopengl0:arm64 \
            libgl1:arm64 \
            libegl1:arm64 \
            libgles2:arm64 \
            libgl1-mesa-dev:arm64
      - name: Build Knulli
        run: ./scripts/build-knulli.sh
      - name: Move output to Dusk subfolder
        run: |
          mkdir -p ./git-artifcats/Dusk
          cp -r build-knulli/dusk ./git-artifcats/Dusk
-      - name: Upload knulli binary
+      - name: Upload Knulli binary
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v3
        with:
          name: dusk-knulli
          path: ./git-artifcats/Dusk
@@ -88,20 +117,31 @@ jobs:
  build-gamecube:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/extremscorner/libogc2:latest
    steps:
      - name: Install Node.js
        run: apt-get update && apt-get install -y nodejs
      - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v4
-      - name: Set up Docker
+      - name: Install additional dependencies
-        uses: docker/setup-docker-action@v5
+        run: |
          apt-get install -y \
            python3-pip python3-polib python3-pil \
            python3-dotenv python3-pyqt5 python3-opengl
          dkp-pacman -Syu --noconfirm
          dkp-pacman -S --needed --noconfirm \
            gamecube-sdl2 ppc-liblzma ppc-libzip \
            gamecube-tools ppc-libmad ppc-zlib-ng ppc-bzip2 ppc-zstd
      - name: Build GameCube
-        run: ./scripts/build-gamecube-docker.sh
+        run: ./scripts/build-gamecube.sh
-      - name: Copy output files.
+      - name: Copy output files
        run: |
          mkdir -p ./git-artifcats/Dusk
          cp build-gamecube/Dusk.dol ./git-artifcats/Dusk/Dusk.dol
          cp build-gamecube/dusk.dsk ./git-artifcats/Dusk/dusk.dsk
      - name: Upload GameCube binary
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v3
        with:
          name: dusk-gamecube
          path: ./git-artifcats/Dusk
@@ -109,21 +149,32 @@ jobs:
  build-gamecube-iso:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/extremscorner/libogc2:latest
    steps:
      - name: Install Node.js
        run: apt-get update && apt-get install -y nodejs
      - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v4
-      - name: Set up Docker
+      - name: Install additional dependencies
-        uses: docker/setup-docker-action@v5
+        run: |
          apt-get install -y \
            python3-pip python3-polib python3-pil \
            python3-dotenv python3-pyqt5 python3-opengl xorriso
          dkp-pacman -Syu --noconfirm
          dkp-pacman -S --needed --noconfirm \
            gamecube-sdl2 ppc-liblzma ppc-libzip \
            gamecube-tools ppc-libmad ppc-zlib-ng ppc-bzip2 ppc-zstd
      - name: Build GameCube ISO
-        run: ./scripts/build-gamecube-iso-docker.sh
+        run: ./scripts/build-gamecube-iso.sh
-      - name: Copy output files.
+      - name: Copy output files
        run: |
          mkdir -p ./git-artifcats/Dusk
          cp build-gamecube-iso/Dusk-NTSC-J.iso ./git-artifcats/Dusk/Dusk-NTSC-J.iso
          cp build-gamecube-iso/Dusk-NTSC-U.iso ./git-artifcats/Dusk/Dusk-NTSC-U.iso
          cp build-gamecube-iso/Dusk-PAL.iso    ./git-artifcats/Dusk/Dusk-PAL.iso
      - name: Upload GameCube ISO
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v3
        with:
          name: dusk-gamecube-iso
          path: ./git-artifcats/Dusk
@@ -131,21 +182,32 @@ jobs:
  build-wii:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/extremscorner/libogc2:latest
    steps:
      - name: Install Node.js
        run: apt-get update && apt-get install -y nodejs
      - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v4
-      - name: Set up Docker
+      - name: Install additional dependencies
-        uses: docker/setup-docker-action@v5
+        run: |
          apt-get install -y \
            python3-pip python3-polib python3-pil \
            python3-dotenv python3-pyqt5 python3-opengl
          dkp-pacman -Syu --noconfirm
          dkp-pacman -S --needed --noconfirm \
            gamecube-sdl2 ppc-liblzma ppc-libzip \
            gamecube-tools ppc-libmad ppc-zlib-ng ppc-bzip2 ppc-zstd
      - name: Build Wii
-        run: ./scripts/build-wii-docker.sh
+        run: ./scripts/build-wii.sh
-      - name: Copy output files.
+      - name: Copy output files
        run: |
          mkdir -p ./git-artifcats/Dusk/apps/Dusk
          cp build-wii/boot.dol ./git-artifcats/Dusk/apps/Dusk/boot.dol
          cp build-wii/dusk.dsk ./git-artifcats/Dusk/apps/Dusk/dusk.dsk
          cp build-wii/meta.xml ./git-artifcats/Dusk/apps/Dusk/meta.xml
      - name: Upload Wii binary
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v3
        with:
          name: dusk-wii
          path: ./git-artifcats/Dusk
@@ -153,21 +215,32 @@ jobs:
  build-wii-iso:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/extremscorner/libogc2:latest
    steps:
      - name: Install Node.js
        run: apt-get update && apt-get install -y nodejs
      - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v4
-      - name: Set up Docker
+      - name: Install additional dependencies
-        uses: docker/setup-docker-action@v5
+        run: |
          apt-get install -y \
            python3-pip python3-polib python3-pil \
            python3-dotenv python3-pyqt5 python3-opengl xorriso
          dkp-pacman -Syu --noconfirm
          dkp-pacman -S --needed --noconfirm \
            gamecube-sdl2 ppc-liblzma ppc-libzip \
            gamecube-tools ppc-libmad ppc-zlib-ng ppc-bzip2 ppc-zstd
      - name: Build Wii ISO
-        run: ./scripts/build-wii-iso-docker.sh
+        run: ./scripts/build-wii-iso.sh
-      - name: Copy output files.
+      - name: Copy output files
        run: |
          mkdir -p ./git-artifcats/Dusk
          cp build-wii-iso/Dusk-NTSC-J.iso ./git-artifcats/Dusk/Dusk-NTSC-J.iso
          cp build-wii-iso/Dusk-NTSC-U.iso ./git-artifcats/Dusk/Dusk-NTSC-U.iso
          cp build-wii-iso/Dusk-PAL.iso    ./git-artifcats/Dusk/Dusk-PAL.iso
      - name: Upload Wii ISO
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v3
        with:
          name: dusk-wii-iso
          path: ./git-artifcats/Dusk
@@ -0,0 +1,106 @@
 name: Test Dusk
 on:
  pull_request:
    branches:
      - main
 jobs:
  run-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            build-essential \
            cmake \
            python3 \
            python3-pip \
            python3-polib \
            python3-pil \
            libsdl2-dev \
            libgl1-mesa-dev \
            libzip-dev \
            python3-dotenv \
            python3-pyqt5 \
            python3-opengl \
            xz-utils \
            liblzma-dev \
            libbz2-dev \
            zlib1g-dev \
            git \
            libssl-dev
      - name: Run tests
        run: ./scripts/test-linux.sh
  # Emulator smoke tests: boot the built disc/EBOOT for a fixed window and
  # confirm the emulator doesn't crash. Not yet verified against a real
  # runner (no CI run has exercised these) -- continue-on-error so a
  # flaky/broken emulator step doesn't block the required Linux test job.
  run-tests-gamecube-dolphin:
    runs-on: ubuntu-latest
    continue-on-error: true
    container:
      image: ghcr.io/extremscorner/libogc2:latest
    steps:
      - name: Install Node.js
        run: apt-get update && apt-get install -y nodejs
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install additional dependencies
        run: |
          apt-get install -y \
            python3-pip python3-polib python3-pil \
            python3-dotenv python3-pyqt5 python3-opengl xorriso \
            dolphin-emu xvfb
          dkp-pacman -Syu --noconfirm
          dkp-pacman -S --needed --noconfirm \
            gamecube-sdl2 ppc-liblzma ppc-libzip \
            gamecube-tools ppc-libmad ppc-zlib-ng ppc-bzip2 ppc-zstd
      - name: Build GameCube ISO and boot it in Dolphin
        run: ./scripts/test-gamecube-dolphin.sh
  run-tests-wii-dolphin:
    runs-on: ubuntu-latest
    continue-on-error: true
    container:
      image: ghcr.io/extremscorner/libogc2:latest
    steps:
      - name: Install Node.js
        run: apt-get update && apt-get install -y nodejs
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install additional dependencies
        run: |
          apt-get install -y \
            python3-pip python3-polib python3-pil \
            python3-dotenv python3-pyqt5 python3-opengl xorriso \
            dolphin-emu xvfb
          dkp-pacman -Syu --noconfirm
          dkp-pacman -S --needed --noconfirm \
            gamecube-sdl2 ppc-liblzma ppc-libzip \
            gamecube-tools ppc-libmad ppc-zlib-ng ppc-bzip2 ppc-zstd
      - name: Build Wii ISO and boot it in Dolphin
        run: ./scripts/test-wii-dolphin.sh
  run-tests-psp-ppsspp:
    runs-on: ubuntu-latest
    continue-on-error: true
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Setup pspdev
        uses: ./.github/actions/setup-pspdev
      - name: Install PPSSPPHeadless build dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y git cmake ninja-build libsdl2-dev zlib1g-dev
      - name: Build PPSSPPHeadless
        run: |
          git clone --recursive --depth 1 https://github.com/hrydgard/ppsspp.git /tmp/ppsspp
          cmake -S /tmp/ppsspp -B /tmp/ppsspp/build -DCMAKE_BUILD_TYPE=Release
          cmake --build /tmp/ppsspp/build --target PPSSPPHeadless -- -j$(nproc)
          echo "PPSSPP_HEADLESS_BIN=/tmp/ppsspp/build/PPSSPPHeadless" >> "$GITHUB_ENV"
      - name: Build PSP EBOOT and boot it in PPSSPPHeadless
        run: ./scripts/test-psp-ppsspp.sh
@@ -1,65 +0,0 @@
 # CLAUDE.md
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 ## Project
 Dusk is a C11 RPG game targeting resource-constrained hardware (PSP, GameCube, Wii, PS Vita, Knulli handhelds) and Linux/OpenGL. All game code lives in `src/dusk/`; platform-specific backends live in `src/dusk{platform}/` (e.g. `src/duskgl/`, `src/duskpsp/`, `src/duskdolphin/`).
 Assets are zipped into `dusk.dsk` at build time and loaded at runtime via the asset system.
 ## Build
 ```bash
 # Linux (host)
 ./scripts/build-linux.sh          # outputs build-linux/Dusk
 # Other targets (require Docker)
 ./scripts/build-psp-docker.sh
 ./scripts/build-gamecube-docker.sh
 ./scripts/build-wii-docker.sh
 ./scripts/build-knulli-docker.sh
 ```
 Each script is a thin wrapper around:
 ```bash
 cmake -S . -B build-<target> -DDUSK_TARGET_SYSTEM=<target>
 cmake --build build-<target> -- -j$(nproc)
 ```
 ## Tests
 ```bash
 ./scripts/test-linux.sh           # builds and runs all tests
 # Manually run a single test binary after building:
 ./build-tests/test/<module>/test_<name>
 ```
 Tests use [cmocka](https://cmocka.org/) and are only compiled when `DUSK_BUILD_TESTS=ON`. Test sources live under `test/`.
 ## Key conventions
 - Use `stringCompare`, `stringCopy`, `stringEquals`, etc. from `util/string.h` — never `strcmp`, `strcpy`, and friends directly.
 - All functions that can fail return `errorret_t`. Use `errorThrow(...)`, `errorChain(call())`, and `errorOk()` macros — see `error/error.h`.
 - Positions and game-world values use `fixed_t` (Q24.8 fixed-point, `int32_t`) — not `float`. Use `FIXED(x)` for literals and the `fixedFrom*`/`fixedTo*` helpers in `util/fixed.h`.
 ## Coding style
 See [`.claude/style.md`](.claude/style.md) for the full style guide: indentation, line length, naming, typedefs, defines, include order, `const` usage, assertion placement, error handling, struct initialization, and platform conditionals.
 ## Architecture & systems
 | Doc | Covers |
 |---|---|
 | [`.claude/architecture.md`](.claude/architecture.md) | Platform abstraction pattern, subsystem lifecycle, error handling, code-generation pipeline |
 | [`.claude/display.md`](.claude/display.md) | Rendering pipeline: display state, screen, framebuffer, mesh, shader, texture, spritebatch, text |
 | [`.claude/input.md`](.claude/input.md) | Input actions, buttons, bindings, axis helpers, events |
 | [`.claude/asset.md`](.claude/asset.md) | Asset archive, entry lifecycle, loader types, async/sync split, low-level file I/O |
 | [`.claude/ui.md`](.claude/ui.md) | UI element system, textbox, frames, loading overlay, fullbox transitions, FPS counter |
 | [`.claude/animation.md`](.claude/animation.md) | Keyframe animation, easing functions |
 | [`.claude/systems.md`](.claude/systems.md) | Time, threading, mutex, events, console, logging, system/platform, network |
 | [`.claude/util.md`](.claude/util.md) | String, memory, math, fixed-point, array, sort, ref counting, CRC32, endian |
 | [`.claude/save.md`](.claude/save.md) | Save slots, stream serialization with CRC, locale/i18n |
 | [`.claude/rpg/index.md`](.claude/rpg/index.md) | RPG layer overview → [world](.claude/rpg/world.md), [entities](.claude/rpg/entity.md), [cutscenes](.claude/rpg/cutscene.md), [story/items](.claude/rpg/story.md) |
 | [`.claude/display-refactor.md`](.claude/display-refactor.md) | Planned render-queue refactor (Saturn port context) |
@@ -13,10 +13,10 @@ cmake_policy(SET CMP0079 NEW)
 # set(FETCHCONTENT_UPDATES_DISCONNECTED ON)
 option(DUSK_BUILD_TESTS "Enable tests" OFF)
 option(DUSK_NETWORKING "Enable networking support" OFF)
 # Game identity — override these per-project
 set(DUSK_GAME_NAME "Dusk" CACHE STRING "Game display name")
-set(DUSK_GAME_AUTHOR            "YouWish"             CACHE STRING "Game author / coder")
+set(DUSK_GAME_AUTHOR "YourWishes" CACHE STRING "Game author / coder")
 set(DUSK_GAME_SHORT_DESCRIPTION "Dusk game" CACHE STRING "One-line description")
 set(DUSK_GAME_LONG_DESCRIPTION  "No description yet." CACHE STRING "Full description")
@@ -91,6 +91,12 @@ target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME}
    DUSK_VERSION="${DUSK_VERSION}"
 )
 if(DUSK_NETWORKING)
  target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
    DUSK_NETWORKING
  )
 endif()
 # Toolchains
 include(cmake/targets/${DUSK_TARGET_SYSTEM}.cmake)
@@ -117,7 +123,11 @@ if(DUSK_BUILD_TESTS)
 endif()
 # Build assets
-file(GLOB_RECURSE DUSK_ASSET_FILES CONFIGURE_DEPENDS "${DUSK_ASSETS_DIR}/*")
+# Deliberately not CONFIGURE_DEPENDS: that reruns the full CMake configure
 # step (which invalidates generated headers and forces a huge rebuild) on
 # every single asset edit. Re-run cmake manually when assets are added or
 # removed.
 file(GLOB_RECURSE DUSK_ASSET_FILES "${DUSK_ASSETS_DIR}/*")
 add_custom_command(
  OUTPUT "${DUSK_ASSETS_ZIP}"
  COMMAND ${CMAKE_COMMAND} -E make_directory "${DUSK_ASSETS_DIR}"
@@ -1,12 +0,0 @@
 import sys, os
 import argparse
 # Check if the script is run with the correct arguments
 parser = argparse.ArgumentParser(description="Generate chunk header files")
 parser.add_argument('--assets', required=True, help='Dir to output built assets')
 parser.add_argument('--headers-dir', required=True, help='Directory to output individual asset headers (required for header build)')
 parser.add_argument('--output-headers', help='Output header file for built assets (required for header build)')
 parser.add_argument('--output-assets', required=True, help='Output directory for built assets')
 parser.add_argument('--output-file', required=True, help='Output file for built assets (required for wad build)')
 parser.add_argument('--input', required=True, help='Input assets to process', nargs='+')
 args = parser.parse_args()
@@ -1,66 +0,0 @@
 import sys, os
 from tools.asset.args import args
 from tools.asset.process.asset import processAsset
 from tools.asset.process.palette import processPaletteList
 from tools.asset.process.tileset import processTilesetList
 from tools.asset.process.language import processLanguageList
 from tools.asset.path import getBuiltAssetsRelativePath
 import zipfile
 # Parse input file args.
 inputAssets = []
 for inputArg in args.input:
  files = inputArg.split('$')
  for file in files:
    if str(file).strip() == '':
      continue
    pieces = file.split('#')
    if len(pieces) < 2:
      print(f"Error: Invalid input asset format '{file}'. Expected format: type#path[#option1%option2...]")
      sys.exit(1)
    options = {}
    if len(pieces) > 2:
      optionParts = pieces[2].split('%')
      for part in optionParts:
        partSplit = part.split('=')
        if len(partSplit) < 1:
          continue
        if len(partSplit) == 2:
          options[partSplit[0]] = partSplit[1]
        else:
          options[partSplit[0]] = True
    inputAssets.append({
      'type': pieces[0],
      'path': pieces[1],
      'options': options
    })
 if not inputAssets:
  print("Error: No input assets provided.")
  sys.exit(1)
 # Process each asset.
 files = []
 for asset in inputAssets:
  asset = processAsset(asset)
  files.extend(asset['files'])
 # Generate additional files
 files.extend(processLanguageList()['files'])
 # Take assets and add to a zip archive.
 outputFileName = args.output_file
 print(f"Creating output file: {outputFileName}")
 with zipfile.ZipFile(outputFileName, 'w') as zipf:
  for file in files:
    relativeOutputPath = getBuiltAssetsRelativePath(file)
    zipf.write(file, arcname=relativeOutputPath)
 # Generate additional headers.
 processPaletteList()
 processTilesetList()
@@ -1,12 +0,0 @@
 processedAssets = {}
 def assetGetCache(assetPath):
  if assetPath in processedAssets:
    return processedAssets[assetPath]
  return None
 def assetCache(assetPath, processedData):
  if assetPath in processedAssets:
    return processedAssets[assetPath]
  processedAssets[assetPath] = processedData
  return processedData
@@ -1,10 +0,0 @@
 import os
 from tools.asset.args import args
 def getAssetRelativePath(fullPath):
  # Get the relative path to the asset
  return os.path.relpath(fullPath, start=args.assets).replace('\\', '/')
 def getBuiltAssetsRelativePath(fullPath):
  # Get the relative path to the built asset
  return os.path.relpath(fullPath, start=args.output_assets).replace('\\', '/')
@@ -1,33 +0,0 @@
 import sys
 # from processtileset import processTileset
 from tools.asset.process.image import processImage
 from tools.asset.process.palette import processPalette
 from tools.asset.process.tileset import processTileset
 from tools.asset.process.map import processMap
 from tools.asset.process.language import processLanguage
 from tools.asset.process.script import processScript
 processedAssets = []
 def processAsset(asset):
  if asset['path'] in processedAssets:
    return
  processedAssets.append(asset['path'])
  # Handle tiled tilesets
  t = asset['type'].lower()
  if t == 'palette':
    return processPalette(asset)
  elif t == 'image':
    return processImage(asset)
  elif t == 'tileset':
    return processTileset(asset)
  elif t == 'map':
    return processMap(asset)
  elif t == 'language':
    return processLanguage(asset)
  elif t == 'script':
    return processScript(asset)
  else:
    print(f"Error: Unknown asset type '{asset['type']}' for path '{asset['path']}'")
    sys.exit(1)
@@ -1,134 +0,0 @@
 import os
 import sys
 from PIL import Image
 from tools.asset.process.palette import extractPaletteFromImage, palettes
 from tools.asset.args import args
 from tools.asset.path import getAssetRelativePath
 from tools.asset.cache import assetGetCache, assetCache
 images = []
 def processImage(asset):
  cache = assetGetCache(asset['path'])
  if cache is not None:
    return cache
  type = None
  if 'type' in asset['options']:
    type = asset['options'].get('type', 'PALETTIZED').upper()
  if type == 'PALETTIZED' or type is None:
    return assetCache(asset['path'], processPalettizedImage(asset))
  elif type == 'ALPHA':
    return assetCache(asset['path'], processAlphaImage(asset))
  else:
    print(f"Error: Unknown image type {type} for asset {asset['path']}")
    sys.exit(1)
 def processPalettizedImage(asset):
  assetPath = asset['path']
  cache = assetGetCache(assetPath)
  if cache is not None:
    return cache
  image = Image.open(assetPath)
  imagePalette = extractPaletteFromImage(image)
  # Find palette that contains every color
  palette = None
  for p in palettes:
    hasAllColors = True
    for color in imagePalette:
      for palColor in p['pixels']:
        if color[0] == palColor[0] and color[1] == palColor[1] and color[2] == palColor[2] and color[3] == palColor[3]:
          break
        elif color[3] == 0 and palColor[3] == 0:
          break
      else:
        print('Pallete {} does not contain color #{}'.format(p['paletteName'], '{:02x}{:02x}{:02x}{:02x}'.format(color[0], color[1], color[2], color[3])))
        hasAllColors = False
        break
    if hasAllColors:
      palette = p
      break
  if palette is None:
    palette = palettes[0]  # Just to avoid reference error
    print(f"No matching palette found for {assetPath}!")
    # Find which pixel is missing
    for color in imagePalette:
      if color in palette['pixels']:
        continue
      # Convert to hex (with alpha)
      hexColor = '#{:02x}{:02x}{:02x}{:02x}'.format(color[0], color[1], color[2], color[3])
      print(f"Missing color: {hexColor} in palette {palette['paletteName']}")
    sys.exit(1)
  print(f"Converting image {assetPath} to use palette")
  paletteIndexes = []
  for pixel in list(image.getdata()):
    if pixel[3] == 0:
      pixel = (0, 0, 0, 0)
    paletteIndex = palette['pixels'].index(pixel)
    paletteIndexes.append(paletteIndex)
  data = bytearray()
  data.extend(b"DPI")  # Dusk Palettized Image
  data.extend(image.width.to_bytes(4, 'little'))   # Width
  data.extend(image.height.to_bytes(4, 'little'))  # Height
  data.append(palette['paletteIndex'])   # Palette index
  for paletteIndex in paletteIndexes:
    if paletteIndex > 255 or paletteIndex < 0:
      print(f"Error: Palette index {paletteIndex} exceeds 255!")
      sys.exit(1)
    data.append(paletteIndex.to_bytes(1, 'little')[0])  # Pixel index
  relative = getAssetRelativePath(assetPath)
  fileNameWithoutExt = os.path.splitext(os.path.basename(assetPath))[0]
  outputFileRelative = os.path.join(os.path.dirname(relative), f"{fileNameWithoutExt}.dpi")
  outputFilePath = os.path.join(args.output_assets, outputFileRelative)
  os.makedirs(os.path.dirname(outputFilePath), exist_ok=True)
  with open(outputFilePath, "wb") as f:
    f.write(data)
  outImage = {
    "imagePath": outputFileRelative,
    "files": [ outputFilePath ],
    'width': image.width,
    'height': image.height,
  }
  return assetCache(assetPath, outImage)
 def processAlphaImage(asset):
  assetPath = asset['path']
  cache = assetGetCache(assetPath)
  if cache is not None:
    return cache
  print(f"Processing alpha image: {assetPath}")
  data = bytearray()
  data.extend(b"DAI")  # Dusk Alpha Image
  image = Image.open(assetPath).convert("RGBA")
  data.extend(image.width.to_bytes(4, 'little'))   # Width
  data.extend(image.height.to_bytes(4, 'little'))  # Height
  for pixel in list(image.getdata()):
    # Only write alpha channel
    data.append(pixel[3].to_bytes(1, 'little')[0])  # Pixel alpha
  relative = getAssetRelativePath(assetPath)
  fileNameWithoutExt = os.path.splitext(os.path.basename(assetPath))[0]
  outputFileRelative = os.path.join(os.path.dirname(relative), f"{fileNameWithoutExt}.dai")
  outputFilePath = os.path.join(args.output_assets, outputFileRelative)
  os.makedirs(os.path.dirname(outputFilePath), exist_ok=True)
  with open(outputFilePath, "wb") as f:
    f.write(data)
  outImage = {
    "imagePath": outputFileRelative,
    "files": [ outputFilePath ],
    'width': image.width,
    'height': image.height,
  }
  return assetCache(assetPath, outImage)
@@ -1,228 +0,0 @@
 import sys
 import os
 from tools.asset.args import args
 from tools.asset.cache import assetCache, assetGetCache
 from tools.asset.path import getAssetRelativePath
 from tools.dusk.defs import defs
 import polib
 import re
 LANGUAGE_CHUNK_CHAR_COUNT = int(defs.get('ASSET_LANG_CHUNK_CHAR_COUNT'))
 LANGUAGE_DATA = {}
 LANGUAGE_KEYS = []
 def processLanguageList():
  # Language keys header data
  headerKeys = "// Auto-generated language keys header file.\n"
  headerKeys += "#pragma once\n"
  headerKeys += "#include \"dusk.h\"\n\n"
  # This is the desired chunk groups list.. if a language key STARTS with any
  # of the keys in this list we would "like to" put it in that chunk group.
  # If there is no match, or the list is full then we will add it to the next
  # available chunk group (that isn't a 'desired' one). If the chunk becomes
  # full, then we attempt to make another chunk with the same prefix so that
  # a second batching can occur.
  desiredChunkGroups = {
    'ui': 0
  }
  # Now, for each language key, create the header reference and index.
  keyIndex = 0
  languageKeyIndexes = {}
  languageKeyChunk = {}
  languageKeyChunkIndexes = {}
  languageKeyChunkOffsets = {}
  for key in LANGUAGE_KEYS:
    headerKeys += f"#define {getLanguageVariableName(key)} {keyIndex}\n"
    languageKeyIndexes[key] = keyIndex
    keyIndex += 1
    # Find desired chunk group
    assignedChunk = None
    for desiredKey in desiredChunkGroups:
      if key.lower().startswith(desiredKey):
        assignedChunk = desiredChunkGroups[desiredKey]
        break
    # If no desired chunk group matched, assign to -1
    if assignedChunk is None:
      assignedChunk = -1
    languageKeyChunk[key] = assignedChunk
    # Setup header.
    for lang in LANGUAGE_DATA:
      if key not in LANGUAGE_DATA[lang]:
        print(f"Warning: Missing translation for key '{key}' in language '{lang}'")
        sys.exit(1)
  # Seal the header.
  headerKeys += f"\n#define LANG_KEY_COUNT {len(LANGUAGE_KEYS)}\n"
  # Now we can generate the language string chunks.
  nextChunkIndex = max(desiredChunkGroups.values()) + 1
  files = []
  for lang in LANGUAGE_DATA:
    langData = LANGUAGE_DATA[lang]
    # Key = chunkIndex, value = chunkInfo
    languageChunks = {}
    for key in LANGUAGE_KEYS:
      keyIndex = languageKeyIndexes[key]
      chunkIndex = languageKeyChunk[key]
      wasSetChunk = chunkIndex != -1
      # This will keep looping until we find a chunk
      while True:
        # Determine the next chunkIndex IF chunkIndex is -1
        if chunkIndex == -1:
          chunkIndex = nextChunkIndex
        # Is the chunk full?
        curLen = languageChunks.get(chunkIndex, {'len': 0})['len']
        newLen = curLen + len(langData[key])
        if newLen > LANGUAGE_CHUNK_CHAR_COUNT:
          # Chunk is full, need to create a new chunk.
          chunkIndex = -1
          if wasSetChunk:
            wasSetChunk = False
          else:
            nextChunkIndex += 1
          continue
        # Chunk is not full, we can use it.
        if chunkIndex not in languageChunks:
          languageChunks[chunkIndex] = {
            'len': 0,
            'keys': []
          }
        languageChunks[chunkIndex]['len'] = newLen
        languageChunks[chunkIndex]['keys'].append(key)
        languageKeyChunkIndexes[key] = chunkIndex
        languageKeyChunkOffsets[key] = curLen
        break
    # We have now chunked all the keys for this language!
    langBuffer = b""
    # Write header info 
    langBuffer += b'DLF'  # Dusk Language File
    for key in LANGUAGE_KEYS:
      # Write the chunk that this key belongs to as uint32_t
      chunkIndex = languageKeyChunkIndexes[key]
      langBuffer += chunkIndex.to_bytes(4, byteorder='little')
      # Write the offset for this key as uint32_t
      offset = languageKeyChunkOffsets[key]
      langBuffer += offset.to_bytes(4, byteorder='little')
      # Write the length of the string as uint32_t
      strData = langData[key].encode('utf-8')
      langBuffer += len(strData).to_bytes(4, byteorder='little')
    # Now write out each chunk's string data, packed tight and no null term.
    for chunkIndex in sorted(languageChunks.keys()):
      chunkInfo = languageChunks[chunkIndex]
      for key in chunkInfo['keys']:
        strData = langData[key].encode('utf-8')
        langBuffer += strData
      # Now pad the chunk to full size
      curLen = chunkInfo['len']
      if curLen < LANGUAGE_CHUNK_CHAR_COUNT:
        padSize = LANGUAGE_CHUNK_CHAR_COUNT - curLen
        langBuffer += b'\0' * padSize
    # Write out the language data file
    outputFile = os.path.join(args.output_assets, "language", f"{lang}.dlf")
    files.append(outputFile)
    os.makedirs(os.path.dirname(outputFile), exist_ok=True)
    with open(outputFile, "wb") as f:
      f.write(langBuffer)
  # Write out the language keys header file
  outputFile = os.path.join(args.headers_dir, "locale", "language", "keys.h")
  os.makedirs(os.path.dirname(outputFile), exist_ok=True)
  with open(outputFile, "w") as f:
    f.write(headerKeys)
  # Generate language list.
  langValues = {}
  headerLocale = "#pragma once\n#include \"locale/localeinfo.h\"\n\n"
  headerLocale += "typedef enum {\n"
  count = 0
  headerLocale += f"  DUSK_LOCALE_NULL = {count},\n"
  count += 1
  for lang in LANGUAGE_DATA:
    langKey = lang.replace('-', '_').replace(' ', '_').upper()
    langValues[lang] = count
    headerLocale += f"  DUSK_LOCALE_{langKey} = {count},\n"
    count += 1
  headerLocale += f"  DUSK_LOCALE_COUNT = {count}\n"
  headerLocale += "} dusklocale_t;\n\n"
  headerLocale += f"static const localeinfo_t LOCALE_INFOS[DUSK_LOCALE_COUNT] = {{\n"
  for lang in LANGUAGE_DATA:
    langKey = lang.replace('-', '_').replace(' ', '_').upper()
    headerLocale += f"  [DUSK_LOCALE_{langKey}] = {{\n"
    headerLocale += f"    .file = \"{lang}\"\n"
    headerLocale += f"  }},\n"
  headerLocale += "};\n"
  headerLocale += f"static const char_t *LOCALE_SCRIPT = \n"
  for lang in LANGUAGE_DATA:
    langKey = lang.replace('-', '_').replace(' ', '_').upper()
    langValue = langValues[lang]
    headerLocale += f"  \"DUSK_LOCALE_{langKey} = {langValue}\\n\"\n"
  headerLocale +=  ";\n"
  # Write out the locale enum header file
  outputFile = os.path.join(args.headers_dir, "locale", "locale.h")
  os.makedirs(os.path.dirname(outputFile), exist_ok=True)
  with open(outputFile, "w") as f:
    f.write(headerLocale)
  return {
    'files': files
  }
 def getLanguageVariableName(languageKey):
  # Take the language key, prepend LANG_, uppercase, replace any non symbols
  # with _
  key = languageKey.strip().upper()
  key = re.sub(r'[^A-Z0-9]', '_', key)
  return f"LANG_{key}"
 def processLanguage(asset):
  cache = assetGetCache(asset['path'])
  if cache is not None:
    return cache
  # Load PO File
  po = polib.pofile(asset['path'])
  langName = po.metadata.get('Language')
  if langName not in LANGUAGE_DATA:
    LANGUAGE_DATA[langName] = {}
  for entry in po:
    key = entry.msgid
    val = entry.msgstr
    if key not in LANGUAGE_KEYS:
      LANGUAGE_KEYS.append(key)
    if key not in LANGUAGE_DATA[langName]:
      LANGUAGE_DATA[langName][key] = val
    else:
      print(f"Error: Duplicate translation key '{key}' in language '{langName}'")
      sys.exit(1)
  outLanguageData = {
    'data': po,
    'path': asset['path'],
    'files': []
  }
  return assetCache(asset['path'], outLanguageData)
@@ -1,154 +0,0 @@
 import struct
 import sys
 import os
 import json
 from tools.asset.args import args
 from tools.asset.cache import assetCache, assetGetCache
 from tools.asset.path import getAssetRelativePath
 from tools.dusk.defs import TILE_WIDTH, TILE_HEIGHT, TILE_DEPTH, CHUNK_WIDTH, CHUNK_HEIGHT, CHUNK_DEPTH, CHUNK_TILE_COUNT
 from tools.dusk.map import Map
 from tools.dusk.chunk import Chunk
 def convertModelData(modelData):
  # TLDR; Model data stores things efficiently with indices, but we buffer it 
  # out to 6 vertex quads for simplicity.
  outVertices = []
  outUVs = []
  outColors = []
  for indice in modelData['indices']:
    vertex = modelData['vertices'][indice]
    uv = modelData['uvs'][indice]
    color = modelData['colors'][indice]
    outVertices.append(vertex)
    outUVs.append(uv)
    outColors.append(color)
  return {
    'vertices': outVertices,
    'uvs': outUVs,
    'colors': outColors
  }
 def processChunk(chunk):
  cache = assetGetCache(chunk.getFilename())
  if cache:
    return cache
  baseModel = {
    'vertices': [],
    'colors': [],
    'uvs': []
  }
  models = [ baseModel ]
  for tileIndex, tile in chunk.tiles.items():
    tileBase = tile.getBaseTileModel()
    convertedBase = convertModelData(tileBase)
    baseModel['vertices'].extend(convertedBase['vertices'])
    baseModel['colors'].extend(convertedBase['colors'])
    baseModel['uvs'].extend(convertedBase['uvs'])
  # Generate binary buffer for efficient output
  buffer = bytearray()
  buffer.extend(b'DMC')# Header
  buffer.extend(len(chunk.tiles).to_bytes(4, 'little'))  # Number of tiles
  buffer.extend(len(models).to_bytes(1, 'little'))  # Number of models
  buffer.extend(len(chunk.entities).to_bytes(1, 'little'))  # Number of entities
  # Buffer tile data as array of uint8_t
  for tileIndex, tile in chunk.tiles.items():
    buffer.extend(tile.shape.to_bytes(1, 'little'))
  # # For each model
  for model in models:
    vertexCount = len(model['vertices'])
    buffer.extend(vertexCount.to_bytes(4, 'little'))
    for i in range(vertexCount):
      vertex = model['vertices'][i]
      uv = model['uvs'][i]
      color = model['colors'][i]
      buffer.extend(color[0].to_bytes(1, 'little'))
      buffer.extend(color[1].to_bytes(1, 'little'))
      buffer.extend(color[2].to_bytes(1, 'little'))
      buffer.extend(color[3].to_bytes(1, 'little'))
      buffer.extend(bytearray(struct.pack('<f', uv[0])))
      buffer.extend(bytearray(struct.pack('<f', uv[1])))
      buffer.extend(bytearray(struct.pack('<f', vertex[0])))
      buffer.extend(bytearray(struct.pack('<f', vertex[1])))
      buffer.extend(bytearray(struct.pack('<f', vertex[2])))
  # For each entity
  for entity in chunk.entities.values():
    buffer.extend(entity.type.to_bytes(1, 'little'))
    buffer.extend(entity.localX.to_bytes(1, 'little'))
    buffer.extend(entity.localY.to_bytes(1, 'little'))
    buffer.extend(entity.localZ.to_bytes(1, 'little'))
    pass
  # Write out map file
  relative = getAssetRelativePath(chunk.getFilename())
  fileNameWithoutExt = os.path.splitext(os.path.basename(relative))[0]
  outputFileRelative = os.path.join(os.path.dirname(relative), f"{fileNameWithoutExt}.dmc")
  outputFilePath = os.path.join(args.output_assets, outputFileRelative)
  os.makedirs(os.path.dirname(outputFilePath), exist_ok=True)
  with open(outputFilePath, "wb") as f:
    f.write(buffer)
  outChunk = {
    'files': [ outputFilePath ],
    'chunk': chunk
  }
  return assetCache(chunk.getFilename(), outChunk)
 def processMap(asset):
  cache = assetGetCache(asset['path'])
  if cache is not None:
    return cache
  map = Map(None)
  map.load(asset['path'])
  chunksDir = map.getChunkDirectory()
  files = os.listdir(chunksDir)
  if len(files) == 0:
    print(f"Error: No chunk files found in {chunksDir}.")
    sys.exit(1)
  chunkFiles = []
  for fileName in files:
    if not fileName.endswith('.json'):
      continue
    fNameNoExt = os.path.splitext(fileName)[0]
    fnPieces = fNameNoExt.split('_')
    if len(fnPieces) != 3:
      print(f"Error: Chunk filename {fileName} does not contain valid chunk coordinates.")
      sys.exit(1)
    chunk = Chunk(map, int(fnPieces[0]), int(fnPieces[1]), int(fnPieces[2]))
    chunk.load()
    result = processChunk(chunk)
    chunkFiles.extend(result['files'])
  # Map file
  outBuffer = bytearray()
  outBuffer.extend(b'DMF')
  outBuffer.extend(len(chunkFiles).to_bytes(4, 'little'))
  # DMF (Dusk Map file)
  fileRelative = getAssetRelativePath(asset['path'])
  fileNameWithoutExt = os.path.splitext(os.path.basename(fileRelative))[0]
  outputMapRelative = os.path.join(os.path.dirname(fileRelative), f"{fileNameWithoutExt}.dmf")
  outputMapPath = os.path.join(args.output_assets, outputMapRelative)
  os.makedirs(os.path.dirname(outputMapPath), exist_ok=True)
  with open(outputMapPath, "wb") as f:
    f.write(outBuffer)
  outMap = {
    'files': chunkFiles
  }
  outMap['files'].append(outputMapPath)
  return assetCache(asset['path'], outMap)
@@ -1,96 +0,0 @@
 import json
 import os
 from PIL import Image
 import datetime
 from tools.asset.args import args
 from tools.asset.cache import assetCache, assetGetCache
 palettes = []
 def extractPaletteFromImage(image):
  # goes through and finds all unique colors in the image
  if image.mode != 'RGBA':
    image = image.convert('RGBA')
  pixels = list(image.getdata())
  uniqueColors = []
  for color in pixels:
    # We treat all alpha 0 as rgba(0,0,0,0) for palette purposes
    if color[3] == 0:
      color = (0, 0, 0, 0)
    if color not in uniqueColors:
      uniqueColors.append(color)
  return uniqueColors
 def processPalette(asset):
  print(f"Processing palette: {asset['path']}")
  cache = assetGetCache(asset['path'])
  if cache is not None:
    return cache
  paletteIndex = len(palettes)
  image = Image.open(asset['path'])
  pixels = extractPaletteFromImage(image)
  fileNameWithoutExt = os.path.splitext(os.path.basename(asset['path']))[0]
  fileNameWithoutPalette = os.path.splitext(fileNameWithoutExt)[0]
  # PSP requires that the palette size be a power of two, so we will pad the
  # palette with transparent colors if needed.
  def mathNextPowTwo(x):
    return 1 << (x - 1).bit_length()
  nextPowTwo = mathNextPowTwo(len(pixels))
  while len(pixels) < nextPowTwo:
    pixels.append((0, 0, 0, 0))
  # Header
  now = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
  data = f"// Palette Generated for {asset['path']} at {now}\n"
  data += f"#include \"display/palette/palette.h\"\n\n"
  data += f"#define PALETTE_{paletteIndex}_COLOR_COUNT {len(pixels)}\n\n"
  data += f"#pragma pack(push, 1)\n"
  data += f"static const color_t PALETTE_{paletteIndex}_COLORS[PALETTE_{paletteIndex}_COLOR_COUNT] = {{\n"
  for pixel in pixels:
    data += f"  {{ 0x{pixel[0]:02X}, 0x{pixel[1]:02X}, 0x{pixel[2]:02X}, 0x{pixel[3]:02X} }},\n"
  data += f"}};\n"
  data += f"#pragma pack(pop)\n\n"
  data += f"static const palette_t PALETTE_{paletteIndex} = {{\n"
  data += f"  .colorCount = PALETTE_{paletteIndex}_COLOR_COUNT,\n"
  data += f"  .colors = PALETTE_{paletteIndex}_COLORS,\n"
  data += f"}};\n"
  # Write Header
  outputFile = os.path.join(args.headers_dir, "display", "palette", f"palette_{paletteIndex}.h")
  os.makedirs(os.path.dirname(outputFile), exist_ok=True)
  with open(outputFile, "w") as f:
    f.write(data)
  palette = {
    "paletteIndex": paletteIndex,
    "paletteName": fileNameWithoutPalette,
    "pixels": pixels,
    "headerFile": os.path.relpath(outputFile, args.headers_dir),
    "asset": asset,
    "files": [ ],# No zippable files.
  }
  palettes.append(palette)
  return assetCache(asset['path'], palette)
 def processPaletteList():
  data = f"// Auto-generated palette list\n"
  print(f"Generating palette list with {len(palettes)} palettes.")
  for palette in palettes:
    data += f"#include \"{palette['headerFile']}\"\n"
  data += f"\n"
  data += f"#define PALETTE_LIST_COUNT {len(palettes)}\n\n"
  data += f"static const palette_t* PALETTE_LIST[PALETTE_LIST_COUNT] = {{\n"
  for palette in palettes:
    data += f"  &PALETTE_{palette['paletteIndex']},\n"
  data += f"}};\n"
  # Write the palette list to a header file
  outputFile = os.path.join(args.headers_dir, "display", "palette", "palettelist.h")
  os.makedirs(os.path.dirname(outputFile), exist_ok=True)
  with open(outputFile, "w") as f:
    f.write(data)
@@ -1,43 +0,0 @@
 import sys
 import os
 from tools.asset.args import args
 from tools.asset.cache import assetCache, assetGetCache
 from tools.asset.path import getAssetRelativePath
 from tools.dusk.defs import fileDefs
 def processScript(asset):
  cache = assetGetCache(asset['path'])
  if cache is not None:
    return cache
  # Load the lua file as a string
  with open(asset['path'], 'r', encoding='utf-8') as f:
    luaCode = f.read()
  # TODO: I will precompile or minify the Lua code here in the future
  # Replace all definitions in the code
  for key, val in fileDefs.items():
    luaCode = luaCode.replace(key, str(val))
  # Create output Dusk Script File (DSF) data
  data = ""
  data += "DSF"
  data += luaCode
  # Write to relative output file path.
  relative = getAssetRelativePath(asset['path'])
  fileNameWithoutExt = os.path.splitext(os.path.basename(asset['path']))[0]
  outputFileRelative = os.path.join(os.path.dirname(relative), f"{fileNameWithoutExt}.dsf")
  outputFilePath = os.path.join(args.output_assets, outputFileRelative)
  os.makedirs(os.path.dirname(outputFilePath), exist_ok=True)
  with open(outputFilePath, "wb") as f:
    f.write(data.encode('utf-8'))
  outScript = {
    'data': data,
    'path': asset['path'],
    'files': [ outputFilePath ],
    'scriptPath': outputFileRelative,
  }
  return assetCache(asset['path'], outScript)
@@ -1,178 +0,0 @@
 import json
 import sys
 import os
 import datetime
 from xml.etree import ElementTree
 from tools.asset.process.image import processImage
 from tools.asset.path import getAssetRelativePath
 from tools.asset.args import args
 from tools.asset.cache import assetGetCache, assetCache
 tilesets = []
 def loadTilesetFromTSX(asset):
  # Load the TSX file
  tree = ElementTree.parse(asset['path'])
  root = tree.getroot()
  # Expect tileheight, tilewidth, columns and tilecount attributes
  if 'tilewidth' not in root.attrib or 'tileheight' not in root.attrib or 'columns' not in root.attrib or 'tilecount' not in root.attrib:
    print(f"Error: TSX file {asset['path']} is missing required attributes (tilewidth, tileheight, columns, tilecount)")
    sys.exit(1)
  tileWidth = int(root.attrib['tilewidth'])
  tileHeight = int(root.attrib['tileheight'])
  columns = int(root.attrib['columns'])
  tileCount = int(root.attrib['tilecount'])
  rows = (tileCount + columns - 1) // columns  # Calculate rows based on tileCount and columns
  # Find the image element
  imageElement = root.find('image')
  if imageElement is None or 'source' not in imageElement.attrib:
    print(f"Error: TSX file {asset['path']} is missing an image element with a source attribute")
    sys.exit(1)
  imagePath = imageElement.attrib['source']
  # Image is relative to the TSX file
  imageAssetPath = os.path.join(os.path.dirname(asset['path']), imagePath)
  image = processImage({
    'path': imageAssetPath,
    'options': asset['options'],
  })
  return {
    "image": image,
    "tileWidth": tileWidth,
    "tileHeight": tileHeight,
    "columns": columns,
    "rows": rows,
    "originalWidth": tileWidth * columns,
    "originalHeight": tileHeight * rows,
  }
 def loadTilesetFromArgs(asset):
  # We need to determine how big each tile is. This can either be provided as
  # an arg of tileWidth/tileHeight or as a count of rows/columns.
  # Additionally, if the image has been factored, then the user can provide both
  # tile sizes AND cols/rows to indicate the original size of the image.
  image = processImage(asset)
  tileWidth, tileHeight = None, None
  columns, rows = None, None
  originalWidth, originalHeight = image['width'], image['height']
  if 'tileWidth' in asset['options'] and 'columns' in asset['options']:
    tileWidth = int(asset['options']['tileWidth'])
    columns = int(asset['options']['columns'])
    originalWidth = tileWidth * columns
  elif 'tileWidth' in asset['options']:
    tileWidth = int(asset['options']['tileWidth'])
    columns = image['width'] // tileWidth
  elif 'columns' in asset['options']:
    columns = int(asset['options']['columns'])
    tileWidth = image['width'] // columns
  else:
    print(f"Error: Tileset {asset['path']} must specify either tileWidth or columns")
    sys.exit(1)
  if 'tileHeight' in asset['options'] and 'rows' in asset['options']:
    tileHeight = int(asset['options']['tileHeight'])
    rows = int(asset['options']['rows'])
    originalHeight = tileHeight * rows
  elif 'tileHeight' in asset['options']:
    tileHeight = int(asset['options']['tileHeight'])
    rows = image['height'] // tileHeight
  elif 'rows' in asset['options']:
    rows = int(asset['options']['rows'])
    tileHeight = image['height'] // rows
  else:
    print(f"Error: Tileset {asset['path']} must specify either tileHeight or rows")
    sys.exit(1)
  return {
    "image": image,
    "tileWidth": tileWidth,
    "tileHeight": tileHeight,
    "columns": columns,
    "rows": rows,
    "originalWidth": originalWidth,
    "originalHeight": originalHeight,
  }
 def processTileset(asset):
  cache = assetGetCache(asset['path'])
  if cache is not None:
    return cache
  print(f"Processing tileset: {asset['path']}")
  tilesetData = None
  if asset['path'].endswith('.tsx'):
    tilesetData = loadTilesetFromTSX(asset)
  else:
    tilesetData = loadTilesetFromArgs(asset)
  fileNameWithoutExtension = os.path.splitext(os.path.basename(asset['path']))[0]
  now = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
  tilesetName = fileNameWithoutExtension
  tilesetNameUpper = tilesetName.upper()
  widthScale = tilesetData['originalWidth'] / tilesetData['image']['width']
  heightScale = tilesetData['originalHeight'] / tilesetData['image']['height']
  # Create header
  data = f"// Tileset Generated for {asset['path']} at {now}\n"
  data += f"#pragma once\n"
  data += f"#include \"display/tileset/tileset.h\"\n\n"
  data += f"static const tileset_t TILESET_{tilesetNameUpper} = {{\n"
  data += f"  .name = {json.dumps(tilesetName)},\n"
  data += f"  .tileWidth = {tilesetData['tileWidth']},\n"
  data += f"  .tileHeight = {tilesetData['tileHeight']},\n"
  data += f"  .tileCount = {tilesetData['columns'] * tilesetData['rows']},\n"
  data += f"  .columns = {tilesetData['columns']},\n"
  data += f"  .rows = {tilesetData['rows']},\n"
  data += f"  .uv = {{ {widthScale / tilesetData['columns']}f, {heightScale / tilesetData['rows']}f }},\n"
  data += f"  .image = {json.dumps(tilesetData['image']['imagePath'])},\n"
  data += f"}};\n"
  # Write Header
  outputFile = os.path.join(args.headers_dir, "display", "tileset", f"tileset_{tilesetName}.h")
  os.makedirs(os.path.dirname(outputFile), exist_ok=True)
  with open(outputFile, 'w') as f:
    f.write(data)
  print(f"Write header for tileset: {outputFile}")
  tileset = {
    "files": [],
    "image": tilesetData['image'],
    "headerFile": os.path.relpath(outputFile, args.headers_dir),
    "tilesetName": tilesetName,
    "tilesetNameUpper": tilesetNameUpper,
    "tilesetIndex": len(tilesets),
    "tilesetData": tilesetData,
    "files": tilesetData['image']['files'],
  }
  tilesets.append(tileset)
  return assetCache(asset['path'], tileset)
 def processTilesetList():
  data = f"// Tileset List Generated at {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n"
  data += f"#pragma once\n"
  for tileset in tilesets:
    data += f"#include \"{tileset['headerFile']}\"\n"
  data += f"\n"
  data += f"#define TILESET_LIST_COUNT {len(tilesets)}\n\n"
  data += f"static const tileset_t* TILESET_LIST[TILESET_LIST_COUNT] = {{\n"
  for tileset in tilesets:
    data += f"  &TILESET_{tileset['tilesetNameUpper']},\n"
  data += f"}};\n"
  # Write header.
  outputFile = os.path.join(args.headers_dir, "display", "tileset", f"tilesetlist.h")
  os.makedirs(os.path.dirname(outputFile), exist_ok=True)
  with open(outputFile, 'w') as f:
    f.write(data)
@@ -1,47 +0,0 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "assetpalette.h"
 #include "asset/assettype.h"
 #include "assert/assert.h"
 errorret_t assetPaletteLoad(assetentire_t entire) {
  assertNotNull(entire.data, "Data pointer cannot be NULL.");
  assertNotNull(entire.output, "Output pointer cannot be NULL.");
  assetpalette_t *assetData = (assetpalette_t *)entire.data;
  palette_t *palette = (palette_t *)entire.output;
  // Read header and version (first 4 bytes)
  if(
    assetData->header[0] != 'D' || 
    assetData->header[1] != 'P' ||
    assetData->header[2] != 'F'
  ) {
    errorThrow("Invalid palette header");
  }
  // Version (can only be 1 atm)
  if(assetData->version != 0x01) {
    errorThrow("Unsupported palette version");
  }
  // Check color count.
  if(
    assetData->colorCount == 0 || 
    assetData->colorCount > PALETTE_COLOR_COUNT_MAX
  ) {
    errorThrow("Invalid palette color count");
  }
  paletteInit(
    palette,
    assetData->colorCount,
    assetData->colors
  );
  errorOk();
 }
@@ -1,30 +0,0 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "display/texture/palette.h"
 typedef struct assetentire_s assetentire_t;
 #pragma pack(push, 1)
 typedef struct {
  char_t header[3];
  uint8_t version;
  uint8_t colorCount;
  color_t colors[PALETTE_COLOR_COUNT_MAX];
 } assetpalette_t;
 #pragma pack(pop)
 /**
 * Loads a palette from the given data pointer into the output palette.
 *
 * @param entire Data received from the asset loader system.
 * @return An error code.
 */
 errorret_t assetPaletteLoad(assetentire_t entire);
@@ -1,107 +0,0 @@
 /**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "camera.h"
 #include "display/display.h"
 #include "assert/assert.h"
 #include "display/framebuffer/framebuffer.h"
 #include "display/screen/screen.h"
 void cameraInit(camera_t *camera) {
  cameraInitPerspective(camera);
 }
 void cameraInitPerspective(camera_t *camera) {
  assertNotNull(camera, "Not a camera component");
  camera->projType = CAMERA_PROJECTION_TYPE_PERSPECTIVE;
  camera->perspective.fov = glm_rad(45.0f);
  camera->nearClip = 0.1f;
  camera->farClip = 10000.0f;
  camera->viewType = CAMERA_VIEW_TYPE_LOOKAT;
  glm_vec3_copy((vec3){ 5.0f, 5.0f, 5.0f }, camera->lookat.position);
  glm_vec3_copy((vec3){ 0.0f, 1.0f, 0.0f }, camera->lookat.up);
  glm_vec3_copy((vec3){ 0.0f, 0.0f, 0.0f }, camera->lookat.target);
 }
 void cameraInitOrthographic(camera_t *camera) {
  assertNotNull(camera, "Not a camera component");
  camera->projType = CAMERA_PROJECTION_TYPE_ORTHOGRAPHIC;
  camera->orthographic.left = 0.0f;
  camera->orthographic.right = SCREEN.width;
  camera->orthographic.top = SCREEN.height;
  camera->orthographic.bottom = 0.0f;
  camera->nearClip = 0.1f;
  camera->farClip = 1.0f;
  camera->viewType = CAMERA_VIEW_TYPE_2D;
  glm_vec2_copy((vec2){ 0.0f, 0.0f }, camera->_2d.position);
  camera->_2d.zoom = 1.0f;
 }
 void cameraGetProjectionMatrix(camera_t *camera, mat4 dest) {
  assertNotNull(camera, "Not a camera component");
  assertNotNull(dest, "Destination matrix must not be null");
  if(
    camera->projType == CAMERA_PROJECTION_TYPE_PERSPECTIVE ||
    camera->projType == CAMERA_PROJECTION_TYPE_PERSPECTIVE_FLIPPED
  ) {
    glm_mat4_identity(dest);
    glm_perspective(
      camera->perspective.fov,
      SCREEN.aspect,
      camera->nearClip,
      camera->farClip,
      dest
    );
    if(camera->projType == CAMERA_PROJECTION_TYPE_PERSPECTIVE_FLIPPED) {
      dest[1][1] *= -1.0f;
    }
  } else if(camera->projType == CAMERA_PROJECTION_TYPE_ORTHOGRAPHIC) {
    glm_mat4_identity(dest);
    glm_ortho(
      camera->orthographic.left,
      camera->orthographic.right,
      camera->orthographic.top,
      camera->orthographic.bottom,
      camera->nearClip,
      camera->farClip,
      dest
    );
  }
 }
 void cameraGetViewMatrix(camera_t *camera, mat4 dest) {
  assertNotNull(camera, "Not a camera component");
  assertNotNull(dest, "Destination matrix must not be null");
  if(camera->viewType == CAMERA_VIEW_TYPE_MATRIX) {
    glm_mat4_ucopy(camera->view, dest);
  } else if(camera->viewType == CAMERA_VIEW_TYPE_LOOKAT) {
    glm_mat4_identity(dest);
    glm_lookat(
      camera->lookat.position,
      camera->lookat.target,
      camera->lookat.up,
      dest
    );
  } else if(camera->viewType == CAMERA_VIEW_TYPE_2D) {
    glm_mat4_identity(dest);
    glm_lookat(
      (vec3){ camera->_2d.position[0], camera->_2d.position[1], 0.5f },
      (vec3){ camera->_2d.position[0], camera->_2d.position[1], 0.0f },
      (vec3){ 0.0f, 1.0f, 0.0f },
      dest
    );
  } else if(camera->viewType == CAMERA_VIEW_TYPE_LOOKAT_PIXEL_PERFECT) {
    assertUnreachable("LOOKAT_PIXEL_PERFECT view type is not implemented yet");
  }
 }
@@ -1,97 +0,0 @@
 /**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "dusk.h"
 #include "display/color.h"
 #include "display/camera/cameraplatform.h"
 #ifndef cameraPushMatrixPlatform
  #error "cameraPushMatrixPlatform must be defined"
 #endif
 typedef enum {
  CAMERA_VIEW_TYPE_MATRIX,
  CAMERA_VIEW_TYPE_LOOKAT,
  CAMERA_VIEW_TYPE_2D,
  CAMERA_VIEW_TYPE_LOOKAT_PIXEL_PERFECT
 } cameraviewtype_t;
 typedef struct camera_s {
  union {
    mat4 view;
    struct {
      vec3 position;
      vec3 target;
      vec3 up;
    } lookat;
    struct {
      vec3 offset;
      vec3 target;
      vec3 up;
      float_t pixelsPerUnit;
    } lookatPixelPerfect;
    struct {
      vec2 position;
      float_t zoom;
    } _2d;
  };
  union {
    struct {
      float_t fov;
    } perspective;
    struct {
      float_t left;
      float_t right;
      float_t top;
      float_t bottom;
    } orthographic;
  };
  float_t nearClip;
  float_t farClip;
  cameraprojectiontype_t projType;
  cameraviewtype_t viewType;
 } camera_t;
 /**
 * Initializes a camera to default values. This calls cameraInitPerspective.
 */
 void cameraInit(camera_t *camera);
 /**
 * Initializes a camera for perspective projection.
 */
 void cameraInitPerspective(camera_t *camera);
 /**
 * Initializes a camera for orthographic projection.
 */
 void cameraInitOrthographic(camera_t *camera);
 /**
 * Gets the projection matrix for a camera.
 * 
 * @param camera Camera to get the projection matrix for
 * @param dest Matrix to store the projection matrix in
 */
 void cameraGetProjectionMatrix(camera_t *camera, mat4 dest);
 /**
 * Gets the view matrix for a camera.
 * 
 * @param camera Camera to get the view matrix for
 * @param dest Matrix to store the view matrix in
 */
 void cameraGetViewMatrix(camera_t *camera, mat4 dest);
@@ -1,158 +0,0 @@
 import json
 import os
 from tools.dusk.event import Event
 from tools.dusk.defs import CHUNK_WIDTH, CHUNK_HEIGHT, CHUNK_DEPTH, CHUNK_VERTEX_COUNT_MAX, TILE_SHAPE_NULL
 from tools.dusk.tile import Tile
 from tools.dusk.entity import Entity
 from tools.dusk.region import Region
 from tools.editor.map.vertexbuffer import VertexBuffer
 from OpenGL.GL import *
 class Chunk:
  def __init__(self, map, x, y, z):
    self.map = map
    self.x = x
    self.y = y
    self.z = z
    self.current = {}
    self.original = {}
    self.entities = {}
    self.regions = {}
    self.onChunkData = Event()
    self.dirty = False
    self.tiles = {}
    self.vertexBuffer = VertexBuffer()
    # Test Region
    region = self.regions[0] = Region(self)
    region.minX = 0
    region.minY = 0
    region.minZ = 0
    region.maxX = 32
    region.maxY = 32
    region.maxZ = 32
    region.updateVertexs()
    # Gen tiles.
    tileIndex = 0
    for tz in range(CHUNK_DEPTH):
      for ty in range(CHUNK_HEIGHT):
        for tx in range(CHUNK_WIDTH):
          self.tiles[tileIndex] = Tile(self, tx, ty, tz, tileIndex)
          tileIndex += 1
    # Update vertices
    self.tileUpdateVertices()
  def reload(self, newX, newY, newZ):
    self.x = newX
    self.y = newY
    self.z = newZ
    self.entities = {}
    for tile in self.tiles.values():
      tile.chunkReload(newX, newY, newZ)
    self.load()
  def tileUpdateVertices(self):
    self.vertexBuffer.clear()
    for tile in self.tiles.values():
      tile.buffer(self.vertexBuffer)
    self.vertexBuffer.buildData()
  def load(self):
    fname = self.getFilename()
    if not fname or not os.path.exists(fname):
      self.new()
      return
    try:
      with open(fname, 'r') as f:
        data = json.load(f)
      if not 'shapes' in data:
        data['shapes'] = []
      # For each tile.
      for tile in self.tiles.values():
        tile.load(data)
      # For each entity.
      self.entities = {}
      if 'entities' in data:
        for id, entData in enumerate(data['entities']):
          ent = Entity(self)
          ent.load(entData)
          self.entities[id] = ent
      self.tileUpdateVertices()
      self.dirty = False
      self.onChunkData.invoke(self)
      self.map.onEntityData.invoke()
    except Exception as e:
      raise RuntimeError(f"Failed to load chunk file: {e}")
  def save(self):
    if not self.isDirty():
      return
    dataOut = {
      'shapes': [],
      'entities': []
    }
    for tile in self.tiles.values():
      dataOut['shapes'].append(tile.shape)
    for ent in self.entities.values():
      entData = {}
      ent.save(entData)
      dataOut['entities'].append(entData)
    fname = self.getFilename()
    if not fname:
      raise ValueError("No filename specified for saving chunk.")
    try:
      with open(fname, 'w') as f:
        json.dump(dataOut, f)
      self.dirty = False
      self.onChunkData.invoke(self)
    except Exception as e:
      raise RuntimeError(f"Failed to save chunk file: {e}")
  def new(self):
    for tile in self.tiles.values():
      tile.shape = TILE_SHAPE_NULL
    self.tileUpdateVertices()
    self.dirty = False
    self.onChunkData.invoke(self)
  def isDirty(self):
    return self.dirty
  def getFilename(self):
    if not self.map or not hasattr(self.map, 'getChunkDirectory'):
      return None
    dirPath = self.map.getChunkDirectory()
    if dirPath is None:
      return None
    return f"{dirPath}/{self.x}_{self.y}_{self.z}.json"
  def draw(self):
    self.vertexBuffer.draw()
  def addEntity(self, localX=0, localY=0, localZ=0):
    ent = Entity(self, localX, localY, localZ)
    self.entities[len(self.entities)] = ent
    self.map.onEntityData.invoke()
    self.dirty = True
    return ent
  def removeEntity(self, entity):
    for key, val in list(self.entities.items()):
      if val == entity:
        del self.entities[key]
        self.map.onEntityData.invoke()
        self.dirty = True
        return True
    return False
@@ -1,49 +0,0 @@
 from dotenv import load_dotenv, dotenv_values
 import os
 import sys
 current_file_path = os.path.abspath(__file__)
 duskDefsPath = os.path.join(os.path.dirname(current_file_path), "..", "..", "src", "duskdefs.env")
 # Ensure the .env file exists
 if not os.path.isfile(duskDefsPath):
  print(f"Error: .env file not found at {duskDefsPath}")
  sys.exit(1)
 load_dotenv(dotenv_path=duskDefsPath)
 defs = {key: os.getenv(key) for key in os.environ.keys()}
 fileDefs = dotenv_values(dotenv_path=duskDefsPath)
 # Parsed out definitions
 CHUNK_WIDTH = int(defs.get('CHUNK_WIDTH'))
 CHUNK_HEIGHT = int(defs.get('CHUNK_HEIGHT'))
 CHUNK_DEPTH = int(defs.get('CHUNK_DEPTH'))
 CHUNK_TILE_COUNT = CHUNK_WIDTH * CHUNK_HEIGHT * CHUNK_DEPTH
 CHUNK_VERTEX_COUNT_MAX = int(defs.get('CHUNK_VERTEX_COUNT_MAX'))
 TILE_WIDTH = float(defs.get('TILE_WIDTH'))
 TILE_HEIGHT = float(defs.get('TILE_HEIGHT'))
 TILE_DEPTH = float(defs.get('TILE_DEPTH'))
 RPG_CAMERA_PIXELS_PER_UNIT = float(defs.get('RPG_CAMERA_PIXELS_PER_UNIT'))
 RPG_CAMERA_Z_OFFSET = float(defs.get('RPG_CAMERA_Z_OFFSET'))
 RPG_CAMERA_FOV = float(defs.get('RPG_CAMERA_FOV'))
 MAP_WIDTH = 5
 MAP_HEIGHT = 5
 MAP_DEPTH = 3
 MAP_CHUNK_COUNT = MAP_WIDTH * MAP_HEIGHT * MAP_DEPTH
 TILE_SHAPES = {}
 for key in defs.keys():
  if key.startswith('TILE_SHAPE_'):
    globals()[key] = int(defs.get(key))
    TILE_SHAPES[key] = int(defs.get(key))
 ENTITY_TYPES = {}
 for key in defs.keys():
  if key.startswith('ENTITY_TYPE_'):
    globals()[key] = int(defs.get(key))
    if key != 'ENTITY_TYPE_COUNT':
      ENTITY_TYPES[key] = int(defs.get(key))
@@ -1,90 +0,0 @@
 from tools.dusk.defs import ENTITY_TYPE_NULL, ENTITY_TYPE_NPC, CHUNK_WIDTH, CHUNK_HEIGHT, CHUNK_DEPTH, TILE_WIDTH, TILE_HEIGHT, TILE_DEPTH
 from tools.editor.map.vertexbuffer import VertexBuffer
 class Entity:
  def __init__(self, chunk, localX=0, localY=0, localZ=0):
    self.type = ENTITY_TYPE_NPC
    self.name = "Unititled"
    self.localX = localX % CHUNK_WIDTH
    self.localY = localY % CHUNK_HEIGHT
    self.localZ = localZ % CHUNK_DEPTH
    self.chunk = chunk
    self.vertexBuffer = VertexBuffer()
    pass
  def load(self, obj):
    self.type = obj.get('type', ENTITY_TYPE_NULL)
    self.localX = obj.get('x', 0)
    self.localY = obj.get('y', 0)
    self.localZ = obj.get('z', 0)
    self.name = obj.get('name', "Untitled")
    pass
  def save(self, obj):
    obj['type'] = self.type
    obj['name'] = self.name
    obj['x'] = self.localX
    obj['y'] = self.localY
    obj['z'] = self.localZ
    pass
  def setType(self, entityType):
    if self.type == entityType:
      return
    self.type = entityType
    self.chunk.dirty = True
    self.chunk.map.onEntityData.invoke()
  def setName(self, name):
    if self.name == name:
      return
    self.name = name
    self.chunk.dirty = True
    self.chunk.map.onEntityData.invoke()
  def draw(self):
    self.vertexBuffer.clear()
    startX = (self.chunk.x * CHUNK_WIDTH + self.localX) * TILE_WIDTH
    startY = (self.chunk.y * CHUNK_HEIGHT + self.localY) * TILE_HEIGHT
    startZ = (self.chunk.z * CHUNK_DEPTH + self.localZ) * TILE_DEPTH
    w = TILE_WIDTH
    h = TILE_HEIGHT
    d = TILE_DEPTH
    # Center
    startX -= w / 2
    startY -= h / 2
    startZ -= d / 2
    # Offset upwards a little
    startZ += 1
    # Buffer simple quad at current position (need 6 positions)
    self.vertexBuffer.vertices = [
      startX,     startY,     startZ,
      startX + w, startY,     startZ,
      startX + w, startY + h, startZ,
      startX,     startY,     startZ,
      startX + w, startY + h, startZ,
      startX,     startY + h, startZ,
    ]
    self.vertexBuffer.colors = [
      1.0, 0.0, 1.0, 1.0,
      1.0, 0.0, 1.0, 1.0,
      1.0, 0.0, 1.0, 1.0,
      1.0, 0.0, 1.0, 1.0,
      1.0, 0.0, 1.0, 1.0,
      1.0, 0.0, 1.0, 1.0,
    ]
    self.vertexBuffer.uvs = [
      0.0, 0.0,
      1.0, 0.0,
      1.0, 1.0,
      0.0, 0.0,
      1.0, 1.0,
      0.0, 1.0,
    ]
    self.vertexBuffer.buildData()
    self.vertexBuffer.draw()
@@ -1,18 +0,0 @@
 class Event:
  def __init__(self):
    self._subscribers = []
  def sub(self, callback):
    """Subscribe a callback to the event."""
    if callback not in self._subscribers:
      self._subscribers.append(callback)
  def unsub(self, callback):
    """Unsubscribe a callback from the event."""
    if callback in self._subscribers:
      self._subscribers.remove(callback)
  def invoke(self, *args, **kwargs):
    """Invoke all subscribers with the given arguments."""
    for callback in self._subscribers:
      callback(*args, **kwargs)
@@ -1,259 +0,0 @@
 import json
 import sys
 from tools.dusk.event import Event
 from PyQt5.QtWidgets import QFileDialog, QMessageBox
 from PyQt5.QtCore import QTimer
 import os
 from tools.dusk.chunk import Chunk
 from tools.dusk.defs import MAP_WIDTH, MAP_HEIGHT, MAP_DEPTH, CHUNK_WIDTH, CHUNK_HEIGHT, CHUNK_DEPTH
 import traceback
 MAP_DEFAULT_PATH = os.path.join(os.path.dirname(__file__), '../../assets/map/')
 EDITOR_CONFIG_PATH = os.path.join(os.path.dirname(__file__), '.editor')
 class Map:
  def __init__(self, parent):
    self.parent = parent
    self.data = {}
    self.dataOriginal = {}
    self.position = [None, None, None]  # x, y, z
    self.topLeftX = None
    self.topLeftY = None
    self.topLeftZ = None
    self.chunks = {}
    self.onMapData = Event()
    self.onPositionChange = Event()
    self.onEntityData = Event()
    self.mapFileName = None
    self.lastFile = None
    self.firstLoad = True
    index = 0
    for x in range(MAP_WIDTH):
      for y in range(MAP_HEIGHT):
        for z in range(MAP_DEPTH):
          self.chunks[index] = Chunk(self, x, y, z)
          index += 1
    # Only in editor instances:
    self.moveTo(0, 0, 0)
    if parent is not None:
      QTimer.singleShot(16, self.loadLastFile)
  def loadLastFile(self):
    if not os.path.exists(EDITOR_CONFIG_PATH):
      return
    try:
      with open(EDITOR_CONFIG_PATH, 'r') as f:
        config = json.load(f)
      lastFile = config.get('lastFile')
      lastPosition = config.get('lastPosition')
      leftPanelIndex = config.get('leftPanelIndex')
      if lastFile and os.path.exists(lastFile):
        self.load(lastFile)
      if lastPosition and isinstance(lastPosition, list) and len(lastPosition) == 3:
        self.moveTo(*lastPosition)
      if leftPanelIndex is not None:
        self.parent.leftPanel.tabs.setCurrentIndex(leftPanelIndex)
    except Exception:
      traceback.print_exc()
  def updateEditorConfig(self):
    if self.parent is None:
      return
    try:
      mapFileName = self.getMapFilename()
      config = {
        'lastFile': mapFileName if mapFileName else "",
        'lastPosition': self.position,
        'leftPanelIndex': self.parent.leftPanel.tabs.currentIndex()
      }
      config_dir = os.path.dirname(EDITOR_CONFIG_PATH)
      if not os.path.exists(config_dir):
        os.makedirs(config_dir, exist_ok=True)
      with open(EDITOR_CONFIG_PATH, 'w') as f:
        json.dump(config, f, indent=2)
    except Exception:
      traceback.print_exc()
  def newFile(self):
    self.data = {}
    self.dataOriginal = {}
    self.mapFileName = None
    self.lastFile = None
    for chunk in self.chunks.values():
      chunk.new()
    self.moveTo(0, 0, 0)
    self.onMapData.invoke(self.data)
    self.updateEditorConfig()
  def save(self, fname=None):
    if not self.getMapFilename() and fname is None:
      filePath, _ = QFileDialog.getSaveFileName(None, "Save Map File", MAP_DEFAULT_PATH, "Map Files (*.json)")
      if not filePath:
        return
      self.mapFileName = filePath
    if fname:
      self.mapFileName = fname
    try:
      with open(self.getMapFilename(), 'w') as f:
        json.dump(self.data, f, indent=2)
      self.dataOriginal = json.loads(json.dumps(self.data))  # Deep copy
      for chunk in self.chunks.values():
        chunk.save()
      self.updateEditorConfig()
    except Exception as e:
      traceback.print_exc()
      QMessageBox.critical(None, "Save Error", f"Failed to save map file:\n{e}")
  def load(self, fileName):
    try:
      with open(fileName, 'r') as f:
        self.data = json.load(f)
      self.mapFileName = fileName
      self.dataOriginal = json.loads(json.dumps(self.data))  # Deep copy
      for chunk in self.chunks.values():
        chunk.load()
      self.onMapData.invoke(self.data)
      self.updateEditorConfig()
    except Exception as e:
      traceback.print_exc()
      QMessageBox.critical(None, "Load Error", f"Failed to load map file:\n{e}")
  def isMapFileDirty(self):
    return json.dumps(self.data, sort_keys=True) != json.dumps(self.dataOriginal, sort_keys=True)
  def isDirty(self):
    return self.isMapFileDirty() or self.anyChunksDirty()
  def getMapFilename(self):
    return self.mapFileName if self.mapFileName and os.path.exists(self.mapFileName) else None
  def getMapDirectory(self):
    if self.mapFileName is None:
      return None
    dirname = os.path.dirname(self.mapFileName)
    return dirname
  def getChunkDirectory(self):
    dirName = self.getMapDirectory()
    if dirName is None:
      return None
    return os.path.join(dirName, 'chunks')
  def anyChunksDirty(self):
    for chunk in self.chunks.values():
      if chunk.isDirty():
        return True
    return False
  def moveTo(self, x, y, z):
    if self.position == [x, y, z]:
      return
    # We need to decide if the chunks should be unloaded here or not.
    newTopLeftChunkX = x // CHUNK_WIDTH - (MAP_WIDTH // 2)
    newTopLeftChunkY = y // CHUNK_HEIGHT - (MAP_HEIGHT // 2)
    newTopLeftChunkZ = z // CHUNK_DEPTH - (MAP_DEPTH // 2)
    if(newTopLeftChunkX != self.topLeftX or
        newTopLeftChunkY != self.topLeftY or
        newTopLeftChunkZ != self.topLeftZ):
      chunksToUnload = []
      chunksToKeep = []
      for chunk in self.chunks.values():
        chunkWorldX = chunk.x
        chunkWorldY = chunk.y
        chunkWorldZ = chunk.z
        if(chunkWorldX < newTopLeftChunkX or
            chunkWorldX >= newTopLeftChunkX + MAP_WIDTH or
            chunkWorldY < newTopLeftChunkY or
            chunkWorldY >= newTopLeftChunkY + MAP_HEIGHT or
            chunkWorldZ < newTopLeftChunkZ or
            chunkWorldZ >= newTopLeftChunkZ + MAP_DEPTH):
          chunksToUnload.append(chunk)
        else:
          chunksToKeep.append(chunk)
      # Unload chunks that are out of the new bounds.
      for chunk in chunksToUnload:
        if chunk.isDirty():
          print(f"Can't move map, some chunks are dirty: ({chunk.x}, {chunk.y}, {chunk.z})")
          return
      # Now we can safely unload the chunks.
      chunkIndex = 0
      newChunks = {}
      for chunk in chunksToKeep:
        newChunks[chunkIndex] = chunk
        chunkIndex += 1
      for xPos in range(newTopLeftChunkX, newTopLeftChunkX + MAP_WIDTH):
        for yPos in range(newTopLeftChunkY, newTopLeftChunkY + MAP_HEIGHT):
          for zPos in range(newTopLeftChunkZ, newTopLeftChunkZ + MAP_DEPTH):
            # Check if we already have this chunk.
            found = False
            for chunk in chunksToKeep:
              if chunk.x == xPos and chunk.y == yPos and chunk.z == zPos:
                found = True
                break
            if not found:
              # Create a new chunk.
              newChunk = chunksToUnload.pop()
              newChunk.reload(xPos, yPos, zPos)
              newChunks[chunkIndex] = newChunk
              chunkIndex += 1
      self.chunks = newChunks
      self.topLeftX = newTopLeftChunkX
      self.topLeftY = newTopLeftChunkY
      self.topLeftZ = newTopLeftChunkZ
    self.position = [x, y, z]
    self.onPositionChange.invoke(self.position)
    if not self.firstLoad:
      self.updateEditorConfig()
    self.firstLoad = False
  def moveRelative(self, x, y, z):
    self.moveTo(
      self.position[0] + x,
      self.position[1] + y,
      self.position[2] + z
    )
  def draw(self):
    for chunk in self.chunks.values():
      chunk.draw()
    for chunk in self.chunks.values():
      for entity in chunk.entities.values():
        entity.draw()
    # Only render on Region tab
    if self.parent.leftPanel.tabs.currentWidget() == self.parent.leftPanel.regionPanel:
      for chunk in self.chunks.values():
        for region in chunk.regions.values():
          region.draw()
  def getChunkAtWorldPos(self, x, y, z):
    chunkX = x // CHUNK_WIDTH
    chunkY = y // CHUNK_HEIGHT
    chunkZ = z // CHUNK_DEPTH
    for chunk in self.chunks.values():
      if chunk.x == chunkX and chunk.y == chunkY and chunk.z == chunkZ:
        return chunk
    return None
  def getTileAtWorldPos(self, x, y, z):
    chunk = self.getChunkAtWorldPos(x, y, z)
    if not chunk:
      print("No chunk found at position:", (x, y, z))
      return None
    tileX = x % CHUNK_WIDTH
    tileY = y % CHUNK_HEIGHT
    tileZ = z % CHUNK_DEPTH
    tileIndex = tileX + tileY * CHUNK_WIDTH + tileZ * CHUNK_WIDTH * CHUNK_HEIGHT
    return chunk.tiles.get(tileIndex)
@@ -1,141 +0,0 @@
 from tools.dusk.defs import CHUNK_WIDTH, CHUNK_HEIGHT, CHUNK_DEPTH, TILE_WIDTH, TILE_HEIGHT, TILE_DEPTH
 from tools.editor.map.vertexbuffer import VertexBuffer
 from OpenGL.GL import *
 from OpenGL.GLU import *
 class Region:
  def __init__(self, chunk):
    self.minX = 0
    self.minY = 0
    self.minZ = 0
    self.maxX = 0
    self.maxY = 0
    self.maxZ = 0
    self.chunk = chunk
    self.vertexBuffer = VertexBuffer()
    self.color = (1.0, 0.0, 0.0)
    self.updateVertexs()
    pass
  def updateVertexs(self):
    # Draw a quad, semi transparent with solid outlines
    vminX = (self.minX * CHUNK_WIDTH) * TILE_WIDTH
    vminY = (self.minY * CHUNK_HEIGHT) * TILE_HEIGHT
    vminZ = (self.minZ * CHUNK_DEPTH) * TILE_DEPTH
    vmaxX = (self.maxX * CHUNK_WIDTH) * TILE_WIDTH
    vmaxY = (self.maxY * CHUNK_HEIGHT) * TILE_HEIGHT
    vmaxZ = (self.maxZ * CHUNK_DEPTH) * TILE_DEPTH
    alpha = 0.25
    # Move back half a tile width
    vminX -= TILE_WIDTH / 2
    vmaxX -= TILE_WIDTH / 2
    vminY -= TILE_HEIGHT / 2
    vmaxY -= TILE_HEIGHT / 2
    vminZ -= TILE_DEPTH / 2
    vmaxZ -= TILE_DEPTH / 2
    # Cube (6 verts per face)
    self.vertexBuffer.vertices = [
      # Front face
      vminX, vminY, vmaxZ,
      vmaxX, vminY, vmaxZ,
      vmaxX, vmaxY, vmaxZ,
      vminX, vminY, vmaxZ,
      vmaxX, vmaxY, vmaxZ,
      vminX, vmaxY, vmaxZ,
      # Back face
      vmaxX, vminY, vminZ,
      vminX, vminY, vminZ,
      vminX, vmaxY, vminZ,
      vmaxX, vminY, vminZ,
      vminX, vmaxY, vminZ,
      vmaxX, vmaxY, vminZ,
      # Left face
      vminX, vminY, vminZ,
      vminX, vminY, vmaxZ,
      vminX, vmaxY, vmaxZ,
      vminX, vminY, vminZ,
      vminX, vmaxY, vmaxZ,
      vminX, vmaxY, vminZ,
      # Right face
      vmaxX, vminY, vmaxZ,
      vmaxX, vminY, vminZ,
      vmaxX, vmaxY, vminZ,
      vmaxX, vminY, vmaxZ,
      vmaxX, vmaxY, vminZ,
      vmaxX, vmaxY, vmaxZ,
      # Top face
      vminX, vmaxY, vmaxZ,
      vmaxX, vmaxY, vmaxZ,
      vmaxX, vmaxY, vminZ,
      vminX, vmaxY, vmaxZ,
      vmaxX, vmaxY, vminZ,
      vminX, vmaxY, vminZ,
      # Bottom face
      vminX, vminY, vminZ,
      vmaxX, vminY, vminZ,
      vmaxX, vminY, vmaxZ,
      vminX, vminY, vminZ,
      vmaxX, vminY, vmaxZ,
      vminX, vminY, vmaxZ,
    ]
    self.vertexBuffer.colors = [
      # Front face
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      # Back face
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      # Left face
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      # Right face
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      # Top face
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      # Bottom face
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
      self.color[0], self.color[1], self.color[2], alpha,
    ]
    self.vertexBuffer.buildData()
  def draw(self):
    self.vertexBuffer.draw()
@@ -1,206 +0,0 @@
 from OpenGL.GL import *
 from tools.dusk.defs import (
  TILE_WIDTH, TILE_HEIGHT, TILE_DEPTH,
  CHUNK_WIDTH, CHUNK_HEIGHT, CHUNK_DEPTH,
  TILE_SHAPE_NULL, TILE_SHAPE_FLOOR,
  TILE_SHAPE_RAMP_NORTH, TILE_SHAPE_RAMP_SOUTH,
  TILE_SHAPE_RAMP_EAST, TILE_SHAPE_RAMP_WEST,
  TILE_SHAPE_RAMP_SOUTHWEST, TILE_SHAPE_RAMP_SOUTHEAST,
  TILE_SHAPE_RAMP_NORTHWEST, TILE_SHAPE_RAMP_NORTHEAST
 )
 def getItem(arr, index, default):
  if index < len(arr):
    return arr[index]
  return default
 class Tile:
  def __init__(self, chunk, x, y, z, tileIndex):
    self.shape = TILE_SHAPE_NULL
    self.chunk = chunk
    self.x = x
    self.y = y
    self.z = z
    self.index = tileIndex
    self.posX = x * TILE_WIDTH + chunk.x * CHUNK_WIDTH * TILE_WIDTH
    self.posY = y * TILE_HEIGHT + chunk.y * CHUNK_HEIGHT * TILE_HEIGHT
    self.posZ = z * TILE_DEPTH + chunk.z * CHUNK_DEPTH * TILE_DEPTH
  def chunkReload(self, newX, newY, newZ):
    self.posX = self.x * TILE_WIDTH + newX * CHUNK_WIDTH * TILE_WIDTH
    self.posY = self.y * TILE_HEIGHT + newY * CHUNK_HEIGHT * TILE_HEIGHT
    self.posZ = self.z * TILE_DEPTH + newZ * CHUNK_DEPTH * TILE_DEPTH
  def load(self, chunkData):
    self.shape = getItem(chunkData['shapes'], self.index, TILE_SHAPE_NULL)
  def setShape(self, shape):
    if shape == self.shape:
      return
    self.shape = shape
    self.chunk.dirty = True
    self.chunk.tileUpdateVertices()
    self.chunk.onChunkData.invoke(self.chunk)
  def getBaseTileModel(self):
    vertices = []
    indices = []
    uvs = []
    colors = [] 
    if self.shape == TILE_SHAPE_NULL:
      pass
    elif self.shape == TILE_SHAPE_FLOOR:
      vertices = [
        (self.posX, self.posY, self.posZ),
        (self.posX + TILE_WIDTH, self.posY, self.posZ),
        (self.posX + TILE_WIDTH, self.posY + TILE_HEIGHT, self.posZ),
        (self.posX, self.posY + TILE_HEIGHT, self.posZ)
      ]
      indices = [0, 1, 2, 0, 2, 3]
      uvs = [ (0, 0), (1, 0), (1, 1), (0, 1) ]
      colors = [ (255, 255, 255, 255) ] * 4
    elif self.shape == TILE_SHAPE_RAMP_NORTH:
      vertices = [
        (self.posX, self.posY, self.posZ + TILE_DEPTH),
        (self.posX + TILE_WIDTH, self.posY, self.posZ + TILE_DEPTH),
        (self.posX + TILE_WIDTH, self.posY + TILE_HEIGHT, self.posZ),
        (self.posX, self.posY + TILE_HEIGHT, self.posZ)
      ]
      indices = [0, 1, 2, 0, 2, 3]
      uvs = [ (0, 0), (1, 0), (1, 1), (0, 1) ]
      colors = [ (255, 0, 0, 255) ] * 4
    elif self.shape == TILE_SHAPE_RAMP_SOUTH:
      vertices = [
        (self.posX, self.posY, self.posZ),
        (self.posX + TILE_WIDTH, self.posY, self.posZ),
        (self.posX + TILE_WIDTH, self.posY + TILE_HEIGHT, self.posZ + TILE_DEPTH),
        (self.posX, self.posY + TILE_HEIGHT, self.posZ + TILE_DEPTH)
      ]
      indices = [0, 1, 2, 0, 2, 3]
      uvs = [ (0, 0), (1, 0), (1, 1), (0, 1) ]
      colors = [ (0, 255, 0, 255) ] * 4
    elif self.shape == TILE_SHAPE_RAMP_EAST:
      vertices = [
        (self.posX, self.posY, self.posZ),
        (self.posX + TILE_WIDTH, self.posY, self.posZ + TILE_DEPTH),
        (self.posX + TILE_WIDTH, self.posY + TILE_HEIGHT, self.posZ + TILE_DEPTH),
        (self.posX, self.posY + TILE_HEIGHT, self.posZ)
      ]
      indices = [0, 1, 2, 0, 2, 3]
      uvs = [ (0, 0), (1, 0), (1, 1), (0, 1) ]
      colors = [ (0, 0, 255, 255) ] * 4
    elif self.shape == TILE_SHAPE_RAMP_WEST:
      vertices = [
        (self.posX, self.posY, self.posZ + TILE_DEPTH),
        (self.posX + TILE_WIDTH, self.posY, self.posZ),
        (self.posX + TILE_WIDTH, self.posY + TILE_HEIGHT, self.posZ),
        (self.posX, self.posY + TILE_HEIGHT, self.posZ + TILE_DEPTH)
      ]
      indices = [0, 1, 2, 0, 2, 3]
      uvs = [ (0, 0), (1, 0), (1, 1), (0, 1) ]
      colors = [ (255, 255, 0, 255) ] * 4
    elif self.shape == TILE_SHAPE_RAMP_SOUTHWEST:
      vertices = [
        (self.posX, self.posY, self.posZ + TILE_DEPTH),
        (self.posX + TILE_WIDTH, self.posY, self.posZ),
        (self.posX + TILE_WIDTH, self.posY + TILE_HEIGHT, self.posZ + TILE_DEPTH),
        (self.posX, self.posY + TILE_HEIGHT, self.posZ + TILE_DEPTH)
      ]
      indices = [0, 1, 2, 0, 2, 3]
      uvs = [ (0, 0), (1, 0), (1, 1), (0, 1) ]
      colors = [ (255, 128, 0, 255) ] * 4
    elif self.shape == TILE_SHAPE_RAMP_NORTHWEST:
      vertices = [
        (self.posX, self.posY, self.posZ + TILE_DEPTH),
        (self.posX + TILE_WIDTH, self.posY, self.posZ + TILE_DEPTH),
        (self.posX + TILE_WIDTH, self.posY + TILE_HEIGHT, self.posZ),
        (self.posX, self.posY + TILE_HEIGHT, self.posZ + TILE_DEPTH)
      ]
      indices = [0, 1, 2, 0, 2, 3]
      uvs = [ (0, 0), (1, 0), (1, 1), (0, 1) ]
      colors = [ (128, 255, 0, 255) ] * 4
    elif self.shape == TILE_SHAPE_RAMP_NORTHEAST:
      vertices = [
        (self.posX, self.posY, self.posZ + TILE_DEPTH),
        (self.posX + TILE_WIDTH, self.posY, self.posZ + TILE_DEPTH),
        (self.posX + TILE_WIDTH, self.posY + TILE_HEIGHT, self.posZ + TILE_DEPTH),
        (self.posX, self.posY + TILE_HEIGHT, self.posZ)
      ]
      indices = [0, 1, 2, 0, 2, 3]
      uvs = [ (0, 0), (1, 0), (1, 1), (0, 1) ]
      colors = [ (0, 255, 128, 255) ] * 4
    elif self.shape == TILE_SHAPE_RAMP_SOUTHEAST:
      vertices = [
        (self.posX, self.posY, self.posZ),
        (self.posX + TILE_WIDTH, self.posY, self.posZ + TILE_DEPTH),
        (self.posX + TILE_WIDTH, self.posY + TILE_HEIGHT, self.posZ + TILE_DEPTH),
        (self.posX, self.posY + TILE_HEIGHT, self.posZ + TILE_DEPTH)
      ]
      indices = [0, 1, 2, 0, 2, 3]
      uvs = [ (0, 0), (1, 0), (1, 1), (0, 1) ]
      colors = [ (255, 128, 255, 255) ] * 4
    else:
      # Solid black cube for unknown shape
      x0, y0, z0 = self.posX, self.posY, self.posZ
      x1, y1, z1 = self.posX + TILE_WIDTH, self.posY + TILE_HEIGHT, self.posZ + TILE_DEPTH
      vertices = [
        (x0, y0, z0), (x1, y0, z0), (x1, y1, z0), (x0, y1, z0), # bottom
        (x0, y0, z1), (x1, y0, z1), (x1, y1, z1), (x0, y1, z1)  # top
      ]
      indices = [
        0,1,2, 0,2,3,   # bottom
        4,5,6, 4,6,7,   # top
        0,1,5, 0,5,4,   # front
        2,3,7, 2,7,6,   # back
        1,2,6, 1,6,5,   # right
        3,0,4, 3,4,7    # left
      ]
      uvs = [ (0,0) ] * 8
      colors = [ (0,0,0,255) ] * 8
    return {
      'vertices': vertices,
      'indices': indices,
      'uvs': uvs,
      'colors': colors
    }
  def buffer(self, vertexBuffer):
    if self.shape == TILE_SHAPE_NULL:
      return
    # New code:
    baseData = self.getBaseTileModel()
    # Base data is indiced but we need to buffer unindiced data
    for index in baseData['indices']:
      verts = baseData['vertices'][index]
      uv = baseData['uvs'][index]
      color = baseData['colors'][index]
      vertexBuffer.vertices.extend([
        verts[0] - (TILE_WIDTH / 2.0),
        verts[1] - (TILE_HEIGHT / 2.0),
        verts[2] - (TILE_DEPTH / 2.0)
      ])
      vertexBuffer.colors.extend([
        color[0] / 255.0,
        color[1] / 255.0,
        color[2] / 255.0,
        color[3] / 255.0
      ])
@@ -0,0 +1,18 @@
 # Copyright (c) 2026 Dominic Masters
 # 
 # This software is released under the MIT License.
 # https://opensource.org/licenses/MIT
 add_subdirectory(debug)
 add_subdirectory(frame)
 add_subdirectory(focus)
 add_subdirectory(overlay)
 add_subdirectory(transition)
 add_subdirectory(widget)
 # Sources
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    ui.c
    uielement.c
 )
@@ -5,5 +5,6 @@
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
-    scenerainbownothing.c
+    uiconsole.c
    uifps.c
 )
@@ -0,0 +1,138 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uiconsole.h"
 #include "assert/assert.h"
 #include "console/console.h"
 #include "display/screen/screen.h"
 #include "display/text/text.h"
 #include "display/spritebatch/spritebatch.h"
 #include "display/shader/shaderunlit.h"
 #include "display/mesh/mesh.h"
 #include "util/memory.h"
 typedef struct {
  mesh_t mesh;
  bool_t built;
  meshvertex_t vertices[UI_CONSOLE_CACHE_VERTEX_MAX];
  int32_t vertexCount;
  int32_t cachedScanX;
  int32_t cachedScanY;
 } uiconsolecache_t;
 uiconsolecache_t UI_CONSOLE_CACHE;
 errorret_t uiConsoleDraw(void) {
  if(!CONSOLE.visible) errorOk();
  if(
    CONSOLE.dirty ||
    UI_CONSOLE_CACHE.cachedScanX != SCREEN.scanX ||
    UI_CONSOLE_CACHE.cachedScanY != SCREEN.scanY
  ) {
    errorChain(uiConsoleRebuild());
  }
  if(UI_CONSOLE_CACHE.vertexCount == 0) errorOk();
  shadermaterial_t material = {
    .unlit = {
      .color = COLOR_RED,
      .texture = FONT_DEFAULT.texture
    }
  };
  errorChain(shaderBind(&SHADER_UNLIT));
  errorChain(shaderSetMaterial(&SHADER_UNLIT, &material));
  return meshDraw(&UI_CONSOLE_CACHE.mesh, 0, UI_CONSOLE_CACHE.vertexCount);
 }
 errorret_t uiConsoleRebuild(void) {
  int32_t spriteCount = 0;
  for(uint32_t i = 0; i < CONSOLE_HISTORY_MAX; i++) {
    char_t c;
    int32_t j = 0;
    while((c = CONSOLE.line[i][j++]) != '\0') {
      if(c != ' ' && c != '\n') spriteCount++;
    }
  }
  assertTrue(
    spriteCount <= UI_CONSOLE_CACHE_GLYPH_MAX,
    "Console history exceeds fixed cache capacity"
  );
  const int32_t vertexCount = spriteCount * QUAD_VERTEX_COUNT;
  UI_CONSOLE_CACHE.vertexCount = vertexCount;
  if(vertexCount > 0) {
    const float_t lineH = (float_t)FONT_DEFAULT.tileset->tileHeight;
    const float_t charW = (float_t)FONT_DEFAULT.tileset->tileWidth;
    int32_t index = 0;
    int32_t row = 0;
    for(uint32_t i = 0; i < CONSOLE_HISTORY_MAX; i++) {
      float_t posX = (float_t)SCREEN.scanX;
      float_t posY = (float_t)SCREEN.scanY + lineH * (float_t)row;
      char_t c;
      int32_t j = 0;
      while((c = CONSOLE.line[i][j++]) != '\0') {
        if(c == '\n') {
          posX = (float_t)SCREEN.scanX;
          posY += lineH;
          row++;
          continue;
        }
        if(c == ' ') {
          posX += charW;
          continue;
        }
        const spritebatchsprite_t sprite = textGetSprite(
          (vec2){ posX, posY }, c, &FONT_DEFAULT
        );
        spriteBatchBufferToMesh(
          &sprite, 1,
          &UI_CONSOLE_CACHE.vertices[index], QUAD_VERTEX_COUNT
        );
        index += QUAD_VERTEX_COUNT;
        posX += charW;
      }
      row++;
    }
    if(!UI_CONSOLE_CACHE.built) {
      errorChain(meshInit(
        &UI_CONSOLE_CACHE.mesh,
        QUAD_PRIMITIVE_TYPE,
        UI_CONSOLE_CACHE_VERTEX_MAX,
        UI_CONSOLE_CACHE.vertices
      ));
      UI_CONSOLE_CACHE.built = true;
    } else {
      errorChain(meshFlush(&UI_CONSOLE_CACHE.mesh, 0, vertexCount));
    }
  }
  UI_CONSOLE_CACHE.cachedScanX = SCREEN.scanX;
  UI_CONSOLE_CACHE.cachedScanY = SCREEN.scanY;
  CONSOLE.dirty = false;
  errorOk();
 }
 errorret_t uiConsoleDispose(void) {
  if(UI_CONSOLE_CACHE.built) {
    errorChain(meshDispose(&UI_CONSOLE_CACHE.mesh));
  }
  memoryZero(&UI_CONSOLE_CACHE, sizeof(uiconsolecache_t));
  errorOk();
 }
@@ -0,0 +1,48 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "display/mesh/quad.h"
 // Fixed capacity for the console's cached glyph mesh, in glyphs -- the
 // mesh/vertex buffer is sized to this once and never grown/shrunk, so
 // history producing more non-space characters than this asserts (see
 // uiConsoleRebuild) instead of reallocating.
 #define UI_CONSOLE_CACHE_GLYPH_MAX 512
 #define UI_CONSOLE_CACHE_VERTEX_MAX (\
  UI_CONSOLE_CACHE_GLYPH_MAX * QUAD_VERTEX_COUNT \
 )
 /**
 * Renders the console history into the scan-safe area, drawing a mesh
 * that is only rebuilt when the history changes or the scan-safe origin
 * moves, rather than rebuffering vertices every frame. No-ops when the
 * console is not visible.
 *
 * @return Any error that occurs.
 */
 errorret_t uiConsoleDraw(void);
 /**
 * Rebuilds the cached mesh for the console's current history and
 * scan-safe origin. Called automatically by uiConsoleDraw() whenever
 * needed; only needs calling directly to force an immediate rebuild.
 * The underlying vertex buffer is a fixed-size array (see
 * UI_CONSOLE_CACHE_VERTEX_MAX) -- asserts if the history produces more
 * glyphs than that capacity, rather than growing it.
 *
 * @return Any error that occurs.
 */
 errorret_t uiConsoleRebuild(void);
 /**
 * Frees the mesh and vertex buffer built up by uiConsoleDraw().
 *
 * @return Any error that occurs.
 */
 errorret_t uiConsoleDispose(void);
@@ -0,0 +1,78 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uifps.h"
 #include "time/time.h"
 #include "util/string.h"
 #include "display/text/text.h"
 #include "display/screen/screen.h"
 #include "engine/engine.h"
 uifps_t UIFPS;
 errorret_t uiFPSInit() {
  uiLabelInit(&UIFPS.fpsLabel, &FONT_DEFAULT);
  uiLabelInit(&UIFPS.versionLabel, &FONT_DEFAULT);
  uiLabelSetText(&UIFPS.versionLabel, ENGINE.version);
  uiLabelSetColor(&UIFPS.versionLabel, color(255, 255, 255, 128));
  errorOk();
 }
 errorret_t uiFPSDraw() {
  char_t fpsText[32];
  // Get now.
  dusktimeepoch_t now = timeGetEpoch();
  double_t delta = now.time - UIFPS.lastTick.time;
  UIFPS.lastTick = now;
  // Raw current FPS
  float_t fps = delta > 0 ? 1.0 / delta : 0.0;
  // Average FPS using exponential moving average
  const float_t alpha = 0.1f; // Smoothing factor
  if(UIFPS.fpsAverage == 0.0f) {
    UIFPS.fpsAverage = fps; // Initialize average on first run
  } else {
    UIFPS.fpsAverage = alpha * fps + (1.0f - alpha) * UIFPS.fpsAverage;
  }
  snprintf(
    fpsText,
    sizeof(fpsText),
    "%.1f/%.1fms",
    UIFPS.fpsAverage,
    delta * 1000.0f
  );
  color_t textColor;
  if(fps >= 55.0f) {
    textColor = COLOR_GREEN;
  } else if(fps >= 45.0f) {
    textColor = COLOR_YELLOW;
  } else {
    textColor = COLOR_RED;
  }
  uiLabelSetColor(&UIFPS.fpsLabel, textColor);
  if(stringCompare(fpsText, UIFPS.fpsLabel.text) != 0) {
    uiLabelSetText(&UIFPS.fpsLabel, fpsText);
  }
  errorChain(uiLabelDraw(
    &UIFPS.fpsLabel, (float_t)SCREEN.scanX, (float_t)SCREEN.scanY
  ));
  int32_t versionWidth, versionHeight;
  uiLabelGetSize(&UIFPS.versionLabel, &versionWidth, &versionHeight);
  errorChain(uiLabelDraw(
    &UIFPS.versionLabel,
    (float_t)(SCREEN.scanX + SCREEN.scanWidth - versionWidth),
    (float_t)(SCREEN.scanY + SCREEN.scanHeight - versionHeight)
  ));
  errorOk();
 }
@@ -8,15 +8,24 @@
 #pragma once
 #include "error/error.h"
 #include "time/timeepoch.h"
-#include "util/fixed.h"
+#include "ui/widget/uilabel.h"
 typedef struct {
  dusktimeepoch_t lastTick;
-  fixed_t fpsAverage;
+  float_t fpsAverage;
  uilabel_t fpsLabel;
  uilabel_t versionLabel;
 } uifps_t;
 extern uifps_t UIFPS;
 /**
 * Initializes the FPS counter, caching the (static) version label.
 *
 * @return Any error that occurs.
 */
 errorret_t uiFPSInit();
 /**
 * Draws the FPS counter on the screen, and also does the update (for now).
 *
@@ -5,5 +5,5 @@
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
-    renderpsp.c
+    uifocus.c
 )
@@ -0,0 +1,190 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uifocus.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "input/input.h"
 #include "time/time.h"
 const uifocusdirmap_t UI_FOCUS_DIR_MAP[] = {
  { INPUT_BIND_UP,    UI_FOCUS_DIRECTION_UP,     0, -1 },
  { INPUT_BIND_DOWN,  UI_FOCUS_DIRECTION_DOWN,   0,  1 },
  { INPUT_BIND_LEFT,  UI_FOCUS_DIRECTION_LEFT,  -1,  0 },
  { INPUT_BIND_RIGHT, UI_FOCUS_DIRECTION_RIGHT,  1,  0 },
  { INPUT_BIND_NULL,  UI_FOCUS_DIRECTION_NONE,   0,  0 },
 };
 uifocus_t UI_FOCUS;
 void uiFocusInit(void) {
  memoryZero(&UI_FOCUS, sizeof(uifocus_t));
 }
 uifocusitem_t * uiFocusPush(
  const uint8_t cols,
  const uint8_t rows,
  uifocusitemcallback_t selected,
  uifocusitemcallback_t changed,
  uifocusitemcallback_t closed,
  uifocusitemdirectioncallback_t direction,
  void *user
 ) {
  assertTrue(
    UI_FOCUS.count < UI_FOCUS_STACK_MAX,
    "UI focus stack overflow"
  );
  assertTrue(cols > 0, "Focus item cols must be > 0");
  assertTrue(rows > 0, "Focus item rows must be > 0");
  uifocusitem_t *item = &UI_FOCUS.items[UI_FOCUS.count];
  memoryZero(item, sizeof(uifocusitem_t));
  item->cols = cols;
  item->rows = rows;
  item->selected = selected;
  item->changed = changed;
  item->closed = closed;
  item->direction = direction;
  item->user = user;
  UI_FOCUS.count++;
  UI_FOCUS.pushedThisTick = true;
  if(item->changed != NULL) item->changed(item);
  return item;
 }
 void uiFocusPop(void) {
  assertTrue(UI_FOCUS.count > 0, "UI focus stack underflow");
  uifocusitem_t *item = &UI_FOCUS.items[UI_FOCUS.count - 1];
  if(item->closed != NULL) item->closed(item);
  UI_FOCUS.count--;
 }
 void uiFocusPopItem(uifocusitem_t *item) {
  assertTrue(UI_FOCUS.count > 0, "UI focus stack underflow");
  assertTrue(item >= UI_FOCUS.items, "Item is not on the focus stack");
  assertTrue(
    item < UI_FOCUS.items + UI_FOCUS.count,
    "Item is not on the focus stack"
  );
  while(&UI_FOCUS.items[UI_FOCUS.count - 1] != item) {
    uiFocusPop();
  }
  uiFocusPop();
 }
 void uiFocusSetPosition(uifocusitem_t *item, const uint8_t x, const uint8_t y) {
  assertTrue(UI_FOCUS.count > 0, "No active focus item");
  assertTrue(item->cols > 0, "Focus item cols must be > 0");
  assertTrue(item->rows > 0, "Focus item rows must be > 0");
  uint8_t newX = x % item->cols;
  uint8_t newY = y % item->rows;
  if(item->changed != NULL) {
    uint8_t oldX = item->x;
    uint8_t oldY = item->y;
    item->x = newX;
    item->y = newY;
    if(!item->changed(item)) {
      item->x = oldX;
      item->y = oldY;
    }
    return;
  }
  item->x = newX;
  item->y = newY;
 }
 void uiFocusMoveDirection(
  uifocusitem_t *item,
  const uifocusdirection_t dir
 ) {
  for(
    const uifocusdirmap_t *m = UI_FOCUS_DIR_MAP;
    m->action != INPUT_BIND_NULL;
    m++
  ) {
    if(m->direction != dir) continue;
    uint8_t x = (uint8_t)(item->x + m->dx);
    uint8_t y = (uint8_t)(item->y + m->dy);
    uiFocusSetPosition(item, x, y);
    break;
  }
 }
 void uiFocusHandleDirection(
  uifocusitem_t *item,
  const uifocusdirection_t dir
 ) {
  if(item->direction != NULL && item->direction(item, dir)) return;
  uiFocusMoveDirection(item, dir);
 }
 void uiFocusUpdate(void) {
  if(UI_FOCUS.count == 0) return;
  #ifdef DUSK_TIME_DYNAMIC
    if(TIME.dynamicUpdate) return;
  #endif
  if(UI_FOCUS.pushedThisTick) {
    UI_FOCUS.pushedThisTick = false;
    return;
  }
  uifocusitem_t *item = &UI_FOCUS.items[UI_FOCUS.count - 1];
  if(inputPressed(INPUT_BIND_ACCEPT)) {
    if(item->selected != NULL) item->selected(item);
    return;
  }
  if(inputPressed(INPUT_BIND_CANCEL)) {
    uiFocusPop();
    return;
  }
  for(
    const uifocusdirmap_t *m = UI_FOCUS_DIR_MAP;
    m->action != INPUT_BIND_NULL;
    m++
  ) {
    if(!inputPressed(m->action)) continue;
    UI_FOCUS.direction = m->direction;
    UI_FOCUS.timeHeld = 0.0f;
    uiFocusHandleDirection(item, m->direction);
    return;
  }
  bool_t held = false;
  for(
    const uifocusdirmap_t *m = UI_FOCUS_DIR_MAP;
    m->action != INPUT_BIND_NULL;
    m++
  ) {
    if(m->direction != UI_FOCUS.direction) continue;
    held = inputIsDown(m->action);
    break;
  }
  if(!held) {
    UI_FOCUS.direction = UI_FOCUS_DIRECTION_NONE;
    UI_FOCUS.timeHeld = 0.0f;
    return;
  }
  UI_FOCUS.timeHeld += TIME.delta;
  if(UI_FOCUS.timeHeld < UI_FOCUS_HOLD_DELAY) return;
  if(UI_FOCUS.timeHeld < UI_FOCUS_HOLD_DELAY + UI_FOCUS_HOLD_REPEAT) return;
  UI_FOCUS.timeHeld = UI_FOCUS_HOLD_DELAY;
  uiFocusHandleDirection(item, UI_FOCUS.direction);
 }
@@ -0,0 +1,133 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "uifocusitem.h"
 #include "input/inputaction.h"
 /** Maximum depth of the focus stack. */
 #define UI_FOCUS_STACK_MAX 8
 /**
 * How long a direction must be held before repeating begins, in seconds.
 */
 #define UI_FOCUS_HOLD_DELAY 0.5f
 /**
 * Interval between repeated moves while a direction is held, in seconds.
 */
 #define UI_FOCUS_HOLD_REPEAT 0.1f
 typedef struct {
  inputbind_t action;
  uifocusdirection_t direction;
  int8_t dx;
  int8_t dy;
 } uifocusdirmap_t;
 /**
 * Mapping of input actions to focus directions, terminated by an
 * entry with action == INPUT_BIND_NULL.
 */
 extern const uifocusdirmap_t UI_FOCUS_DIR_MAP[];
 /**
 * A stack of focused UI items. Push an item when a widget captures
 * focus; pop it when focus is released. The topmost item is always
 * the active focus context.
 */
 typedef struct {
  uifocusitem_t items[UI_FOCUS_STACK_MAX];
  uint8_t count;
  uifocusdirection_t direction;
  float_t timeHeld;
  bool_t pushedThisTick;
 } uifocus_t;
 extern uifocus_t UI_FOCUS;
 /**
 * Initializes the focus system, zeroing all state.
 */
 void uiFocusInit(void);
 /**
 * Pushes a new focus item onto the stack with the given grid dimensions
 * and callbacks. x and y are initialized to 0.
 *
 * @param cols      Number of columns in the focus grid.
 * @param rows      Number of rows in the focus grid.
 * @param selected  Called when the user selects the focused cell.
 * @param changed   Called when the focused cell position changes.
 * @param closed    Called when this focus item is popped.
 * @param direction Called on a direction press/hold before the default
 *                  cell-to-cell movement is applied; may be NULL.
 * @param user      Arbitrary pointer stored on the item before changed fires.
 * @returns Pointer to the newly pushed focus item.
 */
 uifocusitem_t * uiFocusPush(
  const uint8_t cols,
  const uint8_t rows,
  uifocusitemcallback_t selected,
  uifocusitemcallback_t changed,
  uifocusitemcallback_t closed,
  uifocusitemdirectioncallback_t direction,
  void *user
 );
 /**
 * Pops the topmost focus item from the stack, invoking its closed
 * callback if one is set.
 */
 void uiFocusPop(void);
 /**
 * Pops an item and anything that was pushed after it from the focus stack.
 * 
 * @param item The focus item to pop to. Must be on the stack.
 */
 void uiFocusPopItem(uifocusitem_t *item);
 /**
 * Manually sets the cursor position of the topmost focus item and
 * fires its changed callback.
 *
 * @param x Column to move to.
 * @param y Row to move to.
 */
 void uiFocusSetPosition(uifocusitem_t *item, const uint8_t x, const uint8_t y);
 /**
 * Moves the topmost focus item one step in the given direction,
 * wrapping at the grid edges, and fires its changed callback.
 *
 * @param item The focus item to move.
 * @param dir Direction to move.
 */
 void uiFocusMoveDirection(
  uifocusitem_t *item,
  const uifocusdirection_t dir
 );
 /**
 * Handles a direction press/hold for the given item: gives the item's
 * direction callback (if any) first refusal, falling back to the
 * default cell-to-cell movement if it's unset or returns false.
 *
 * @param item The focus item to move.
 * @param dir Direction that was pressed or held.
 */
 void uiFocusHandleDirection(
  uifocusitem_t *item,
  const uifocusdirection_t dir
 );
 /**
 * Updates the focus system. Handles first-press movement and
 * held-direction repeating. Called once per game tick.
 */
 void uiFocusUpdate(void);
@@ -0,0 +1,57 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "dusk.h"
 typedef struct uifocusitem_s uifocusitem_t;
 typedef enum {
  UI_FOCUS_DIRECTION_NONE,
  UI_FOCUS_DIRECTION_UP,
  UI_FOCUS_DIRECTION_DOWN,
  UI_FOCUS_DIRECTION_LEFT,
  UI_FOCUS_DIRECTION_RIGHT
 } uifocusdirection_t;
 /**
 * Callback invoked when a focus item's selected cell changes.
 *
 * @param item The focus item that changed.
 */
 typedef bool_t (*uifocusitemcallback_t)(const uifocusitem_t *item);
 /**
 * Callback invoked when a direction is pressed or held-repeated while
 * this item is focused, before the default cell-to-cell movement is
 * applied.
 *
 * @param item The focus item that is currently focused.
 * @param direction The direction that was pressed.
 * @returns True if the direction was fully handled and the default
 * grid movement should be skipped; false to fall through to it.
 */
 typedef bool_t (*uifocusitemdirectioncallback_t)(
  const uifocusitem_t *item,
  const uifocusdirection_t direction
 );
 /**
 * A single entry on the UI focus stack. Tracks the focused cell
 * within a grid of cols x rows, and the current x/y position.
 */
 struct uifocusitem_s {
  uint8_t cols;
  uint8_t rows;
  uint8_t x;
  uint8_t y;
  uifocusitemcallback_t selected;
  uifocusitemcallback_t changed;
  uifocusitemcallback_t closed;
  uifocusitemdirectioncallback_t direction;
  void *user;
 };
@@ -0,0 +1,12 @@
 # Copyright (c) 2026 Dominic Masters
 #
 # This software is released under the MIT License.
 # https://opensource.org/licenses/MIT
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    uiframe.c
    uiconfirm.c
 )
 add_subdirectory(settings)
@@ -0,0 +1,13 @@
 # Copyright (c) 2026 Dominic Masters
 #
 # This software is released under the MIT License.
 # https://opensource.org/licenses/MIT
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    uisettings.c
    uisettingsgeneral.c
    uisettingsinput.c
    uisettingsdisplay.c
    uisettingsaudio.c
 )
@@ -0,0 +1,248 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uisettings.h"
 #include "uisettingsgeneral.h"
 #include "uisettingsinput.h"
 #include "uisettingsdisplay.h"
 #include "uisettingsaudio.h"
 #include "ui/frame/uiframe.h"
 #include "ui/frame/uiconfirm.h"
 #include "util/memory.h"
 #include "display/text/text.h"
 #include "display/screen/screen.h"
 #include "assert/assert.h"
 #include "locale/localemanager.h"
 #include "asset/loader/locale/assetlocaleloader.h"
 uisettings_t UI_SETTINGS;
 uisettingstabdef_t UI_SETTINGS_TAB_DEFS[UI_SETTINGS_TAB_COUNT] = {
  {
    .localeId = "ui.settings.tabs.general",
    .init = uiSettingsGeneralInit,
    .menu = (uimenu_t *)&UI_SETTINGS.data,
    .load = uiSettingsGeneralLoad,
    .apply = uiSettingsGeneralApply,
    .hasChanges = uiSettingsGeneralHasChanges
  },
  {
    .localeId = "ui.settings.tabs.input",
    .init = uiSettingsInputInit,
    .menu = (uimenu_t *)&UI_SETTINGS.data,
    .load = uiSettingsInputLoad,
    .apply = uiSettingsInputApply,
    .hasChanges = uiSettingsInputHasChanges
  },
  {
    .localeId = "ui.settings.tabs.display",
    .init = uiSettingsDisplayInit,
    .menu = (uimenu_t *)&UI_SETTINGS.data,
    .load = uiSettingsDisplayLoad,
    .apply = uiSettingsDisplayApply,
    .hasChanges = uiSettingsDisplayHasChanges
  },
  {
    .localeId = "ui.settings.tabs.audio",
    .init = uiSettingsAudioInit,
    .menu = (uimenu_t *)&UI_SETTINGS.data,
    .load = uiSettingsAudioLoad,
    .apply = uiSettingsAudioApply,
    .hasChanges = uiSettingsAudioHasChanges
  }
 };
 static uisettingstabdef_t UI_SETTINGS_TOP_DEF = {
  .menu = &UI_SETTINGS.tabsMenu,
  .load = uiSettingsLoad,
  .hasChanges = uiSettingsHasChanges
 };
 static uisettingstabdef_t *UI_SETTINGS_PENDING_DISCARD = NULL;
 static uisettingstabdef_t *UI_SETTINGS_ACTIVE_TAB = NULL;
 errorret_t uiSettingsActivateTab(uisettingstabdef_t *def) {
  if(def == UI_SETTINGS_ACTIVE_TAB) errorOk();
  errorChain(def->init(&UI_SETTINGS.data));
  def->menu->user = def;
  def->load();
  UI_SETTINGS_ACTIVE_TAB = def;
  errorOk();
 }
 void uiSettingsTabChanged(
  const uimenu_t *menu,
  const uint8_t index,
  const uimenuitem_t *item
 ) {
  if(index >= UI_SETTINGS_TAB_COUNT) return;
  errorCatch(uiSettingsActivateTab(&UI_SETTINGS_TAB_DEFS[index]));
 }
 void uiSettingsTabSelected(
  const uimenu_t *menu,
  const uint8_t index,
  const uimenuitem_t *item
 ) {
  if(index >= UI_SETTINGS_TAB_COUNT) return;
  uisettingstabdef_t *def = &UI_SETTINGS_TAB_DEFS[index];
  errorCatch(uiSettingsActivateTab(def));
  uiMenuOpen(def->menu);
 }
 errorret_t uiSettingsInit(void) {
  memoryZero(&UI_SETTINGS, sizeof(uisettings_t));
  UI_SETTINGS_ACTIVE_TAB = NULL;
  for(uint8_t i = 0; i < UI_SETTINGS_TAB_COUNT; i++) {
    errorChain(assetLocaleGetString(
      &LOCALE.entry->data.locale,
      UI_SETTINGS_TAB_DEFS[i].localeId,
      0,
      UI_SETTINGS.tabLabels[i],
      UI_SETTINGS_TAB_LABEL_MAX
    ));
  }
  MENU_BEGIN(
    &UI_SETTINGS.tabsMenu, UI_SETTINGS.tabs, uiSettingsTabSelected,
    uiSettingsDiscardMenuClosed, uiSettingsTabChanged
  );
  for(uint8_t i = 0; i < UI_SETTINGS_TAB_COUNT; i++) {
    MENU_TAB(UI_SETTINGS.tabLabels[i]);
  }
  MENU_END(UI_SETTINGS.tabs, menuIndex);
  UI_SETTINGS.tabsMenu.user = &UI_SETTINGS_TOP_DEF;
  errorChain(assetLocaleGetString(
    &LOCALE.entry->data.locale,
    "ui.settings.apply",
    0,
    UI_SETTINGS.applyLabel,
    UI_SETTINGS_APPLY_LABEL_MAX
  ));
  errorChain(uiSettingsActivateTab(&UI_SETTINGS_TAB_DEFS[0]));
  errorOk();
 }
 errorret_t uiSettingsDraw(void) {
  if(!uiMenuIsActive(&UI_SETTINGS.tabsMenu)) errorOk();
  const float_t width = SCREEN.width;
  const float_t height = SCREEN.height;
  const float_t x = (float_t)SCREEN.scanX +
    ((float_t)SCREEN.scanWidth - width) * 0.5f;
  const float_t y = (float_t)SCREEN.scanY +
    ((float_t)SCREEN.scanHeight - height) * 0.5f;
  errorChain(uiFrameDrawCached(&UI_SETTINGS.frameCache, x, y, width, height));
  const float_t contentX = x + UI_FRAME_START_X;
  const float_t contentY = y + UI_FRAME_START_Y;
  const float_t contentWidth = width - (UI_FRAME_START_X * 2);
  const float_t contentHeight = height - (UI_FRAME_START_Y * 2);
  errorChain(uiMenuDraw(
    &UI_SETTINGS.tabsMenu,
    contentX,
    contentY,
    contentWidth,
    contentHeight
  ));
  const float_t tabsRowHeight = (float_t)FONT_DEFAULT.tileset->tileHeight;
  const float_t pageY = contentY + tabsRowHeight + UI_FRAME_PADDING_Y;
  const float_t pageHeight = contentHeight - tabsRowHeight - UI_FRAME_PADDING_Y;
  if(UI_SETTINGS_ACTIVE_TAB != NULL) {
    errorChain(uiMenuDraw(
      UI_SETTINGS_ACTIVE_TAB->menu, contentX, pageY, contentWidth, pageHeight
    ));
  }
  errorOk();
 }
 errorret_t uiSettingsUpdate(void) {
  if(!UI_SETTINGS_PENDING_DISCARD) errorOk();
  uisettingstabdef_t *def = UI_SETTINGS_PENDING_DISCARD;
  UI_SETTINGS_PENDING_DISCARD = NULL;
  return uiSettingsDiscardUpdate(def);
 }
 bool_t uiSettingsIsOpen(void) {
  return uiMenuIsActive(&UI_SETTINGS.tabsMenu);
 }
 void uiSettingsOpen() {
  uiSettingsLoad();
  uiMenuOpen(&UI_SETTINGS.tabsMenu);
 }
 void uiSettingsClose() {
  uiMenuClose(&UI_SETTINGS.tabsMenu);
 }
 errorret_t uiSettingsDispose(void) {
  errorOk();
 }
 void uiSettingsLoad(void) {
  if(UI_SETTINGS_ACTIVE_TAB != NULL) UI_SETTINGS_ACTIVE_TAB->load();
 }
 void uiSettingsApply(void) {
  if(UI_SETTINGS_ACTIVE_TAB != NULL) UI_SETTINGS_ACTIVE_TAB->apply();
 }
 bool_t uiSettingsHasChanges(void) {
  return UI_SETTINGS_ACTIVE_TAB != NULL && UI_SETTINGS_ACTIVE_TAB->hasChanges();
 }
 void uiSettingsDiscardMenuClosed(const uimenu_t *menu) {
  uisettingstabdef_t *def = (uisettingstabdef_t *)menu->user;
  if(def->hasChanges()) UI_SETTINGS_PENDING_DISCARD = def;
 }
 errorret_t uiSettingsDiscardUpdate(uisettingstabdef_t *def) {
  #define UI_SETTINGS_DISCARD_TEXT_MAX 128
  char_t text[UI_SETTINGS_DISCARD_TEXT_MAX];
  errorChain(assetLocaleGetString(
    &LOCALE.entry->data.locale,
    "ui.confirm.discard_changes",
    0,
    text,
    UI_SETTINGS_DISCARD_TEXT_MAX
  ));
  #undef UI_SETTINGS_DISCARD_TEXT_MAX
  uiConfirmOpen(text, uiSettingsDiscardConfirmResult, def);
  errorOk();
 }
 void uiSettingsDiscardConfirmResult(const bool_t result, void *user) {
  uisettingstabdef_t *def = (uisettingstabdef_t *)user;
  if(!result) {
    uiMenuOpen(def->menu);
    return;
  }
  def->load();
 }
@@ -0,0 +1,135 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "ui/widget/uimenu.h"
 #include "ui/frame/uiframe.h"
 #include "uisettingsdata.h"
 #define UI_SETTINGS_TAB_COUNT 4
 #define UI_SETTINGS_TAB_LABEL_MAX 32
 #define UI_SETTINGS_APPLY_LABEL_MAX 32
 typedef struct {
  const char_t *localeId;
  errorret_t (*init)(uisettingsdata_t *data);
  uimenu_t *menu;
  void (*load)(void);
  void (*apply)(void);
  bool_t (*hasChanges)(void);
 } uisettingstabdef_t;
 typedef struct {
  uimenu_t tabsMenu;
  uimenuitem_t tabs[UI_SETTINGS_TAB_COUNT];
  char_t tabLabels[UI_SETTINGS_TAB_COUNT][UI_SETTINGS_TAB_LABEL_MAX];
  char_t applyLabel[UI_SETTINGS_APPLY_LABEL_MAX];
  uisettingsdata_t data;
  uiframecache_t frameCache;
 } uisettings_t;
 extern uisettings_t UI_SETTINGS;
 extern uisettingstabdef_t UI_SETTINGS_TAB_DEFS[UI_SETTINGS_TAB_COUNT];
 /**
 * Menu closed callback that flags a pending discard-changes
 * confirmation if the menu's settings page/panel reports unsaved
 * changes. Pass this directly as a settings page menu's closed
 * callback. The pending def is picked up by uiSettingsUpdate on the
 * next tick.
 *
 * @param menu The menu that was just closed.
 */
 void uiSettingsDiscardMenuClosed(const uimenu_t *menu);
 /**
 * Shows the discard-changes confirmation dialog for def. Called once
 * by uiSettingsUpdate when uiSettingsDiscardMenuClosed has flagged a
 * pending def.
 *
 * @param def The tab/panel def to show the confirmation for.
 * @return Any error that occurs.
 */
 errorret_t uiSettingsDiscardUpdate(uisettingstabdef_t *def);
 /**
 * Callback passed to uiConfirmOpen by uiSettingsDiscardUpdate. Reopens
 * the menu if the user chose to keep editing, otherwise reloads the
 * widgets back to the actual engine values.
 *
 * @param result True if the user confirmed discarding changes, false
 * to keep editing.
 * @param user The uisettingstabdef_t* this confirmation belongs to.
 */
 void uiSettingsDiscardConfirmResult(const bool_t result, void *user);
 /**
 * Initializes the settings panel and all of its category pages.
 *
 * @return Any error that occurs.
 */
 errorret_t uiSettingsInit(void);
 /**
 * Draws the settings panel. No-op when not visible.
 *
 * @return Any error that occurs.
 */
 errorret_t uiSettingsDraw(void);
 /**
 * Updates the settings panel. Shows a discard-changes confirmation if
 * the panel was just closed with unsaved changes.
 *
 * @return Any error that occurs.
 */
 errorret_t uiSettingsUpdate(void);
 /**
 * Returns true when the settings panel is currently open.
 *
 * @returns True if open.
 */
 bool_t uiSettingsIsOpen(void);
 /**
 * Opens the settings panel. No-op when already open.
 */
 void uiSettingsOpen();
 /**
 * Closes the settings panel. No-op when already closed.
 */
 void uiSettingsClose();
 /**
 * Disposes of the settings panel.
 *
 * @return Any error that occurs.
 */
 errorret_t uiSettingsDispose(void);
 /**
 * Loads every category page's widgets from the current engine settings.
 * Called automatically by uiSettingsOpen.
 */
 void uiSettingsLoad(void);
 /**
 * Applies every category page's widget values to the engine settings.
 * Called automatically when a page's own Apply button is pressed.
 */
 void uiSettingsApply(void);
 /**
 * Returns whether any category page has a widget value that differs
 * from what was loaded.
 *
 * @returns True if there are unsaved changes.
 */
 bool_t uiSettingsHasChanges(void);
@@ -0,0 +1,47 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uisettingsaudio.h"
 #include "uisettings.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 void uiSettingsAudioSelected(
  const uimenu_t *menu,
  const uint8_t index,
  const uimenuitem_t *item
 ) {
  if(index != UI_SETTINGS_AUDIO_INDEX_APPLY) return;
  uiSettingsAudioApply();
 }
 errorret_t uiSettingsAudioInit(uisettingsdata_t *data) {
  uisettingsaudio_t *audio = &data->audio;
  memoryZero(audio, sizeof(uisettingsaudio_t));
  MENU_BEGIN(
    &audio->menu, audio->items,
    uiSettingsAudioSelected, uiSettingsDiscardMenuClosed, NULL
  );
  MENU_LABEL("No audio settings yet");
  MENU_BUTTON(UI_SETTINGS.applyLabel);
  MENU_END(audio->items, 1);
  errorOk();
 }
 void uiSettingsAudioLoad(void) {
 }
 void uiSettingsAudioApply(void) {
  uiMenuClose(&UI_SETTINGS.data.audio.menu);
 }
 bool_t uiSettingsAudioHasChanges(void) {
  return false;
 }
@@ -0,0 +1,36 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "uisettingsdata.h"
 /**
 * Initializes the audio settings page into the shared settings data
 * union.
 *
 * @param data The shared settings data union to initialize into.
 * @return Any error that occurs.
 */
 errorret_t uiSettingsAudioInit(uisettingsdata_t *data);
 /**
 * Loads the page's widgets from the current engine audio settings.
 */
 void uiSettingsAudioLoad(void);
 /**
 * Applies the page's widget values to the engine audio settings.
 */
 void uiSettingsAudioApply(void);
 /**
 * Returns whether any widget's value differs from what was loaded.
 *
 * @returns True if there are unsaved changes.
 */
 bool_t uiSettingsAudioHasChanges(void);
@@ -0,0 +1,67 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "ui/widget/uimenu.h"
 #define UI_SETTINGS_GENERAL_ITEM_COUNT 3
 #define UI_SETTINGS_GENERAL_INDEX_LANGUAGE 0
 #define UI_SETTINGS_GENERAL_INDEX_LANGUAGE_DETAIL 1
 #define UI_SETTINGS_GENERAL_INDEX_APPLY 2
 #define UI_SETTINGS_GENERAL_LOCALE_COUNT 3
 #define UI_SETTINGS_GENERAL_LABEL_MAX 32
 #define UI_SETTINGS_GENERAL_INFO_MAX 64
 typedef struct {
  uimenu_t menu;
  uimenuitem_t items[UI_SETTINGS_GENERAL_ITEM_COUNT];
  const char_t *localeNames[UI_SETTINGS_GENERAL_LOCALE_COUNT];
  char_t languageLabel[UI_SETTINGS_GENERAL_LABEL_MAX];
  char_t labelInfo[UI_SETTINGS_GENERAL_INFO_MAX];
 } uisettingsgeneral_t;
 #define UI_SETTINGS_INPUT_ITEM_COUNT 2
 #define UI_SETTINGS_INPUT_LABEL_MAX 32
 #define UI_SETTINGS_INPUT_INDEX_DEADZONE 0
 #define UI_SETTINGS_INPUT_INDEX_APPLY 1
 typedef struct {
  uimenu_t menu;
  uimenuitem_t items[UI_SETTINGS_INPUT_ITEM_COUNT];
  char_t deadzoneLabel[UI_SETTINGS_INPUT_LABEL_MAX];
 } uisettingsinput_t;
 #define UI_SETTINGS_DISPLAY_ITEM_COUNT 2
 #define UI_SETTINGS_DISPLAY_INDEX_APPLY 1
 typedef struct {
  uimenu_t menu;
  uimenuitem_t items[UI_SETTINGS_DISPLAY_ITEM_COUNT];
 } uisettingsdisplay_t;
 #define UI_SETTINGS_AUDIO_ITEM_COUNT 2
 #define UI_SETTINGS_AUDIO_INDEX_APPLY 1
 typedef struct {
  uimenu_t menu;
  uimenuitem_t items[UI_SETTINGS_AUDIO_ITEM_COUNT];
 } uisettingsaudio_t;
 /**
 * Shared, overlapping storage for every settings tab's page data. Only
 * one member is ever live at a time -- the active tab's Init writes
 * into it, overwriting whatever the previously active tab left there.
 * This trades simultaneous access to every tab for a memory footprint
 * of only the single largest page.
 */
 typedef union {
  uisettingsgeneral_t general;
  uisettingsinput_t input;
  uisettingsdisplay_t display;
  uisettingsaudio_t audio;
 } uisettingsdata_t;
@@ -0,0 +1,47 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uisettingsdisplay.h"
 #include "uisettings.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 void uiSettingsDisplaySelected(
  const uimenu_t *menu,
  const uint8_t index,
  const uimenuitem_t *item
 ) {
  if(index != UI_SETTINGS_DISPLAY_INDEX_APPLY) return;
  uiSettingsDisplayApply();
 }
 errorret_t uiSettingsDisplayInit(uisettingsdata_t *data) {
  uisettingsdisplay_t *display = &data->display;
  memoryZero(display, sizeof(uisettingsdisplay_t));
  MENU_BEGIN(
    &display->menu, display->items,
    uiSettingsDisplaySelected, uiSettingsDiscardMenuClosed, NULL
  );
  MENU_LABEL("No display settings yet");
  MENU_BUTTON(UI_SETTINGS.applyLabel);
  MENU_END(display->items, 1);
  errorOk();
 }
 void uiSettingsDisplayLoad(void) {
 }
 void uiSettingsDisplayApply(void) {
  uiMenuClose(&UI_SETTINGS.data.display.menu);
 }
 bool_t uiSettingsDisplayHasChanges(void) {
  return false;
 }
@@ -0,0 +1,36 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "uisettingsdata.h"
 /**
 * Initializes the display settings page into the shared settings data
 * union.
 *
 * @param data The shared settings data union to initialize into.
 * @return Any error that occurs.
 */
 errorret_t uiSettingsDisplayInit(uisettingsdata_t *data);
 /**
 * Loads the page's widgets from the current engine display settings.
 */
 void uiSettingsDisplayLoad(void);
 /**
 * Applies the page's widget values to the engine display settings.
 */
 void uiSettingsDisplayApply(void);
 /**
 * Returns whether any widget's value differs from what was loaded.
 *
 * @returns True if there are unsaved changes.
 */
 bool_t uiSettingsDisplayHasChanges(void);
@@ -0,0 +1,117 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uisettingsgeneral.h"
 #include "uisettings.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "util/string.h"
 #include "locale/localemanager.h"
 #include "locale/localeinfo.h"
 #include "asset/loader/locale/assetlocaleloader.h"
 static const localeinfo_t *const UI_SETTINGS_GENERAL_LOCALES[
  UI_SETTINGS_GENERAL_LOCALE_COUNT
 ] = {
  &LOCALE_EN_US,
  &LOCALE_JP_JP,
  &LOCALE_ES_MX
 };
 void uiSettingsGeneralSelected(
  const uimenu_t *menu,
  const uint8_t index,
  const uimenuitem_t *item
 ) {
  switch(index) {
    case UI_SETTINGS_GENERAL_INDEX_APPLY:
      uiSettingsGeneralApply();
      break;
    default:
      break;
  }
 }
 errorret_t uiSettingsGeneralInit(uisettingsdata_t *data) {
  uisettingsgeneral_t *general = &data->general;
  memoryZero(general, sizeof(uisettingsgeneral_t));
  for(uint8_t i = 0; i < UI_SETTINGS_GENERAL_LOCALE_COUNT; i++) {
    general->localeNames[i] = UI_SETTINGS_GENERAL_LOCALES[i]->name;
  }
  errorChain(assetLocaleGetString(
    &LOCALE.entry->data.locale,
    "ui.settings.general.language",
    0,
    general->languageLabel,
    UI_SETTINGS_GENERAL_LABEL_MAX
  ));
  errorChain(assetLocaleGetString(
    &LOCALE.entry->data.locale,
    "ui.settings.general.language_detail",
    0,
    general->labelInfo,
    UI_SETTINGS_GENERAL_INFO_MAX
  ));
  MENU_BEGIN(
    &general->menu, general->items,
    uiSettingsGeneralSelected, uiSettingsDiscardMenuClosed, NULL
  );
  MENU_DROPDOWN(
    general->languageLabel, general->localeNames,
    UI_SETTINGS_GENERAL_LOCALE_COUNT, 0
  );
  MENU_LABEL(general->labelInfo);
  MENU_BUTTON(UI_SETTINGS.applyLabel);
  MENU_END(general->items, 1);
  errorOk();
 }
 void uiSettingsGeneralLoad(void) {
  uisettingsgeneral_t *general = &UI_SETTINGS.data.general;
  uint8_t index = 0;
  for(uint8_t i = 0; i < UI_SETTINGS_GENERAL_LOCALE_COUNT; i++) {
    if(stringCompare(LOCALE.locale->file, UI_SETTINGS_GENERAL_LOCALES[i]->file) != 0) {
      continue;
    }
    index = i;
    break;
  }
  uiDropdownSetSelectedIndex(
    &general->items[UI_SETTINGS_GENERAL_INDEX_LANGUAGE].dropdown, index
  );
 }
 void uiSettingsGeneralApply(void) {
  uisettingsgeneral_t *general = &UI_SETTINGS.data.general;
  uint8_t index = uiDropdownGetSelectedIndex(
    &general->items[UI_SETTINGS_GENERAL_INDEX_LANGUAGE].dropdown
  );
  errorCatch(localeManagerSetLocale(UI_SETTINGS_GENERAL_LOCALES[index]));
  uiMenuClose(&general->menu);
 }
 bool_t uiSettingsGeneralHasChanges(void) {
  uisettingsgeneral_t *general = &UI_SETTINGS.data.general;
  uint8_t index = uiDropdownGetSelectedIndex(
    &general->items[UI_SETTINGS_GENERAL_INDEX_LANGUAGE].dropdown
  );
  return stringCompare(
    LOCALE.locale->file, UI_SETTINGS_GENERAL_LOCALES[index]->file
  ) != 0;
 }
@@ -0,0 +1,36 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "uisettingsdata.h"
 /**
 * Initializes the general settings page into the shared settings data
 * union.
 *
 * @param data The shared settings data union to initialize into.
 * @return Any error that occurs.
 */
 errorret_t uiSettingsGeneralInit(uisettingsdata_t *data);
 /**
 * Loads the page's widgets from the current engine general settings.
 */
 void uiSettingsGeneralLoad(void);
 /**
 * Applies the page's widget values to the engine general settings.
 */
 void uiSettingsGeneralApply(void);
 /**
 * Returns whether any widget's value differs from what was loaded.
 *
 * @returns True if there are unsaved changes.
 */
 bool_t uiSettingsGeneralHasChanges(void);
@@ -0,0 +1,82 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uisettingsinput.h"
 #include "uisettings.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "locale/localemanager.h"
 #include "asset/loader/locale/assetlocaleloader.h"
 #include "input/input.h"
 #include "save/savesettings.h"
 void uiSettingsInputSelected(
  const uimenu_t *menu,
  const uint8_t index,
  const uimenuitem_t *item
 ) {
  if(index != UI_SETTINGS_INPUT_INDEX_APPLY) return;
  uiSettingsInputApply();
 }
 errorret_t uiSettingsInputInit(uisettingsdata_t *data) {
  uisettingsinput_t *input = &data->input;
  memoryZero(input, sizeof(uisettingsinput_t));
  MENU_BEGIN(
    &input->menu, input->items,
    uiSettingsInputSelected, uiSettingsDiscardMenuClosed, NULL
  );
  #ifdef DUSK_INPUT_GAMEPAD
    errorChain(assetLocaleGetString(
      &LOCALE.entry->data.locale,
      "ui.settings.input.deadzone",
      0,
      input->deadzoneLabel,
      UI_SETTINGS_INPUT_LABEL_MAX
    ));
    MENU_SLIDER_FLOAT(
      input->deadzoneLabel, INPUT_DEADZONE_DEFAULT, 0.0f, 1.0f, 0.05f
    );
  #else
    MENU_LABEL("No input settings yet");
  #endif
  MENU_BUTTON(UI_SETTINGS.applyLabel);
  MENU_END(input->items, 1);
  errorOk();
 }
 void uiSettingsInputLoad(void) {
  #ifdef DUSK_INPUT_GAMEPAD
    uiSliderSetFloat(
      &UI_SETTINGS.data.input.items[UI_SETTINGS_INPUT_INDEX_DEADZONE].slider,
      INPUT.deadzone
    );
  #endif
 }
 void uiSettingsInputApply(void) {
  #ifdef DUSK_INPUT_GAMEPAD
    INPUT.deadzone = uiSliderGetFloat(
      &UI_SETTINGS.data.input.items[UI_SETTINGS_INPUT_INDEX_DEADZONE].slider
    );
  #endif
  errorCatch(errorPrint(saveSettingsWrite()));
  uiMenuClose(&UI_SETTINGS.data.input.menu);
 }
 bool_t uiSettingsInputHasChanges(void) {
  #ifdef DUSK_INPUT_GAMEPAD
    if(uiSliderGetFloat(
      &UI_SETTINGS.data.input.items[UI_SETTINGS_INPUT_INDEX_DEADZONE].slider
    ) != INPUT.deadzone) return true;
  #endif
  return false;
 }
@@ -0,0 +1,36 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "uisettingsdata.h"
 /**
 * Initializes the input settings page into the shared settings data
 * union.
 *
 * @param data The shared settings data union to initialize into.
 * @return Any error that occurs.
 */
 errorret_t uiSettingsInputInit(uisettingsdata_t *data);
 /**
 * Loads the page's widgets from the current engine input settings.
 */
 void uiSettingsInputLoad(void);
 /**
 * Applies the page's widget values to the engine input settings.
 */
 void uiSettingsInputApply(void);
 /**
 * Returns whether any widget's value differs from what was loaded.
 *
 * @returns True if there are unsaved changes.
 */
 bool_t uiSettingsInputHasChanges(void);
@@ -0,0 +1,126 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uiconfirm.h"
 #include "uiframe.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "util/math.h"
 #include "display/screen/screen.h"
 #include "display/text/text.h"
 #include "display/color.h"
 #include "display/spritebatch/spritebatch.h"
 #include "display/texture/texture.h"
 #include "display/shader/shaderunlit.h"
 #define UI_CONFIRM_BACKDROP_COLOR color4b(0, 0, 0, 160)
 uiconfirm_t UI_CONFIRM;
 void uiConfirmSelected(
  const uimenu_t *menu,
  const uint8_t index,
  const uimenuitem_t *item
 ) {
  UI_CONFIRM.result = index == UI_CONFIRM_INDEX_CONFIRM;
  uiConfirmClose();
 }
 void uiConfirmClosed(const uimenu_t *menu) {
  if(UI_CONFIRM.callback != NULL) {
    UI_CONFIRM.callback(UI_CONFIRM.result, UI_CONFIRM.user);
  }
 }
 errorret_t uiConfirmInit(void) {
  memoryZero(&UI_CONFIRM, sizeof(uiconfirm_t));
  uiLabelInit(&UI_CONFIRM.textLabel, &FONT_DEFAULT);
  MENU_BEGIN(
    &UI_CONFIRM.menu, UI_CONFIRM.items, uiConfirmSelected, uiConfirmClosed, NULL
  );
  MENU_BUTTON("Confirm");
  MENU_BUTTON("Cancel");
  MENU_END(UI_CONFIRM.items, menuIndex);
  errorOk();
 }
 errorret_t uiConfirmDraw(void) {
  if(!uiMenuIsActive(&UI_CONFIRM.menu)) errorOk();
  spritebatchsprite_t backdropSprite = {
    .min = { 0.0f, 0.0f, 0.0f },
    .max = { (float_t)SCREEN.width, (float_t)SCREEN.height, 0.0f },
    .uvMin = { 0.0f, 0.0f },
    .uvMax = { 1.0f, 1.0f }
  };
  shadermaterial_t backdropMaterial = {
    .unlit = {
      .color = UI_CONFIRM_BACKDROP_COLOR,
      .texture = &TEXTURE_WHITE
    }
  };
  errorChain(
    spriteBatchBuffer(&backdropSprite, 1, &SHADER_UNLIT, backdropMaterial)
  );
  int32_t textW, textH;
  uiLabelGetSize(&UI_CONFIRM.textLabel, &textW, &textH);
  float_t rowHeight = (float_t)FONT_DEFAULT.tileset->tileHeight;
  float_t width = mathMax(
    (float_t)textW + (UI_FRAME_START_X * 2), UI_CONFIRM_MIN_WIDTH
  );
  float_t height = (UI_FRAME_START_Y * 2) + rowHeight + UI_FRAME_PADDING_Y +
    rowHeight;
  float_t x = (float_t)SCREEN.scanX + ((float_t)SCREEN.scanWidth - width) * 0.5f;
  float_t y = (float_t)SCREEN.scanY + ((float_t)SCREEN.scanHeight - height) * 0.5f;
  errorChain(uiFrameDrawCached(&UI_CONFIRM.frameCache, x, y, width, height));
  float_t contentX = x + UI_FRAME_START_X;
  float_t contentY = y + UI_FRAME_START_Y;
  float_t contentWidth = width - (UI_FRAME_START_X * 2);
  errorChain(uiLabelDraw(&UI_CONFIRM.textLabel, contentX, contentY));
  float_t buttonsY = contentY + rowHeight + UI_FRAME_PADDING_Y;
  errorChain(uiMenuDraw(&UI_CONFIRM.menu, contentX, buttonsY, contentWidth, rowHeight));
  errorOk();
 }
 bool_t uiConfirmIsOpen(void) {
  return uiMenuIsActive(&UI_CONFIRM.menu);
 }
 bool_t uiConfirmGetResult(void) {
  return UI_CONFIRM.result;
 }
 void uiConfirmOpen(
  const char_t *question,
  uiconfirmcallback_t callback,
  void *user
 ) {
  assertNotNull(question, "Question cannot be NULL");
  uiLabelSetText(&UI_CONFIRM.textLabel, question);
  UI_CONFIRM.callback = callback;
  UI_CONFIRM.user = user;
  UI_CONFIRM.result = false;
  uiMenuOpen(&UI_CONFIRM.menu);
 }
 void uiConfirmClose(void) {
  uiMenuClose(&UI_CONFIRM.menu);
 }
 errorret_t uiConfirmDispose(void) {
  errorOk();
 }
@@ -0,0 +1,96 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "ui/widget/uimenu.h"
 #include "ui/widget/uilabel.h"
 #include "ui/frame/uiframe.h"
 #define UI_CONFIRM_MIN_WIDTH 160.0f
 #define UI_CONFIRM_INDEX_CONFIRM 0
 #define UI_CONFIRM_INDEX_CANCEL 1
 #define UI_CONFIRM_ITEM_COUNT 2
 /**
 * Callback invoked once a confirm dialog is dismissed.
 *
 * @param result True if Confirm was selected, false if Cancel was
 * selected or the dialog was backed out of.
 * @param user Arbitrary pointer passed to uiConfirmOpen.
 */
 typedef void (*uiconfirmcallback_t)(const bool_t result, void *user);
 typedef struct {
  uilabel_t textLabel;
  uimenu_t menu;
  uimenuitem_t items[UI_CONFIRM_ITEM_COUNT];
  uiconfirmcallback_t callback;
  void *user;
  bool_t result;
  uiframecache_t frameCache;
 } uiconfirm_t;
 extern uiconfirm_t UI_CONFIRM;
 /**
 * Initializes the confirm dialog.
 *
 * @return Any error that occurs.
 */
 errorret_t uiConfirmInit(void);
 /**
 * Draws the confirm dialog: a semi-transparent black backdrop covering
 * the whole screen, then its own centered frame with the question text
 * and Confirm/Cancel buttons. No-op when not open.
 *
 * @return Any error that occurs.
 */
 errorret_t uiConfirmDraw(void);
 /**
 * Returns true when the confirm dialog is currently open.
 *
 * @returns True if open.
 */
 bool_t uiConfirmIsOpen(void);
 /**
 * Returns the result of the most recently dismissed confirm dialog.
 *
 * @returns True if Confirm was selected, false otherwise.
 */
 bool_t uiConfirmGetResult(void);
 /**
 * Opens the confirm dialog with the given question text. callback is
 * invoked exactly once with the result, whether the dialog was
 * dismissed by selecting a button or by pressing cancel/back.
 *
 * @param question Display text; copied internally, safe to be transient.
 * @param callback Called with the result once the dialog closes. May be
 * NULL.
 * @param user Arbitrary pointer passed through to callback.
 */
 void uiConfirmOpen(
  const char_t *question,
  uiconfirmcallback_t callback,
  void *user
 );
 /**
 * Closes the confirm dialog. No-op when already closed.
 */
 void uiConfirmClose(void);
 /**
 * Disposes of the confirm dialog.
 *
 * @return Any error that occurs.
 */
 errorret_t uiConfirmDispose(void);
@@ -0,0 +1,161 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uiframe.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "display/texture/texture.h"
 #include "display/spritebatch/spritebatch.h"
 #include "display/shader/shaderunlit.h"
 #include "display/color.h"
 uiframe_t UI_FRAME;
 errorret_t uiFrameInit(void) {
  memoryZero(&UI_FRAME, sizeof(uiframe_t));
  // Init texture.
  color_t border = color4b(0, 50, 255, 255);
  color_t center = color4b(0, 100, 220, 240);
  for(uint8_t y = 0; y < UI_FRAME_TEXTURE_HEIGHT_POW2; y++) {
    for(uint8_t x = 0; x < UI_FRAME_TEXTURE_WIDTH_POW2; x++) {
      color_t c;
      if(x >= UI_FRAME_TEXTURE_WIDTH || y >= UI_FRAME_TEXTURE_HEIGHT) {
        c = COLOR_TRANSPARENT;
      } else if(
        y < UI_FRAME_TILE_HEIGHT || y >= UI_FRAME_TILE_HEIGHT * 2 ||
        x < UI_FRAME_TILE_WIDTH  || x >= UI_FRAME_TILE_WIDTH * 2
      ) {
        c = border;
      } else {
        c = center;
      }
      UI_FRAME.pixels[y * UI_FRAME_TEXTURE_WIDTH_POW2 + x] = c;
    }
  }
  errorChain(textureInit(
    &UI_FRAME.texture,
    UI_FRAME_TEXTURE_WIDTH_POW2, UI_FRAME_TEXTURE_HEIGHT_POW2,
    TEXTURE_FORMAT_RGBA,
    (texturedata_t){ .rgbaColors = UI_FRAME.pixels }
  ));
  UI_FRAME.tileset.tileWidth = UI_FRAME_TILE_WIDTH;
  UI_FRAME.tileset.tileHeight = UI_FRAME_TILE_HEIGHT;
  UI_FRAME.tileset.columns = 3;
  UI_FRAME.tileset.rows = 3;
  UI_FRAME.tileset.tileCount = 9;
  UI_FRAME.tileset.uv[0] =
    (float_t)UI_FRAME_TILE_WIDTH / UI_FRAME_TEXTURE_WIDTH_POW2;
  UI_FRAME.tileset.uv[1] =
    (float_t)UI_FRAME_TILE_HEIGHT / UI_FRAME_TEXTURE_HEIGHT_POW2;
  errorOk();
 }
 errorret_t uiFrameDraw(
  const float_t x,
  const float_t y,
  const float_t width,
  const float_t height
 ) {
  shadermaterial_t material = {
    .unlit = {
      .color = COLOR_WHITE,
      .texture = &UI_FRAME.texture
    }
  };
  spritebatchsprite_t sprites[9];
  uiFrameBuildSprites(sprites, x, y, width, height);
  return spriteBatchBuffer(sprites, 9, &SHADER_UNLIT, material);
 }
 void uiFrameBuildSprites(
  spritebatchsprite_t sprites[9],
  const float_t x,
  const float_t y,
  const float_t width,
  const float_t height
 ) {
  float_t tileW = (float_t)UI_FRAME_BORDER_WIDTH;
  float_t tileH = (float_t)UI_FRAME_BORDER_HEIGHT;
  sprites[0] = spriteBatchSpriteTilesetPosition(
    &UI_FRAME.tileset, 0, 0,
    x, y, tileW, tileH
  );
  sprites[1] = spriteBatchSpriteTilesetPosition(
    &UI_FRAME.tileset, 1, 0,
    x + tileW, y, width - (tileW * 2.0f), tileH
  );
  sprites[2] = spriteBatchSpriteTilesetPosition(
    &UI_FRAME.tileset, 2, 0,
    x + width - tileW, y, tileW, tileH
  );
  sprites[3] = spriteBatchSpriteTilesetPosition(
    &UI_FRAME.tileset, 0, 1,
    x, y + tileH, tileW, height - (tileH * 2.0f)
  );
  sprites[4] = spriteBatchSpriteTilesetPosition(
    &UI_FRAME.tileset, 1, 1,
    x + tileW, y + tileH,
    width - (tileW * 2.0f), height - (tileH * 2.0f)
  );
  sprites[5] = spriteBatchSpriteTilesetPosition(
    &UI_FRAME.tileset, 2, 1,
    x + width - tileW, y + tileH, tileW, height - (tileH * 2.0f)
  );
  sprites[6] = spriteBatchSpriteTilesetPosition(
    &UI_FRAME.tileset, 0, 2,
    x, y + height - tileH, tileW, tileH
  );
  sprites[7] = spriteBatchSpriteTilesetPosition(
    &UI_FRAME.tileset, 1, 2,
    x + tileW, y + height - tileH, width - (tileW * 2.0f), tileH
  );
  sprites[8] = spriteBatchSpriteTilesetPosition(
    &UI_FRAME.tileset, 2, 2,
    x + width - tileW, y + height - tileH, tileW, tileH
  );
 }
 errorret_t uiFrameDrawCached(
  uiframecache_t *cache,
  const float_t x,
  const float_t y,
  const float_t width,
  const float_t height
 ) {
  assertNotNull(cache, "Frame cache cannot be NULL");
  if(
    !cache->built ||
    cache->lastX != x || cache->lastY != y ||
    cache->lastWidth != width || cache->lastHeight != height
  ) {
    uiFrameBuildSprites(cache->sprites, x, y, width, height);
    cache->lastX = x;
    cache->lastY = y;
    cache->lastWidth = width;
    cache->lastHeight = height;
    cache->built = true;
  }
  shadermaterial_t material = {
    .unlit = {
      .color = COLOR_WHITE,
      .texture = &UI_FRAME.texture
    }
  };
  return spriteBatchBuffer(cache->sprites, 9, &SHADER_UNLIT, material);
 }
 errorret_t uiFrameDispose(void) {
  return textureDispose(&UI_FRAME.texture);
 }
@@ -0,0 +1,122 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "display/texture/texture.h"
 #include "display/texture/tileset.h"
 #include "display/spritebatch/spritebatchsprite.h"
 #define UI_FRAME_BORDER_WIDTH 6
 #define UI_FRAME_BORDER_HEIGHT 6
 #define UI_FRAME_PADDING_X 2
 #define UI_FRAME_PADDING_Y 2
 #define UI_FRAME_START_X (UI_FRAME_BORDER_WIDTH + UI_FRAME_PADDING_X)
 #define UI_FRAME_START_Y (UI_FRAME_BORDER_HEIGHT + UI_FRAME_PADDING_Y)
 #define UI_FRAME_TILE_WIDTH 1
 #define UI_FRAME_TILE_HEIGHT 1
 #define UI_FRAME_TEXTURE_WIDTH (UI_FRAME_TILE_WIDTH * 3)
 #define UI_FRAME_TEXTURE_HEIGHT (UI_FRAME_TILE_HEIGHT * 3)
 #define UI_FRAME_TEXTURE_WIDTH_POW2 4
 #define UI_FRAME_TEXTURE_HEIGHT_POW2 4 
 typedef struct {
  tileset_t tileset;
  texture_t texture;
  color_t pixels[UI_FRAME_BORDER_WIDTH * UI_FRAME_BORDER_HEIGHT];
 } uiframe_t;
 extern uiframe_t UI_FRAME;
 /**
 * Initializes the global UI_FRAME: builds the dummy texture and
 * configures the tileset. Call once after displayInit().
 *
 * @return Any error that occurs.
 */
 errorret_t uiFrameInit(void);
 /**
 * Draws UI_FRAME using 9-slice rendering from its 3x3 tileset.
 * Pushes quads to the sprite batch without flushing.
 *
 * @param x Screen x position.
 * @param y Screen y position.
 * @param width Total width of the frame.
 * @param height Total height of the frame.
 * @return Any error that occurs.
 */
 errorret_t uiFrameDraw(
  const float_t x,
  const float_t y,
  const float_t width,
  const float_t height
 );
 /**
 * Builds the 9 sprites for a 9-slice frame at the given rect. Used
 * internally by uiFrameDraw and uiFrameDrawCached -- call directly only
 * if you need the raw sprites instead of buffering them.
 *
 * @param sprites Destination array of exactly 9 sprites.
 * @param x Screen x position.
 * @param y Screen y position.
 * @param width Total width of the frame.
 * @param height Total height of the frame.
 */
 void uiFrameBuildSprites(
  spritebatchsprite_t sprites[9],
  const float_t x,
  const float_t y,
  const float_t width,
  const float_t height
 );
 /**
 * A frame's cached 9-slice sprites, plus the rect they were built for.
 * Owned by whichever widget/screen draws a frame repeatedly (dialogs,
 * textboxes, settings panels) so uiFrameDrawCached can skip rebuilding
 * the sprites when the rect hasn't moved since the last draw.
 */
 typedef struct {
  spritebatchsprite_t sprites[9];
  bool_t built;
  float_t lastX;
  float_t lastY;
  float_t lastWidth;
  float_t lastHeight;
 } uiframecache_t;
 /**
 * Draws a 9-slice frame using a caller-owned cache, only rebuilding the
 * sprites (via uiFrameBuildSprites) when x/y/width/height differ from
 * the last call -- unlike uiFrameDraw, which rebuilds unconditionally
 * every time. Prefer this for frames redrawn every frame at a fixed or
 * rarely-changing rect (dialogs, panels); use plain uiFrameDraw for
 * genuinely one-off or per-frame-varying rects.
 *
 * @param cache Caller-owned cache, zero-initialized before first use.
 * @param x Screen x position.
 * @param y Screen y position.
 * @param width Total width of the frame.
 * @param height Total height of the frame.
 * @return Any error that occurs.
 */
 errorret_t uiFrameDrawCached(
  uiframecache_t *cache,
  const float_t x,
  const float_t y,
  const float_t width,
  const float_t height
 );
 /**
 * Disposes of the global UI_FRAME, releasing its GPU texture.
 *
 * @return Any error that occurs.
 */
 errorret_t uiFrameDispose(void);
@@ -0,0 +1,11 @@
 # Copyright (c) 2026 Dominic Masters
 #
 # This software is released under the MIT License.
 # https://opensource.org/licenses/MIT
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    uicrop.c
    uifullbox.c
    uiloading.c
 )
@@ -0,0 +1,89 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uicrop.h"
 #include "display/screen/screen.h"
 #include "display/spritebatch/spritebatch.h"
 #include "display/shader/shaderunlit.h"
 #include "display/texture/texture.h"
 uicrop_t UI_CROP;
 errorret_t uiCropInit(void) {
  UI_CROP.color = COLOR_BLACK;
  errorOk();
 }
 errorret_t uiCropDraw(void) {
  #ifndef DUSK_DISPLAY_SIZE_DYNAMIC
    errorOk();
  #endif
  if(
    SCREEN.scanX == 0 &&
    SCREEN.scanY == 0 &&
    SCREEN.scanWidth == SCREEN.width &&
    SCREEN.scanHeight == SCREEN.height
  ) errorOk();
  float_t x0 = (float_t)SCREEN.scanX;
  float_t y0 = (float_t)SCREEN.scanY;
  float_t x1 = (float_t)(SCREEN.scanX + SCREEN.scanWidth);
  float_t y1 = (float_t)(SCREEN.scanY + SCREEN.scanHeight);
  float_t w = (float_t)SCREEN.width;
  float_t h = (float_t)SCREEN.height;
  spritebatchsprite_t sprites[4];
  int32_t count = 0;
  if(SCREEN.scanX > 0) {
    sprites[count++] = (spritebatchsprite_t){
      .min = { 0.0f, 0.0f, 0.0f },
      .max = { x0, h, 0.0f },
      .uvMin = { 0.0f, 0.0f },
      .uvMax = { 1.0f, 1.0f }
    };
  }
  if(SCREEN.scanX + SCREEN.scanWidth < SCREEN.width) {
    sprites[count++] = (spritebatchsprite_t){
      .min = { x1, 0.0f, 0.0f },
      .max = { w, h, 0.0f },
      .uvMin = { 0.0f, 0.0f },
      .uvMax = { 1.0f, 1.0f }
    };
  }
  if(SCREEN.scanY > 0) {
    sprites[count++] = (spritebatchsprite_t){
      .min = { x0, 0.0f, 0.0f },
      .max = { x1, y0, 0.0f },
      .uvMin = { 0.0f, 0.0f },
      .uvMax = { 1.0f, 1.0f }
    };
  }
  if(SCREEN.scanY + SCREEN.scanHeight < SCREEN.height) {
    sprites[count++] = (spritebatchsprite_t){
      .min = { x0, y1, 0.0f },
      .max = { x1, h, 0.0f },
      .uvMin = { 0.0f, 0.0f },
      .uvMax = { 1.0f, 1.0f }
    };
  }
  if(count == 0) errorOk();
  shadermaterial_t material = {
    .unlit = {
      .color = UI_CROP.color,
      .texture = &TEXTURE_WHITE
    }
  };
  errorChain(spriteBatchBuffer(sprites, count, &SHADER_UNLIT, material));
  errorOk();
 }
@@ -0,0 +1,32 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "display/color.h"
 typedef struct {
  color_t color;
 } uicrop_t;
 extern uicrop_t UI_CROP;
 /**
 * Initializes the crop bars to opaque black.
 *
 * @return Any error that occurs.
 */
 errorret_t uiCropInit(void);
 /**
 * Renders solid-color bars covering every area outside the
 * current scan-safe region. No-ops when the scan area equals
 * the full viewport.
 *
 * @return Any error that occurs.
 */
 errorret_t uiCropDraw(void);
@@ -8,6 +8,7 @@
 #include "uifullbox.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "time/time.h"
 #include "display/screen/screen.h"
 #include "display/texture/texture.h"
 #include "display/spritebatch/spritebatch.h"
@@ -29,7 +30,7 @@ void uiFullboxInit(uifullbox_t *fullbox) {
 void uiFullboxUpdate(uifullbox_t *fullbox, float_t delta) {
  assertNotNull(fullbox, "fullbox must not be NULL");
-  if(fullbox->duration <= 0 || fullbox->time >= fullbox->duration) return;
+  if(fullbox->duration <= 0.0f || fullbox->time >= fullbox->duration) return;
  fullbox->time += delta;
  if(fullbox->time >= fullbox->duration) {
@@ -39,30 +40,19 @@ void uiFullboxUpdate(uifullbox_t *fullbox, float_t delta) {
 }
 static color_t uiFullboxGetColor(const uifullbox_t *fullbox) {
-  if(fullbox->duration <= 0 || fullbox->time >= fullbox->duration) {
+  if(fullbox->duration <= 0.0f || fullbox->time >= fullbox->duration) {
    return fullbox->toColor;
  }
-  fixed_t t = easingApply(
+  float_t t = easingApply(fullbox->easing, fullbox->time / fullbox->duration);
    fullbox->easing,
    fixedFromFloat(fullbox->time / fullbox->duration)
  );
  return color4b(
-    fixedToU8(fixedLerp(
+    (uint8_t)((float_t)fullbox->fromColor.r +
-      fixedFromU8(fullbox->fromColor.r),
+      ((float_t)fullbox->toColor.r - (float_t)fullbox->fromColor.r) * t),
-      fixedFromU8(fullbox->toColor.r), t
+    (uint8_t)((float_t)fullbox->fromColor.g +
-    )),
+      ((float_t)fullbox->toColor.g - (float_t)fullbox->fromColor.g) * t),
-    fixedToU8(fixedLerp(
+    (uint8_t)((float_t)fullbox->fromColor.b +
-      fixedFromU8(fullbox->fromColor.g),
+      ((float_t)fullbox->toColor.b - (float_t)fullbox->fromColor.b) * t),
-      fixedFromU8(fullbox->toColor.g), t
+    (uint8_t)((float_t)fullbox->fromColor.a +
-    )),
+      ((float_t)fullbox->toColor.a - (float_t)fullbox->fromColor.a) * t)
    fixedToU8(fixedLerp(
      fixedFromU8(fullbox->fromColor.b),
      fixedFromU8(fullbox->toColor.b), t
    )),
    fixedToU8(fixedLerp(
      fixedFromU8(fullbox->fromColor.a),
      fixedFromU8(fullbox->toColor.a), t
    ))
  );
 }
@@ -85,7 +75,7 @@ errorret_t uiFullboxDraw(uifullbox_t *fullbox) {
    }
  };
  errorChain(spriteBatchBuffer(&sprite, 1, &SHADER_UNLIT, material));
-  return spriteBatchFlush();
+  errorOk();
 }
 void uiFullboxTransition(
@@ -99,14 +89,34 @@ void uiFullboxTransition(
  fullbox->fromColor = from;
  fullbox->toColor = to;
  fullbox->duration = duration;
-  fullbox->time = 0;
+  fullbox->time = 0.0f;
  fullbox->easing = easing;
 }
 errorret_t uiFullboxUnderInit(void) {
  uiFullboxInit(&UI_FULLBOX_UNDER);
  errorOk();
 }
 errorret_t uiFullboxUnderUpdate(void) {
  uiFullboxUpdate(&UI_FULLBOX_UNDER, TIME.delta);
  errorOk();
 }
 errorret_t uiFullboxUnderDraw(void) {
  return uiFullboxDraw(&UI_FULLBOX_UNDER);
 }
 errorret_t uiFullboxOverInit(void) {
  uiFullboxInit(&UI_FULLBOX_OVER);
  errorOk();
 }
 errorret_t uiFullboxOverUpdate(void) {
  uiFullboxUpdate(&UI_FULLBOX_OVER, TIME.delta);
  errorOk();
 }
 errorret_t uiFullboxOverDraw(void) {
  return uiFullboxDraw(&UI_FULLBOX_OVER);
 }
@@ -66,12 +66,44 @@ void uiFullboxTransition(
  easingtype_t easing
 );
 /**
 * Init function for UI_FULLBOX_UNDER (registered in UI_ELEMENTS).
 *
 * @return Any error that occurs.
 */
 errorret_t uiFullboxUnderInit(void);
 /**
 * Update function for UI_FULLBOX_UNDER (registered in UI_ELEMENTS).
 *
 * @return Any error that occurs.
 */
 errorret_t uiFullboxUnderUpdate(void);
 /**
 * Draw function for UI_FULLBOX_UNDER (registered in UI_ELEMENTS).
 *
 * @return Any error that occurs.
 */
 errorret_t uiFullboxUnderDraw(void);
 /**
 * Init function for UI_FULLBOX_OVER (registered in UI_ELEMENTS).
 *
 * @return Any error that occurs.
 */
 errorret_t uiFullboxOverInit(void);
 /**
 * Update function for UI_FULLBOX_OVER (registered in UI_ELEMENTS).
 *
 * @return Any error that occurs.
 */
 errorret_t uiFullboxOverUpdate(void);
 /**
 * Draw function for UI_FULLBOX_OVER (registered in UI_ELEMENTS).
 *
 * @return Any error that occurs.
 */
 errorret_t uiFullboxOverDraw(void);
@@ -8,38 +8,42 @@
 #include "uiloading.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "time/time.h"
 #include "display/text/text.h"
 #include "display/screen/screen.h"
-#include "display/spritebatch/spritebatch.h"
+#include "uifullbox.h"
 #include "ui/uifullbox.h"
 #define UI_LOADING_TEXT "loading"
 uiloading_t UI_LOADING;
-void uiLoadingInit(void) {
+errorret_t uiLoadingInit(void) {
  memoryZero(&UI_LOADING, sizeof(uiloading_t));
  uiLabelInit(&UI_LOADING.textLabel, &FONT_DEFAULT);
  uiLabelSetText(&UI_LOADING.textLabel, UI_LOADING_TEXT);
  eventInit(
    &UI_LOADING.onTransitionEnd,
    UI_LOADING.onTransitionEndCallbacks,
    UI_LOADING.onTransitionEndUsers,
    4
  );
  errorOk();
 }
-void uiLoadingUpdate(float_t delta) {
+errorret_t uiLoadingUpdate(void) {
-  if(UI_LOADING.duration <= 0 || UI_LOADING.time >= UI_LOADING.duration)
+  if(UI_LOADING.duration > 0.0f && UI_LOADING.time < UI_LOADING.duration) {
-    return;
+    UI_LOADING.time += TIME.delta;
  UI_LOADING.time += delta;
    if(UI_LOADING.time >= UI_LOADING.duration) {
      UI_LOADING.time = UI_LOADING.duration;
      eventInvoke(&UI_LOADING.onTransitionEnd, &UI_LOADING);
    }
  }
  errorOk();
 }
 errorret_t uiLoadingDraw(void) {
  float_t alpha;
-  if(UI_LOADING.duration <= 0 || UI_LOADING.time >= UI_LOADING.duration) {
+  if(UI_LOADING.duration <= 0.0f || UI_LOADING.time >= UI_LOADING.duration) {
    alpha = UI_LOADING.toAlpha;
  } else {
    float_t t = UI_LOADING.time / UI_LOADING.duration;
@@ -50,16 +54,19 @@ errorret_t uiLoadingDraw(void) {
  if(alpha <= 0.0f) errorOk();
  int32_t textW, textH;
-  textMeasure(UI_LOADING_TEXT, &FONT_DEFAULT, &textW, &textH);
+  uiLabelGetSize(&UI_LOADING.textLabel, &textW, &textH);
-  float_t x = (float_t)SCREEN.width - (float_t)textW - UI_LOADING_MARGIN;
+  float_t x = (float_t)(SCREEN.scanX + SCREEN.scanWidth) -
-  float_t y = (float_t)SCREEN.height - (float_t)textH - UI_LOADING_MARGIN;
+    (float_t)textW - UI_LOADING_MARGIN;
  float_t y = (float_t)(SCREEN.scanY + SCREEN.scanHeight) -
    (float_t)textH - UI_LOADING_MARGIN;
  color_t color = COLOR_WHITE;
  color.a = (uint8_t)(alpha * 255.0f);
  uiLabelSetColor(&UI_LOADING.textLabel, color);
-  errorChain(textDraw(x, y, UI_LOADING_TEXT, color, &FONT_DEFAULT));
+  errorChain(uiLabelDraw(&UI_LOADING.textLabel, x, y));
-  return spriteBatchFlush();
+  errorOk();
 }
 static void uiLoadingTransition(
@@ -71,7 +78,7 @@ static void uiLoadingTransition(
  UI_LOADING.fromAlpha = from;
  UI_LOADING.toAlpha = to;
  UI_LOADING.duration = UI_LOADING_FADE_DURATION;
-  UI_LOADING.time = 0;
+  UI_LOADING.time = 0.0f;
  eventInit(
    &UI_LOADING.onTransitionEnd,
    UI_LOADING.onTransitionEndCallbacks,
@@ -8,6 +8,7 @@
 #pragma once
 #include "error/error.h"
 #include "event/event.h"
 #include "ui/widget/uilabel.h"
 #define UI_LOADING_FADE_DURATION 0.5f
 #define UI_LOADING_MARGIN 8.0f
@@ -20,22 +21,25 @@ typedef struct {
  eventcallback_t onTransitionEndCallbacks[4];
  void *onTransitionEndUsers[4];
  event_t onTransitionEnd;
  uilabel_t textLabel;
 } uiloading_t;
 extern uiloading_t UI_LOADING;
 /**
 * Initializes the loading indicator.
 *
 * @return Any error that occurs.
 */
-void uiLoadingInit(void);
+errorret_t uiLoadingInit(void);
 /**
 * Advances the loading indicator fade transition. Fires onTransitionEnd once
 * when the transition completes.
 *
- * @param delta Seconds elapsed since last update.
+ * @return Any error that occurs.
 */
-void uiLoadingUpdate(float_t delta);
+errorret_t uiLoadingUpdate(void);
 /**
 * Draws the loading indicator. No-op when fully transparent.
@@ -0,0 +1,10 @@
 # Copyright (c) 2026 Dominic Masters
 #
 # This software is released under the MIT License.
 # https://opensource.org/licenses/MIT
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    uitransition.c
    uitransitionfade.c
 )
@@ -0,0 +1,81 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uitransition.h"
 #include "uitransitionfade.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "time/time.h"
 #include "util/math.h"
 uitransition_t UI_TRANSITION;
 uitransitiondrawfunc_t UI_TRANSITION_TYPE_DRAW[UI_TRANSITION_TYPE_COUNT] = {
  [UI_TRANSITION_TYPE_FADE] = uiTransitionFadeDraw
 };
 errorret_t uiTransitionInit(void) {
  memoryZero(&UI_TRANSITION, sizeof(uitransition_t));
  // uiTransitionStart((uitransitionstartparams_t){
  //   .duration = 5.0f,
  //   .type = UI_TRANSITION_TYPE_FADE,
  //   .params = {
  //     .fade = {
  //       .easing = EASING_OUT_QUART,
  //       .fromColor = COLOR_TRANSPARENT_BLACK,
  //       .toColor = COLOR_BLACK
  //     }
  //   },
  //   .finished = NULL,
  //   .user = NULL
  // });
  errorOk();
 }
 errorret_t uiTransitionUpdate(void) {
  // Update time.
  float_t newTime = UI_TRANSITION.data.time + TIME.delta;
  UI_TRANSITION.data.time = mathClamp(
    newTime,
    0.0f,
    UI_TRANSITION.data.duration
  );
  UI_TRANSITION.data.t = (
    (UI_TRANSITION.data.duration <= 0.0f) ?
    1.0f :
    (UI_TRANSITION.data.time / UI_TRANSITION.data.duration)
  );
  if(UI_TRANSITION.data.t >= 1.0f && UI_TRANSITION.finished) {
    UI_TRANSITION.finished(UI_TRANSITION.user);
  }
  errorOk();
 }
 errorret_t uiTransitionDraw(void) {
  uitransitiondrawfunc_t draw = UI_TRANSITION_TYPE_DRAW[UI_TRANSITION.type];
  if(!draw) errorOk();
  return draw(&UI_TRANSITION.data);
 }
 void uiTransitionStart(const uitransitionstartparams_t info) {
  assertTrue(info.type > UI_TRANSITION_TYPE_NULL, "Invalid type");
  assertTrue(info.type < UI_TRANSITION_TYPE_COUNT, "Invalid type");
  assertTrue(info.duration >= 0.0f, "Duration must be non-negative");
  memoryZero(&UI_TRANSITION, sizeof(uitransition_t));
  UI_TRANSITION.data.duration = info.duration;
  UI_TRANSITION.type = info.type;
  UI_TRANSITION.data.params = info.params;
  UI_TRANSITION.finished = info.finished;
  UI_TRANSITION.user = info.user;
 }
@@ -0,0 +1,74 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "display/color.h"
 #include "animation/easing.h"
 #include "uitransitiondata.h"
 typedef void (*uitransitioncallback_t)(void *user);
 typedef enum {
  UI_TRANSITION_TYPE_NULL,
  UI_TRANSITION_TYPE_FADE,
  UI_TRANSITION_TYPE_COUNT
 } uitransitiontype_t;
 extern uitransitiondrawfunc_t UI_TRANSITION_TYPE_DRAW[UI_TRANSITION_TYPE_COUNT];
 typedef struct {
  uitransitiondata_t data;
  uitransitiontype_t type;
  uitransitioncallback_t finished;
  void *user;
 } uitransition_t;
 extern uitransition_t UI_TRANSITION;
 /**
 * Initializes the transition overlay, zeroing all fields and wiring the
 * onTransitionEnd event.
 *
 * @return Any error that occurs.
 */
 errorret_t uiTransitionInit(void);
 /**
 * Advances the transition. Fires onTransitionEnd once when it completes.
 * Safe to call when no transition is running.
 *
 * @return Any error that occurs.
 */
 errorret_t uiTransitionUpdate(void);
 /**
 * Renders the transition overlay. Skipped entirely when the current alpha
 * is zero.
 *
 * @return Any error that occurs.
 */
 errorret_t uiTransitionDraw(void);
 typedef struct {
  float_t duration;
  uitransitiontype_t type;
  uitransitionparams_t params;
  uitransitioncallback_t finished;
  void *user;
 } uitransitionstartparams_t;
 /**
 * Starts a transition described by an info struct.
 *
 * @param info Transition parameters.
 */
 void uiTransitionStart(const uitransitionstartparams_t info);
@@ -0,0 +1,23 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "uitransitionfade.h"
 typedef union uitransitionparams_u {
  uitransitionfade_t fade;
 } uitransitionparams_t;
 typedef struct uitransitiondata_s {
  float_t time;
  float_t duration;
  float_t t;
  uitransitionparams_t params;
 } uitransitiondata_t;
 typedef errorret_t (*uitransitiondrawfunc_t)(const uitransitiondata_t *data);
@@ -0,0 +1,56 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uitransition.h"
 #include "assert/assert.h"
 #include "display/screen/screen.h"
 #include "display/texture/texture.h"
 #include "display/spritebatch/spritebatch.h"
 #include "display/shader/shaderunlit.h"
 errorret_t uiTransitionFadeDraw(const uitransitiondata_t *data) {
  assertNotNull(data, "data must not be NULL");
  float_t e = easingApply(data->params.fade.easing, data->t);
  float_t r = (float_t)(
    data->params.fade.toColor.r - data->params.fade.fromColor.r
  ) * e;
  float_t g = (float_t)(
    data->params.fade.toColor.g - data->params.fade.fromColor.g
  ) * e;
  float_t b = (float_t)(
    data->params.fade.toColor.b - data->params.fade.fromColor.b
  ) * e;
  float_t a = (float_t)(
    data->params.fade.toColor.a - data->params.fade.fromColor.a
  ) * e;
  color_t color = color4b(
    data->params.fade.fromColor.r + (uint8_t)r,
    data->params.fade.fromColor.g + (uint8_t)g,
    data->params.fade.fromColor.b + (uint8_t)b,
    data->params.fade.fromColor.a + (uint8_t)a
  );
  if(color.a == 0) errorOk();
  spritebatchsprite_t sprite = {
    .min = { 0.0f, 0.0f, 0.0f },
    .max = { (float_t)SCREEN.width, (float_t)SCREEN.height, 0.0f },
    .uvMin = { 0.0f, 0.0f },
    .uvMax = { 1.0f, 1.0f }
  };
  shadermaterial_t material = {
    .unlit = {
      .color = color,
      .texture = NULL
    }
  };
  errorChain(spriteBatchBuffer(&sprite, 1, &SHADER_UNLIT, material));
  errorOk();
 }
@@ -0,0 +1,29 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "display/color.h"
 #include "animation/easing.h"
 typedef struct uitransitiondata_s uitransitiondata_t;
 typedef struct {
  color_t fromColor;
  color_t toColor;
  easingtype_t easing;
 } uitransitionfade_t;
 /**
 * Renders a full-screen color overlay interpolated between fade->fromColor
 * and fade->toColor using fade->easing. t is the raw normalized progress
 * in [0, 1] before easing is applied. No-op when the resulting alpha is zero.
 *
 * @param fade The fade parameters.
 * @return Any error that occurs.
 */
 errorret_t uiTransitionFadeDraw(const uitransitiondata_t *fade);
@@ -0,0 +1,62 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "ui.h"
 #include "util/memory.h"
 #include "assert/assert.h"
 #include "display/spritebatch/spritebatch.h"
 #include "display/screen/screen.h"
 #include "ui/uielement.h"
 #include "ui/focus/uifocus.h"
 ui_t UI;
 errorret_t uiInit(void) {
  memoryZero(&UI, sizeof(ui_t));
  uiFocusInit();
  uiElementsSort();
  uielement_t *element = &UI_ELEMENTS[0];
  while(!uiElementIsNull(element)) {
    errorChain(uiElementInit(element));
    element++;
  }
  errorOk();
 }
 errorret_t uiUpdate(void) {
  uiFocusUpdate();
  uielement_t *element = &UI_ELEMENTS[0];
  while(!uiElementIsNull(element)) {
    errorChain(uiElementUpdate(element));
    element++;
  }
  errorOk();
 }
 errorret_t uiRender(void) {
  const uielement_t *element = &UI_ELEMENTS[0];
  while(!uiElementIsNull(element)) {
    errorChain(uiElementDraw(element));
    element++;
  }
  errorChain(spriteBatchFlush());
  errorOk();
 }
 errorret_t uiDispose(void) {
  uielement_t *element = &UI_ELEMENTS[0];
  while(!uiElementIsNull(element)) {
    errorChain(uiElementDispose(element));
    element++;
  }
  errorOk();
 }
@@ -0,0 +1,41 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 typedef struct {
  void *nothing;
 } ui_t;
 extern ui_t UI;
 /**
 * Initializes the UI system.
 */
 errorret_t uiInit(void);
 /**
 * Updates the UI system.
 *
 * @return Any error that occurs.
 */
 errorret_t uiUpdate(void);
 /**
 * Renders the UI system.
 * 
 * @return Any error that occurs.
 */
 errorret_t uiRender(void);
 /**
 * Disposes of the UI system.
 *
 * @return Any error that occurs.
 */
 errorret_t uiDispose(void);
@@ -0,0 +1,86 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uielement.h"
 #include "assert/assert.h"
 #include "util/sort.h"
 #include "ui/frame/uiframe.h"
 #include "ui/debug/uifps.h"
 #include "engine/engine.h"
 #include "ui/overlay/uifullbox.h"
 #include "ui/overlay/uiloading.h"
 #include "ui/overlay/uicrop.h"
 #include "ui/transition/uitransition.h"
 #include "ui/debug/uiconsole.h"
 #include "ui/frame/uiconfirm.h"
 // Priming pass: X does nothing here, so this only exists to process any
 // #include directives nested in uielementlist.h/ui/uielementgame.h at
 // file scope (each such header's own #pragma once makes it a no-op on
 // the real pass below, which happens inside UI_ELEMENTS[]'s braces,
 // where a raw #include of a declaration would be invalid).
 #define X(initFn, updateFn, drawFn, disposeFn, order) // do nothing
 #include "uielementlist.h"
 #undef X
 uielement_t UI_ELEMENTS[] = {
  #define X(initFn, updateFn, drawFn, disposeFn, elementOrder) \
    { \
      .init = initFn, .update = updateFn, .draw = drawFn, \
      .dispose = disposeFn, .order = elementOrder \
    },
  #include "uielementlist.h"
  #undef X
  { 0 } // Null terminator
 };
 bool_t uiElementIsNull(const uielement_t *element) {
  return element->init == NULL &&
    element->update == NULL &&
    element->draw == NULL &&
    element->dispose == NULL;
 }
 int_t uiElementCompareOrder(const void *a, const void *b) {
  const uielement_t *elementA = (const uielement_t *)a;
  const uielement_t *elementB = (const uielement_t *)b;
  if(elementA->order < elementB->order) return -1;
  if(elementA->order > elementB->order) return 1;
  return 0;
 }
 void uiElementsSort(void) {
  // The trailing null terminator is always the last static entry -- sort
  // everything before it, and leave it in place.
  const size_t count = (sizeof(UI_ELEMENTS) / sizeof(UI_ELEMENTS[0])) - 1;
  sortBubble(UI_ELEMENTS, count, sizeof(uielement_t), uiElementCompareOrder);
 }
 errorret_t uiElementInit(uielement_t *element) {
  assertNotNull(element, "element must not be NULL");
  if(element->init != NULL) errorChain(element->init());
  errorOk();
 }
 errorret_t uiElementUpdate(uielement_t *element) {
  assertNotNull(element, "element must not be NULL");
  if(element->update != NULL) errorChain(element->update());
  errorOk();
 }
 errorret_t uiElementDraw(const uielement_t *element) {
  assertNotNull(element, "element must not be NULL");
  if(element->draw != NULL) errorChain(element->draw());
  errorOk();
 }
 errorret_t uiElementDispose(uielement_t *element) {
  assertNotNull(element, "element must not be NULL");
  if(element->dispose != NULL) errorChain(element->dispose());
  errorOk();
 }
@@ -0,0 +1,84 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 // Built-in order tiers. Lower values update/render first; ties preserve
 // their relative UI_ELEMENTS declaration order (uiElementsSort uses a
 // stable sort). Game-specific elements can use any int32_t value -- these
 // are just the ones the engine itself relies on.
 #define UI_ELEMENT_ORDER_DEFAULT 0
 #define UI_ELEMENT_ORDER_DEBUG   1000
 typedef struct {
  errorret_t (*init)();
  errorret_t (*update)();
  errorret_t (*draw)();
  errorret_t (*dispose)();
  int32_t order;
 } uielement_t;
 extern uielement_t UI_ELEMENTS[];
 /**
 * Returns true when all four callbacks on the element are NULL,
 * which marks the end of the UI_ELEMENTS array.
 *
 * @param element The element to test.
 * @returns True if the element is the null terminator.
 */
 bool_t uiElementIsNull(const uielement_t *element);
 /**
 * Compares two elements by their .order field, ascending. Matches
 * sortcompare_t, for use with the project's sort utilities.
 *
 * @param a First uielement_t to compare.
 * @param b Second uielement_t to compare.
 * @return Negative if a < b, zero if a == b, positive if a > b.
 */
 int_t uiElementCompareOrder(const void *a, const void *b);
 /**
 * Stably sorts UI_ELEMENTS in place by .order, ascending. The trailing
 * null terminator is never moved. Called once by uiInit -- element order
 * is static after that, so there's no need to re-sort every frame.
 */
 void uiElementsSort(void);
 /**
 * Initializes a UI element, invoking its init callback if set.
 *
 * @param element The element to initialize.
 * @return Any error that occurs.
 */
 errorret_t uiElementInit(uielement_t *element);
 /**
 * Updates a UI element, calling its update callback if set.
 *
 * @param element The element to update.
 * @return Any error that occurs.
 */
 errorret_t uiElementUpdate(uielement_t *element);
 /**
 * Draws a UI element, calling its draw callback if set.
 *
 * @param element The element to render.
 * @return Any error that occurs.
 */
 errorret_t uiElementDraw(const uielement_t *element);
 /**
 * Disposes of a UI element, invoking its dispose callback if set.
 *
 * @param element The element to dispose.
 * @return Any error that occurs.
 */
 errorret_t uiElementDispose(uielement_t *element);
@@ -0,0 +1,47 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 // X(init, update, draw, dispose, order) -- pass NULL for any callback the
 // element doesn't need. order controls update/draw sequence (lower first,
 // see UI_ELEMENT_ORDER_* in uielement.h); ties preserve declaration order.
 // See uielement.c for how this expands.
 X(uiFrameInit, NULL, NULL, uiFrameDispose, UI_ELEMENT_ORDER_DEFAULT)
 // Fullbox under: above scene, below system UI.
 X(
  uiFullboxUnderInit, uiFullboxUnderUpdate, uiFullboxUnderDraw, NULL,
  UI_ELEMENT_ORDER_DEFAULT
 )
 // Text stuffs
 X(uiConfirmInit, NULL, uiConfirmDraw, uiConfirmDispose, UI_ELEMENT_ORDER_DEFAULT)
 X(
  uiTransitionInit, uiTransitionUpdate, uiTransitionDraw, NULL,
  UI_ELEMENT_ORDER_DEFAULT
 )
 // Fullbox over: above absolutely everything (except debug).
 X(
  uiFullboxOverInit, uiFullboxOverUpdate, uiFullboxOverDraw, NULL,
  UI_ELEMENT_ORDER_DEFAULT
 )
 X(
  uiLoadingInit, uiLoadingUpdate, uiLoadingDraw, NULL,
  UI_ELEMENT_ORDER_DEFAULT
 )
 X(uiCropInit, NULL, uiCropDraw, NULL, UI_ELEMENT_ORDER_DEFAULT)
 // Debug items -- always last.
 X(NULL, NULL, uiConsoleDraw, uiConsoleDispose, UI_ELEMENT_ORDER_DEBUG)
 X(uiFPSInit, NULL, uiFPSDraw, NULL, UI_ELEMENT_ORDER_DEBUG)
 // Game-specific UI elements (duskrpg)
 #include "ui/uielementgame.h"
@@ -0,0 +1,17 @@
 # Copyright (c) 2026 Dominic Masters
 #
 # This software is released under the MIT License.
 # https://opensource.org/licenses/MIT
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    uibutton.c
    uicheckbox.c
    uitab.c
    uislider.c
    uidropdown.c
    uiscrolling.c
    uimenu.c
    uilabel.c
    uiwidgetlabel.c
 )
@@ -0,0 +1,42 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uibutton.h"
 #include "assert/assert.h"
 #include "display/text/text.h"
 #include "display/color.h"
 void uiButtonInit(uibutton_t *button, const char_t *label) {
  assertNotNull(button, "Button cannot be NULL");
  assertNotNull(label, "Label cannot be NULL");
  uiWidgetLabelInit(&button->label, &FONT_DEFAULT);
  uiWidgetLabelSetText(&button->label, label);
  button->highlighted = false;
 }
 bool_t uiButtonIsHighlighted(const uibutton_t *button) {
  assertNotNull(button, "Button cannot be NULL");
  return button->highlighted;
 }
 void uiButtonSetHighlighted(uibutton_t *button, const bool_t highlighted) {
  assertNotNull(button, "Button cannot be NULL");
  button->highlighted = highlighted;
  uiWidgetLabelSetColor(
    &button->label, highlighted ? COLOR_RED : COLOR_WHITE
  );
 }
 errorret_t uiButtonDraw(
  const uibutton_t *button,
  const float_t x,
  const float_t y
 ) {
  assertNotNull(button, "Button cannot be NULL");
  errorChain(uiWidgetLabelDraw(&button->label, x, y));
  errorOk();
 }
@@ -0,0 +1,53 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "ui/widget/uiwidgetlabel.h"
 typedef struct {
  uiwidgetlabel_t label;
  bool_t highlighted;
 } uibutton_t;
 /**
 * Initializes a button.
 *
 * @param button The button to initialize.
 * @param label Display label.
 */
 void uiButtonInit(uibutton_t *button, const char_t *label);
 /**
 * Returns whether the button is highlighted.
 *
 * @param button The button to query.
 * @returns True if highlighted.
 */
 bool_t uiButtonIsHighlighted(const uibutton_t *button);
 /**
 * Sets the highlighted state of the button.
 *
 * @param button The button to update.
 * @param highlighted The new highlighted state.
 */
 void uiButtonSetHighlighted(uibutton_t *button, const bool_t highlighted);
 /**
 * Draws the button at the given screen position.
 *
 * @param button The button to draw.
 * @param x Screen x position.
 * @param y Screen y position.
 * @return Any error that occurs.
 */
 errorret_t uiButtonDraw(
  const uibutton_t *button,
  const float_t x,
  const float_t y
 );
@@ -0,0 +1,64 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uicheckbox.h"
 #include "util/memory.h"
 #include "util/string.h"
 #include "display/text/text.h"
 #include "display/color.h"
 void uiCheckboxInit(
  uicheckbox_t *checkbox,
  const char_t *label
 ) {
  memoryZero(checkbox, sizeof(uicheckbox_t));
  checkbox->rawLabel = label;
  uiWidgetLabelInit(&checkbox->label, &FONT_DEFAULT);
  uiCheckboxRebuildLabel(checkbox);
 }
 bool_t uiCheckboxIsChecked(const uicheckbox_t *checkbox) {
  return checkbox->checked;
 }
 void uiCheckboxSetChecked(uicheckbox_t *checkbox, const bool_t checked) {
  checkbox->checked = checked;
  uiCheckboxRebuildLabel(checkbox);
 }
 void uiCheckboxToggle(uicheckbox_t *checkbox) {
  uiCheckboxSetChecked(checkbox, !uiCheckboxIsChecked(checkbox));
 }
 bool_t uiCheckboxIsHighlighted(const uicheckbox_t *checkbox) {
  return checkbox->highlighted;
 }
 void uiCheckboxSetHighlighted(uicheckbox_t *checkbox, const bool_t highlighted) {
  checkbox->highlighted = highlighted;
  uiWidgetLabelSetColor(
    &checkbox->label, highlighted ? COLOR_RED : COLOR_WHITE
  );
 }
 errorret_t uiCheckboxDraw(
  const uicheckbox_t *checkbox,
  const float_t x,
  const float_t y
 ) {
  errorChain(uiWidgetLabelDraw(&checkbox->label, x, y));
  errorOk();
 }
 void uiCheckboxRebuildLabel(uicheckbox_t *checkbox) {
  char_t combined[UI_WIDGET_LABEL_TEXT_MAX];
  stringFormat(
    combined, UI_WIDGET_LABEL_TEXT_MAX - 1, "%s %s",
    checkbox->checked ? "Y" : "N", checkbox->rawLabel
  );
  uiWidgetLabelSetText(&checkbox->label, combined);
 }
@@ -0,0 +1,90 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "ui/widget/uiwidgetlabel.h"
 typedef struct uicheckbox_s {
  const char_t *rawLabel;
  uiwidgetlabel_t label;
  bool_t checked;
  bool_t highlighted;
 } uicheckbox_t;
 /**
 * Initializes a checkbox.
 *
 * @param checkbox The checkbox to initialize.
 * @param label Display label.
 */
 void uiCheckboxInit(
  uicheckbox_t *checkbox,
  const char_t *label
 );
 /**
 * Returns whether the checkbox is checked.
 *
 * @param checkbox The checkbox to query.
 * @returns True if checked.
 */
 bool_t uiCheckboxIsChecked(const uicheckbox_t *checkbox);
 /**
 * Sets the checked state of the checkbox.
 *
 * @param checkbox The checkbox to update.
 * @param checked The new checked state.
 */
 void uiCheckboxSetChecked(uicheckbox_t *checkbox, const bool_t checked);
 /**
 * Toggles the checked state of the checkbox.
 *
 * @param checkbox The checkbox to toggle.
 */
 void uiCheckboxToggle(uicheckbox_t *checkbox);
 /**
 * Returns whether the checkbox is highlighted.
 *
 * @param checkbox The checkbox to query.
 * @returns True if highlighted.
 */
 bool_t uiCheckboxIsHighlighted(const uicheckbox_t *checkbox);
 /**
 * Sets the highlighted state of the checkbox.
 *
 * @param checkbox The checkbox to update.
 * @param highlighted The new highlighted state.
 */
 void uiCheckboxSetHighlighted(uicheckbox_t *checkbox, const bool_t highlighted);
 /**
 * Draws the checkbox at the given screen position.
 *
 * @param checkbox The checkbox to draw.
 * @param x Screen x position.
 * @param y Screen y position.
 * @return Any error that occurs.
 */
 errorret_t uiCheckboxDraw(
  const uicheckbox_t *checkbox,
  const float_t x,
  const float_t y
 );
 /**
 * Rebuilds the checkbox's cached label ("Y "/"N " mark plus rawLabel)
 * from its current checked state. Called internally whenever checked
 * changes.
 *
 * @param checkbox The checkbox to update.
 */
 void uiCheckboxRebuildLabel(uicheckbox_t *checkbox);
@@ -0,0 +1,110 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uidropdown.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "util/string.h"
 #include "display/text/text.h"
 #include "display/color.h"
 void uiDropdownInit(
  uidropdown_t *dropdown,
  const char_t *label,
  const char_t *const *options,
  const uint8_t optionCount,
  const uint8_t selectedIndex
 ) {
  assertNotNull(dropdown, "Dropdown cannot be NULL");
  assertNotNull(label, "Label cannot be NULL");
  assertNotNull(options, "Options cannot be NULL");
  assertTrue(optionCount > 0, "Dropdown must have at least one option");
  memoryZero(dropdown, sizeof(uidropdown_t));
  uiWidgetLabelInit(&dropdown->label, &FONT_DEFAULT);
  uiWidgetLabelSetText(&dropdown->label, label);
  uiWidgetLabelInit(&dropdown->value, &FONT_DEFAULT);
  dropdown->options = options;
  dropdown->optionCount = optionCount;
  dropdown->selectedIndex = selectedIndex < optionCount ? selectedIndex : 0;
  uiDropdownRebuildValue(dropdown);
 }
 uint8_t uiDropdownGetSelectedIndex(const uidropdown_t *dropdown) {
  assertNotNull(dropdown, "Dropdown cannot be NULL");
  return dropdown->selectedIndex;
 }
 const char_t *uiDropdownGetSelectedOption(const uidropdown_t *dropdown) {
  assertNotNull(dropdown, "Dropdown cannot be NULL");
  return dropdown->options[dropdown->selectedIndex];
 }
 void uiDropdownSetSelectedIndex(uidropdown_t *dropdown, const uint8_t index) {
  assertNotNull(dropdown, "Dropdown cannot be NULL");
  assertTrue(index < dropdown->optionCount, "Dropdown index out of range");
  dropdown->selectedIndex = index;
  uiDropdownRebuildValue(dropdown);
 }
 void uiDropdownStepNext(uidropdown_t *dropdown) {
  assertNotNull(dropdown, "Dropdown cannot be NULL");
  dropdown->selectedIndex =
    (dropdown->selectedIndex + 1) % dropdown->optionCount;
  uiDropdownRebuildValue(dropdown);
 }
 void uiDropdownStepPrev(uidropdown_t *dropdown) {
  assertNotNull(dropdown, "Dropdown cannot be NULL");
  dropdown->selectedIndex = dropdown->selectedIndex == 0 ?
    dropdown->optionCount - 1 : dropdown->selectedIndex - 1;
  uiDropdownRebuildValue(dropdown);
 }
 bool_t uiDropdownIsHighlighted(const uidropdown_t *dropdown) {
  assertNotNull(dropdown, "Dropdown cannot be NULL");
  return dropdown->highlighted;
 }
 void uiDropdownSetHighlighted(
  uidropdown_t *dropdown,
  const bool_t highlighted
 ) {
  assertNotNull(dropdown, "Dropdown cannot be NULL");
  dropdown->highlighted = highlighted;
  color_t color = highlighted ? COLOR_RED : COLOR_WHITE;
  uiWidgetLabelSetColor(&dropdown->label, color);
  uiWidgetLabelSetColor(&dropdown->value, color);
 }
 errorret_t uiDropdownDraw(
  const uidropdown_t *dropdown,
  const float_t x,
  const float_t y
 ) {
  assertNotNull(dropdown, "Dropdown cannot be NULL");
  errorChain(uiWidgetLabelDraw(&dropdown->label, x, y));
  int32_t labelW, labelH;
  uiWidgetLabelGetSize(&dropdown->label, &labelW, &labelH);
  errorChain(uiWidgetLabelDraw(
    &dropdown->value, x + (float_t)labelW + UI_DROPDOWN_GAP, y
  ));
  errorOk();
 }
 void uiDropdownRebuildValue(uidropdown_t *dropdown) {
  char_t valueText[UI_WIDGET_LABEL_TEXT_MAX];
  stringFormat(
    valueText, UI_WIDGET_LABEL_TEXT_MAX - 1, "< %s >",
    uiDropdownGetSelectedOption(dropdown)
  );
  uiWidgetLabelSetText(&dropdown->value, valueText);
 }
@@ -0,0 +1,123 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "ui/widget/uiwidgetlabel.h"
 #define UI_DROPDOWN_GAP 4.0f
 typedef struct {
  uiwidgetlabel_t label;
  uiwidgetlabel_t value;
  const char_t *const *options;
  uint8_t optionCount;
  uint8_t selectedIndex;
  bool_t highlighted;
 } uidropdown_t;
 /**
 * Initializes a dropdown.
 *
 * @param dropdown The dropdown to initialize.
 * @param label Display label.
 * @param options Array of option display strings; caller-owned, must
 * outlive the dropdown.
 * @param optionCount Number of entries in options. Must be > 0.
 * @param selectedIndex Initial selected option index, clamped to
 * [0, optionCount - 1].
 */
 void uiDropdownInit(
  uidropdown_t *dropdown,
  const char_t *label,
  const char_t *const *options,
  const uint8_t optionCount,
  const uint8_t selectedIndex
 );
 /**
 * Returns the index of the currently selected option.
 *
 * @param dropdown The dropdown to query.
 * @returns The selected option index.
 */
 uint8_t uiDropdownGetSelectedIndex(const uidropdown_t *dropdown);
 /**
 * Returns the currently selected option's display string.
 *
 * @param dropdown The dropdown to query.
 * @returns The selected option string.
 */
 const char_t *uiDropdownGetSelectedOption(const uidropdown_t *dropdown);
 /**
 * Sets the selected option by index.
 *
 * @param dropdown The dropdown to update.
 * @param index The new selected option index. Must be < optionCount.
 */
 void uiDropdownSetSelectedIndex(uidropdown_t *dropdown, const uint8_t index);
 /**
 * Selects the next option, wrapping around to the first option past
 * the last.
 *
 * @param dropdown The dropdown to update.
 */
 void uiDropdownStepNext(uidropdown_t *dropdown);
 /**
 * Selects the previous option, wrapping around to the last option
 * before the first.
 *
 * @param dropdown The dropdown to update.
 */
 void uiDropdownStepPrev(uidropdown_t *dropdown);
 /**
 * Returns whether the dropdown is highlighted.
 *
 * @param dropdown The dropdown to query.
 * @returns True if highlighted.
 */
 bool_t uiDropdownIsHighlighted(const uidropdown_t *dropdown);
 /**
 * Sets the highlighted state of the dropdown.
 *
 * @param dropdown The dropdown to update.
 * @param highlighted The new highlighted state.
 */
 void uiDropdownSetHighlighted(
  uidropdown_t *dropdown,
  const bool_t highlighted
 );
 /**
 * Draws the dropdown at the given screen position: label, then the
 * currently selected option surrounded by cycle arrows.
 *
 * @param dropdown The dropdown to draw.
 * @param x Screen x position.
 * @param y Screen y position.
 * @return Any error that occurs.
 */
 errorret_t uiDropdownDraw(
  const uidropdown_t *dropdown,
  const float_t x,
  const float_t y
 );
 /**
 * Rebuilds the dropdown's cached value label ("< option >") from its
 * current selectedIndex. Called internally whenever selectedIndex
 * changes.
 *
 * @param dropdown The dropdown to update.
 */
 void uiDropdownRebuildValue(uidropdown_t *dropdown);
@@ -0,0 +1,70 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uilabel.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "util/string.h"
 #include "display/text/text.h"
 void uiLabelInit(uilabel_t *label, font_t *font) {
  assertNotNull(label, "Label cannot be NULL");
  assertNotNull(font, "Font cannot be NULL");
  memoryZero(label, sizeof(uilabel_t));
  label->font = font;
  label->color = COLOR_WHITE;
 }
 void uiLabelSetText(uilabel_t *label, const char_t *text) {
  assertNotNull(label, "Label cannot be NULL");
  assertNotNull(text, "Text cannot be NULL");
  assertStrLenMax(text, UI_LABEL_TEXT_MAX, "Label text too long");
  stringCopy(label->text, text, UI_LABEL_TEXT_MAX);
  label->spriteCount = textBuildSpriteCache(
    label->text, label->font, label->sprites, UI_LABEL_SPRITE_COUNT_MAX,
    &label->width, &label->height
  );
 }
 void uiLabelSetColor(uilabel_t *label, const color_t color) {
  assertNotNull(label, "Label cannot be NULL");
  label->color = color;
 }
 void uiLabelGetSize(
  const uilabel_t *label,
  int32_t *outWidth,
  int32_t *outHeight
 ) {
  assertNotNull(label, "Label cannot be NULL");
  assertNotNull(outWidth, "Output width cannot be NULL");
  assertNotNull(outHeight, "Output height cannot be NULL");
  *outWidth = label->width;
  *outHeight = label->height;
 }
 errorret_t uiLabelDraw(
  const uilabel_t *label,
  const float_t x,
  const float_t y
 ) {
  assertNotNull(label, "Label cannot be NULL");
  if(label->spriteCount == 0) errorOk();
  // Cached sprites are relative to (0,0); textDrawSpriteCache translates
  // into the requested screen position here instead of in
  // uiLabelSetText, so a label can be repositioned every frame without
  // rebuilding the (much more expensive) glyph/UV cache.
  spritebatchsprite_t scratch[UI_LABEL_SPRITE_COUNT_MAX];
  errorChain(textDrawSpriteCache(
    label->sprites, label->spriteCount, scratch, x, y, label->color,
    label->font->texture
  ));
  errorOk();
 }
@@ -0,0 +1,85 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "display/text/font.h"
 #include "display/spritebatch/spritebatchsprite.h"
 #include "display/color.h"
 #define UI_LABEL_TEXT_MAX 256
 #define UI_LABEL_SPRITE_COUNT_MAX UI_LABEL_TEXT_MAX
 typedef struct {
  char_t text[UI_LABEL_TEXT_MAX];
  color_t color;
  font_t *font;
  spritebatchsprite_t sprites[UI_LABEL_SPRITE_COUNT_MAX];
  uint32_t spriteCount;
  int32_t width;
  int32_t height;
 } uilabel_t;
 /**
 * Initializes a label, defaulting to white text and no text set.
 *
 * @param label The label to initialize.
 * @param font Font to use for rendering. Must outlive the label.
 */
 void uiLabelInit(uilabel_t *label, font_t *font);
 /**
 * Sets the label's text, rebuilding its cached sprites (glyph lookup, UV,
 * and layout) immediately. This is the only way the sprite cache gets
 * rebuilt -- uiLabelDraw never recomputes it, so call this whenever the
 * text changes rather than once up front and expecting it to stay in sync.
 *
 * @param label The label to update.
 * @param text Null-terminated string to display. Must be shorter than
 * UI_LABEL_TEXT_MAX.
 */
 void uiLabelSetText(uilabel_t *label, const char_t *text);
 /**
 * Sets the label's tint color. Cheap -- doesn't touch the sprite cache,
 * since color is applied via the draw material, not baked into sprites.
 *
 * @param label The label to update.
 * @param color The new tint color.
 */
 void uiLabelSetColor(uilabel_t *label, const color_t color);
 /**
 * Gets the measured size (in pixels) of the label's current text, cached
 * from the last uiLabelSetText call.
 *
 * @param label The label to query.
 * @param outWidth Pointer to store the width.
 * @param outHeight Pointer to store the height.
 */
 void uiLabelGetSize(
  const uilabel_t *label,
  int32_t *outWidth,
  int32_t *outHeight
 );
 /**
 * Draws the label's cached sprites at the given screen position in a
 * single batched buffer call. Does not recompute glyph layout -- call
 * uiLabelSetText first whenever the text changes.
 *
 * @param label The label to draw.
 * @param x Screen x position.
 * @param y Screen y position.
 * @return Any error that occurs.
 */
 errorret_t uiLabelDraw(
  const uilabel_t *label,
  const float_t x,
  const float_t y
 );
@@ -0,0 +1,293 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uimenu.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "display/text/text.h"
 #include "display/color.h"
 #include "ui/widget/uiwidgetlabel.h"
 #include "ui/widget/uibutton.h"
 #include "ui/widget/uitab.h"
 #include "ui/widget/uislider.h"
 #include "ui/widget/uidropdown.h"
 void uiMenuInit(
  uimenu_t *menu,
  uimenuselectedcallback_t selected,
  uimenuclosedcallback_t closed,
  uimenuchangedcallback_t changed
 ) {
  assertNotNull(menu, "Menu cannot be NULL");
  memoryZero(menu, sizeof(uimenu_t));
  menu->selected = selected;
  menu->closed = closed;
  menu->changed = changed;
 }
 void uiMenuSetItems(
  uimenu_t *menu,
  const uimenuitem_t *items,
  const uint8_t itemCount,
  const uint8_t columns
 ) {
  assertNotNull(menu, "Menu cannot be NULL");
  assertNotNull(items, "Items cannot be NULL");
  assertTrue(itemCount > 0, "Item count must be > 0");
  assertTrue(columns > 0, "Columns must be > 0");
  menu->items = (uimenuitem_t *)items;
  menu->itemCount = itemCount;
  menu->columns = columns;
 }
 void uiMenuSetPosition(uimenu_t *menu, const uint8_t x, const uint8_t y) {
  assertNotNull(menu, "Menu cannot be NULL");
  if(menu->focusItem == NULL) return;
  uiFocusSetPosition(menu->focusItem, x, y);
 }
 void uiMenuOpen(uimenu_t *menu) {
  assertNotNull(menu, "Menu cannot be NULL");
  assertNotNull(menu->items, "Menu items cannot be NULL");
  assertTrue(menu->itemCount > 0, "Menu item count must be > 0");
  assertTrue(menu->columns > 0, "Menu columns must be > 0");
  if(menu->focusItem != NULL) return;
  uint8_t focusable = uiMenuFocusableCount(menu);
  uint8_t rows = focusable > 0 ?
    (focusable + menu->columns - 1) / menu->columns : 1;
  menu->focusItem = uiFocusPush(
    menu->columns, rows,
    uiMenuFocusSelected,
    uiMenuFocusChanged,
    uiMenuFocusClosed,
    uiMenuFocusDirection,
    menu
  );
 }
 void uiMenuClose(uimenu_t *menu) {
  assertNotNull(menu, "Menu cannot be NULL");
  if(menu->focusItem == NULL) return;
  uiFocusPopItem(menu->focusItem);
  menu->focusItem = NULL;
 }
 bool_t uiMenuIsActive(const uimenu_t *menu) {
  assertNotNull(menu, "Menu cannot be NULL");
  return menu->focusItem != NULL;
 }
 errorret_t uiMenuDraw(
  const uimenu_t *menu,
  const float_t x,
  const float_t y,
  const float_t width,
  const float_t height
 ) {
  assertNotNull(menu, "Menu cannot be NULL");
  if(menu->itemCount == 0) errorOk();
  float_t colStep = width / (float_t)menu->columns;
  float_t rowHeight = (float_t)FONT_DEFAULT.tileset->tileHeight;
  uint8_t col = 0;
  uint8_t row = 0;
  for(uint8_t i = 0; i < menu->itemCount; i++) {
    const uimenuitem_t *item = &menu->items[i];
    if(item->type == UI_MENU_WIDGET_TYPE_LABEL) {
      if(col > 0) { row++; col = 0; }
      errorChain(uiWidgetLabelDraw(
        &item->label, x, y + (float_t)row * rowHeight
      ));
      row++;
      continue;
    }
    if(item->type == UI_MENU_WIDGET_TYPE_SPACER) {
      if(col > 0) { row++; col = 0; }
      row++;
      continue;
    }
    float_t ix = x + (float_t)col * colStep;
    float_t iy = y + (float_t)row * rowHeight;
    switch(item->type) {
      case UI_MENU_WIDGET_TYPE_CHECKBOX:
        errorChain(uiCheckboxDraw(&item->checkbox, ix, iy));
        break;
      case UI_MENU_WIDGET_TYPE_BUTTON:
        errorChain(uiButtonDraw(&item->button, ix, iy));
        break;
      case UI_MENU_WIDGET_TYPE_TAB:
        errorChain(uiTabDraw(&item->tab, ix, iy));
        break;
      case UI_MENU_WIDGET_TYPE_SLIDER:
        errorChain(uiSliderDraw(&item->slider, ix, iy));
        break;
      case UI_MENU_WIDGET_TYPE_DROPDOWN:
        errorChain(uiDropdownDraw(&item->dropdown, ix, iy));
        break;
      default:
        break;
    }
    col++;
    if(col >= menu->columns) { col = 0; row++; }
  }
  errorOk();
 }
 bool_t uiMenuFocusSelected(const uifocusitem_t *focusItem) {
  assertNotNull(focusItem, "Focus item cannot be NULL");
  assertNotNull(focusItem->user, "Focus item user cannot be NULL");
  uimenu_t *menu = (uimenu_t *)focusItem->user;
  if(menu->selected == NULL) return true;
  uint8_t slot = focusItem->y * menu->columns + focusItem->x;
  uint8_t index = uiMenuFocusSlotToIndex(menu, slot);
  if(index == 0xFF) return true;
  menu->selected(menu, index, &menu->items[index]);
  return true;
 }
 bool_t uiMenuFocusChanged(const uifocusitem_t *focusItem) {
  assertNotNull(focusItem, "Focus item cannot be NULL");
  assertNotNull(focusItem->user, "Focus item user cannot be NULL");
  uimenu_t *menu = (uimenu_t *)focusItem->user;
  uint8_t focusSlot = focusItem->y * menu->columns + focusItem->x;
  uint8_t slot = 0;
  for(uint8_t i = 0; i < menu->itemCount; i++) {
    uimenuitem_t *item = &menu->items[i];
    if(
      item->type == UI_MENU_WIDGET_TYPE_LABEL ||
      item->type == UI_MENU_WIDGET_TYPE_SPACER
    ) continue;
    uiMenuItemSetHighlighted(item, slot == focusSlot);
    slot++;
  }
  if(menu->changed == NULL) return true;
  uint8_t index = uiMenuFocusSlotToIndex(menu, focusSlot);
  if(index == 0xFF) return true;
  menu->changed(menu, index, &menu->items[index]);
  return true;
 }
 bool_t uiMenuFocusClosed(const uifocusitem_t *focusItem) {
  assertNotNull(focusItem, "Focus item cannot be NULL");
  assertNotNull(focusItem->user, "Focus item user cannot be NULL");
  uimenu_t *menu = (uimenu_t *)focusItem->user;
  menu->focusItem = NULL;
  for(uint8_t i = 0; i < menu->itemCount; i++) {
    uiMenuItemSetHighlighted(&menu->items[i], false);
  }
  if(menu->closed != NULL) menu->closed(menu);
  return true;
 }
 bool_t uiMenuFocusDirection(
  const uifocusitem_t *focusItem,
  const uifocusdirection_t direction
 ) {
  assertNotNull(focusItem, "Focus item cannot be NULL");
  assertNotNull(focusItem->user, "Focus item user cannot be NULL");
  if(direction != UI_FOCUS_DIRECTION_LEFT && direction != UI_FOCUS_DIRECTION_RIGHT) {
    return false;
  }
  uimenu_t *menu = (uimenu_t *)focusItem->user;
  uint8_t slot = focusItem->y * menu->columns + focusItem->x;
  uint8_t index = uiMenuFocusSlotToIndex(menu, slot);
  if(index == 0xFF) return false;
  uimenuitem_t *item = &menu->items[index];
  bool_t right = direction == UI_FOCUS_DIRECTION_RIGHT;
  if(item->type == UI_MENU_WIDGET_TYPE_SLIDER) {
    if(right) {
      uiSliderStepUp(&item->slider);
    } else {
      uiSliderStepDown(&item->slider);
    }
    return true;
  }
  if(item->type == UI_MENU_WIDGET_TYPE_CHECKBOX) {
    uiCheckboxToggle(&item->checkbox);
    return true;
  }
  if(item->type == UI_MENU_WIDGET_TYPE_DROPDOWN) {
    if(right) {
      uiDropdownStepNext(&item->dropdown);
    } else {
      uiDropdownStepPrev(&item->dropdown);
    }
    return true;
  }
  return false;
 }
 uint8_t uiMenuFocusableCount(const uimenu_t *menu) {
  assertNotNull(menu, "Menu cannot be NULL");
  uint8_t count = 0;
  for(uint8_t i = 0; i < menu->itemCount; i++) {
    uimenuwidgettype_t t = menu->items[i].type;
    if(t != UI_MENU_WIDGET_TYPE_LABEL && t != UI_MENU_WIDGET_TYPE_SPACER) count++;
  }
  return count;
 }
 uint8_t uiMenuFocusSlotToIndex(const uimenu_t *menu, const uint8_t slot) {
  assertNotNull(menu, "Menu cannot be NULL");
  uint8_t focusable = 0;
  for(uint8_t i = 0; i < menu->itemCount; i++) {
    uimenuwidgettype_t t = menu->items[i].type;
    if(t == UI_MENU_WIDGET_TYPE_LABEL || t == UI_MENU_WIDGET_TYPE_SPACER) continue;
    if(focusable == slot) return i;
    focusable++;
  }
  return 0xFF;
 }
 void uiMenuLabelInit(uimenuitem_t *item, const char_t *text) {
  assertNotNull(item, "Item cannot be NULL");
  assertNotNull(text, "Text cannot be NULL");
  uiWidgetLabelInit(&item->label, &FONT_DEFAULT);
  uiWidgetLabelSetText(&item->label, text);
 }
 void uiMenuItemSetHighlighted(uimenuitem_t *item, const bool_t highlighted) {
  if(item->type == UI_MENU_WIDGET_TYPE_CHECKBOX) {
    uiCheckboxSetHighlighted(&item->checkbox, highlighted);
  } else if(item->type == UI_MENU_WIDGET_TYPE_BUTTON) {
    uiButtonSetHighlighted(&item->button, highlighted);
  } else if(item->type == UI_MENU_WIDGET_TYPE_TAB) {
    uiTabSetActive(&item->tab, highlighted);
  } else if(item->type == UI_MENU_WIDGET_TYPE_SLIDER) {
    uiSliderSetHighlighted(&item->slider, highlighted);
  } else if(item->type == UI_MENU_WIDGET_TYPE_DROPDOWN) {
    uiDropdownSetHighlighted(&item->dropdown, highlighted);
  }
 }
@@ -0,0 +1,292 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "ui/focus/uifocus.h"
 #include "ui/widget/uiwidgetlabel.h"
 #include "ui/widget/uibutton.h"
 #include "ui/widget/uicheckbox.h"
 #include "ui/widget/uitab.h"
 #include "ui/widget/uislider.h"
 #include "ui/widget/uidropdown.h"
 typedef struct uimenu_s uimenu_t;
 typedef enum {
  UI_MENU_WIDGET_TYPE_NONE,
  UI_MENU_WIDGET_TYPE_LABEL,
  UI_MENU_WIDGET_TYPE_SPACER,
  UI_MENU_WIDGET_TYPE_CHECKBOX,
  UI_MENU_WIDGET_TYPE_BUTTON,
  UI_MENU_WIDGET_TYPE_TAB,
  UI_MENU_WIDGET_TYPE_SLIDER,
  UI_MENU_WIDGET_TYPE_DROPDOWN,
 } uimenuwidgettype_t;
 typedef struct {
  uimenuwidgettype_t type;
  union {
    uiwidgetlabel_t label;
    uicheckbox_t checkbox;
    uibutton_t button;
    uitab_t tab;
    uislider_t slider;
    uidropdown_t dropdown;
  };
 } uimenuitem_t;
 typedef void (*uimenuselectedcallback_t)(
  const uimenu_t *menu,
  const uint8_t index,
  const uimenuitem_t *item
 );
 typedef void (*uimenuchangedcallback_t)(
  const uimenu_t *menu,
  const uint8_t index,
  const uimenuitem_t *item
 );
 typedef void (*uimenuclosedcallback_t)(const uimenu_t *menu);
 typedef struct uimenu_s {
  uimenuitem_t *items;
  uint8_t itemCount;
  uint8_t columns;
  uifocusitem_t *focusItem;
  uimenuselectedcallback_t selected;
  uimenuclosedcallback_t closed;
  uimenuchangedcallback_t changed;
  void *user;
 } uimenu_t;
 /**
 * Initializes a menu, clearing all items and focus state.
 *
 * @param menu The menu to initialize.
 * @param items The list of items to display in the menu.
 * @param itemCount The number of items in the list.
 * @param columns The number of columns to display the items in.
 * @param selected The callback to invoke when an item is selected.
 * @param closed The callback to invoke when the menu is closed.
 * @param changed The callback to invoke when the menu changes.
 */
 void uiMenuInit(
  uimenu_t *menu,
  uimenuselectedcallback_t selected,
  uimenuclosedcallback_t closed,
  uimenuchangedcallback_t changed
 );
 /**
 * Sets the items to display in the menu.
 *
 * @param menu The menu to update.
 * @param items The list of items to display in the menu.
 * @param itemCount The number of items in the list.
 * @param columns The number of columns to display the items in.
 */
 void uiMenuSetItems(
  uimenu_t *menu,
  const uimenuitem_t *items,
  const uint8_t itemCount,
  const uint8_t columns
 );
 /**
 * Sets the position of the menu on the screen.
 *
 * @param menu The menu to position.
 * @param x The x-coordinate to position the menu at.
 * @param y The y-coordinate to position the menu at.
 */
 void uiMenuSetPosition(uimenu_t *menu, const uint8_t x, const uint8_t y);
 /**
 * Pushes a menu onto the UI focus stack, making it the active menu.
 *
 * @param menu The menu to push.
 */
 void uiMenuOpen(uimenu_t *menu);
 /**
 * Pops a menu from the UI focus stack, removing it from the active menu.
 * 
 * @param menu The menu to pop.
 */
 void uiMenuClose(uimenu_t *menu);
 /**
 * Returns whether the menu is currently active (on the UI focus stack).
 *
 * @param menu The menu to query.
 * @returns True if the menu is active.
 */
 bool_t uiMenuIsActive(const uimenu_t *menu);
 /**
 * Draws the menu at the specified position and size.
 *
 * @param menu The menu to draw.
 * @param x The x-coordinate to draw the menu at.
 * @param y The y-coordinate to draw the menu at.
 * @param width The width of the menu.
 * @param height The height of the menu.
 * @returns An error code indicating success or failure.
 */
 errorret_t uiMenuDraw(
  const uimenu_t *menu,
  const float_t x,
  const float_t y,
  const float_t width,
  const float_t height
 );
 /**
 * Returns the number of focusable (non-label) items in the menu.
 *
 * @param menu The menu to query.
 * @returns Count of non-label items.
 */
 uint8_t uiMenuFocusableCount(const uimenu_t *menu);
 /**
 * Maps a flat focus slot index to the corresponding item array index,
 * skipping over label items which are not focusable.
 *
 * @param menu The menu to query.
 * @param slot The focus slot index (y * columns + x).
 * @returns The item array index, or 0xFF if out of range.
 */
 uint8_t uiMenuFocusSlotToIndex(const uimenu_t *menu, const uint8_t slot);
 /**
 * Sets the highlighted/active state on a menu item, dispatching to the
 * matching widget's setter based on its type. No-op for label/spacer
 * items and any other type with no highlight concept.
 *
 * @param item The item to update.
 * @param highlighted The new highlighted/active state.
 */
 void uiMenuItemSetHighlighted(uimenuitem_t *item, const bool_t highlighted);
 /**
 * Initializes a menu item as a standalone label, caching its text.
 * Used internally by the MENU_LABEL helper macro.
 *
 * @param item The item to initialize.
 * @param text Display text.
 */
 void uiMenuLabelInit(uimenuitem_t *item, const char_t *text);
 /**
 * Internal focus callback  -  forwards selection to the menu's selected handler.
 *
 * @param focusItem The active focus item; user field must point to uimenu_t.
 * @returns True.
 */
 bool_t uiMenuFocusSelected(const uifocusitem_t *focusItem);
 /**
 * Internal focus callback  -  updates widget highlights and fires changed.
 *
 * @param focusItem The active focus item; user field must point to uimenu_t.
 * @returns True.
 */
 bool_t uiMenuFocusChanged(const uifocusitem_t *focusItem);
 /**
 * Internal focus callback  -  clears focusItem and fires the closed handler.
 *
 * @param focusItem The active focus item; user field must point to uimenu_t.
 * @returns True.
 */
 bool_t uiMenuFocusClosed(const uifocusitem_t *focusItem);
 /**
 * Internal focus callback  -  gives the focused item's widget a chance to
 * handle LEFT/RIGHT itself (e.g. a slider adjusting its value) before
 * falling back to the default cell-to-cell movement.
 *
 * @param focusItem The active focus item; user field must point to uimenu_t.
 * @param direction The direction that was pressed or held.
 * @returns True if the focused widget handled the direction.
 */
 bool_t uiMenuFocusDirection(
  const uifocusitem_t *focusItem,
  const uifocusdirection_t direction
 );
 // Helper macros
 #define MENU_BEGIN(menuPtr, itemsArray, selected, closed, changed) \
  uimenu_t *menu = (menuPtr); \
  uiMenuInit(menu, selected, closed, changed); \
  menu->items = (itemsArray); \
  uint8_t menuIndex = 0; \
  uint8_t menuCapacity = sizeof(itemsArray) / sizeof((itemsArray)[0])
 #define MENU_LABEL(text) \
  assertTrue(menuIndex < menuCapacity, "Menu item count exceeds capacity"); \
  menu->items[menuIndex].type = UI_MENU_WIDGET_TYPE_LABEL; \
  uiMenuLabelInit(&menu->items[menuIndex], text); \
  ++menuIndex
 #define MENU_SPACER() \
  assertTrue(menuIndex < menuCapacity, "Menu item count exceeds capacity"); \
  menu->items[menuIndex].type = UI_MENU_WIDGET_TYPE_SPACER; \
  ++menuIndex
 #define MENU_CHECKBOX(label) \
  assertTrue(menuIndex < menuCapacity, "Menu item count exceeds capacity"); \
  menu->items[menuIndex].type = UI_MENU_WIDGET_TYPE_CHECKBOX; \
  uiCheckboxInit(&menu->items[menuIndex].checkbox, label); \
  ++menuIndex
 #define MENU_BUTTON(label) \
  assertTrue(menuIndex < menuCapacity, "Menu item count exceeds capacity"); \
  menu->items[menuIndex].type = UI_MENU_WIDGET_TYPE_BUTTON; \
  uiButtonInit(&menu->items[menuIndex].button, label); \
  ++menuIndex
 #define MENU_TAB(label) \
  assertTrue(menuIndex < menuCapacity, "Menu item count exceeds capacity"); \
  menu->items[menuIndex].type = UI_MENU_WIDGET_TYPE_TAB; \
  uiTabInit(&menu->items[menuIndex].tab, label); \
  ++menuIndex
 #define MENU_SLIDER_FLOAT(label, value, min, max, step) \
  assertTrue(menuIndex < menuCapacity, "Menu item count exceeds capacity"); \
  menu->items[menuIndex].type = UI_MENU_WIDGET_TYPE_SLIDER; \
  uiSliderInitFloat( \
    &menu->items[menuIndex].slider, label, value, min, max, step \
  ); \
  ++menuIndex
 #define MENU_SLIDER_INT(label, value, min, max, step) \
  assertTrue(menuIndex < menuCapacity, "Menu item count exceeds capacity"); \
  menu->items[menuIndex].type = UI_MENU_WIDGET_TYPE_SLIDER; \
  uiSliderInitInt( \
    &menu->items[menuIndex].slider, label, value, min, max, step \
  ); \
  ++menuIndex
 #define MENU_DROPDOWN(label, options, optionCount, selectedIndex) \
  assertTrue(menuIndex < menuCapacity, "Menu item count exceeds capacity"); \
  menu->items[menuIndex].type = UI_MENU_WIDGET_TYPE_DROPDOWN; \
  uiDropdownInit( \
    &menu->items[menuIndex].dropdown, label, options, optionCount, \
    selectedIndex \
  ); \
  ++menuIndex
 #define MENU_END(itemsArray, columns) \
  uiMenuSetItems(menu, (itemsArray), menuIndex, (columns))
 //EOF
--- a/Show More
+++ b/Show More