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>

.claude/animation.md

@@ -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.

.claude/architecture.md

@@ -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.

.claude/asset.md

@@ -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.

.claude/display-refactor-progress.md

@@ -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.

.claude/display.md

@@ -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.

.claude/input.md

@@ -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/`.

.claude/rpg/cutscene.md

@@ -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.

.claude/rpg/entity.md

@@ -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.

.claude/rpg/index.md

@@ -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`.

.claude/rpg/story.md

@@ -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.

.claude/rpg/world.md

@@ -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.

.claude/save.md

@@ -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.

.claude/style.md

@@ -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.

.claude/systems.md

@@ -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.

.claude/ui.md

@@ -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.

.claude/util.md

@@ -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`.

.github/actions/setup-devkitpro/action.yml

@@ -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

.github/actions/setup-pspdev/action.yml

@@ -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

.github/workflows/build.yml

@@ -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
-      - name: Set up Docker
-        uses: docker/setup-docker-action@v5
+        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: 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
-      - name: Set up Docker
-        uses: docker/setup-docker-action@v5
-      - name: Build psp
-        run: ./scripts/build-psp-docker.sh
+        uses: actions/checkout@v4
+      - name: Setup pspdev
+        uses: ./.github/actions/setup-pspdev
+      - name: Build PSP
+        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
-        uses: actions/upload-artifact@v6
+      - name: Upload PSP binary
+        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
-      - name: Set up Docker
-        uses: docker/setup-docker-action@v5
-      - name: Build knulli
-        run: ./scripts/build-knulli-docker.sh
+        uses: actions/checkout@v4
+      - name: Install dependencies
+        run: |
+          dpkg --add-architecture arm64
+          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
-        uses: actions/upload-artifact@v6
+      - name: Upload Knulli binary
+        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
-      - name: Set up Docker
-        uses: docker/setup-docker-action@v5
+        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
+          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
-      - name: Copy output files.
+        run: ./scripts/build-gamecube.sh
+      - 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
-      - name: Set up Docker
-        uses: docker/setup-docker-action@v5
+        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
+          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
-      - name: Copy output files.
+        run: ./scripts/build-gamecube-iso.sh
+      - 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
-      - name: Set up Docker
-        uses: docker/setup-docker-action@v5
+        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
+          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
-      - name: Copy output files.
+        run: ./scripts/build-wii.sh
+      - 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,22 +215,33 @@ 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
-      - name: Set up Docker
-        uses: docker/setup-docker-action@v5
+        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
+          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
-      - name: Copy output files.
+        run: ./scripts/build-wii-iso.sh
+      - 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
-          if-no-files-found: error
+          if-no-files-found: error

.github/workflows/test.yml

@@ -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

CLAUDE.md

@@ -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) |

CMakeLists.txt

@@ -13,11 +13,11 @@ 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_SHORT_DESCRIPTION "Dusk game"           CACHE STRING "One-line description")
+set(DUSK_GAME_NAME "Dusk" CACHE STRING "Game display name")
+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")
 
 # Prep cache
@@ -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}"

archive/asset/args.py

@@ -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()

archive/asset/bundle/__main__.py

@@ -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()

archive/asset/cache.py

@@ -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

archive/asset/path.py

@@ -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('\\', '/')

archive/asset/process/asset.py

@@ -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)

archive/asset/process/image.py

@@ -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)

archive/asset/process/language.py

@@ -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)

archive/asset/process/map.py

@@ -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)

archive/asset/process/palette.py

@@ -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)

archive/asset/process/script.py

@@ -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)

archive/asset/process/tileset.py

@@ -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)

archive/assetpalette.c

@@ -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();
-}

archive/assetpalette.h

@@ -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);

archive/camera/camera.c

@@ -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");
-  }
-}

archive/camera/camera.h

@@ -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);

archive/dusk/chunk.py

@@ -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

archive/dusk/defs.py

@@ -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))

archive/dusk/entity.py

@@ -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()

archive/dusk/event.py

@@ -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)

archive/dusk/map.py

@@ -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)

archive/dusk/region.py

@@ -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()

archive/dusk/tile.py

@@ -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
-      ])

archive/dusk/ui/CMakeLists.txt

@@ -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
+)

archive/dusk/ui/debug/CMakeLists.txt

@@ -5,5 +5,6 @@
 
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
   PUBLIC
-    scenerainbownothing.c
+    uiconsole.c
+    uifps.c
 )

archive/dusk/ui/debug/uiconsole.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();
+}

archive/dusk/ui/debug/uiconsole.h

@@ -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);

archive/dusk/ui/debug/uifps.c

@@ -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();
+}

archive/dusk/ui/debug/uifps.h

@@ -8,18 +8,27 @@
 #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).
- * 
+ *
  * @return Any error that occurs.
  */
 errorret_t uiFPSDraw();

archive/dusk/ui/focus/CMakeLists.txt

@@ -5,5 +5,5 @@
 
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
   PUBLIC
-    renderpsp.c
+    uifocus.c
 )

archive/dusk/ui/focus/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);
+}

archive/dusk/ui/focus/uifocus.h

@@ -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);

archive/dusk/ui/focus/uifocusitem.h

@@ -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;
+};

archive/dusk/ui/frame/CMakeLists.txt

@@ -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)

archive/dusk/ui/frame/settings/CMakeLists.txt

@@ -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
+)

archive/dusk/ui/frame/settings/uisettings.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();
+}

archive/dusk/ui/frame/settings/uisettings.h

@@ -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);

archive/dusk/ui/frame/settings/uisettingsaudio.c

@@ -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;
+}

archive/dusk/ui/frame/settings/uisettingsaudio.h

@@ -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);

archive/dusk/ui/frame/settings/uisettingsdata.h

@@ -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;

archive/dusk/ui/frame/settings/uisettingsdisplay.c

@@ -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;
+}

archive/dusk/ui/frame/settings/uisettingsdisplay.h

@@ -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);

archive/dusk/ui/frame/settings/uisettingsgeneral.c

@@ -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;
+}

archive/dusk/ui/frame/settings/uisettingsgeneral.h

@@ -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);

archive/dusk/ui/frame/settings/uisettingsinput.c

@@ -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;
+}

archive/dusk/ui/frame/settings/uisettingsinput.h

@@ -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);

archive/dusk/ui/frame/uiconfirm.c

@@ -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();
+}

archive/dusk/ui/frame/uiconfirm.h

@@ -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);

archive/dusk/ui/frame/uiframe.c

@@ -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);
+}

archive/dusk/ui/frame/uiframe.h

@@ -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);

archive/dusk/ui/overlay/CMakeLists.txt

@@ -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
+)

archive/dusk/ui/overlay/uicrop.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();
+}

archive/dusk/ui/overlay/uicrop.h

@@ -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);

archive/dusk/ui/overlay/uifullbox.c

@@ -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(
-    fullbox->easing,
-    fixedFromFloat(fullbox->time / fullbox->duration)
-  );
+  float_t t = easingApply(fullbox->easing, fullbox->time / fullbox->duration);
   return color4b(
-    fixedToU8(fixedLerp(
-      fixedFromU8(fullbox->fromColor.r),
-      fixedFromU8(fullbox->toColor.r), t
-    )),
-    fixedToU8(fixedLerp(
-      fixedFromU8(fullbox->fromColor.g),
-      fixedFromU8(fullbox->toColor.g), t
-    )),
-    fixedToU8(fixedLerp(
-      fixedFromU8(fullbox->fromColor.b),
-      fixedFromU8(fullbox->toColor.b), t
-    )),
-    fixedToU8(fixedLerp(
-      fixedFromU8(fullbox->fromColor.a),
-      fixedFromU8(fullbox->toColor.a), t
-    ))
+    (uint8_t)((float_t)fullbox->fromColor.r +
+      ((float_t)fullbox->toColor.r - (float_t)fullbox->fromColor.r) * t),
+    (uint8_t)((float_t)fullbox->fromColor.g +
+      ((float_t)fullbox->toColor.g - (float_t)fullbox->fromColor.g) * t),
+    (uint8_t)((float_t)fullbox->fromColor.b +
+      ((float_t)fullbox->toColor.b - (float_t)fullbox->fromColor.b) * t),
+    (uint8_t)((float_t)fullbox->fromColor.a +
+      ((float_t)fullbox->toColor.a - (float_t)fullbox->fromColor.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);
 }

archive/dusk/ui/overlay/uifullbox.h

@@ -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);

archive/dusk/ui/overlay/uiloading.c

@@ -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 "ui/uifullbox.h"
+#include "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) {
-  if(UI_LOADING.duration <= 0 || UI_LOADING.time >= UI_LOADING.duration)
-    return;
-  UI_LOADING.time += delta;
-  if(UI_LOADING.time >= UI_LOADING.duration) {
-    UI_LOADING.time = UI_LOADING.duration;
-    eventInvoke(&UI_LOADING.onTransitionEnd, &UI_LOADING);
+errorret_t uiLoadingUpdate(void) {
+  if(UI_LOADING.duration > 0.0f && UI_LOADING.time < UI_LOADING.duration) {
+    UI_LOADING.time += 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 y = (float_t)SCREEN.height - (float_t)textH - UI_LOADING_MARGIN;
+  float_t x = (float_t)(SCREEN.scanX + SCREEN.scanWidth) -
+    (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));
-  return spriteBatchFlush();
+  errorChain(uiLabelDraw(&UI_LOADING.textLabel, x, y));
+  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,

archive/dusk/ui/overlay/uiloading.h

@@ -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.

archive/dusk/ui/transition/CMakeLists.txt

@@ -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
+)

archive/dusk/ui/transition/uitransition.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;
+}

archive/dusk/ui/transition/uitransition.h

@@ -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);
+

archive/dusk/ui/transition/uitransitiondata.h

@@ -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);

archive/dusk/ui/transition/uitransitionfade.c

@@ -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();
+}

archive/dusk/ui/transition/uitransitionfade.h

@@ -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);

archive/dusk/ui/ui.c

@@ -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();
+}

archive/dusk/ui/ui.h

@@ -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);

archive/dusk/ui/uielement.c

@@ -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();
+}

archive/dusk/ui/uielement.h

@@ -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);

archive/dusk/ui/uielementlist.h

@@ -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"

archive/dusk/ui/widget/CMakeLists.txt

@@ -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
+)

archive/dusk/ui/widget/uibutton.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();
+}

archive/dusk/ui/widget/uibutton.h

@@ -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
+);

archive/dusk/ui/widget/uicheckbox.c

@@ -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);
+}

archive/dusk/ui/widget/uicheckbox.h

@@ -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);

archive/dusk/ui/widget/uidropdown.c

@@ -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);
+}

archive/dusk/ui/widget/uidropdown.h

@@ -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);

archive/dusk/ui/widget/uilabel.c

@@ -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();
+}

archive/dusk/ui/widget/uilabel.h

@@ -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
+);

archive/dusk/ui/widget/uimenu.c

@@ -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);
+  }
+}

archive/dusk/ui/widget/uimenu.h

@@ -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