Final docs

This reverts commit efd31237be.

.claude/animation.md

@@ -0,0 +1,88 @@
+# Animation System
+
+Source: `src/dusk/animation/`
+
+## Overview
+
+The animation system provides time-based keyframe interpolation with
+pluggable easing functions. It is intentionally minimal -- no skeleton,
+no blending, no state machine. Animations produce a single `float_t`
+value at a given time, which callers apply to whatever property they
+are animating.
+
+## Keyframes (`keyframe.h`)
+
+```c
+typedef struct {
+  float_t time;    // time in seconds this keyframe is at
+  float_t value;   // the value at this keyframe
+  easingtype_t easing; // easing applied between this frame and the next
+} keyframe_t;
+```
+
+## Animation (`animation.h`)
+
+```c
+typedef struct {
+  keyframe_t *keyframes;  // caller-owned array
+  uint16_t keyframeCount;
+} animation_t;
+
+void animationInit(
+  animation_t *anim,
+  keyframe_t *keyframes,
+  uint16_t keyframeCount
+);
+
+float_t animationGetValue(animation_t *anim, float_t time);
+// Returns the interpolated value at the given time.
+// Before the first keyframe: returns the first keyframe's value.
+// After the last keyframe: returns the last keyframe's value.
+```
+
+## Easing functions (`easing.h`)
+
+```c
+typedef float_t (*easingfn_t)(float_t t);  // t in [0, 1], out in [0, 1]
+
+extern const easingfn_t EASING_FUNCTIONS[EASING_COUNT];
+
+float_t easingApply(easingtype_t type, float_t t);
+```
+
+Available easing types:
+
+```
+EASING_LINEAR
+EASING_IN_SINE   EASING_OUT_SINE   EASING_IN_OUT_SINE
+EASING_IN_QUAD   EASING_OUT_QUAD   EASING_IN_OUT_QUAD
+EASING_IN_CUBIC  EASING_OUT_CUBIC  EASING_IN_OUT_CUBIC
+EASING_IN_QUART  EASING_OUT_QUART  EASING_IN_OUT_QUART
+EASING_IN_BACK   EASING_OUT_BACK   EASING_IN_OUT_BACK
+```
+
+## Usage pattern
+
+```c
+// Declare keyframes statically (no allocation):
+static keyframe_t kfs[] = {
+  { .time = 0.0f, .value = 0.0f, .easing = EASING_OUT_CUBIC },
+  { .time = 1.0f, .value = 1.0f, .easing = EASING_LINEAR },
+};
+
+animation_t anim;
+animationInit(&anim, kfs, 2);
+
+// In update loop:
+float_t alpha = animationGetValue(&anim, TIME.time);
+// Apply alpha to whatever is being animated.
+```
+
+## Design notes
+
+- Keyframe arrays are caller-owned and not copied. Use static or
+  long-lived arrays; do not allocate per-frame.
+- The system has no notion of looping -- wrap `time` with `fmodf` if
+  you need a repeating animation.
+- For multi-property animations, use multiple `animation_t` instances
+  sharing the same time source.

.claude/assets.md

@@ -0,0 +1,125 @@
+# Asset System
+
+Source: `src/dusk/asset/`
+
+## Overview
+
+All game assets are packed into a single ZIP archive named `dusk.dsk`
+(`ASSET_FILE_NAME`). The asset system loads entries from this archive
+asynchronously on a background thread, caches them, and provides
+synchronous blocking access when an asset is required immediately.
+
+## Key limits
+
+| Constant | Value | Meaning |
+|----------|-------|---------|
+| `ASSET_LOADING_COUNT_MAX` | 4 | Concurrent in-flight loads |
+| `ASSET_ENTRY_COUNT_MAX` | 128 | Cached entries |
+
+## Top-level API (`asset.h`)
+
+```c
+errorret_t assetInit();    // Open dusk.dsk, start background thread
+void assetUpdate();        // Dispatch completed-load callbacks (main thread)
+errorret_t assetDispose(); // Wait for loads, close archive
+
+assetentry_t *assetGetEntry(
+  const char_t *path,
+  assetloadertype_t type,
+  assetloaderinput_t *input
+);  // Get (or create) a cache entry; does NOT start loading
+
+errorret_t assetRequireLoaded(assetentry_t *entry);
+// Block the calling thread until this entry is fully loaded.
+// Only safe to call from the main thread.
+
+void assetLock(assetentry_t *entry);
+void assetUnlock(assetentry_t *entry);
+// Reference counting. Lock before using loaded data; unlock when done.
+// The entry will not be evicted while locked.
+```
+
+## Asset entry states
+
+Each cache entry goes through a state machine:
+
+```
+IDLE -> QUEUED -> READING (async) -> PROCESSING (sync, main thread) -> LOADED
+                                                                     -> ERROR
+```
+
+- **READING** runs on the background loader thread (file I/O).
+- **PROCESSING** runs on the main thread (GPU uploads, parsing finalization).
+- Once LOADED, data is available in `entry->data`.
+
+## Loader types
+
+Loader types are registered in the `ASSET_LOADER_CALLBACKS[]` table.
+Each type implements three callbacks: `loadSync`, `loadAsync`, `dispose`.
+
+| `assetloadertype_t` | Data read | Description |
+|---------------------|-----------|-------------|
+| `ASSET_LOADER_TYPE_TEXTURE` | STB image | Loads image bytes async, creates GPU texture sync |
+| `ASSET_LOADER_TYPE_TILESET` | `.dtf` binary | Custom tile format (magic, version, grid, UVs) |
+| `ASSET_LOADER_TYPE_MESH` | `.stl` | STL mesh with configurable axis orientation |
+| `ASSET_LOADER_TYPE_JSON` | yyjson | Up to 256 KB; parsed async |
+| `ASSET_LOADER_TYPE_LOCALE` | Gettext `.po` | PO parser with plural-form expression evaluation |
+| `ASSET_LOADER_TYPE_SCRIPT` | JS source | JerryScript module |
+
+## Adding a new loader type
+
+1. Add an enum value before `_COUNT` in `assetloadertype_t`
+   (`src/dusk/asset/loader/assetloader.h`).
+2. Add fields to the input/loading/output unions in `assetloader.h`.
+3. Implement `assetXxxLoaderSync`, `assetXxxLoaderAsync`, and
+   `assetXxxDispose` in `src/dusk/asset/loader/xxx/`.
+4. Register the three callbacks in `ASSET_LOADER_CALLBACKS[]` in
+   `src/dusk/asset/loader/assetloader.c`.
+5. If user-facing, create a JS module and a `.d.ts` file (see `CLAUDE.md`).
+
+## Asset batch (`assetbatch.h`)
+
+`assetbatch_t` groups multiple asset requests into a single logical
+load. All entries in the batch start loading concurrently. The batch
+fires a completion callback once every entry has reached LOADED (or
+ERROR).
+
+```c
+assetbatch_t batch;
+assetBatchInit(&batch, entries, count, onComplete, user);
+assetBatchStart(&batch);
+// ... later, after assetUpdate() fires the callback ...
+assetBatchDispose(&batch);
+```
+
+## Usage pattern
+
+```c
+// 1. Get or create the cache entry (no I/O yet).
+assetentry_t *tex = assetGetEntry(
+  "textures/hero.png",
+  ASSET_LOADER_TYPE_TEXTURE,
+  NULL
+);
+assetLock(tex);
+
+// 2. Option A -- non-blocking: check tex->state each frame.
+// Option B -- blocking (main thread only):
+errorChain(assetRequireLoaded(tex));
+
+// 3. Use the loaded data.
+texture_t *t = &tex->data.texture;
+
+// 4. Release when done.
+assetUnlock(tex);
+```
+
+## Error macros (inside loader implementations)
+
+```c
+assetLoaderErrorThrow("msg %d", val);  // errorThrow equivalent
+assetLoaderErrorChain(someCall());     // errorChain equivalent
+```
+
+Use these instead of the bare error macros inside loader callbacks so
+that failures include the loader context in the stack trace.

.claude/build.md

@@ -0,0 +1,116 @@
+# Build System
+
+Dusk uses CMake exclusively. Every source subdirectory owns its own
+`CMakeLists.txt`; the root file only wires them together.
+
+## Golden rule
+
+**Never add source files to the root `CMakeLists.txt` directly.**
+
+Every `.c` file is registered in the `CMakeLists.txt` that lives in
+the same directory (or a direct parent within the same module):
+
+```cmake
+target_sources(${DUSK_LIBRARY_TARGET_NAME}
+  PUBLIC
+    myfile.c
+)
+```
+
+## Configuration variables
+
+| Variable               | Purpose                                      |
+|------------------------|----------------------------------------------|
+| `DUSK_TARGET_SYSTEM`   | Selects the platform (see `.claude/platforms.md`) |
+| `DUSK_BUILD_TESTS`     | Enables the test suite (`ON` / `OFF`)        |
+| `CMAKE_TOOLCHAIN_FILE` | Cross-compiler toolchain for console targets |
+| `CMAKE_BUILD_TYPE`     | `Debug` / `Release` / `RelWithDebInfo`       |
+
+## Typical configure + build
+
+```sh
+# Linux debug build
+cmake -B build -DDUSK_TARGET_SYSTEM=linux -DCMAKE_BUILD_TYPE=Debug
+cmake --build build
+
+# Linux with tests
+cmake -B build \
+      -DDUSK_TARGET_SYSTEM=linux \
+      -DDUSK_BUILD_TESTS=ON \
+      -DCMAKE_BUILD_TYPE=Debug
+cmake --build build
+ctest --test-dir build
+```
+
+## Module layout convention
+
+Each logical module under `src/` gets its own directory:
+
+```
+src/dusk/              Platform-agnostic core
+src/dusk<platform>/    Platform-specific impl (one dir per target)
+```
+
+Within a module, subdirectories mirror subsystem boundaries
+(`asset/`, `entity/`, `script/`, etc.). Each subdirectory has its own
+`CMakeLists.txt` that is `add_subdirectory()`-included by its parent.
+
+## Adding a new source file
+
+1. Create `src/.../myfile.c` (and `myfile.h` if needed).
+2. Open the `CMakeLists.txt` in the same directory.
+3. Add `myfile.c` to the `target_sources(...)` block.
+4. Do **not** touch any parent or root `CMakeLists.txt`.
+
+## Platform-conditional sources
+
+Wrap platform-only files in a generator expression or `if()` block:
+
+```cmake
+if(DUSK_TARGET_SYSTEM STREQUAL "psp")
+  target_sources(${DUSK_LIBRARY_TARGET_NAME}
+    PUBLIC
+      mypspfile.c
+  )
+endif()
+```
+
+## Embedding JS files (`dusk_embed_js`)
+
+Source: `cmake/modules/duskjs2c.cmake`
+
+The `dusk_embed_js()` CMake function embeds a `.js` source file as a
+C string constant in a generated header. It is used to ship script
+module code alongside the engine binary without a separate file load.
+
+```cmake
+dusk_embed_js(
+  TARGET   ${DUSK_LIBRARY_TARGET_NAME}
+  JS_FILE  path/to/mymodule.js
+  # NAME is optional; defaults to uppercase stem + "_JS"
+  # e.g. "mymodule.js" -> "MYMODULE_JS"
+  NAME     MY_CUSTOM_NAME
+)
+```
+
+The generated header is placed in
+`${DUSK_GENERATED_HEADERS_DIR}/<stem>_js.h` and defines:
+
+```c
+static const char MY_CUSTOM_NAME[]     = "... js source ...";
+static const size_t MY_CUSTOM_NAME_SIZE = sizeof(MY_CUSTOM_NAME) - 1;
+```
+
+Under the hood it calls `python -m tools.js2c` from the repo root.
+The header is generated at build time; include it in the `.c` file
+that registers the JS module, then pass `NAME` and `NAME_SIZE` to
+`jerry_eval()` (or the equivalent module load helper).
+
+## Tests
+
+- Test files live in `test/` mirroring the `src/dusk/` structure.
+- Enable with `-DDUSK_BUILD_TESTS=ON`.
+- Uses cmocka; include `dusktest.h` in every test file.
+- Every test must assert `memoryGetAllocatedCount() == 0` at teardown
+  to catch allocator leaks.
+- Test function signature: `static void test_something(void **state)`

.claude/console.md

@@ -0,0 +1,92 @@
+# Console
+
+Source: `src/dusk/console/`
+
+---
+
+## Overview
+
+The console is a lightweight in-engine debug overlay. It maintains a
+fixed-size ring buffer of text lines and can render them to the screen
+as an overlay. On Linux (where `DUSK_CONSOLE_POSIX` is defined), it
+also reads commands from stdin on a background thread, allowing
+interactive input during development without pausing the game loop.
+
+---
+
+## Limits
+
+| Constant | Value |
+|----------|-------|
+| `CONSOLE_LINE_MAX` | 512 chars per line |
+| `CONSOLE_HISTORY_MAX` | 16 lines in the ring buffer |
+| `CONSOLE_EXEC_BUFFER_MAX` | 32 pending execution slots |
+
+---
+
+## Global state
+
+```c
+typedef struct {
+  char_t line[CONSOLE_HISTORY_MAX][CONSOLE_LINE_MAX]; // ring buffer
+  bool_t visible;
+
+  #ifdef DUSK_CONSOLE_POSIX
+    threadmutex_t printMutex;  // guards ring buffer on POSIX targets
+  #endif
+} console_t;
+
+extern console_t CONSOLE;
+```
+
+---
+
+## API
+
+```c
+void consoleInit(void);
+
+// printf-style print into the ring buffer.
+// Thread-safe on POSIX (uses printMutex).
+void consolePrint(const char_t *message, ...);
+
+// Process any queued script input lines. Must be called from the
+// main thread once per frame.
+void consoleUpdate(void);
+
+// Draw the ring buffer as an overlay in UI space.
+errorret_t consoleDraw(void);
+
+void consoleDispose(void);
+```
+
+---
+
+## POSIX stdin mode (`DUSK_CONSOLE_POSIX`)
+
+On Linux only (`DUSK_CONSOLE_POSIX`), the console launches a background
+thread that polls stdin using `poll()` at 75 ms intervals
+(`CONSOLE_POSIX_POLL_RATE`). Lines typed at the terminal are queued
+and dispatched on the main thread by `consoleUpdate()`.
+
+This allows typing commands or JS expressions into the running game
+without blocking the render loop. The ring buffer is protected by
+`CONSOLE.printMutex` so `consolePrint` is safe to call from either
+thread.
+
+POSIX mode is not available on PSP, Vita, or Dolphin targets.
+
+---
+
+## Notes
+
+- `CONSOLE.visible` controls whether `consoleDraw` renders anything.
+  Toggle it from a debug keybind or always set it to `true` in
+  development builds.
+- `consolePrint` wraps lines at `CONSOLE_LINE_MAX` -- long messages are
+  truncated. Use multiple calls for long output.
+- The console is distinct from the error system (`errorThrow` /
+  `errorPrint`). Use `consolePrint` for diagnostic output; use
+  `errorThrow` for recoverable failures.
+- Log calls (`logDebug`, `logError`) go to the platform's debug output
+  (stdout/stderr), not to the console ring buffer.

.claude/display-color.md

@@ -0,0 +1,88 @@
+# Display -- Color
+
+Source: `build/generated/display/color.h` (generated at build time)
+
+---
+
+## Overview
+
+`color.h` is a generated header. It is not hand-edited -- the source
+lives in the CMake generator that produces it from platform configuration.
+Include it via `"display/color.h"`.
+
+---
+
+## Types
+
+```c
+typedef float_t    colorchannelf_t;   // float channel  [0.0, 1.0]
+typedef uint8_t    colorchannel8_t;   // 8-bit channel  [0, 255]
+
+typedef struct { colorchannelf_t r, g, b;    } color3f_t;
+typedef struct { colorchannelf_t r, g, b, a; } color4f_t;
+typedef struct { colorchannel8_t r, g, b;    } color3b_t;
+typedef struct { colorchannel8_t r, g, b, a; } color4b_t;
+
+typedef color4b_t color_t;  // default: RGBA uint8
+```
+
+`color_t` is always `color4b_t` -- four `uint8_t` channels.
+Most engine APIs (text rendering, UI, mesh vertices) take `color_t`.
+
+---
+
+## Constructors
+
+```c
+color3f(r, g, b)       // float RGB
+color4f(r, g, b, a)    // float RGBA
+color3b(r, g, b)       // uint8 RGB
+color4b(r, g, b, a)    // uint8 RGBA
+color(r, g, b, a)      // alias for color4b
+colorHex(0xRRGGBBAA)   // unpack 32-bit hex into color4b
+```
+
+---
+
+## Predefined constants
+
+Each named colour comes in four variants: `_4B` (uint8 RGBA, default),
+`_3B` (uint8 RGB), `_4F` (float RGBA), `_3F` (float RGB). The bare
+name (e.g. `COLOR_BLACK`) always resolves to the `_4B` variant.
+
+| Constant | RGBA (uint8) |
+|----------|-------------|
+| `COLOR_BLACK` | 0, 0, 0, 255 |
+| `COLOR_WHITE` | 255, 255, 255, 255 |
+| `COLOR_RED` | 255, 0, 0, 255 |
+| `COLOR_GREEN` | 0, 255, 0, 255 |
+| `COLOR_BLUE` | 0, 0, 255, 255 |
+| `COLOR_YELLOW` | 255, 255, 0, 255 |
+| `COLOR_CYAN` | 0, 255, 255, 255 |
+| `COLOR_MAGENTA` | 255, 0, 255, 255 |
+| `COLOR_ORANGE` | 255, 165, 0, 255 |
+| `COLOR_PURPLE` | 127, 0, 127, 255 |
+| `COLOR_GRAY` | 127, 127, 127, 255 |
+| `COLOR_LIGHT_GRAY` | 191, 191, 191, 255 |
+| `COLOR_DARK_GRAY` | 63, 63, 63, 255 |
+| `COLOR_BROWN` | 153, 102, 51, 255 |
+| `COLOR_PINK` | 255, 191, 204, 255 |
+| `COLOR_LIME` | 191, 255, 0, 255 |
+| `COLOR_NAVY` | 0, 0, 127, 255 |
+| `COLOR_TEAL` | 0, 127, 127, 255 |
+| `COLOR_CORNFLOWER_BLUE` | 99, 147, 237, 255 |
+| `COLOR_TRANSPARENT` | 0, 0, 0, 0 |
+| `COLOR_TRANSPARENT_WHITE` | 255, 255, 255, 0 |
+| `COLOR_TRANSPARENT_BLACK` | 0, 0, 0, 0 |
+
+---
+
+## Notes
+
+- `color_t` uses premultiplied-friendly `uint8_t` channels for
+  compatibility with both OpenGL texture uploads and GX on Dolphin.
+- For shader uniforms that expect float colours, convert manually:
+  `(float_t)col.r / 255.0f` etc.
+- The `COLOR_SCRIPT` macro is a C string containing the JS Color class
+  static methods. It is concatenated into the embedded JS runtime
+  during module init (see `.claude/script.md`).

.claude/display-core.md

@@ -0,0 +1,81 @@
+# Display -- Screen, Framebuffer, and Size Modes
+
+Source: `src/dusk/display/`
+
+See also: `.claude/display-texture.md`, `.claude/display-shader.md`
+
+---
+
+## Display size modes
+
+Two compile-time configurations exist:
+
+### Fixed size (`DUSK_DISPLAY_WIDTH` + `DUSK_DISPLAY_HEIGHT`)
+
+The render resolution is constant. Set both defines at CMake configure
+time. `SCREEN.width` and `SCREEN.height` are compile-time constants.
+
+### Dynamic size (`DUSK_DISPLAY_SIZE_DYNAMIC`)
+
+The window can be resized (desktop targets). Instead of fixed defines,
+set `DUSK_DISPLAY_WIDTH_DEFAULT` and `DUSK_DISPLAY_HEIGHT_DEFAULT`.
+The screen system renders to an internal framebuffer at a logical
+resolution and scales/letterboxes to the actual window.
+
+Screen modes available only with `DUSK_DISPLAY_SIZE_DYNAMIC`:
+
+| Mode | Behaviour |
+|------|-----------|
+| `SCREEN_MODE_BACKBUFFER` | Render directly to the window backbuffer |
+| `SCREEN_MODE_FIXED_SIZE` | Fixed pixel dimensions; letterboxed |
+| `SCREEN_MODE_ASPECT_RATIO` | Maintain aspect ratio at all cost |
+| `SCREEN_MODE_FIXED_HEIGHT` | Fixed height; width expands/contracts |
+| `SCREEN_MODE_FIXED_WIDTH` | Fixed width; height expands/contracts |
+| `SCREEN_MODE_FIXED_VIEWPORT_HEIGHT` | Fixed height at higher resolution |
+
+Configure via `SCREEN.mode` and the corresponding union field before
+calling `screenInit()`.
+
+---
+
+## Framebuffer (`framebuffer.h`)
+
+```c
+extern framebuffer_t FRAMEBUFFER_BACKBUFFER;
+extern const framebuffer_t *FRAMEBUFFER_BOUND;
+
+// Bind/unbind:
+frameBufferBind(fb);
+frameBufferUnbind();
+
+// Clear (pass flag combination):
+frameBufferClear(fb, FRAMEBUFFER_CLEAR_COLOR | FRAMEBUFFER_CLEAR_DEPTH);
+
+// Dimensions of the currently bound framebuffer:
+int32_t w = frameBufferGetWidth();
+int32_t h = frameBufferGetHeight();
+```
+
+`FRAMEBUFFER_BACKBUFFER` is the window surface. Off-screen framebuffers
+are used by the screen system when `DUSK_DISPLAY_SIZE_DYNAMIC` is on.
+
+---
+
+## Screen (`screen.h`)
+
+```c
+extern screen_t SCREEN;
+// SCREEN.width, SCREEN.height  -- logical render dimensions
+// SCREEN.aspect                -- width / height
+// SCREEN.background            -- clear colour
+
+errorret_t screenInit();
+errorret_t screenBind();    // call before rendering game content
+errorret_t screenUnbind();  // call after game content, before UI
+errorret_t screenRender();  // blit the internal framebuffer to the window
+errorret_t screenDispose();
+```
+
+`screenBind` / `screenUnbind` / `screenRender` are called by the scene
+system automatically each frame. Game code normally does not call them
+directly -- use the JS `render()` hook instead.

.claude/display-mesh.md

@@ -0,0 +1,240 @@
+# Display -- Mesh
+
+Source: `src/dusk/display/mesh/`
+
+See also: `.claude/display-spritebatch.md`, `.claude/display-shader.md`
+
+---
+
+## Overview
+
+The mesh system wraps platform-specific GPU geometry buffers behind a
+common `mesh_t` type. Geometry is described as an array of
+`meshvertex_t` values and a primitive type. The platform layer
+(`meshplatform.h`) provides the concrete buffer and draw implementation
+(VBO on OpenGL, display list or immediate-mode on Dolphin GX).
+
+---
+
+## Vertex format (`meshvertex.h`)
+
+```c
+typedef struct {
+  #if MESH_ENABLE_COLOR
+    color_t color;     // optional per-vertex colour (disabled by default)
+  #endif
+  float_t uv[2];      // texture coordinates (U, V)
+  float_t pos[3];     // position (X, Y, Z)
+} meshvertex_t;
+```
+
+`MESH_ENABLE_COLOR` is a compile-time flag (default 0). Enable it with
+`-DMESH_ENABLE_COLOR=1` at CMake configure time if per-vertex colouring
+is needed; be aware this changes the struct size and breaks binary
+compatibility with pre-built mesh data.
+
+---
+
+## Core API (`mesh.h`)
+
+```c
+// Platform alias -- do not use meshplatform_t directly.
+typedef meshplatform_t mesh_t;
+typedef meshprimitivetypeplatform_t meshprimitivetype_t;
+
+// Upload vertices to the GPU. Must be called from the main thread.
+errorret_t meshInit(
+  mesh_t *mesh,
+  const meshprimitivetype_t primitiveType,
+  const int32_t vertexCount,
+  const meshvertex_t *vertices
+);
+
+// Flush a range of updated vertices to the GPU (modern targets only).
+// vertexCount == -1 flushes all vertices.
+errorret_t meshFlush(
+  mesh_t *mesh,
+  const int32_t vertexOffset,
+  const int32_t vertexCount
+);
+
+// Draw the mesh. vertexCount == -1 draws all vertices.
+errorret_t meshDraw(
+  const mesh_t *mesh,
+  const int32_t vertexOffset,
+  const int32_t vertexCount
+);
+
+// Compute the axis-aligned bounding box.
+void meshGetBounds(const mesh_t *mesh, vec3 outMin, vec3 outMax);
+
+int32_t meshGetVertexCount(const mesh_t *mesh);
+
+errorret_t meshDispose(mesh_t *mesh);
+```
+
+On constrained targets (GameCube/Wii) `meshFlush` is a no-op -- the
+hardware reads vertices from main memory directly. Always call it on
+desktop/mobile targets after modifying vertex data.
+
+---
+
+## Primitive generators
+
+Each generator provides:
+- A `*Buffer(vertices, ...)` function that writes into a caller-supplied
+  `meshvertex_t` array (no allocation).
+- A global pre-built `*_MESH_SIMPLE` singleton + `*_MESH_SIMPLE_VERTICES`
+  array initialised at engine startup (for common one-off uses).
+
+All generators use CCW winding and `MESH_PRIMITIVE_TYPE_TRIANGLES`.
+
+### Quad (`quad.h`)
+
+```c
+#define QUAD_VERTEX_COUNT 6  // two triangles
+
+// 2D quad in XY plane:
+void quadBuffer(
+  meshvertex_t *vertices,
+  const float_t minX, const float_t minY,
+  const float_t maxX, const float_t maxY,
+  const float_t u0, const float_t v0,
+  const float_t u1, const float_t v1
+);
+
+// 3D quad using full vec3 min/max:
+void quadBuffer3D(
+  meshvertex_t *vertices,
+  const vec3 min, const vec3 max,
+  const vec2 uvMin, const vec2 uvMax
+);
+
+extern mesh_t QUAD_MESH_SIMPLE;
+```
+
+The SpriteBatch is built on `quadBuffer3D` internally.
+
+### Cube (`cube.h`)
+
+```c
+#define CUBE_VERTEX_COUNT 36  // 6 faces x 6 vertices
+
+// Axis-aligned box from min to max:
+void cubeBuffer(
+  meshvertex_t *vertices,
+  const vec3 min, const vec3 max
+);
+
+extern mesh_t CUBE_MESH_SIMPLE;  // unit cube (0,0,0) to (1,1,1)
+```
+
+### Plane (`plane.h`)
+
+```c
+#define PLANE_VERTEX_COUNT 6
+
+typedef enum {
+  PLANE_AXIS_XY,  // flat in XY, normal along +Z (billboard / wall face)
+  PLANE_AXIS_XZ,  // flat in XZ, normal along +Y (ground / floor)
+  PLANE_AXIS_YZ,  // flat in YZ, normal along +X (side wall)
+} planeaxis_t;
+
+void planeBuffer(
+  meshvertex_t *vertices,
+  const planeaxis_t axis,
+  const vec3 min, const vec3 max,
+  const vec2 uvMin, const vec2 uvMax
+);
+
+extern mesh_t PLANE_MESH_SIMPLE;  // unit XZ plane (0,0,0) to (1,0,1)
+```
+
+### Sphere (`sphere.h`)
+
+```c
+#define SPHERE_STACKS  8
+#define SPHERE_SECTORS 16
+#define SPHERE_VERTEX_COUNT (SPHERE_STACKS * SPHERE_SECTORS * 6)
+
+void sphereBuffer(
+  meshvertex_t *vertices,
+  const vec3 center,
+  const float_t radius,
+  const int32_t stacks,
+  const int32_t sectors
+);
+
+extern mesh_t SPHERE_MESH_SIMPLE;  // unit sphere centered at (0,0,0), r=0.5
+```
+
+### Capsule (`capsule.h`)
+
+```c
+#define CAPSULE_CAP_RINGS 4
+#define CAPSULE_SECTORS   16
+// Total vertex count = (2 * capRings + 1) * sectors * 6
+
+void capsuleBuffer(
+  meshvertex_t *vertices,
+  const vec3 center,
+  const float_t radius,
+  const float_t halfHeight,  // half-height of the cylindrical section only
+  const int32_t capRings,
+  const int32_t sectors
+);
+
+extern mesh_t CAPSULE_MESH_SIMPLE;  // r=0.5, halfHeight=0.5 (total h=2.0)
+```
+
+The long axis is always Y. This mirrors the physics capsule body (see
+`.claude/physics.md`).
+
+### Triangular prism (`triprism.h`)
+
+```c
+#define TRIPRISM_VERTEX_COUNT 24
+
+// Cross-section triangle defined by three 2D points in XY;
+// extruded along Z from minZ to maxZ.
+void triPrismBuffer(
+  meshvertex_t *vertices,
+  const float_t x0, const float_t y0,
+  const float_t x1, const float_t y1,
+  const float_t x2, const float_t y2,
+  const float_t minZ, const float_t maxZ
+);
+
+extern mesh_t TRIPRISM_MESH_SIMPLE;
+// Unit prism: triangle (0,0),(1,0),(0.5,1) extruded z=0 to z=1.
+```
+
+---
+
+## Custom dynamic mesh
+
+If you need to update geometry each frame (e.g. a procedural mesh):
+
+```c
+static meshvertex_t myVerts[MY_VERT_COUNT];
+static mesh_t myMesh;
+
+// On init:
+// Fill myVerts, then:
+errorChain(meshInit(&myMesh, MESH_PRIMITIVE_TYPE_TRIANGLES,
+  MY_VERT_COUNT, myVerts));
+
+// Each frame (after modifying myVerts):
+errorChain(meshFlush(&myMesh, 0, -1));
+errorChain(meshDraw(&myMesh, 0, -1));
+```
+
+---
+
+## Notes
+
+- `meshInit` must be called on the **main thread** (GPU upload).
+- `meshFlush` is required on OpenGL targets when vertices change
+  after init. It is a no-op on Dolphin.
+- All `_MESH_SIMPLE` globals are initialised during engine startup --
+  do not call `meshInit` on them manually.

.claude/display-shader.md

@@ -0,0 +1,86 @@
+# Display -- Shader, Material, and Display State
+
+Source: `src/dusk/display/`
+
+See also: `.claude/display-core.md`, `.claude/display-texture.md`
+
+---
+
+## Shader (`shader.h` + `shaderlist.h`)
+
+Shaders are platform-abstracted. The current shader list is defined
+in `shaderlist.h`. Currently only one shader is implemented:
+
+| Enum | Description |
+|------|-------------|
+| `SHADER_LIST_SHADER_UNLIT` | Unlit / flat colour + texture shader |
+
+```c
+extern shaderlistdef_t SHADER_LIST_DEFS[SHADER_LIST_SHADER_COUNT];
+// SHADER_LIST_DEFS[n].shader is the platform shader object.
+
+// Bind a shader before drawing:
+errorret_t shaderBind(shader_t *shader);
+
+// Upload a mat4 uniform by name:
+errorret_t shaderSetMatrix(shader_t *shader, const char_t *name, mat4 m);
+```
+
+Adding a new shader means adding an entry to `shaderlist.h`, providing
+platform-specific vertex/fragment sources, and implementing the
+corresponding material type in `shadermaterial_t`.
+
+---
+
+## Shader material (`shadermaterial.h`)
+
+`shadermaterial_t` is a union over per-shader material structs.
+Currently contains only the unlit material:
+
+```c
+typedef union shadermaterial_u {
+  shaderunlitmaterial_t unlit;
+} shadermaterial_t;
+```
+
+`shaderunlitmaterial_t` fields:
+
+```c
+typedef struct {
+  color_t color;      // tint colour (multiplied with the texture sample)
+  texture_t *texture; // NULL uses TEXTURE_WHITE (solid colour draw)
+} shaderunlitmaterial_t;
+```
+
+The shader exposes uniforms `u_Proj`, `u_View`, `u_Model` (mat4),
+`u_Texture` (sampler), and `u_Color` (vec4). They are uploaded via
+`shaderUnlitSetMaterial(shader, material)`.
+
+A global singleton `SHADER_UNLIT` is the live shader object;
+`SHADER_UNLIT_DEFINITION` is its platform definition descriptor.
+
+To use a shader material on a renderable entity:
+
+1. Set `renderable.type = ENTITY_RENDERABLE_TYPE_SHADER_MATERIAL`.
+2. Set `renderable.data.material.shaderType` to the desired
+   `shaderlistshadertype_t` value (e.g. `SHADER_LIST_SHADER_UNLIT`).
+3. Fill in the corresponding union field:
+   `renderable.data.material.material.unlit`.
+4. Set `renderable.data.material.state.flags` for rasterizer state.
+
+---
+
+## Display state (`displaystate.h`)
+
+`displaystate_t` controls per-draw rasterizer state flags:
+
+```c
+DISPLAY_STATE_FLAG_CULL        // back-face culling
+DISPLAY_STATE_FLAG_DEPTH_TEST  // depth testing
+DISPLAY_STATE_FLAG_BLEND       // alpha blending
+```
+
+Set flags via `data.material.state.flags` on the renderable's material.
+The default for an uninitialised state is all flags clear (no culling,
+no depth test, no blending). Most opaque geometry should set at least
+`CULL | DEPTH_TEST`.

.claude/display-spritebatch.md

@@ -0,0 +1,133 @@
+# Display -- SpriteBatch
+
+Source: `src/dusk/display/spritebatch/`
+
+See also: `.claude/display-mesh.md`, `.claude/display-texture.md`
+
+---
+
+## Overview
+
+The SpriteBatch is the primary 2D rendering primitive. It accumulates
+axis-aligned quads (sprites) into a shared vertex buffer and draws them
+in batches. All 2D rendering in the engine -- UI frames, text, tilemaps,
+HUD -- goes through the global `SPRITEBATCH`.
+
+The batch flushes automatically when the per-flush limit is reached, or
+explicitly via `spriteBatchFlush()`.
+
+---
+
+## Limits
+
+| Constant | Value | Meaning |
+|----------|-------|---------|
+| `SPRITEBATCH_SPRITES_MAX` | 512 | Total sprites in the vertex buffer |
+| `SPRITEBATCH_FLUSH_COUNT` | 16 | Number of auto-flush segments |
+| `SPRITEBATCH_SPRITES_MAX_PER_FLUSH` | 32 | Sprites per auto-flush segment |
+| `SPRITEBATCH_VERTEX_COUNT` | 3072 | Total vertices (512 * QUAD_VERTEX_COUNT) |
+
+---
+
+## Sprite structure
+
+```c
+typedef struct {
+  vec3 min;    // minimum XYZ corner of the quad in world/screen space
+  vec3 max;    // maximum XYZ corner of the quad in world/screen space
+  vec2 uvMin;  // minimum UV (top-left in [0,1] texture space)
+  vec2 uvMax;  // maximum UV (bottom-right in [0,1] texture space)
+} spritebatchsprite_t;
+```
+
+Z in `min` and `max` controls draw depth (further from camera = higher Z
+in a typical orthographic setup). For flat 2D, set `min.z = max.z = 0`.
+
+---
+
+## SpriteBatch struct
+
+```c
+typedef struct {
+  mesh_t mesh;
+  int32_t spriteCount;
+  int32_t spriteFlush;
+  shader_t *shader;
+  shadermaterial_t material;
+} spritebatch_t;
+
+extern spritebatch_t SPRITEBATCH;
+extern meshvertex_t SPRITEBATCH_VERTICES[SPRITEBATCH_VERTEX_COUNT];
+```
+
+`SPRITEBATCH_VERTICES` is a separate global (not embedded in the struct)
+for platform alignment requirements.
+
+---
+
+## API
+
+```c
+errorret_t spriteBatchInit();
+errorret_t spriteBatchDispose();
+
+// Clear the buffer and reset state. Call before starting a new batch.
+void spriteBatchClear();
+
+// Append sprites to the buffer. Flushes automatically when the per-flush
+// segment fills. shader + material are used on the next flush.
+errorret_t spriteBatchBuffer(
+  const spritebatchsprite_t *sprites,
+  const uint32_t count,
+  shader_t *shader,
+  const shadermaterial_t material
+);
+
+// Upload and draw all buffered sprites. Binds shader and applies
+// material if set. No-op if the buffer is empty.
+errorret_t spriteBatchFlush();
+```
+
+---
+
+## Typical usage
+
+```c
+// Beginning of a 2D render pass:
+spriteBatchClear();
+
+// Build sprites (e.g. via tilesetTileGetUV, then fill spritebatchsprite_t):
+spritebatchsprite_t s;
+glm_vec3_copy((vec3){ x, y, 0 }, s.min);
+glm_vec3_copy((vec3){ x + w, y + h, 0 }, s.max);
+glm_vec2_copy(uvMin, s.uvMin);
+glm_vec2_copy(uvMax, s.uvMax);
+
+shadermaterial_t mat = { .unlit = { .texture = myTexture } };
+spriteBatchBuffer(&s, 1, myShader, mat);
+
+// End of pass -- flush remaining sprites:
+spriteBatchFlush();
+```
+
+---
+
+## Relationship to other systems
+
+- **Text rendering** (`textDraw`) internally calls `spriteBatchBuffer`
+  for each glyph and requires a final `spriteBatchFlush()` after drawing.
+- **UI frames** (`uiFrameDraw`) push 9 quads to the batch without
+  flushing -- the caller or `uitextboxDraw` is responsible for the flush.
+- **ECS renderables** of type `ENTITY_RENDERABLE_TYPE_SPRITEBATCH` are
+  drawn via the spritebatch in the scene render pipeline.
+
+---
+
+## Notes
+
+- `spriteBatchBuffer` changes the batch's `shader` and `material` fields.
+  If you mix different shaders or textures in one batch, add an explicit
+  `spriteBatchFlush()` call between groups to avoid draws with the wrong
+  material.
+- The vertex buffer is a static global -- `SPRITEBATCH_VERTICES` must
+  not be written from multiple threads.

.claude/display-text.md

@@ -0,0 +1,115 @@
+# Display -- Text Rendering
+
+Source: `src/dusk/display/text/`
+
+See also: `.claude/display-spritebatch.md`, `.claude/display-texture.md`
+
+---
+
+## Overview
+
+Text rendering is layered on top of the SpriteBatch. Each character
+maps to a glyph tile in a bitmap font atlas; `textDraw` builds the
+corresponding `spritebatchsprite_t` values and pushes them to the
+global `SPRITEBATCH`. The caller is responsible for flushing the batch.
+
+---
+
+## Font type (`font.h`)
+
+```c
+typedef struct {
+  texture_t *texture;   // glyph atlas texture
+  tileset_t *tileset;   // grid describing glyph size + UV layout
+} font_t;
+```
+
+Both pointers are caller-owned. The text system does not allocate or
+free them.
+
+```c
+extern font_t FONT_DEFAULT;
+```
+
+`FONT_DEFAULT` is the engine's built-in bitmap font. It is initialised
+during `textInit()` and available for the engine lifetime.
+
+---
+
+## Character range
+
+```c
+#define TEXT_CHAR_START '!'   // ASCII 33
+```
+
+The glyph atlas begins at `'!'` (ASCII 33). Characters below this value
+-- space, control characters -- are handled specially:
+
+- `' '` (space) advances the cursor by one tile width without drawing.
+- Characters below `TEXT_CHAR_START` other than space are skipped.
+
+---
+
+## API (`text.h`)
+
+```c
+// Initialises the text system and FONT_DEFAULT.
+errorret_t textInit(void);
+
+// Disposes of the text system.
+errorret_t textDispose(void);
+
+// Draw a null-terminated string at (x, y) in screen/world space.
+// Pushes sprites to SPRITEBATCH. Caller must call spriteBatchFlush()
+// after all text has been drawn.
+errorret_t textDraw(
+  const float_t x,
+  const float_t y,
+  const char_t *text,
+  const color_t color,
+  font_t *font
+);
+
+// Measure the bounding box of a string without drawing it.
+void textMeasure(
+  const char_t *text,
+  const font_t *font,
+  int32_t *outWidth,
+  int32_t *outHeight
+);
+
+// Low-level: build a single glyph sprite at position pos.
+// Returns a spritebatchsprite_t ready for spriteBatchBuffer.
+spritebatchsprite_t textGetSprite(
+  const vec2 pos,
+  const char_t c,
+  const font_t *font
+);
+```
+
+---
+
+## Typical usage
+
+```c
+// Inside a render callback:
+errorChain(textDraw(10.0f, 10.0f, "Hello", COLOR_WHITE, &FONT_DEFAULT));
+errorChain(spriteBatchFlush());
+```
+
+If you are also drawing UI frames or other sprites in the same pass,
+batch all the `textDraw` and `spriteBatchBuffer` calls first, then call
+`spriteBatchFlush()` once at the end.
+
+---
+
+## Notes
+
+- Text coordinates are in the same space as the scene render (screen
+  space for UI, or world space if placed in the scene).
+- `textMeasure` returns pixel dimensions based on the font's
+  `tileset.tileWidth` and `tileset.tileHeight`. Use it to centre or
+  right-align text before drawing.
+- For UI-attached text (dialogue, labels), prefer the `uitextbox_t`
+  system which handles word-wrap and paging automatically
+  (see `.claude/ui.md`).

.claude/display-texture.md

@@ -0,0 +1,86 @@
+# Display -- Texture, Tileset, and Font
+
+Source: `src/dusk/display/`
+
+See also: `.claude/display-core.md`, `.claude/display-shader.md`
+
+---
+
+## Texture (`texture.h`)
+
+```c
+extern texture_t TEXTURE_WHITE;  // 4x4 opaque white; always available
+
+errorret_t textureInit(
+  texture_t *texture,
+  int32_t width,
+  int32_t height,
+  textureformat_t format,
+  texturedata_t data
+);
+errorret_t textureDispose(texture_t *texture);
+```
+
+`textureformat_t` and `texture_t` are platform aliases
+(`textureformatplatform_t`, `textureplatform_t`). On OpenGL targets
+the format maps to GL texture format constants.
+
+`texturedata_t` is a union:
+- `.paletted.indices` + `.paletted.palette` -- for paletted formats
+- `.rgbaColors` -- for RGBA formats
+
+### Texture rules
+
+- Dimensions must be powers of two on PSP and GameCube/Wii. Use
+  `mathNextPowTwo` from `util/math.h` if needed.
+- Texture upload must happen on the main thread. In the asset loader,
+  this means `loadSync` (not `loadAsync`).
+- `TEXTURE_WHITE` is always available without loading; use it as a
+  placeholder or for untextured geometry.
+
+---
+
+## Tileset (`tileset.h`)
+
+A tileset subdivides a texture into a uniform grid of tiles.
+
+```c
+typedef struct {
+  uint16_t tileWidth, tileHeight;
+  uint16_t tileCount;
+  uint16_t columns, rows;
+  vec2 uv;   // UV size per tile (pre-computed from grid dimensions)
+} tileset_t;
+
+// Get UV rect for a tile by index:
+void tilesetTileGetUV(
+  const tileset_t *ts, uint16_t tileIndex, vec4 outUV
+);
+
+// Get UV rect for a tile by grid position:
+void tilesetPositionGetUV(
+  const tileset_t *ts, uint16_t column, uint16_t row, vec4 outUV
+);
+```
+
+`outUV` is `{u, v, u2, v2}` in normalised [0, 1] texture space.
+
+Tilesets are loaded from `.dtf` binary files via
+`ASSET_LOADER_TYPE_TILESET`. The DTF format stores tile width/height,
+grid dimensions, and per-tile UV offsets (magic + version header).
+
+---
+
+## Font (`font.h`)
+
+```c
+typedef struct {
+  texture_t *texture;
+  tileset_t *tileset;
+} font_t;
+```
+
+A font is a tileset-backed texture atlas where each tile is a character
+glyph. No heap allocation -- both pointers are owned by the caller.
+Character lookup is by glyph index into the tileset grid. Rendering is
+handled by the spritebatch system using the tileset UV helpers.

.claude/display.md

@@ -0,0 +1,23 @@
+# Display System
+
+Source: `src/dusk/display/`
+
+## Overview
+
+The display system is a platform-abstracted rendering layer. Each
+subsystem (texture, shader, framebuffer, screen) is defined by a core
+header that requires the platform layer to provide concrete types and
+hook macros. The OpenGL implementation lives in `src/duskgl/`; the
+Dolphin (GX) implementation in `src/duskdolphin/`.
+
+## Subsystem documentation
+
+| Subsystem | Reference |
+|-----------|-----------|
+| Screen size modes, framebuffer, screen | `.claude/display-core.md` |
+| Texture, tileset, font | `.claude/display-texture.md` |
+| Shader, shader material, display state | `.claude/display-shader.md` |
+| Mesh, vertex format, primitive generators | `.claude/display-mesh.md` |
+| SpriteBatch (2D quad renderer) | `.claude/display-spritebatch.md` |
+| Text rendering, font, FONT_DEFAULT | `.claude/display-text.md` |
+| Color types, macros, named constants | `.claude/display-color.md` |

.claude/ecs.md

@@ -0,0 +1,179 @@
+# Entity Component System (ECS)
+
+Source: `src/dusk/entity/`
+
+## Core concepts
+
+- **Entity** (`entityid_t` = `uint8_t`) -- a numeric ID. No data of
+  its own; just an index into the entity manager pool.
+- **Component** -- a plain data struct registered in `componentlist.h`.
+  Stores state; no behaviour.
+- **System** -- functions that query all entities with a given component
+  type and act on them each tick.
+
+## Hard limits
+
+| Constant | Value |
+|----------|-------|
+| `ENTITY_COUNT_MAX` | 64 |
+| `ENTITY_COMPONENT_COUNT_MAX` | 16 per entity |
+| Total component slots | 1024 (64 x 16) |
+| Update callbacks per entity | 5 |
+| Dispose callbacks per entity | 5 |
+
+`ENTITY_ID_INVALID = 0xFF`, `COMPONENT_ID_INVALID = 0xFF`.
+
+## Global state
+
+```c
+extern entitymanager_t ENTITY_MANAGER;
+// .entities[64]          -- entity structs
+// .components[1024]      -- all component data (entity * 16 + comp)
+// .entitiesWithComponent -- O(1) lookup indexed by [type * 64 + entityId]
+```
+
+## Entity lifecycle
+
+```c
+entityid_t id = entityManagerAdd();   // reserve first inactive slot
+entityInit(id);                        // zero the entity, mark active
+
+componentid_t posId = entityAddComponent(id, COMPONENT_TYPE_POSITION);
+componentid_t rendId = entityAddComponent(id, COMPONENT_TYPE_RENDERABLE);
+
+// Per-frame update (called by entityManagerUpdate):
+entityUpdate(id);
+
+// Cleanup:
+entityDispose(id);           // dispose components, mark inactive
+entityDisposeDeep(id);       // dispose self + entire position hierarchy
+```
+
+## Component registration (X-macro)
+
+All component types are declared in a single table in
+`src/dusk/entity/componentlist.h`:
+
+```c
+X(NAME, type_t, fieldName, initFn, disposeFn, renderFn)
+```
+
+This generates:
+- `COMPONENT_TYPE_NAME` enum value
+- Union field `fieldName` in `componentdata_t`
+- Entry in `COMPONENT_DEFINITIONS[]` with `init` / `dispose` /
+  `render` function pointers (any may be `NULL`)
+
+Current registered components:
+
+| Enum suffix | Struct | Notes |
+|-------------|--------|-------|
+| `POSITION` | `entityposition_t` | Transform + parent/child hierarchy |
+| `CAMERA` | `entitycamera_t` | View matrix setup |
+| `RENDERABLE` | `entityrenderable_t` | Sprite batch, shader material, or custom draw |
+| `PHYSICS` | `entityphysics_t` | Physics body (see `.claude/physics.md`) |
+| `TRIGGER` | `entitytrigger_t` | Collision trigger zone |
+
+## Accessing component data
+
+```c
+void *componentGetData(
+  entityid_t entityId,
+  componentid_t componentId,
+  componenttype_t type
+);
+// Returns pointer into the preallocated components pool.
+// Never NULL for a valid (id, type) pair.
+```
+
+Querying all entities with a given type:
+
+```c
+entityid_t ids[ENTITY_COUNT_MAX];
+componentid_t comps[ENTITY_COUNT_MAX];
+entityid_t count = componentGetEntitiesWithComponent(
+  COMPONENT_TYPE_PHYSICS, ids, comps
+);
+```
+
+## Adding a new component -- checklist
+
+1. Create `src/dusk/entity/component/<category>/entity<Name>.h/.c`.
+   - Struct: `entity<Name>_t`
+   - `entity<Name>Init(entityid_t, componentid_t)` (required)
+   - `entity<Name>Dispose(entityid_t, componentid_t)` (if needed)
+2. `#include` the new header in the header block of `componentlist.h`.
+3. Add an `X(...)` row in `componentlist.h`.
+4. If JS-facing, add a script module (see `CLAUDE.md`).
+
+## Position component (`entityposition_t`)
+
+The position component implements the transform hierarchy and uses lazy
+evaluation with dirty flags to avoid redundant matrix rebuilds.
+
+**Dirty flags:**
+
+| Flag | Meaning |
+|------|---------|
+| `ENTITY_POSITION_FLAG_PRS_DIRTY` | Cached position/rotation/scale stale vs localTransform |
+| `ENTITY_POSITION_FLAG_ROTATION_DIRTY` | Rotation columns of localTransform stale |
+| `ENTITY_POSITION_FLAG_POSITION_DIRTY` | Position column of localTransform stale |
+| `ENTITY_POSITION_FLAG_WORLD_DIRTY` | World matrix stale |
+
+**Hierarchy:** up to 8 children per entity. `entityPositionSetParent()`
+reparents and maintains the child list. `entityDisposeDeep()` /
+`entityPositionDisposeDeep()` recursively disposes the entire subtree.
+
+**Key functions:**
+
+```c
+// Local space getters/setters (mark local dirty):
+entityPositionGetLocalPosition / SetLocalPosition
+entityPositionGetLocalRotation / SetLocalRotation
+entityPositionGetLocalScale    / SetLocalScale
+
+// World space getters/setters (ensure world updated):
+entityPositionGetWorldPosition / SetWorldPosition
+entityPositionGetWorldRotation / SetWorldRotation
+entityPositionGetWorldScale    / SetWorldScale
+
+entityPositionSetParent(entityId, parentEntityId, parentComponentId);
+entityPositionLookAt(entityId, componentId, eye, target, up);
+entityPositionRebuild(pos);  // force immediate matrix rebuild
+```
+
+## Renderable component (`entityrenderable_t`)
+
+Three rendering modes selected via `entityrenderabletype_t`:
+
+| Mode | Description |
+|------|-------------|
+| `ENTITY_RENDERABLE_TYPE_CUSTOM` | User-supplied `draw` callback |
+| `ENTITY_RENDERABLE_TYPE_SPRITEBATCH` | Up to 64 sprites + texture |
+| `ENTITY_RENDERABLE_TYPE_SHADER_MATERIAL` | Up to 8 meshes, shader, material, display state |
+
+Default on init: shader material (white, unlit, depth-tested cube).
+`priority` (int8_t) controls render order; 0 = automatic.
+
+## Callback hooks on entities
+
+Entities support up to 5 registered update callbacks and 5 dispose
+callbacks. These are used by systems that need per-entity ticks without
+building a full query loop every frame:
+
+```c
+entityUpdateAdd(entityId, updateFn, componentId, user);
+entityUpdateRemove(entityId, updateFn);
+
+entityDisposeAdd(entityId, disposeFn, componentId, user);
+entityDisposeRemove(entityId, disposeFn);
+```
+
+## Design rules
+
+- Components store **data only**. No logic in a component struct or
+  its init beyond setting default values.
+- Keep components small and focused.
+- Cross-component access is fine from a system, but a component must
+  never hold a pointer to another component -- use entity IDs.
+- Systems must not assume component ordering. Use `componentGetEntitiesWithComponent`.

.claude/engine.md

@@ -0,0 +1,95 @@
+# Engine, System, and Log
+
+Sources: `src/dusk/engine/`, `src/dusk/system/`, `src/dusk/log/`
+
+---
+
+## Engine (`engine.h`)
+
+The engine owns the top-level init / update / dispose loop. Every
+platform's `main()` calls these three functions in order.
+
+```c
+extern engine_t ENGINE;
+// ENGINE.running  -- false causes the main loop to exit
+// ENGINE.argc / ENGINE.argv -- passed from main()
+// ENGINE.version  -- version string
+
+errorret_t engineInit(int32_t argc, const char_t **argv);
+errorret_t engineUpdate(void);   // called once per tick
+errorret_t engineDispose(void);
+```
+
+`engineInit` initialises subsystems in order: system, log, assert,
+display, time, asset, input, physics, script, etc.
+
+`engineUpdate` steps each subsystem: time, input, physics, script, ECS
+entities, rendering, audio, network, asset completion callbacks.
+
+`engineDispose` shuts everything down in reverse order.
+
+**To exit gracefully:** set `ENGINE.running = false` -- the platform
+main loop checks this each tick and calls `engineDispose` before
+returning.
+
+---
+
+## System (`system.h`)
+
+The system module is initialised very early (before most other
+subsystems) and provides two things:
+
+### Platform identity
+
+```c
+typedef enum { SYSTEM_PLATFORM_LIST } systemplatform_t;
+
+systemplatform_t systemGetPlatform(void);
+```
+
+Platform names come from `systemplatformlist.h` via an X-macro. This
+lets game code query the runtime platform when compile-time guards are
+not sufficient (e.g. serializing platform name to a log).
+
+### Dialog blocking
+
+Some platforms (PSP, Wii) show OS-level dialogs (Wi-Fi setup, save
+management) that block the normal game loop. The system module exposes
+the current dialog state so the engine main loop can adjust:
+
+```c
+typedef enum {
+  SYSTEM_DIALOG_TYPE_NONE,
+  SYSTEM_DIALOG_TYPE_RENDER_BLOCKING,  // skip render but still tick
+  SYSTEM_DIALOG_TYPE_TICK_BLOCKING,    // skip both render and tick
+} systemdialogtype_t;
+
+systemdialogtype_t systemGetActiveDialogType(void);
+```
+
+`engineUpdate` checks this before calling render / update code.
+Most platforms always return `SYSTEM_DIALOG_TYPE_NONE`.
+
+---
+
+## Log (`log.h`)
+
+Simple printf-style logging with two levels. Always use these instead
+of `printf` / `fprintf`.
+
+```c
+void logDebug(const char_t *message, ...);
+// Writes to the debug output (stdout on desktop, platform console
+// on handhelds). No-op in release builds on some platforms.
+
+void logError(const char_t *message, ...);
+// Writes to the error output. On some platforms (PSP) this may
+// pause execution to ensure the message is visible before continuing.
+```
+
+**Do not** use `logDebug` / `logError` for structured error handling --
+that is what `errorThrow` / `errorChain` are for. Log calls are for
+human-readable diagnostics only.
+
+The error system calls `logError` internally when printing a caught
+error via `errorPrint()`.

.claude/errors.md

@@ -0,0 +1,133 @@
+# Error Handling System
+
+Source: `src/dusk/error/`
+
+## Philosophy
+
+Error handling is return-value based. Functions that can fail return
+`errorret_t`. There are no exceptions, `errno`, `setjmp`, or global
+error codes. Each thread has its own isolated error state.
+
+## Types
+
+```c
+typedef uint8_t errorcode_t;
+
+typedef struct {
+  errorcode_t code;
+  char_t *message;  // allocated; freed by errorCatch
+  char_t *lines;    // call-stack trace; allocated; freed by errorCatch
+} errorstate_t;
+
+typedef struct {
+  errorcode_t code;
+  errorstate_t *state;  // NULL on success
+} errorret_t;
+```
+
+**Constants:** `ERROR_OK = 0`, `ERROR_NOT_OK = 1`.
+
+Error state is thread-local:
+
+```c
+extern THREAD_LOCAL errorstate_t ERROR_STATE;
+```
+
+Each thread has its own `ERROR_STATE` so concurrent errors never
+interfere.
+
+## Macros
+
+### Throwing an error
+
+```c
+errorThrow("message %d", value);
+// Throws with ERROR_NOT_OK, captures __FILE__ / __func__ / __LINE__.
+
+errorThrowWithCode(code, "message %d", value);
+// Same but with a specific error code.
+```
+
+Both macros **return from the current function** with an `errorret_t`.
+Do not call them in void functions.
+
+### Propagating up the call stack
+
+```c
+errorChain(someCall());
+```
+
+If `someCall()` returned an error, appends the current location to the
+stack trace and **returns** that error from the current function.
+If `someCall()` returned success, execution continues normally.
+
+### Returning success
+
+```c
+errorOk();
+```
+
+Returns `errorret_t` with `code == ERROR_OK` and asserts the thread's
+`ERROR_STATE` is clean (no leftover error). Must be the last statement
+in a fallible function.
+
+### Inspecting a result
+
+```c
+if(errorIsOk(ret)) { ... }
+if(errorIsNotOk(ret)) { ... }
+```
+
+### Cleaning up
+
+```c
+errorCatch(ret);
+```
+
+Frees `ret.state->message` and `ret.state->lines`, resets the thread's
+`ERROR_STATE.code` to `ERROR_OK`. Safe to call on a success return
+(no-op). **Always call `errorCatch` on errors you are handling** --
+otherwise the allocated message and stack-trace leak.
+
+### Logging
+
+```c
+errorPrint(ret);       // prints code + message + stack trace, returns ret
+```
+
+## Typical patterns
+
+### Fallible function
+
+```c
+errorret_t myFunction(int_t x) {
+  if(x < 0) errorThrow("x must be non-negative, got %d", x);
+  errorChain(someOtherFallibleCall(x));
+  errorOk();
+}
+```
+
+### Caller that handles errors
+
+```c
+errorret_t ret = myFunction(-1);
+if(errorIsNotOk(ret)) {
+  errorCatch(errorPrint(ret));
+  // ... fallback logic ...
+}
+```
+
+### Stack trace accumulation
+
+Each `errorChain()` call appends a line to `ret.state->lines` in the
+format `  at file:line in function\n`. A deeply chained error produces
+a full call path readable from `ret.state->lines`.
+
+## What NOT to do
+
+- Do not use raw `errno` for in-engine errors.
+- Do not return an error code integer -- always return `errorret_t`.
+- Do not ignore an error return without calling `errorCatch` on it if
+  you are not propagating it.
+- Do not mix assertions with error handling. Assertions are for
+  programmer mistakes; `errorThrow` is for expected failure paths.

.claude/events.md

@@ -0,0 +1,109 @@
+# Event System
+
+Source: `src/dusk/event/`
+
+## Overview
+
+The event system is a simple publish-subscribe mechanism backed by
+caller-owned static arrays. There is no heap allocation in the event
+system itself -- the caller provides the backing storage.
+
+## API
+
+```c
+typedef void (*eventcallback_t)(void *params, void *user);
+
+typedef struct {
+  eventcallback_t *callbacks;
+  void **users;
+  size_t size;
+  uint32_t count;
+} event_t;
+```
+
+### Initialise
+
+```c
+void eventInit(
+  event_t *event,
+  eventcallback_t *callbacks,
+  void **users,
+  size_t size
+);
+```
+
+`callbacks` and `users` are caller-owned arrays of length `size`. Both
+are zeroed by `eventInit`. `users` may be `NULL` if no subscriber needs
+a user pointer.
+
+### Subscribe / unsubscribe
+
+```c
+void eventSubscribe(event_t *event, eventcallback_t callback, void *user);
+void eventUnsubscribe(event_t *event, eventcallback_t callback);
+```
+
+The same `(callback, user)` pair may only be subscribed once --
+`eventSubscribe` asserts on a duplicate. `eventUnsubscribe` is a no-op
+if the pair is not found. Unsubscribing uses swap-with-last to keep the
+array packed; ordering is not preserved.
+
+### Fire
+
+```c
+void eventInvoke(const event_t *event, void *params);
+```
+
+Calls every subscriber in registration order, passing `params` and
+each subscriber's `user` pointer.
+
+## Usage pattern
+
+Declare the backing arrays alongside the event struct, typically as
+struct fields or static variables:
+
+```c
+#define MY_EVENT_CAPACITY 4
+
+typedef struct {
+  event_t onComplete;
+  eventcallback_t _completeCbs[MY_EVENT_CAPACITY];
+  void *_completeUsers[MY_EVENT_CAPACITY];
+} mystate_t;
+
+// Init:
+eventInit(
+  &state.onComplete,
+  state._completeCbs,
+  state._completeUsers,
+  MY_EVENT_CAPACITY
+);
+
+// Publish:
+eventInvoke(&state.onComplete, &someParams);
+
+// Subscribe from outside:
+eventSubscribe(&state.onComplete, myHandler, myUserPtr);
+```
+
+## Constraints
+
+- Capacity is fixed at init time. Exceeding it is a runtime assertion.
+- Subscriber order is not stable after an unsubscribe.
+- `eventInvoke` is synchronous -- all callbacks run on the calling
+  thread before it returns.
+- Do not subscribe or unsubscribe from inside a callback -- the array
+  may shift during iteration.
+
+## Where events are used
+
+| Subsystem | Event | Fires when |
+|-----------|-------|-----------|
+| `inputactiondata_t` | `onPressed`, `onReleased` | Action button state changes |
+| `uitextbox_t` | `onPageComplete` | Typewriter scroll reveals the full page |
+| `uitextbox_t` | `onLastPage` | Last page is fully scrolled |
+| `uifullbox_t` | `onTransitionEnd` | Colour transition animation completes |
+| `uiloading_t` | `onShow` / `onHide` | Loading indicator fade completes |
+| Asset system | `assetbatch_t` callback | All entries in a batch reach LOADED/ERROR |
+
+See `.claude/ui.md` for the UI event details.

.claude/input.md

@@ -0,0 +1,187 @@
+# Input System
+
+Source: `src/dusk/input/`, platform layers in `src/dusk<platform>/input/`
+
+## Architecture
+
+The input system has two layers:
+
+1. **Action layer** (`inputaction_t`) -- named gameplay inputs, e.g.
+   UP, DOWN, ACCEPT, CANCEL. This is what game code reads.
+2. **Button layer** (`inputbutton_t`) -- physical hardware inputs, e.g.
+   keyboard key, gamepad button, analog axis, mouse axis. Multiple
+   buttons can bind to the same action (the highest value wins).
+
+The platform layer implements two hooks:
+- `inputUpdatePlatform()` -- read hardware state once per frame
+- `inputButtonGetValuePlatform()` -- return the analog value [0.0, 1.0]
+  for a given button
+
+## Defined actions
+
+Actions are defined in `src/dusk/input/input.csv` and code-generated
+into the `inputaction_t` enum. Current values:
+
+| Constant | Meaning |
+|----------|---------|
+| `INPUT_ACTION_NULL` | Invalid / sentinel (0) |
+| `INPUT_ACTION_UP` | Up direction |
+| `INPUT_ACTION_DOWN` | Down direction |
+| `INPUT_ACTION_LEFT` | Left direction |
+| `INPUT_ACTION_RIGHT` | Right direction |
+| `INPUT_ACTION_ACCEPT` | Confirm / primary action |
+| `INPUT_ACTION_CANCEL` | Back / secondary action |
+| `INPUT_ACTION_RAGEQUIT` | Quit the application |
+| `INPUT_ACTION_CONSOLE` | Toggle debug console |
+| `INPUT_ACTION_POINTERX` | Mouse / pointer X axis |
+| `INPUT_ACTION_POINTERY` | Mouse / pointer Y axis |
+| `INPUT_ACTION_COUNT` | Total count (not a valid action) |
+
+## Global state
+
+```c
+extern input_t INPUT;
+// INPUT.actions[INPUT_ACTION_COUNT] -- all action states
+// INPUT.platform                   -- platform-specific data
+```
+
+## Reading actions (game code)
+
+```c
+// Analog value this frame (0.0 - 1.0)
+float_t inputGetCurrentValue(inputaction_t action);
+
+// Analog value last frame
+float_t inputGetLastValue(inputaction_t action);
+
+// Boolean helpers (built on current/last values)
+bool_t inputIsDown(inputaction_t action);
+bool_t inputWasDown(inputaction_t action);
+bool_t inputPressed(inputaction_t action);   // was up, now down
+bool_t inputReleased(inputaction_t action);  // was down, now up
+
+// Single axis from a neg + pos pair of actions (returns [-1, 1]):
+float_t inputAxis(inputaction_t neg, inputaction_t pos);
+
+// 2D axis from four actions (negX/posX/negY/posY):
+void inputAxis2D(
+  inputaction_t negX, inputaction_t posX,
+  inputaction_t negY, inputaction_t posY,
+  vec2 result
+);
+
+// Same four-action axis, normalized to a unit vector via atan2:
+void inputAngle2D(
+  inputaction_t negX, inputaction_t posX,
+  inputaction_t negY, inputaction_t posY,
+  vec2 result
+);
+
+// Deadzone filter (applied to raw axis values)
+float_t inputDeadzone(float_t value, float_t deadzone);
+```
+
+## Binding buttons to actions
+
+```c
+void inputBind(inputaction_t action, inputbutton_t button);
+```
+
+Each platform's init function calls `inputBind` to wire its hardware
+buttons to the standard action IDs. Game code should never need to call
+`inputBind` -- it is set up once during platform init.
+
+## Button types
+
+```c
+INPUT_BUTTON_TYPE_KEYBOARD   // SDL scancode (SDL2 targets only)
+INPUT_BUTTON_TYPE_POINTER    // Mouse axes: X, Y, Z, WHEEL_X, WHEEL_Y
+INPUT_BUTTON_TYPE_TOUCH      // Touch (defined, not fully implemented)
+INPUT_BUTTON_TYPE_GAMEPAD    // Digital gamepad buttons
+INPUT_BUTTON_TYPE_GAMEPAD_AXIS  // Analog axes (-1.0 to 1.0 internally)
+```
+
+## Events
+
+Each action has `onPressed` and `onReleased` event callbacks. Subscribe
+via the event system (see `.claude/events.md`):
+
+```c
+eventSubscribe(&INPUT.actions[ACTION_ACCEPT].onPressed, myCallback, NULL);
+```
+
+## Platform implementations
+
+### SDL2 (`src/dusksdl2/input/`)
+
+Handles Linux, Knulli, and PSP (PSP adds its own button mapping layer
+on top of SDL2).
+
+- Keyboard: SDL scancode array from `SDL_GetKeyboardState()`
+- Pointer: normalized mouse position (0.0-1.0), scroll axes
+- Gamepad: first available `SDL_GameController`; axis values normalized
+  to [-1.0, 1.0] with deadzone (default 0.2f via `inputGetDeadzoneSDL2`)
+
+### Dolphin -- GameCube / Wii (`src/duskdolphin/input/`)
+
+Uses `libogc` PAD API. No keyboard or pointer input -- trying to use
+those button types is a compile-time `#error`.
+
+- Gamepad: `PAD_ScanPads()` + `PAD_ButtonsHeld()` for pad 0
+- Axes: left stick X/Y, C-stick X/Y, L/R triggers (6 total)
+- Deadzone: hardcoded 0.2f
+- Default bindings set at init: D-pad/L-stick = directional actions,
+  A = ACCEPT, B = CANCEL, X = CONSOLE, Start = RAGEQUIT
+
+### PSP (`src/duskpsp/input/`)
+
+Layered on top of SDL2. `inputInitPSP()` remaps SDL2 controller button
+constants to PSP button names, then calls `inputBind` to wire them:
+
+| PSP button | SDL2 constant |
+|------------|---------------|
+| Cross | `SDL_CONTROLLER_BUTTON_A` |
+| Circle | `SDL_CONTROLLER_BUTTON_B` |
+| Triangle | `SDL_CONTROLLER_BUTTON_Y` |
+| Square | `SDL_CONTROLLER_BUTTON_X` |
+| L / R | `SDL_CONTROLLER_BUTTON_LEFTSHOULDER` / `RIGHTSHOULDER` |
+| L-Stick | `SDL_CONTROLLER_AXIS_LEFTX/Y` |
+
+### Vita (`src/duskvita/input/`)
+
+Layered on top of SDL2 (via vitaSDL2). Behaviour is similar to PSP --
+no keyboard, no pointer, gamepad only.
+
+## JS module (`Input`)
+
+The input system is exposed to JS as the global `Input` object with
+static methods. Action constants are pre-defined as numeric properties
+on the `Input` object (e.g. `Input.ACCEPT`, `Input.UP`):
+
+```js
+// Check if the accept button is held this frame:
+if(Input.isDown(Input.ACCEPT)) { ... }
+
+// Was the cancel button just pressed?
+if(Input.pressed(Input.CANCEL)) { ... }
+
+// Analog value for the right trigger:
+var val = Input.getValue(Input.RIGHT);
+
+// Single axis (-1 to 1) from a neg/pos pair:
+var h = Input.axis(Input.LEFT, Input.RIGHT);
+```
+
+All `Input.*` action constants match the `INPUT_ACTION_*` enum values
+from the C layer (UP, DOWN, LEFT, RIGHT, ACCEPT, CANCEL, RAGEQUIT,
+CONSOLE, POINTERX, POINTERY).
+
+## Platform capability notes
+
+| Feature | Linux/Knulli | PSP | Vita | GameCube/Wii |
+|---------|-------------|-----|------|--------------|
+| Keyboard | Yes (SDL2) | No | No | No |
+| Pointer/Mouse | Yes (SDL2) | No | No | No |
+| Gamepad | Yes (SDL2) | Yes (SDL2) | Yes (SDL2) | Yes (PAD) |
+| Analog axes | Yes | L-Stick only | L-Stick, R-Stick | L-Stick, C-Stick, Triggers |
+| Touch | Defined, not implemented | -- | -- | -- |

.claude/locale.md

@@ -0,0 +1,90 @@
+# Locale System
+
+Source: `src/dusk/locale/`, asset loader at
+`src/dusk/asset/loader/locale/`
+
+## Overview
+
+The locale system loads Gettext PO files from the asset archive and
+provides string lookup with plural-form support and printf-style
+argument substitution. Locale files live in `locale/` inside `dusk.dsk`.
+
+## Global state
+
+```c
+extern localemanager_t LOCALE;
+// LOCALE.locale  -- currently active localeinfo_t
+// LOCALE.entry   -- locked assetentry_t for the current PO file
+```
+
+## Initialise and switch locale
+
+```c
+errorret_t localeManagerInit();
+// Defaults to LOCALE_EN_US (locale/en_US.po).
+
+errorret_t localeManagerSetLocale(const localeinfo_t *locale);
+// Unlocks the old entry, loads and locks the new one.
+// Blocks until the new PO file is fully parsed.
+
+void localeManagerDispose();
+```
+
+## Getting a localised string
+
+```c
+// Variadic (printf-style args):
+localeManagerGetText(id, buffer, bufferSize, plural, ...);
+
+// With a pre-built args array:
+localeManagerGetTextArgs(id, buffer, bufferSize, plural, args, argCount);
+```
+
+Both are macros that delegate to `assetLocaleGetStringWithVA` /
+`assetLocaleGetStringWithArgs`.
+
+- `id` -- message ID string (the English key in the PO file)
+- `plural` -- plural index (0 for singular, 1+ per PO plural rules)
+- `buffer` -- destination `char_t` array
+- `bufferSize` -- size of the destination buffer
+- `...` -- format arguments matching `%s`, `%d`, `%f` placeholders
+
+## Locale descriptors (`localeinfo_t`)
+
+```c
+typedef struct {
+  const char_t *name;  // e.g. "en-US"
+  const char_t *file;  // path inside dusk.dsk, e.g. "locale/en_US.po"
+} localeinfo_t;
+```
+
+The built-in descriptor is:
+
+```c
+static const localeinfo_t LOCALE_EN_US = {
+  .name = "en-US",
+  .file = "locale/en_US.po",
+};
+```
+
+Add new locales by declaring another `localeinfo_t` constant and
+shipping the corresponding `.po` file in the asset archive.
+
+## PO file format notes
+
+The loader (`assetlocaleloader`) parses standard Gettext PO syntax:
+- `msgid` / `msgstr` pairs
+- `msgid_plural` / `msgstr[n]` for plural forms
+- The `Plural-Forms:` header (e.g. `nplurals=2; plural=(n != 1);`)
+  is parsed and evaluated at lookup time
+
+Argument substitution uses `%s`, `%d`, `%f` placeholders (not
+standard Gettext `%1` positional args).
+
+## Adding a new locale
+
+1. Create `locale/<lang_COUNTRY>.po` with a valid `Plural-Forms:`
+   header and the translated `msgid`/`msgstr` entries.
+2. Pack it into `dusk.dsk`.
+3. Add a `localeinfo_t` constant in `localeinfo.h`.
+4. Call `localeManagerSetLocale()` with the new descriptor to activate.

.claude/network.md

@@ -0,0 +1,132 @@
+# Network System
+
+Source: `src/dusk/network/`, platform layers in
+`src/dusk<platform>/network/`
+
+## Overview
+
+The network system provides a platform-agnostic API for detecting and
+managing a network connection. Higher-level functionality (HTTP, sockets)
+is not yet implemented in any platform. The system handles the
+connection lifecycle -- connect, detect disconnect, disconnect -- and
+reports the current IP address.
+
+## Implementation status by platform
+
+| Platform | Connection | IP info | HTTP/Requests | Notes |
+|----------|-----------|---------|--------------|-------|
+| **Linux** | Auto (OS) | IPv4 + IPv6 | Not implemented | `getifaddrs()` |
+| **Knulli** | Auto (OS) | IPv4 + IPv6 | Not implemented | same as Linux |
+| **PSP** | Manual dialog | IPv4 only | Not implemented | `sceUtilityNetconf`; SSL/HTTP modules commented out |
+| **GameCube** | Manual DHCP | IPv4 only | Not implemented | `if_config()` stubbed; `net_init()` commented out |
+| **Wii** | Manual DHCP | IPv4 only | Not implemented | blocking `if_config()` via System Menu Wi-Fi settings |
+
+## Connection states
+
+```c
+typedef enum {
+  NETWORK_STATE_DISCONNECTED,
+  NETWORK_STATE_CONNECTING,
+  NETWORK_STATE_CONNECTED,
+  NETWORK_STATE_DISCONNECTING,
+} networkstate_t;
+```
+
+## Global state
+
+```c
+extern network_t NETWORK;
+// NETWORK.state         -- current connection state
+// NETWORK.platform      -- platform-specific data
+// NETWORK.onDisconnect  -- callback fired on unexpected disconnect
+```
+
+## Core API (`network.h`)
+
+```c
+errorret_t networkInit();
+errorret_t networkUpdate();   // call each frame; detects dropped connections
+errorret_t networkDispose();
+
+bool_t networkIsConnected();
+
+void networkRequestConnection(
+  void (*onConnected)(void *user),
+  void (*onFailed)(errorret_t error, void *user),
+  void (*onDisconnect)(errorret_t error, void *user),
+  void *user
+);
+
+void networkRequestDisconnection(
+  void (*onComplete)(void *user),
+  void *user
+);
+```
+
+On platforms that manage their own connection (Linux, macOS, Windows),
+`networkRequestConnection` immediately calls `onConnected` if a network
+interface is up, or `onFailed` if not. No `networkPlatformRequestConnection`
+macro is needed.
+
+On platforms that require explicit connection (PSP, Wii), the platform
+implements `networkPlatformRequestConnection` and
+`networkPlatformRequestDisconnection`.
+
+## Network info
+
+```c
+networkinfo_t networkGetInfo();
+// Only valid when NETWORK.state == NETWORK_STATE_CONNECTED.
+```
+
+```c
+typedef struct {
+  networktype_t type;   // NETWORK_TYPE_IPV4 or (ifdef) NETWORK_TYPE_IPV6
+  union {
+    networkinfoipv4_t ipv4;  // uint8_t ip[4]
+    networkinfoipv6_t ipv6;  // uint8_t ip[16] (requires DUSK_NETWORK_IPV6)
+  };
+} networkinfo_t;
+```
+
+IPv6 support requires the `DUSK_NETWORK_IPV6` compile-time define.
+
+## Platform-specific notes
+
+### Linux / Knulli
+
+Fully functional for connection detection and IP querying. No explicit
+connect/disconnect step needed -- the OS manages the interface. Uses
+`getifaddrs()` to find the first non-loopback running interface.
+
+### PSP
+
+Connection is asynchronous and driven by a state machine in
+`networkPSPUpdate()`. The PSP shows the built-in network configuration
+dialog (`sceUtilityNetconfInitStart`) to let the user pick a Wi-Fi
+access point.
+
+HTTP/SSL modules (`psphttp`, `pspssl`) are loaded in commented-out code
+-- the infrastructure for HTTP exists but is disabled.
+
+### GameCube
+
+`net_init()` is commented out. Networking on GameCube is non-functional
+in the current build.
+
+### Wii
+
+Uses `if_config()` (DHCP via libogc) to connect using the Wi-Fi settings
+stored in Wii System Menu. This call **blocks** the main thread. The
+connection only works when `DUSK_WII` is defined; the GameCube path
+always fails.
+
+## Adding a new platform implementation
+
+1. Create `src/dusk<platform>/network/network<platform>.h/.c`.
+2. Implement the five required functions:
+   `Init`, `Update`, `Dispose`, `IsConnected`, `GetInfo`.
+3. Optionally implement `RequestConnection` and `RequestDisconnection`
+   if the platform requires an explicit connection step.
+4. Create `networkplatform.h` mapping each `networkPlatform*` macro to
+   your functions, and defining `networkplatform_t`.

.claude/optimization.md

@@ -0,0 +1,83 @@
+# Optimization Guidelines
+
+Dusk must run well on severely resource-constrained hardware. The PSP
+has 32 MB of RAM and a 333 MHz MIPS CPU. The GameCube has 24 MB of RAM
+and a 485 MHz PowerPC CPU with no FPU for integer paths. Optimization
+is not an afterthought -- it is a first-class design constraint.
+
+## General principles
+
+- **Measure before optimizing.** Don't guess where bottlenecks are.
+  Profile on the actual target hardware when possible.
+- **Data-oriented design.** The ECS exists to enable cache-friendly
+  iteration over components. Keep hot data tightly packed (SoA over
+  AoS where it matters).
+- **Minimize allocations.** Dynamic allocation at runtime is expensive
+  and causes fragmentation. Prefer fixed-size pools, arenas, and
+  pre-allocated arrays.
+- **Avoid per-frame allocations.** Anything allocated and freed every
+  tick is a red flag. Use scratch buffers or static pools.
+- **Avoid recursion** on constrained targets -- stack is small.
+
+## Memory
+
+| Platform   | Total RAM   | Notes                             |
+|------------|-------------|-----------------------------------|
+| GameCube   | 24 MB       | 16 MB main + 8 MB "Aram" (audio)  |
+| Wii        | 88 MB       | 24 MB MEM1 + 64 MB MEM2           |
+| PSP        | 32 MB       | 4 MB reserved for OS              |
+| Vita       | 512 MB      | Much more headroom                |
+| Linux      | Host RAM    | Effectively unlimited             |
+
+Treat the GameCube 16 MB main RAM as the worst-case constraint when
+designing data structures and budgets.
+
+Always use `memoryAllocate` / `memoryFree` -- never `malloc` / `free`.
+The engine allocator tracks usage and can enforce budgets per platform.
+
+## Math
+
+- Prefer integer math over floating-point on platforms without an FPU.
+- Use fixed-point arithmetic (`int32_t` with a known scale) for physics
+  and animation on PSP/GameCube where FPU throughput is limited.
+- SIMD / VFPU (PSP) and paired-singles (GameCube) are available but
+  require platform-guarded code paths under `#ifdef DUSK_PSP` etc.
+- Avoid `double` entirely -- use `float_t` (32-bit) throughout.
+
+## Rendering
+
+- Batch draw calls aggressively. Every draw call has overhead on all
+  platforms; consoles are especially sensitive.
+- Minimize state changes (texture binds, shader switches, etc.).
+- Use display lists (GameCube/Wii) and vertex buffer objects (OpenGL)
+  to offload geometry to GPU memory.
+- Keep texture sizes powers of two. Non-PoT textures are unsupported
+  or have penalties on PSP and GameCube.
+
+## Asset loading
+
+- Assets are loaded asynchronously via the asset loader system. Do not
+  block the game loop waiting for assets.
+- Compress textures to the native format for each platform at build
+  time, not at runtime.
+- Stream large assets from the filesystem rather than loading them all
+  at startup.
+
+## Platform-specific notes
+
+### PSP
+- The Media Engine (ME) is a second CPU core -- use it for audio and
+  background decompression, not general logic.
+- VFPU gives 4-wide SIMD floats; use it for matrix and vector math.
+- Keep the uncached scratchpad (4 KB at 0x00010000) in mind for hot
+  temporary data.
+
+### GameCube / Wii
+- The GX display list pipeline is the primary rendering path; avoid
+  immediate-mode GX calls in the hot path.
+- Texture Compression (CMPR / S3TC equivalent) halves texture memory.
+- Wii: prefer MEM1 for GPU-accessed data; MEM2 for CPU-only buffers.
+
+### PSP / Vita
+- OpenGL ES has a subset of desktop OpenGL. Avoid extensions and
+  features that are not in the ES 1.1 / ES 2.0 core.

.claude/physics.md

@@ -0,0 +1,127 @@
+# Physics System
+
+Source: `src/dusk/physics/`, entity component at
+`src/dusk/entity/component/physics/entityphysics.h/.c`
+
+## Overview
+
+Dusk uses a lightweight, custom 3D physics simulation with no external
+library dependency. It is integrated with the ECS: only entities that
+have both a `COMPONENT_TYPE_PHYSICS` and a `COMPONENT_TYPE_POSITION`
+component participate in the simulation.
+
+## Shapes
+
+```c
+typedef enum {
+  PHYSICS_SHAPE_CUBE,     // Axis-aligned bounding box (AABB)
+  PHYSICS_SHAPE_SPHERE,
+  PHYSICS_SHAPE_CAPSULE,  // Y-axis aligned; radius + halfHeight
+  PHYSICS_SHAPE_PLANE,    // Infinite plane; normal + distance
+} physicshapetype_t;
+```
+
+All shape pairs are supported by the collision dispatch
+(`physicsTestShapeVsShape`). See `physicstest.h` for the individual
+test functions.
+
+## Body types
+
+```c
+typedef enum {
+  PHYSICS_BODY_STATIC,     // Never moves; immovable collision surface
+  PHYSICS_BODY_DYNAMIC,    // Driven by gravity, velocity, collisions
+  PHYSICS_BODY_KINEMATIC,  // Moved programmatically; collides but not
+                            // driven by the simulation (e.g. player)
+} physicsbodytype_t;
+```
+
+## World and gravity
+
+```c
+extern physicsworld_t PHYSICS_WORLD;
+// PHYSICS_WORLD.gravity -- default {0, -9.81, 0}
+```
+
+The simulation step is driven by `physicsManagerUpdate()`, which is
+called each fixed-timestep game loop tick. It skips dynamic-timestep
+sub-steps (`DUSK_TIME_DYNAMIC`).
+
+## Simulation phases (each step)
+
+1. **Integrate dynamics** -- apply gravity scaled by `gravityScale`,
+   advance velocity, update position.
+2. **Dynamic vs static/kinematic** -- resolve penetration and cancel
+   the normal velocity component.
+3. **Dynamic vs dynamic** -- split penetration 50/50; exchange
+   relative normal velocity.
+4. **Rebuild transforms** -- call `entityPositionRebuild()` for all
+   affected dynamic bodies.
+
+`PHYSICS_GROUND_THRESHOLD = 0.707f` -- a collision normal with a Y
+component above this value sets `onGround = true` on the dynamic body.
+
+## Entity component (`entityphysics_t`)
+
+```c
+typedef struct {
+  physicsbodytype_t type;
+  physicsshape_t shape;
+  vec3 velocity;
+  float_t gravityScale;  // default 1.0
+  bool_t onGround;       // set by the solver each step
+} entityphysics_t;
+```
+
+Default on init: DYNAMIC body, 0.5m half-extents AABB cube,
+`gravityScale = 1.0f`.
+
+### Component API
+
+```c
+entityphysics_t *entityPhysicsGet(entityid_t, componentid_t);
+
+void  entityPhysicsSetShape(entityid_t, componentid_t, physicsshape_t);
+physicsshape_t entityPhysicsGetShape(entityid_t, componentid_t);
+
+void  entityPhysicsSetVelocity(entityid_t, componentid_t, vec3);
+void  entityPhysicsGetVelocity(entityid_t, componentid_t, vec3 dest);
+void  entityPhysicsApplyImpulse(entityid_t, componentid_t, vec3);
+// No-op on STATIC bodies.
+
+bool_t entityPhysicsIsOnGround(entityid_t, componentid_t);
+void   entityPhysicsSetBodyType(entityid_t, componentid_t, physicsbodytype_t);
+physicsbodytype_t entityPhysicsGetBodyType(entityid_t, componentid_t);
+```
+
+## Collision detection primitives (`physicstest.h`)
+
+Each function returns `true` if overlapping and writes the push-out
+normal (pointing from B toward A) and penetration depth.
+
+| Function | Shapes |
+|----------|--------|
+| `physicsTestAabbVsAabb` | CUBE vs CUBE |
+| `physicsTestSphereVsSphere` | SPHERE vs SPHERE |
+| `physicsTestSphereVsAabb` | SPHERE vs CUBE |
+| `physicsTestSphereVsPlane` | SPHERE vs PLANE |
+| `physicsTestAabbVsPlane` | CUBE vs PLANE |
+| `physicsTestCapsuleVsSphere` | CAPSULE vs SPHERE |
+| `physicsTestCapsuleVsAabb` | CAPSULE vs CUBE |
+| `physicsTestCapsuleVsPlane` | CAPSULE vs PLANE |
+| `physicsTestCapsuleVsCapsule` | CAPSULE vs CAPSULE |
+| `physicsTestShapeVsShape` | Any pair via dispatch |
+
+Capsules are always Y-axis aligned. Planes are infinite (not half-spaces).
+
+## Limitations and known gaps
+
+- No rotation simulation -- bodies do not rotate from collisions.
+- No friction or damping model yet.
+- No sleeping / deactivation for resting bodies.
+- No broad-phase culling: the solver is O(n^2) per phase.
+  This is acceptable up to the ECS entity limit (64 entities) but must
+  be revisited if the entity count grows.
+- Capsule vs plane uses the bottom/top hemisphere centers as a
+  degenerate approximation -- accurate for large planes but
+  not for thin surfaces.

.claude/platform-dolphin.md

@@ -0,0 +1,288 @@
+# Platform -- Dolphin (GameCube and Wii)
+
+`DUSK_TARGET_SYSTEM`: `gamecube` / `wii`  
+Source layer: `src/duskdolphin/`  
+Renderer: libogc GX (native Nintendo hardware)
+
+---
+
+## Overview
+
+GameCube and Wii are collectively called the **Dolphin** targets. They
+share a single source layer (`src/duskdolphin/`) and a shared CMake base
+(`cmake/targets/dolphin.cmake`). Individual targets add `DUSK_GAMECUBE`
+or `DUSK_WII` on top.
+
+Both are **big-endian** PowerPC platforms. They do **not** use SDL2 or
+OpenGL -- rendering and input go through `libogc` (the open-source
+GameCube/Wii SDK) and the GX hardware API directly.
+
+---
+
+## Hardware
+
+| Attribute | GameCube | Wii |
+|-----------|---------|-----|
+| CPU | IBM PowerPC 750CL (Gekko), 485 MHz | IBM Broadway (Wii CPU), 729 MHz |
+| RAM | 24 MB (16 MB MEM1 + 8 MB ARAM) | 88 MB (24 MB MEM1 + 64 MB MEM2) |
+| GPU | ATI Flipper (GX) | ATI Hollywood (GX) |
+| Display | 640x480 (480p max) | 640x480 (480p/576i), 480p/1080i via component |
+| Storage | Memory Card (slots A/B), SD Gecko | SD card, USB, NAND |
+| Endian | Big-endian | Big-endian |
+
+Treat the **GameCube 16 MB MEM1** as the worst-case RAM budget for data
+structures shared between both targets.
+
+---
+
+## Compile-time macros
+
+| Macro | GameCube | Wii | Notes |
+|-------|---------|-----|-------|
+| `DUSK_DOLPHIN` | yes | yes | Set by `dolphin.cmake` |
+| `DUSK_GAMECUBE` | yes | no | |
+| `DUSK_WII` | no | yes | |
+| `DUSK_INPUT_GAMEPAD` | yes | yes | |
+| `DUSK_DISPLAY_WIDTH` | 640 | 640 | |
+| `DUSK_DISPLAY_HEIGHT` | 480 | 480 | |
+| `DUSK_THREAD_PTHREAD` | yes | yes | devkitPPC pthreads |
+| `DUSK_PLATFORM_ENDIAN_BIG` | yes | yes | Not set by cmake -- apply manually |
+| `DOL` | 1 | 1 | Build type token |
+| `ISO` | 2 | 2 | Build type token |
+| `DUSK_DOLPHIN_BUILD_TYPE` | `DOL` or `ISO` | `DOL` or `ISO` | |
+| `DUSK_DOLPHIN_BUILD_ISO` | if ISO mode | if ISO mode | |
+
+No `DUSK_SDL2`, no `DUSK_OPENGL`, no `DUSK_INPUT_KEYBOARD`,
+no `DUSK_INPUT_POINTER`, no `DUSK_TIME_DYNAMIC`.
+
+Attempting to use `DUSK_INPUT_KEYBOARD` or `DUSK_INPUT_POINTER` causes
+a compile-time `#error` in `inputdolphin.h`.
+
+---
+
+## Endianness
+
+**Both GameCube and Wii are big-endian.** This is the most critical
+platform difference from all other targets.
+
+- All binary asset data (`.dtf` tilesets, STL meshes, DTF headers, etc.)
+  must be byte-swapped when read on Dolphin.
+- Use `endianLittleToHost32` / `endianLittleToHost16` etc. from
+  `util/endian.h` when reading any multi-byte value from a file.
+- Save files are stored in little-endian order; the save stream handles
+  this transparently via the `saveFile*` macros.
+- Network data likewise needs endian conversion.
+
+See `.claude/util.md` (Endian section) for the full API.
+
+---
+
+## Display
+
+- Fixed 640x480 resolution, driven by GX (the hardware rasteriser).
+- Uses double-buffered framebuffers:
+  ```c
+  typedef struct {
+    void *frameBuffer[2];  // double-buffered
+    int_t whichFrameBuffer;
+    GXRModeObj *screenMode;
+    void *fifoBuffer;      // GX command FIFO, 256 KB
+  } displaydolphin_t;
+  ```
+- The GX pipeline uses display lists for efficient draw call batching --
+  avoid immediate-mode GX calls in the hot path.
+- `CONF_GetAspectRatio()` returns `CONF_ASPECT_4_3` on GameCube (always)
+  and the user's setting on Wii. Use `systemGetAspectRatioDolphin()`.
+
+---
+
+## Asset loading
+
+Two modes are selected at CMake configure time via
+`DUSK_DOLPHIN_BUILD_TYPE`:
+
+### DOL mode (default -- `DUSK_DOLPHIN_BUILD_TYPE=DOL`)
+
+Assets are loaded from `dusk.dsk` on a FAT filesystem -- SD card on Wii
+(via SD slot), or SD Gecko / SD adapter on GameCube. The loader searches
+these paths in order:
+
+```c
+"/", "/Dusk", "/dusk", "/DUSK",
+"/apps", "/apps/Dusk", "/apps/dusk", "/apps/DUSK",
+".", "./Dusk", "./dusk", ...
+```
+
+Uses `libfat` for filesystem access.
+
+### ISO mode (`DUSK_DOLPHIN_BUILD_TYPE=ISO`)
+
+`dusk.dsk` is read directly off the DVD disc via the libogc DVD driver
+(`assetdolphindvd.c`). Reads are 32-byte aligned:
+
+```c
+#define ASSET_DOLPHIN_DVD_ALIGN 32u
+```
+
+The DVD FST (file-system table) is parsed at init to locate the data
+file. All reads go through `assetDolphinDVDRead(offset, size)` which
+returns an aligned heap buffer that the caller must free.
+
+Post-build in ISO mode, `makedolphiniso.py` produces **three disc
+images** (NTSC-J, NTSC-U, PAL).
+
+---
+
+## Input
+
+Uses libogc `PAD` API. Only GameCube controllers are supported (port 0
+by default; up to 4 via `PAD_CHANMAX`).
+
+Available axes (6 total per controller):
+
+| Axis | Enum |
+|------|------|
+| Left stick X/Y | `INPUT_GAMEPAD_AXIS_LEFT_X/Y` |
+| C-stick X/Y | `INPUT_GAMEPAD_AXIS_C_X/Y` |
+| L trigger | `INPUT_GAMEPAD_AXIS_TRIGGER_LEFT` |
+| R trigger | `INPUT_GAMEPAD_AXIS_TRIGGER_RIGHT` |
+
+Axis values are normalised by dividing the raw 8-bit value by 128.0.
+Deadzone: 0.2 (hardcoded).
+
+Default bindings set at init: D-pad/left stick = directional actions,
+A = ACCEPT, B = CANCEL, X = CONSOLE, Start = RAGEQUIT.
+
+Wii Remote / Nunchuk / Classic Controller / Pro Controller are not yet
+implemented (noted as TODO in `inputdolphin.h`).
+
+---
+
+## Save system
+
+Uses the libogc Memory Card API (`CARD_*`) to read/write save slots.
+
+```c
+typedef struct {
+  card_file cardFile;
+  uint8_t cardBuffer[CARD_WORKAREA] __attribute__((aligned(32)));
+  bool_t mounted;
+} savedolphin_t;
+```
+
+- Default channel: `CARD_SLOTA` (Memory Card slot A).
+  Override via `SAVE_DOLPHIN_CHANNEL`.
+- Sector size: 8192 bytes (`SAVE_DOLPHIN_SECTOR_SIZE`).
+- Buffers must be 32-byte aligned (enforced by `__attribute__((aligned(32)))`).
+- Game code: `DUSK` (4 chars, override via `SAVE_DOLPHIN_GAME_CODE`).
+- The card must be mounted before any read/write. `saveInitDolphin()`
+  mounts slot A; failures are treated as "no save present".
+- Save stream handles little-endian encoding transparently -- all data
+  stored little-endian on the card even though the CPU is big-endian.
+
+---
+
+## Network
+
+### GameCube
+
+`net_init()` is commented out. Networking is **non-functional** on
+GameCube in the current codebase. The BBA (Broadband Adapter) link
+library is in a commented `# bba` in `gamecube.cmake`.
+
+### Wii
+
+Uses `if_config()` from libogc which reads Wi-Fi settings saved in the
+Wii System Menu. The call **blocks** the main thread until DHCP
+completes or fails. Wii network is available only when `DUSK_WII` is
+defined; the GameCube path always fails immediately.
+
+IPv6 is not supported on either Dolphin target.
+
+---
+
+## Time
+
+- No `DUSK_TIME_DYNAMIC`. All ticks are fixed 16 ms steps.
+- Tick source: `__SYS_GetSystemTime()` returns PowerPC bus ticks.
+- Real time: ticks converted to microseconds via `ticks_to_microsecs()`,
+  then offset from the GameCube epoch (2000-01-01 00:00:00) to the UNIX
+  epoch (1970-01-01 00:00:00) by adding **946 684 800 seconds**.
+- Timezone: always returned as 0 -- no timezone data without network time.
+
+---
+
+## System
+
+Language and aspect ratio queries:
+
+```c
+// Language (used for locale selection):
+systemGetLanguageDolphin();
+// -> SYS_GetLanguage() on GameCube
+// -> CONF_GetLanguage() on Wii
+
+// Aspect ratio:
+systemGetAspectRatioDolphin();
+// -> CONF_ASPECT_4_3 always on GameCube
+// -> CONF_GetAspectRatio() on Wii (4:3 or 16:9)
+```
+
+---
+
+## Build and toolchain
+
+Requires [devkitPro](https://devkitpro.org/) with `devkitPPC` and
+`libogc` installed.
+
+```sh
+# GameCube (SD card / DOL mode)
+cmake -B build \
+      -DDUSK_TARGET_SYSTEM=gamecube \
+      -DCMAKE_TOOLCHAIN_FILE=/opt/devkitpro/cmake/GameCube.cmake \
+      -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+
+# Wii (SD card / DOL mode)
+cmake -B build \
+      -DDUSK_TARGET_SYSTEM=wii \
+      -DCMAKE_TOOLCHAIN_FILE=/opt/devkitpro/cmake/Wii.cmake \
+      -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+
+# Either target in ISO mode
+cmake -B build \
+      -DDUSK_TARGET_SYSTEM=gamecube \
+      -DCMAKE_TOOLCHAIN_FILE=/opt/devkitpro/cmake/GameCube.cmake \
+      -DDUSK_DOLPHIN_BUILD_TYPE=ISO \
+      -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+```
+
+Post-build outputs (DOL mode): `Dusk.elf` + `Dusk.dol` (generated by
+`elf2dol`). Copy `Dusk.dol` and `dusk.dsk` to the SD card.
+
+Post-build outputs (ISO mode): `Dusk.dol` + disc images in
+`NTSC-J/`, `NTSC-U/`, `PAL/` subdirectories.
+
+Dependencies: libogc, devkitPPC, `fat` (DOL mode), cglm, zip, bz2,
+zstd, z, lzma, m.
+
+---
+
+## Gotchas
+
+- **Big-endian is the most common source of bugs** when porting code
+  from Linux. Always use `endian.h` utilities for file I/O and network.
+- Memory is tight on GameCube -- 16 MB MEM1 must hold code, stack, heap,
+  framebuffers (2x 640x480x2 bytes), and the GX FIFO (256 KB).
+- GX display lists are the correct rendering path; immediate-mode GX
+  calls carry heavy CPU overhead on the short FIFO pipeline.
+- The GameCube has no FPU for integer paths. Avoid `double`; use
+  `float_t` throughout.
+- `consoleInit` is shadowed to `consoleInitDolphin` to avoid conflicts
+  with the devkitPPC console API.
+- On GameCube `CONF_GetAspectRatio()` is always 4:3; the macro is
+  defined to return `CONF_ASPECT_4_3` unconditionally.
+- DVD reads must be 32-byte aligned and padded -- use
+  `ASSET_DOLPHIN_DVD_ALIGN_UP(n)` when computing read sizes in ISO mode.

.claude/platform-linux.md

@@ -0,0 +1,162 @@
+# Platform -- Linux and Knulli
+
+`DUSK_TARGET_SYSTEM`: `linux` / `knulli`  
+Source layer: `src/dusklinux/`  
+Renderer: OpenGL (Linux) / OpenGL ES via EGL (Knulli)
+
+---
+
+## Overview
+
+Linux is the primary development target. Knulli is a Linux-based handheld
+OS (e.g. Anbernic devices); it shares the `src/dusklinux/` layer entirely
+and differs only in the CMake target (OpenGL ES instead of desktop OpenGL,
+EGL instead of GLX, and no backtrace support).
+
+Both targets use SDL2 for windowing and input. The window is resizable on
+both (`DUSK_DISPLAY_SIZE_DYNAMIC`).
+
+---
+
+## Compile-time macros
+
+| Macro | Linux | Knulli |
+|-------|-------|--------|
+| `DUSK_LINUX` | yes | yes |
+| `DUSK_KNULLI` | no | yes |
+| `DUSK_SDL2` | yes | yes |
+| `DUSK_OPENGL` | yes | yes |
+| `DUSK_OPENGL_ES` | no | yes |
+| `DUSK_DISPLAY_SIZE_DYNAMIC` | yes | yes |
+| `DUSK_INPUT_KEYBOARD` | yes | yes |
+| `DUSK_INPUT_POINTER` | yes | yes |
+| `DUSK_INPUT_GAMEPAD` | yes | yes |
+| `DUSK_TIME_DYNAMIC` | yes | yes |
+| `DUSK_NETWORK_IPV6` | yes | no |
+| `DUSK_THREAD_PTHREAD` | yes | yes |
+| `DUSK_CONSOLE_POSIX` | yes | no |
+
+---
+
+## Display
+
+- Default logical resolution: **640x480** (`DUSK_DISPLAY_WIDTH_DEFAULT` /
+  `DUSK_DISPLAY_HEIGHT_DEFAULT`); game content renders at
+  `DUSK_DISPLAY_SCREEN_HEIGHT=240`.
+- Dynamic resize: the window can be resized at any time; the engine
+  letterboxes/scales the logical framebuffer to fit.
+- Screen mode is configurable via `SCREEN.mode` (see
+  `.claude/display-core.md`).
+- Knulli uses OpenGL ES (GLES2) linked via EGL. Avoid any desktop
+  OpenGL extensions that are not in the ES2 core.
+
+---
+
+## Asset loading
+
+`dusk.dsk` is located by searching a list of paths relative to the
+current working directory:
+
+```c
+static const char_t *ASSET_LINUX_SEARCH_PATHS[] = {
+  "%s",
+  "../%s",
+  "../../%s",
+  "data/%s",
+  "../data/%s",
+  NULL
+};
+```
+
+The first path where `dusk.dsk` is found wins. No packaging step is
+required on Linux -- run from the build directory or the project root.
+
+---
+
+## Input
+
+All three input types are supported:
+
+- **Keyboard** -- SDL scancode array via `SDL_GetKeyboardState()`.
+- **Pointer** -- mouse position normalized to [0, 1], scroll axes.
+- **Gamepad** -- first available `SDL_GameController`; axes normalized
+  to [-1, 1] with a 0.2 deadzone.
+
+See `.claude/input.md` for the full action/button API.
+
+---
+
+## Save system
+
+Save files are plain files written to disk.
+
+- Path: `./saves/save_N.dat` (override `SAVE_LINUX_PATH` to change the
+  directory at CMake configure time).
+- Format: `SAVE_LINUX_FILE_FORMAT = "%s/save_%u.dat"` where `%u` is the
+  slot index.
+- No OS-level dialog blocking -- saves are synchronous filesystem calls.
+- Endian: host byte order (little-endian on x86/ARM).
+
+---
+
+## Network
+
+- Connection is detected automatically via `getifaddrs()`. No explicit
+  connect step is needed.
+- `networkRequestConnection` immediately calls `onConnected` if any
+  non-loopback interface is up, `onFailed` otherwise.
+- IPv4 and IPv6 supported (`DUSK_NETWORK_IPV6`).
+
+---
+
+## Time
+
+- Tick source: `SDL_GetTicks64()`.
+- Real time: `clock_gettime(CLOCK_REALTIME)`.
+- Dynamic timestep enabled (`DUSK_TIME_DYNAMIC`).
+
+---
+
+## Threading
+
+pthreads (`DUSK_THREAD_PTHREAD`). Thread-local storage via `__thread`.
+
+---
+
+## Build and toolchain
+
+No cross-compiler needed -- use the host GCC/Clang.
+
+```sh
+# Debug build
+cmake -B build -DDUSK_TARGET_SYSTEM=linux -DCMAKE_BUILD_TYPE=Debug
+cmake --build build
+
+# Knulli (cross-compile to aarch64)
+cmake -B build \
+      -DDUSK_TARGET_SYSTEM=knulli \
+      -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/aarch64-linux-gnu.cmake \
+      -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+```
+
+Dependencies: `SDL2`, `OpenGL` (Linux) or `GLES2` + `EGL` (Knulli),
+`pthread`, `m`.
+
+---
+
+## Endianness
+
+Little-endian. Detected at CMake configure time via `TestBigEndian` and
+set as `DUSK_PLATFORM_ENDIAN_LITTLE` or `DUSK_PLATFORM_ENDIAN_BIG`.
+
+---
+
+## Gotchas
+
+- `DUSK_CONSOLE_POSIX` enables POSIX-specific assert backtracing (Linux
+  only; Knulli does not set it).
+- Knulli does not set `DUSK_NETWORK_IPV6` -- IPv6 may not be available
+  on handheld devices.
+- `DUSK_TIME_DYNAMIC` is set, so physics/networking skip dynamic sub-steps
+  by checking `if(TIME.dynamicUpdate) return;`.

.claude/platform-macos.md

@@ -0,0 +1,46 @@
+# Platform -- macOS
+
+`DUSK_TARGET_SYSTEM`: `macos`  
+Source layer: `src/duskmacos/` (planned, does not exist yet)  
+Status: **Planned -- not yet implemented**
+
+---
+
+## Overview
+
+macOS desktop is a planned target. No source layer, CMake target file,
+or toolchain exists yet. The intended architecture mirrors Linux: SDL2
+for windowing/input, OpenGL (or Metal via MoltenVK/SDL2) for rendering.
+
+---
+
+## Expected macros (when implemented)
+
+| Macro | Expected |
+|-------|---------|
+| `DUSK_MACOS` | yes |
+| `DUSK_SDL2` | yes |
+| `DUSK_OPENGL` | yes |
+| `DUSK_DISPLAY_SIZE_DYNAMIC` | yes |
+| `DUSK_INPUT_KEYBOARD` | yes |
+| `DUSK_INPUT_POINTER` | yes |
+| `DUSK_INPUT_GAMEPAD` | yes |
+| `DUSK_PLATFORM_ENDIAN_LITTLE` | yes |
+| `DUSK_TIME_DYNAMIC` | yes |
+| `DUSK_THREAD_PTHREAD` | yes |
+
+---
+
+## Notes
+
+- Will be little-endian (Apple Silicon and Intel x86-64).
+- Apple deprecated OpenGL on macOS in 10.14 (Mojave). The implementation
+  will need to either target the deprecated OpenGL path or use MoltenVK
+  (Vulkan-over-Metal) with an SDL2 OpenGL layer. This decision is
+  pending.
+- Save files will likely live in `~/Library/Application Support/`.
+- Expected to share `src/dusksdl2/` and `src/duskgl/` with Linux.
+- Toolchain: native Clang via Xcode Command Line Tools, or a
+  cross-compile from Linux with osxcross.
+
+Update this document when the macOS target is implemented.

.claude/platform-psp.md

@@ -0,0 +1,200 @@
+# Platform -- Sony PSP
+
+`DUSK_TARGET_SYSTEM`: `psp`  
+Source layer: `src/duskpsp/`  
+Renderer: OpenGL ES (legacy, via PSPGL/SDL2)
+
+---
+
+## Overview
+
+The PSP is a 32 MB MIPS-based handheld console running at up to 333 MHz.
+It uses SDL2 (ported to PSP) for windowing and OpenGL in legacy/fixed-
+function mode. The game binary and all assets are packaged together inside
+a `.pbp` file -- the PSP's native executable format.
+
+---
+
+## Hardware
+
+| Attribute | Value |
+|-----------|-------|
+| CPU | MIPS R4000 (Allegrex), up to 333 MHz |
+| RAM | 32 MB (4 MB reserved for OS) |
+| Display | 480x272, 16/32-bit colour |
+| Storage | Memory Stick (UMD for retail; MS for homebrew) |
+| Endian | Little-endian |
+
+---
+
+## Compile-time macros
+
+| Macro | Set |
+|-------|-----|
+| `DUSK_PSP` | yes |
+| `DUSK_SDL2` | yes |
+| `DUSK_OPENGL` | yes |
+| `DUSK_OPENGL_LEGACY` | yes |
+| `DUSK_INPUT_GAMEPAD` | yes |
+| `DUSK_PLATFORM_ENDIAN_LITTLE` | yes |
+| `DUSK_DISPLAY_WIDTH` | 480 |
+| `DUSK_DISPLAY_HEIGHT` | 272 |
+| `DUSK_THREAD_PTHREAD` | yes |
+
+No `DUSK_DISPLAY_SIZE_DYNAMIC` -- the resolution is fixed.  
+No `DUSK_INPUT_KEYBOARD`, no `DUSK_INPUT_POINTER`.
+
+---
+
+## Display
+
+- Fixed 480x272 resolution.
+- OpenGL legacy (fixed-function pipeline, `DUSK_OPENGL_LEGACY`).
+- Texture dimensions **must** be powers of two (use `mathNextPowTwo`).
+- VFPU (4-wide float SIMD) is available -- use it for matrix/vector hot
+  paths under `#ifdef DUSK_PSP`.
+
+---
+
+## Asset loading
+
+Assets are packed into the **PSAR** section of the `.pbp` file by the
+post-build `create_pbp_file()` CMake command. At runtime,
+`assetInitPBP()` locates and opens the PSAR from the running executable's
+path.
+
+The PBP format header:
+```c
+typedef struct {
+  char_t signature[4];  // "\0PBP"
+  uint32_t version;
+  uint32_t sfoOffset;
+  uint32_t icon0Offset;
+  uint32_t icon1Offset;
+  uint32_t pic0Offset;
+  uint32_t pic1Offset;
+  uint32_t snd0Offset;
+  uint32_t pspOffset;
+  uint32_t psarOffset;  // dusk.dsk starts here
+} assetpbpheader_t;
+```
+
+`assetpbp_t` holds the open file handle and parsed header. Asset paths
+inside the PSAR are ZIP paths within `dusk.dsk`.
+
+---
+
+## Input
+
+Layered on SDL2. `inputInitPSP()` maps PSP physical buttons to SDL2
+`SDL_CONTROLLER_BUTTON_*` constants:
+
+| PSP button | Action |
+|------------|--------|
+| Cross | Accept |
+| Circle | Cancel |
+| Triangle | - |
+| Square | - |
+| L / R | Shoulder buttons |
+| D-pad | Directional |
+| L-Stick | Analog axes |
+
+No keyboard or pointer input available. Attempting to use
+`INPUT_BUTTON_TYPE_KEYBOARD` on PSP is undefined behaviour.
+
+The PSP system setting `PSP_UTILITY_ACCEPT_CROSS` / `ACCEPT_CIRCLE`
+swaps the Cross and Circle button roles in OS dialogs -- read this via
+`systemPSPGetCrossButtonSetting()` if you need to match the system
+convention.
+
+---
+
+## Save system
+
+- Path: `ms0:/PSP/SAVEDATA/<TITLE_ID><slot>/save.dat`
+  (default title ID `DUSK00001`, configurable via `SAVE_PSP_TITLE_ID`).
+- Uses `sceIo` for file I/O -- no extra dialog required for raw reads.
+- PSP OS-level save/load dialogs (via `sceUtility`) are separate and
+  block the main loop when open (`systemGetActiveDialogType()` returns
+  `SYSTEM_DIALOG_TYPE_TICK_BLOCKING`).
+- Do not call save functions directly from game code during a dialog.
+
+---
+
+## Network
+
+Connection requires an explicit user Wi-Fi selection step via the PSP
+system network dialog (`sceUtilityNetconfInitStart`).
+
+```
+networkRequestConnection(onConnected, onFailed, onDisconnect, user);
+// -> shows PSP Wi-Fi selection dialog (blocking dialog type)
+// -> calls onConnected or onFailed when the dialog closes
+```
+
+HTTP and SSL modules (`psphttp`, `pspssl`, `pspnet_resolver`) are
+linked in `psp.cmake` but the HTTP implementation code is commented out.
+The infrastructure exists for future use.
+
+---
+
+## Time
+
+- Tick source: `SDL_GetTicks64()`.
+- Real time: `sceRtcGetCurrentTick()` (returns microseconds).
+- Dynamic timestep is **not** enabled (`DUSK_TIME_DYNAMIC` not set).
+  Every tick is a fixed 16 ms step.
+
+---
+
+## System dialogs
+
+PSP shows OS-level dialogs for:
+- Wi-Fi configuration (`networkRequestConnection`)
+- Save management (if using `sceUtility` save dialogs)
+
+Check `systemGetActiveDialogTypePSP()` to know whether the main loop
+should skip rendering or ticking.
+
+---
+
+## Build and toolchain
+
+Requires the [PSPDEV toolchain](https://github.com/pspdev/pspdev).
+Set `PSPDEV` in your environment before configuring.
+
+```sh
+cmake -B build \
+      -DDUSK_TARGET_SYSTEM=psp \
+      -DCMAKE_TOOLCHAIN_FILE=${PSPDEV}/lib/cmake/psp.cmake \
+      -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+```
+
+Post-build output: `Dusk.pbp` (executable + assets combined).
+
+Dependencies: SDL2-PSP, OpenGL-PSP, pspgu, pspctrl, pspdisplay,
+pspaudio, pspaudiolib, psputility, pspvfpu, pspvram, pspnet,
+pspnet_inet, pspnet_apctl, psphttp, pspssl, pspdebug, psphprm,
+mbedtls, mbedcrypto, lzma, zip, bz2, z.
+
+---
+
+## Endianness
+
+Little-endian. `DUSK_PLATFORM_ENDIAN_LITTLE` is set at compile time.
+No runtime endian check is needed.
+
+---
+
+## Gotchas
+
+- The PSP has only 28 MB of usable RAM after the OS. Keep asset budgets
+  tight -- see `.claude/optimization.md`.
+- VFPU instructions are not valid on threads other than the main thread
+  on some firmware versions. Use `assertIsMainThread` on any code that
+  calls VFPU intrinsics.
+- OpenGL legacy mode means no vertex/fragment shaders; rendering uses
+  the fixed-function pipeline via `pspgl`.
+- `DUSK_TIME_DYNAMIC` is absent -- physics always runs at exactly the
+  fixed step rate.

.claude/platform-vita.md

@@ -0,0 +1,173 @@
+# Platform -- PlayStation Vita
+
+`DUSK_TARGET_SYSTEM`: `vita`  
+Source layer: `src/duskvita/`  
+Renderer: vitaGL (OpenGL-over-GXM compatibility layer)
+
+---
+
+## Overview
+
+The PlayStation Vita is an ARM-based handheld with 512 MB of RAM and a
+960x544 OLED/LCD display. It uses SDL2 (ported to Vita) for input
+abstraction, but the graphics layer is vitaGL -- an OpenGL compatibility
+shim that translates OpenGL calls to Sony's native GXM API.
+
+The distribution format is a `.vpk` (Vita Package) file containing the
+signed executable and `dusk.dsk` bundled as `dusk.dsk` at the package
+root, accessible at `app0:/dusk.dsk` at runtime.
+
+---
+
+## Hardware
+
+| Attribute | Value |
+|-----------|-------|
+| CPU | ARM Cortex-A9 quad-core, ~444 MHz |
+| RAM | 512 MB |
+| Display | 960x544 |
+| Storage | Vita game card / memory card / internal flash |
+| Endian | Little-endian |
+
+---
+
+## Compile-time macros
+
+| Macro | Set |
+|-------|-----|
+| `DUSK_VITA` | yes |
+| `DUSK_SDL2` | yes |
+| `DUSK_OPENGL` | yes |
+| `DUSK_OPENGL_LEGACY` | yes |
+| `DUSK_INPUT_GAMEPAD` | yes |
+| `DUSK_PLATFORM_ENDIAN_LITTLE` | yes |
+| `DUSK_DISPLAY_WIDTH` | 960 |
+| `DUSK_DISPLAY_HEIGHT` | 544 |
+
+No `DUSK_DISPLAY_SIZE_DYNAMIC`, no `DUSK_TIME_DYNAMIC`,
+no `DUSK_INPUT_KEYBOARD`, no `DUSK_INPUT_POINTER`,
+no `DUSK_NETWORK_IPV6`.
+
+---
+
+## Display
+
+- Fixed 960x544 resolution.
+- vitaGL translates OpenGL calls to GXM. Some OpenGL calls are stubbed
+  out in `duskplatform.h` where vitaGL does not support them:
+
+  ```c
+  #define glDrawArrays(type, first, count)         ((void)0)
+  #define glDepthFunc(func)                        ((void)0)
+  #define glBlendFunc(sfactor, dfactor)            ((void)0)
+  #define glColorTableEXT(...)                     ((void)0)
+  ```
+
+  These stubs mean the Vita uses the fixed-function pipeline through
+  vitaGL. Do not rely on `glDrawArrays` or depth/blend state changes
+  being applied -- use the engine's `displaystate_t` flags instead
+  (see `.claude/display-shader.md`).
+- `DUSK_OPENGL_LEGACY` is set. Avoid shader-based features that are
+  not in the fixed-function ES1 subset.
+- Texture dimensions **must** be powers of two.
+
+---
+
+## Asset loading
+
+`dusk.dsk` is bundled inside the `.vpk` and mounted at `app0:/` by the
+Vita OS. The asset system opens it at the fixed path:
+
+```c
+#define ASSET_VITA_DSK_PATH "app0:/" ASSET_FILE_NAME
+```
+
+No path search is needed -- the file is always at that location.
+
+---
+
+## Input
+
+Uses SDL2 with Vita button mapping. Buttons map to SDL2 gamepad
+constants:
+
+| Vita button | SDL2 constant |
+|-------------|---------------|
+| Triangle | `SDL_CONTROLLER_BUTTON_Y` |
+| Cross | `SDL_CONTROLLER_BUTTON_A` |
+| Circle | `SDL_CONTROLLER_BUTTON_B` |
+| Square | `SDL_CONTROLLER_BUTTON_X` |
+| Start | `SDL_CONTROLLER_BUTTON_START` |
+| Select | `SDL_CONTROLLER_BUTTON_BACK` |
+| D-pad | `SDL_CONTROLLER_BUTTON_DPAD_*` |
+| L / R | `SDL_CONTROLLER_BUTTON_LEFTSHOULDER / RIGHTSHOULDER` |
+| L-Stick | `SDL_CONTROLLER_AXIS_LEFTX/Y` |
+
+Vita also has L2, R2, L3, R3 and touch surfaces -- not currently wired
+into the input system.
+
+---
+
+## Save system
+
+Uses `SceIofilemgr` (Vita filesystem API) for file I/O. Save data lives
+in the application's sandbox on the memory card. The stream API
+(`savestream_t`) handles all serialization with automatic CRC32 and
+little-endian encoding (see `.claude/save.md`).
+
+---
+
+## Network
+
+No network implementation exists in `src/duskvita/`. Network
+functionality is not currently available on Vita.
+
+---
+
+## Time
+
+No `src/duskvita/time/` directory exists -- the Vita time implementation
+falls back to the SDL2 time layer if available, or is not yet
+implemented.
+
+---
+
+## Build and toolchain
+
+Requires the [VITASDK](https://vitasdk.org/). Set `VITASDK` in your
+environment before configuring.
+
+```sh
+cmake -B build \
+      -DDUSK_TARGET_SYSTEM=vita \
+      -DCMAKE_TOOLCHAIN_FILE=$VITASDK/share/vita.cmake \
+      -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+```
+
+Post-build output: `Dusk.self` (signed executable) and `Dusk.vpk`
+(installable package containing the SELF + `dusk.dsk`).
+
+Title ID: `DUSK00001` (configurable via `VITA_TITLEID`).
+
+Dependencies: SDL2, vitaGL, mathneon, vitashark, kubridge, SceGxm,
+SceCtrl, SceAudio, SceTouch, SceRtc, SceAppUtil, zip, bz2, z, lzma.
+
+---
+
+## Endianness
+
+Little-endian. `DUSK_PLATFORM_ENDIAN_LITTLE` is set at compile time.
+
+---
+
+## Gotchas
+
+- vitaGL stubs several OpenGL calls. Always use the engine display state
+  API rather than calling `glBlendFunc` / `glDepthFunc` directly.
+- `DUSK_TIME_DYNAMIC` is not set -- all ticks are fixed-step 16 ms.
+- Threading: `pthread` is linked but `DUSK_THREAD_PTHREAD` is not
+  explicitly defined in `vita.cmake`. Verify threading behaviour before
+  relying on it.
+- The Vita implementation is less complete than Linux and PSP -- network
+  and time platform layers are absent. Contributions welcome.

.claude/platform-windows.md

@@ -0,0 +1,46 @@
+# Platform -- Windows
+
+`DUSK_TARGET_SYSTEM`: `windows`  
+Source layer: `src/duskwindows/` (planned, does not exist yet)  
+Status: **Planned -- not yet implemented**
+
+---
+
+## Overview
+
+Windows desktop is a planned target. No source layer, CMake target file,
+or toolchain exists yet. The intended architecture closely mirrors Linux:
+SDL2 for windowing/input, desktop OpenGL for rendering, pthreads (via
+MinGW or MSVC pthreads shim) for threading.
+
+---
+
+## Expected macros (when implemented)
+
+| Macro | Expected |
+|-------|---------|
+| `DUSK_WINDOWS` | yes |
+| `DUSK_SDL2` | yes |
+| `DUSK_OPENGL` | yes |
+| `DUSK_DISPLAY_SIZE_DYNAMIC` | yes |
+| `DUSK_INPUT_KEYBOARD` | yes |
+| `DUSK_INPUT_POINTER` | yes |
+| `DUSK_INPUT_GAMEPAD` | yes |
+| `DUSK_PLATFORM_ENDIAN_LITTLE` | yes |
+| `DUSK_TIME_DYNAMIC` | yes |
+| `DUSK_THREAD_PTHREAD` | yes |
+
+---
+
+## Notes
+
+- Will be little-endian (x86-64 Windows).
+- Expected to share `src/dusksdl2/` and `src/duskgl/` with Linux and
+  Knulli; only a thin `src/duskwindows/` layer for OS-specific
+  functionality (save paths, system dialogs) should be needed.
+- Save files will likely live in `%APPDATA%` or a sibling `saves/`
+  directory.
+- No cross-compiler needed; MSVC or MinGW-w64 on Windows or a
+  cross-compile from Linux.
+
+Update this document when the Windows target is implemented.

.claude/platforms.md

@@ -0,0 +1,98 @@
+# Platform Support
+
+Dusk targets a wide range of platforms, from modern desktops to classic
+handheld and home consoles. New platform targets will be added over time.
+
+## Platform index
+
+| Platform | `DUSK_TARGET_SYSTEM` | Status | Reference |
+|----------|----------------------|--------|-----------|
+| Linux | `linux` | Supported | `.claude/platform-linux.md` |
+| Knulli | `knulli` | Supported | `.claude/platform-linux.md` |
+| Windows | `windows` | Planned | `.claude/platform-windows.md` |
+| macOS | `macos` | Planned | `.claude/platform-macos.md` |
+| Sony PSP | `psp` | Supported | `.claude/platform-psp.md` |
+| PlayStation Vita | `vita` | Supported | `.claude/platform-vita.md` |
+| Nintendo GameCube | `gamecube` | Supported | `.claude/platform-dolphin.md` |
+| Nintendo Wii | `wii` | Supported | `.claude/platform-dolphin.md` |
+
+GameCube and Wii share the `src/duskdolphin/` layer and are collectively
+referred to as **Dolphin** targets throughout the codebase.
+
+---
+
+## Layer structure
+
+```
+src/dusk/          Core -- platform-agnostic game logic and ECS
+src/duskgl/        OpenGL abstraction (Linux, Knulli, PSP, Vita)
+src/dusksdl2/      SDL2 window + input (Linux, Knulli, PSP, Vita)
+src/dusklinux/     Linux + Knulli platform impl
+src/duskpsp/       PSP platform impl
+src/duskvita/      Vita platform impl
+src/duskdolphin/   GameCube + Wii platform impl
+```
+
+Dolphin is the only target that bypasses SDL2 and OpenGL entirely --
+it uses native libogc GX for rendering and PAD for input.
+
+---
+
+## Capability macros
+
+Each target sets a combination of these macros. Do not assume a
+capability is present without checking the appropriate macro.
+
+| Macro | Meaning |
+|-------|---------|
+| `DUSK_SDL2` | SDL2 is available |
+| `DUSK_OPENGL` | OpenGL is available |
+| `DUSK_OPENGL_ES` | OpenGL ES variant (Knulli) |
+| `DUSK_OPENGL_LEGACY` | Fixed-function OpenGL (PSP, Vita) |
+| `DUSK_INPUT_GAMEPAD` | Gamepad / controller input |
+| `DUSK_INPUT_KEYBOARD` | Keyboard input (Linux, Knulli only) |
+| `DUSK_INPUT_POINTER` | Mouse / pointer input (Linux, Knulli only) |
+| `DUSK_DISPLAY_SIZE_DYNAMIC` | Window is resizable (Linux, Knulli) |
+| `DUSK_TIME_DYNAMIC` | Dynamic timestep available (Linux, Knulli) |
+| `DUSK_THREAD_PTHREAD` | pthreads available |
+| `DUSK_NETWORK_IPV6` | IPv6 supported (Linux only) |
+| `DUSK_PLATFORM_ENDIAN_BIG` | Big-endian byte order |
+| `DUSK_PLATFORM_ENDIAN_LITTLE` | Little-endian byte order |
+| `DUSK_DOLPHIN` | Any Dolphin target |
+| `DUSK_DOLPHIN_BUILD_ISO` | Dolphin DVD-ISO asset mode |
+| `DUSK_CONSOLE_POSIX` | POSIX assert backtrace (Linux only) |
+
+---
+
+## Quick comparison
+
+| | Linux | Knulli | PSP | Vita | GameCube | Wii |
+|-|-------|--------|-----|------|----------|-----|
+| SDL2 | yes | yes | yes | yes | no | no |
+| OpenGL | desktop | ES2 | legacy | vitaGL | no | no |
+| Endian | little | little | little | little | **big** | **big** |
+| Dynamic resize | yes | yes | no | no | no | no |
+| Dynamic timestep | yes | yes | no | no | no | no |
+| Keyboard | yes | yes | no | no | no | no |
+| Pointer/mouse | yes | yes | no | no | no | no |
+| Network | full | full | partial | no | no | partial |
+| Save storage | file | file | MS/SAVEDATA | SceIo | Mem Card | SD/NAND |
+| Asset source | dsk file | dsk file | inside .pbp | inside .vpk | SD or DVD | SD or DVD |
+
+---
+
+## Abstraction pattern
+
+Platform-specific implementations are wired in via `#define` macros in
+each platform's `displayplatform.h`, `inputplatform.h`, etc., which the
+core calls through. Functions that a platform does not support are
+simply left undefined -- the core guards calls with `#ifdef`.
+
+## Adding platform-specific code
+
+- Put new code under `src/dusk<platform>/` in the matching subsystem
+  folder.
+- Gate any core call-site with `#ifdef DUSK_<PLATFORM>` or the
+  relevant capability macro.
+- Keep `src/dusk/` free of platform `#ifdef`s -- delegate through
+  the platform header macros instead.

.claude/save.md

@@ -0,0 +1,148 @@
+# Save System
+
+Source: `src/dusk/save/`, platform layers in `src/dusk<platform>/save/`
+
+## Overview
+
+The save system provides multi-slot persistent storage. Each slot
+maps to one `savefile_t`. Platform implementations handle the actual
+read/write (memory card on GameCube/Wii, EEPROM/flash on PSP,
+filesystem on Linux).
+
+## Global state
+
+```c
+extern save_t SAVE;
+// SAVE.files[SAVE_FILE_COUNT_MAX]  -- one per slot
+// SAVE.platform                    -- platform-specific state
+```
+
+## API
+
+```c
+errorret_t saveInit(void);
+errorret_t saveDispose(void);
+
+errorret_t saveLoad(uint8_t slot);    // read slot from storage -> SAVE.files[slot]
+errorret_t saveWrite(uint8_t slot);   // write SAVE.files[slot] -> storage
+errorret_t saveDelete(uint8_t slot);  // delete slot from storage
+
+bool_t     saveExists(uint8_t slot);  // true if a save file is present
+
+savefile_t *saveGet(uint8_t slot);    // pointer to the in-memory slot data
+```
+
+Slot indices are 0-based, range `[0, SAVE_FILE_COUNT_MAX - 1]`.
+
+## Save file structure (`savefile.h`)
+
+`savefile_t` is a plain struct written verbatim to storage. Keep it
+small and use fixed-width integer types (`uint8_t`, `int32_t`, etc.)
+to ensure cross-platform binary compatibility.
+
+**Endianness:** storage is always written in little-endian byte order.
+Use the `endian.h` utilities when reading fields on big-endian targets
+(GameCube, Wii). See `.claude/util.md`.
+
+**Versioning:** include a version field at the start of `savefile_t`.
+Check it on load and handle mismatches gracefully (reset to defaults
+rather than crashing on corrupt data).
+
+## Save stream (`savestream.h`)
+
+`savestream_t` is a cursor-based reader/writer used to serialize
+`savefile_t` to/from a raw byte buffer. Platform implementations
+use it to abstract the I/O layer.
+
+```c
+typedef struct {
+  bool_t found;
+  uint32_t checksum;
+  uint32_t expectedChecksum;
+  saveplatformstream_t platform;
+} savestream_t;
+```
+
+### Typed read/write macros
+
+Use the `saveFile*` macros inside `saveFileLoad` and `saveFileWrite`.
+All multi-byte values are stored in little-endian order; endian
+conversion is handled automatically.
+
+```c
+saveFileReadHeader(stream, headerBuf)
+saveFileWriteHeader(stream, headerBuf)
+
+saveFileReadVersion(stream, &version)
+saveFileWriteVersion(stream, &version)
+
+saveFileReadBool(stream, &boolField)
+saveFileWriteBool(stream, &boolField)
+
+saveFileReadInt8(stream, &i8)    saveFileWriteInt8(stream, &i8)
+saveFileReadUInt8(stream, &u8)   saveFileWriteUInt8(stream, &u8)
+saveFileReadInt16(stream, &i16)  saveFileWriteInt16(stream, &i16)
+saveFileReadUInt16(stream, &u16) saveFileWriteUInt16(stream, &u16)
+saveFileReadInt32(stream, &i32)  saveFileWriteInt32(stream, &i32)
+saveFileReadUInt32(stream, &u32) saveFileWriteUInt32(stream, &u32)
+saveFileReadInt64(stream, &i64)  saveFileWriteInt64(stream, &i64)
+saveFileReadUInt64(stream, &u64) saveFileWriteUInt64(stream, &u64)
+saveFileReadFloat(stream, &f)    saveFileWriteFloat(stream, &f)
+
+saveFileReadString(stream, buf, maxLen)
+saveFileWriteString(stream, str, maxLen)
+
+saveFileReadDate(stream, &epoch)
+saveFileWriteDate(stream, &epoch)
+```
+
+Each macro expands to `errorChain(saveStreamRead/WriteXxxImpl(...))`.
+A failing read/write propagates the error up from `saveFileLoad` /
+`saveFileWrite`.
+
+### Typical saveFileLoad / saveFileWrite pattern
+
+```c
+errorret_t saveFileLoad(savestream_t *stream, savefile_t *file) {
+  char_t header[SAVE_FILE_HEADER_SIZE];
+  saveFileReadHeader(stream, header);
+  saveFileReadVersion(stream, &file->version);
+  saveFileReadInt32(stream, &file->score);
+  // ... remaining fields ...
+  errorOk();
+}
+
+errorret_t saveFileWrite(savestream_t *stream, savefile_t *file) {
+  char_t header[SAVE_FILE_HEADER_SIZE] = SAVE_FILE_HEADER;
+  saveFileWriteHeader(stream, header);
+  saveFileWriteVersion(stream, &file->version);
+  saveFileWriteInt32(stream, &file->score);
+  // ... remaining fields ...
+  errorOk();
+}
+```
+
+After `saveFileWrite` completes, the platform layer calls
+`saveStreamFinalizeWriteImpl` which seeks back and writes the CRC32.
+After `saveFileLoad`, the platform calls `saveStreamVerifyChecksumImpl`
+to confirm the CRC matches.
+
+## Platform notes
+
+| Platform | Storage mechanism |
+|----------|------------------|
+| Linux | File in user home / working directory |
+| Knulli | File on filesystem |
+| PSP | EEPROM / memory stick via `sceIo` |
+| GameCube | Memory Card via libogc `CARD_*` API |
+| Wii | NAND filesystem via libogc or SD card |
+
+Platform-specific save implementations go in `src/dusk<platform>/save/`
+and are wired in via `save/saveplatform.h` macros.
+
+## PSP note
+
+PSP save dialogs are OS-level UI shown via `sceUtility`. When a dialog
+is open, `systemGetActiveDialogType()` returns a blocking type so the
+engine pauses the main loop. Never call save functions directly from
+game code without going through the engine's dialog guard.

.claude/scene.md

@@ -0,0 +1,138 @@
+# Scene System
+
+Source: `src/dusk/scene/`
+
+## Overview
+
+The scene system is the top-level coordinator for a running game state.
+It manages one active scene at a time. Scenes are JS scripts -- each
+scene is a `.js` asset file that exports an object with lifecycle hooks.
+The scene system loads, ticks, and tears down these scripts, while the
+C side runs the ECS and render pipeline on each tick.
+
+## Scene lifecycle (C side)
+
+```c
+extern scene_t SCENE;
+
+errorret_t sceneInit(void);     // initialise the scene manager
+errorret_t sceneUpdate(void);   // process pending transition, tick active scene
+errorret_t sceneRender(void);   // render entities + render pipeline + UI
+errorret_t sceneDispose(void);  // dispose the active scene immediately
+```
+
+`sceneUpdate` each tick:
+1. Checks for a pending scene transition and performs it (dispose old,
+   load and init new).
+2. Calls the JS scene's `update()` hook.
+3. Calls `entityManagerUpdate()` to fire all entity update callbacks.
+
+`sceneRender` each tick:
+1. Binds the screen.
+2. Calls `sceneRenderPipeline()` -- renders all entities with a
+   `COMPONENT_TYPE_RENDERABLE` in priority order.
+3. Renders UI.
+4. Calls the JS scene's `render()` hook (for any custom drawing).
+5. Unbinds the screen.
+
+## Scene lifecycle (JS side)
+
+A scene file exports a plain object with these optional hooks:
+
+```js
+var scene = {};
+
+scene.init = async function() {
+  // Load assets, create entities, set up state.
+  // May be async -- await asset loads here.
+};
+
+scene.update = function() {
+  // Called each fixed-timestep tick.
+};
+
+scene.render = function() {
+  // Called each render tick, after ECS renderables.
+};
+
+scene.dispose = function() {
+  // Clean up entities and state.
+};
+
+module.exports = scene;
+```
+
+See `CLAUDE.md` -- "JavaScript (asset scripts)" for JS style rules.
+
+## Render pipeline (`scenerenderpipeline.h`)
+
+`sceneRenderPipeline(cameraEntityId)` gathers all active
+`COMPONENT_TYPE_RENDERABLE` components, sorts them by effective
+priority, and draws each one using its shader.
+
+**Priority rules:**
+- `renderable.priority != 0` -- use that value directly.
+- `renderable.priority == 0` -- auto-derive: opaque geometry sorts
+  before transparent geometry; sprite batches sort before shader
+  materials; etc.
+- Lower priority number = drawn first (behind); higher = drawn last
+  (on top).
+
+The shader used for each renderable:
+- `ENTITY_RENDERABLE_TYPE_SPRITEBATCH` and `CUSTOM` default to
+  `SHADER_LIST_SHADER_UNLIT`.
+- `ENTITY_RENDERABLE_TYPE_SHADER_MATERIAL` uses the shader indexed by
+  `renderable.data.material.shaderType` in `SHADER_LIST_DEFS`.
+
+## Transitioning between scenes
+
+Scene transitions are handled entirely in JS via the `Scene` global.
+The `Scene` object is a singleton with:
+
+```js
+// Switch to a new scene. Calls dispose() on the current scene, then
+// init() on the new one. Both happen synchronously this tick.
+Scene.set(newSceneObject);
+
+// The current scene object (may be null):
+Scene.current
+```
+
+Typical scene-switch pattern:
+
+```js
+// Inside a scene's update or event handler:
+const nextScene = require("scenes/gameplay.js");
+Scene.set(nextScene);
+```
+
+`Scene.set` is synchronous -- it calls `dispose` on the old scene and
+`init` on the new scene before returning. If `init` needs async work
+(loading assets), use an async function and `await` inside `init`:
+
+```js
+nextScene.init = async function() {
+  await batch.load();  // wait for assets before proceeding
+};
+```
+
+The C side does not defer the transition; the switch happens inside
+the current `sceneUpdate` call.
+
+## Relationship to the engine loop
+
+```
+engineUpdate()
+  timeUpdate()
+  inputUpdate()
+  physicsManagerUpdate()
+  scriptUpdate()       <- runs JS microjobs
+  sceneUpdate()        <- JS update + ECS entity updates
+
+engineUpdate() -> sceneRender()
+  screenBind()
+  sceneRenderPipeline()  <- ECS renderables sorted by priority
+  uiRender()
+  sceneRender (JS hook)
+  screenUnbind / screenRender
+```

.claude/script-promises.md

@@ -0,0 +1,104 @@
+# Script -- Async Promises (`scriptpromisepend_t`)
+
+Source: `src/dusk/script/scriptpromisepend.h`
+
+See also: `.claude/script.md`
+
+---
+
+## Overview
+
+When a C module needs to resolve a JS `Promise` from an asynchronous
+C event (e.g. an asset finishing loading, a network response arriving),
+use `scriptpromisepend_t`. The pattern avoids heap allocation by using
+a fixed-size pending slot array declared in the module.
+
+---
+
+## Declaring the pending array
+
+```c
+#define MY_MODULE_PENDING_MAX 8
+static scriptpromisepend_t MY_PENDING[MY_MODULE_PENDING_MAX];
+static uint32_t MY_PENDING_COUNT = 0;
+```
+
+---
+
+## Add a pending promise
+
+Called from the JS-facing function that returns the Promise:
+
+```c
+jerry_value_t promise = jerry_create_promise();
+scriptPromisePendAdd(
+  MY_PENDING, &MY_PENDING_COUNT, MY_MODULE_PENDING_MAX,
+  key,      // opaque void * used to match the resolve/reject later
+  promise
+);
+return jerry_acquire_value(promise); // return a copy to the caller
+```
+
+The `key` should be a stable pointer that uniquely identifies the
+async operation -- e.g. an `assetentry_t *`, a network request handle,
+or a pointer to a fixed-size slot in the module.
+
+---
+
+## Resolve or reject
+
+Called when the C event fires, typically from `moduleUpdate` or an
+event callback:
+
+```c
+// On success:
+scriptPromisePendResolve(
+  MY_PENDING, &MY_PENDING_COUNT,
+  key, jerry_undefined()  // or a result value
+);
+
+// On failure:
+jerry_value_t err = jerry_create_error(
+  JERRY_ERROR_COMMON, (const jerry_char_t *)"reason"
+);
+scriptPromisePendReject(MY_PENDING, &MY_PENDING_COUNT, key, err);
+jerry_release_value(err);
+```
+
+Both macros remove the slot from the pending array after settling.
+
+---
+
+## Guard against double-submit
+
+```c
+if(scriptPromisePendHas(MY_PENDING, MY_PENDING_COUNT, key)) {
+  // already waiting -- return the existing promise or an error
+}
+```
+
+---
+
+## Module teardown
+
+Free all pending promises before cleaning up events or other state:
+
+```c
+scriptPromisePendFreeAll(MY_PENDING, &MY_PENDING_COUNT);
+```
+
+This rejects all still-pending promises and resets the count to 0.
+Call it from the module's `Dispose` function, **before** any backing
+data (asset entries, event subscriptions) is torn down.
+
+---
+
+## Design notes
+
+- `MY_MODULE_PENDING_MAX` sets a hard cap on concurrent async ops.
+  Exceeding it is a runtime assertion -- size the array to the maximum
+  realistic concurrency for the module.
+- The key is opaque (`void *`); the system does not dereference it.
+  A raw integer cast to `void *` is fine if no pointer is available.
+- `scriptUpdate()` runs the JerryScript microjob queue each frame,
+  which is what processes `.then()` chains after a resolve/reject.

.claude/script.md

@@ -0,0 +1,167 @@
+# Script System (JerryScript)
+
+Source: `src/dusk/script/`, modules at `src/dusk/script/module/`
+
+## Overview
+
+The engine embeds **JerryScript** as its scripting runtime. Game scenes
+and logic are authored in JavaScript (ES5 subset). The script system
+initialises JerryScript, registers all built-in C modules as JS globals,
+and runs the event loop each tick.
+
+The full rules for writing JS asset scripts are in `CLAUDE.md` under
+"JavaScript (asset scripts)". This doc covers the C-side module system.
+
+## Script lifecycle
+
+```c
+errorret_t scriptInit();    // start JerryScript, register all modules
+errorret_t scriptUpdate();  // run pending microjobs (call once per frame)
+errorret_t scriptDispose(); // shut down JerryScript
+
+errorret_t scriptExecString(const char_t *source);
+// Evaluate a JS source string in global scope.
+
+errorret_t scriptExecFile(const char_t *path);
+// Load + eval a script from the asset archive. Result cached by asset
+// system -- repeated calls with the same path do not re-execute.
+```
+
+## Module registration
+
+All C modules are initialised in `src/dusk/script/module/modulelist.c`:
+
+```c
+void moduleListInit(void);    // called by scriptInit
+void moduleListDispose(void); // called by scriptDispose
+```
+
+Each module's `Init` is called once. The module registers its
+properties and methods on `scriptproto_t` objects (see below), which
+become JS globals.
+
+## Writing a C module -- the `scriptproto_t` pattern
+
+A `scriptproto_t` represents a JS class prototype backed by a C struct.
+
+### 1. Declare in the header
+
+```c
+// moduleMything.h
+extern scriptproto_t MODULE_MYTHING_PROTO;
+
+// Init and dispose for the module itself:
+void moduleMyThingInit(void);
+void moduleMyThingDispose(void);
+```
+
+### 2. Implement
+
+```c
+// moduleMything.c
+scriptproto_t MODULE_MYTHING_PROTO;
+
+// JS-callable function using the convenience macro:
+moduleBaseFunction(myThingDoSomething) {
+  moduleBaseRequireArgs(1);
+  moduleBaseRequireNumber(0);
+  float_t x = moduleBaseArgFloat(0);
+  // ... do work ...
+  return jerry_undefined();
+}
+
+void moduleMyThingInit(void) {
+  scriptProtoInit(
+    &MODULE_MYTHING_PROTO,
+    "MyThing",    // JS global name; NULL to skip registration
+    sizeof(mything_t),
+    myThingCtor   // constructor handler, or NULL
+  );
+
+  // Instance methods:
+  scriptProtoDefineFunc(
+    &MODULE_MYTHING_PROTO, "doSomething", myThingDoSomething
+  );
+
+  // Instance property (get/set):
+  scriptProtoDefineProp(
+    &MODULE_MYTHING_PROTO, "x", myThingGetX, myThingSetX
+  );
+
+  // Static method:
+  scriptProtoDefineStaticFunc(
+    &MODULE_MYTHING_PROTO, "create", myThingCreate
+  );
+}
+```
+
+### 3. Register
+
+In `modulelist.c`: `#include` the header and call `moduleMyThingInit()`
+in `moduleListInit()` (and `Dispose` in `moduleListDispose()`).
+
+## `moduleBaseFunction` macro
+
+```c
+moduleBaseFunction(myFn) {
+  // callInfo, args[], argc available
+  moduleBaseRequireArgs(2);
+  moduleBaseRequireNumber(0);
+  moduleBaseRequireString(1);
+
+  float_t x = moduleBaseArgFloat(0);
+  int32_t n = moduleBaseArgInt(0);
+  bool_t  b = moduleBaseArgBool(0);
+  float_t opt = moduleBaseOptFloat(2, 0.0f);  // optional with default
+
+  // Error propagation:
+  errorret_t ret = someCall();
+  if(errorIsNotOk(ret)) return moduleBaseThrowError(ret);
+
+  return jerry_undefined();    // or jerry_boolean(true) etc.
+}
+```
+
+## Wrapping C values in JS objects
+
+```c
+// Create a JS object wrapping a copy of a C value:
+jerry_value_t obj = scriptProtoCreateValue(&MY_PROTO, &myValue);
+
+// Unwrap back to C pointer:
+mything_t *ptr = scriptProtoGetValue(&MY_PROTO, jsObj);
+// ptr is NULL if jsObj is not an instance of MY_PROTO.
+```
+
+## Utility helpers (`modulebase.h`)
+
+| Helper | Purpose |
+|--------|---------|
+| `moduleBaseThrow(msg)` | Return a JS TypeError |
+| `moduleBaseThrowError(ret)` | Convert `errorret_t` -> JS error |
+| `moduleBaseToString(val, buf, len)` | Jerry value -> C string |
+| `moduleBaseGetProp(obj, name)` | Get object property by name |
+| `moduleBaseWrapPointer(ptr)` | Wrap a raw pointer in a JS object |
+| `moduleBaseUnwrapPointer(val)` | Unwrap a raw pointer |
+| `moduleBaseSetValue(name, val)` | Set a global JS variable |
+| `moduleBaseSetNumber(name, n)` | Set a global JS number |
+| `moduleBaseSetInt(name, n)` | Set a global JS integer |
+| `moduleBaseDefineMethod(obj, name, fn)` | Add method to any JS object |
+| `moduleBaseDefineGlobalMethod(name, fn)` | Add method to global scope |
+
+## Async JS -- pending promises (`scriptpromisepend.h`)
+
+When a C module needs to resolve a JS `Promise` from an asynchronous
+C event, use `scriptpromisepend_t`. Each module declares a fixed-size
+pending slot array; the helpers add/resolve/reject by an opaque key.
+
+Full API and design notes: `.claude/script-promises.md`
+
+## Type declarations (`.d.ts`)
+
+Every module that is accessible from JS **must** have a corresponding
+TypeScript declaration file in `types/`. The CLAUDE.md checklist
+requires updating these whenever a `.c` module file changes.
+
+- Add `types/<category>/mymod.d.ts`
+- Add `/// <reference path="..." />` to `types/index.d.ts`

.claude/tests.md

@@ -0,0 +1,111 @@
+# Tests and Assertions
+
+## Test infrastructure
+
+Tests live in `test/` and mirror the `src/dusk/` directory structure.
+Enable with `-DDUSK_BUILD_TESTS=ON`. The test runner is **cmocka**.
+
+### Entry point
+
+Every test file includes `dusktest.h`, which pulls in `dusk.h` and
+`assert/assert.h`. When `DUSK_TEST_ASSERT` is defined, `assert.h`
+includes `cmocka.h` and redirects assertion failures through
+`mock_assert()` instead of calling `abort()`.
+
+### Test function signature
+
+```c
+static void test_something(void **state) {
+  // ... setup ...
+  // ... exercise ...
+  // ... assert ...
+  assert_int_equal(memoryGetAllocatedCount(), 0); // leak check
+}
+```
+
+### Registering and running tests
+
+```c
+int main(void) {
+  const struct CMUnitTest tests[] = {
+    cmocka_unit_test(test_errorThrow),
+    cmocka_unit_test(test_errorOk),
+  };
+  return cmocka_run_group_tests(tests, NULL, NULL);
+}
+```
+
+Use `cmocka_unit_test_setup_teardown()` when a test needs per-test
+setup or teardown callbacks.
+
+### Assertion mix
+
+Tests use **two** sets of assertion macros:
+
+| Origin | When to use |
+|--------|-------------|
+| cmocka: `assert_int_equal()`, `assert_non_null()` etc. | Validate results inside test functions |
+| Dusk: `assertTrue()`, `assertNotNull()` etc. | Exercise the code under test (these may fire and need catching) |
+
+To assert that a Dusk assertion fires, use cmocka's mock system:
+
+```c
+expect_assert_failure(assertTrueImpl(__FILE__, __LINE__, false, "msg"));
+```
+
+### Memory leak discipline
+
+Every test function must end by asserting:
+
+```c
+assert_int_equal(memoryGetAllocatedCount(), 0);
+```
+
+This ensures all allocations from the code under test were freed.
+
+---
+
+## Assertion system
+
+Source: `src/dusk/assert/`
+
+### Runtime vs test mode
+
+| Mode | Trigger | Effect on failure |
+|------|---------|-------------------|
+| Runtime (default) | Release / non-test builds | Logs the message + backtrace, then calls `abort()` |
+| Test (`DUSK_TEST_ASSERT`) | `-DDUSK_TEST_ASSERT` build flag | Routes through cmocka `mock_assert()` for controlled catching |
+| Faked (`DUSK_ASSERTIONS_FAKED`) | Defined by platform or test | All macros become no-ops (`((void)0)`) |
+
+### Available macros
+
+| Macro | Description |
+|-------|-------------|
+| `assertTrue(x, msg)` | Fails if `x` is false |
+| `assertFalse(x, msg)` | Fails if `x` is true |
+| `assertNotNull(ptr, msg)` | Fails if `ptr` is NULL |
+| `assertNull(ptr, msg)` | Fails if `ptr` is not NULL |
+| `assertUnreachable(msg)` | Unconditional failure; marks unreachable code |
+| `assertDeprecated(msg)` | Marks a code path as deprecated |
+| `assertStringEqual(a, b, msg)` | Fails if strings differ |
+| `assertStrLenMax(str, len, msg)` | Fails if `strlen(str) >= len` |
+| `assertStrLenMin(str, len, msg)` | Fails if `strlen(str) < len` |
+| `assertIsMainThread(msg)` | Fails if called from a non-main thread |
+| `assertNotMainThread(msg)` | Fails if called from the main thread |
+| `assertStructSize(type, size)` | Compile-time size check via `_Static_assert` |
+
+### Thread tracking
+
+`assertInit()` records the main thread ID (pthreads). The main-thread
+assertions compare against this stored ID. Call `assertInit()` once at
+startup before spawning any threads.
+
+### Usage guidelines
+
+- Prefer the specific macro over a bare `assertTrue` for clarity
+  (e.g. use `assertNotNull` instead of `assertTrue(ptr != NULL, ...)`).
+- Use `assertUnreachable` in `default:` cases of exhaustive switches.
+- Use `assertStructSize` to guard struct layouts that must match
+  a known binary format or a platform ABI.
+- Do not use asserts for expected error paths -- use `errorThrow`
+  instead. Asserts are for programmer mistakes, not runtime errors.

.claude/threading.md

@@ -0,0 +1,100 @@
+# Threading System
+
+Source: `src/dusk/thread/`
+
+## Platform support
+
+Threading currently requires **pthreads** (`DUSK_THREAD_PTHREAD`). The
+implementation lives in the core thread files and is guarded by that
+compile-time flag -- there are no separate per-platform thread
+directories.
+
+Thread-local storage uses the `THREAD_LOCAL` macro, which maps to
+`__thread` when pthreads is available. This is used by the error system
+to give each thread its own `ERROR_STATE`.
+
+## Thread lifecycle
+
+Threads follow a strict state machine:
+
+```
+STOPPED -> STARTING -> RUNNING -> STOP_REQUESTED -> STOPPED
+```
+
+- `threadStart()` -- blocking: starts the thread and waits until it
+  reaches RUNNING.
+- `threadStop()` -- blocking: requests stop and waits until STOPPED.
+- `threadStartRequest()` -- non-blocking equivalent of `threadStart`.
+- `threadStopRequest()` -- non-blocking equivalent of `threadStop`.
+
+The thread callback polls `threadShouldStop()` to know when to exit.
+Never kill a thread forcefully -- always let it stop cooperatively.
+
+## Thread API
+
+```c
+void threadInit(thread_t *thread, errorret_t (*callback)(thread_t *t));
+// Initialise; callback is the thread entry point.
+
+errorret_t threadStart(thread_t *thread);
+// Start and block until RUNNING.
+
+errorret_t threadStop(thread_t *thread);
+// Request stop, block until STOPPED.
+
+void threadStartRequest(thread_t *thread);
+void threadStopRequest(thread_t *thread);
+// Non-blocking variants.
+
+bool_t threadShouldStop(const thread_t *thread);
+// Call from inside the thread callback to know when to exit.
+```
+
+## Mutex API (`threadmutex.h`)
+
+Each `threadmutex_t` wraps a pthread mutex and a condition variable.
+
+```c
+void threadMutexInit(threadmutex_t *mutex);
+void threadMutexDispose(threadmutex_t *mutex);
+
+void threadMutexLock(threadmutex_t *mutex);
+void threadMutexUnlock(threadmutex_t *mutex);
+bool_t threadMutexTryLock(threadmutex_t *mutex);
+// Returns true if the lock was acquired; false if already held.
+
+void threadMutexWaitLock(threadmutex_t *mutex);
+// Block until signalled (like pthread_cond_wait).
+// Must be called while holding the lock.
+
+void threadMutexSignal(threadmutex_t *mutex);
+// Wake one waiter.
+```
+
+## Usage example
+
+```c
+static errorret_t workerCallback(thread_t *t) {
+  while(!threadShouldStop(t)) {
+    // do work
+  }
+  errorOk();
+}
+
+thread_t worker;
+threadInit(&worker, workerCallback);
+errorChain(threadStart(&worker));
+// ... later ...
+errorChain(threadStop(&worker));
+```
+
+## Thread safety rules
+
+- The error system (`ERROR_STATE`) is thread-local -- each thread has
+  its own error state. Do not pass `errorret_t` across thread
+  boundaries without copying the message and lines strings first.
+- Asset loading: the background thread calls `loadAsync`; the main
+  thread calls `loadSync`. Never call GPU or SDL functions from the
+  loader background thread.
+- Use `assertIsMainThread()` / `assertNotMainThread()` to guard
+  functions that have thread affinity requirements.

.claude/time.md

@@ -0,0 +1,115 @@
+# Time System
+
+Source: `src/dusk/time/`, platform layers in `src/dusk<platform>/time/`
+
+## Global state
+
+```c
+extern dusktime_t TIME;
+```
+
+```c
+typedef struct {
+  float_t delta;   // Fixed step size in seconds (DUSK_TIME_STEP)
+  float_t time;    // Accumulated game time in seconds
+
+  // Only present when DUSK_TIME_DYNAMIC is defined:
+  float_t lastNonDynamic;
+  bool_t dynamicUpdate;   // true on sub-step ticks
+  float_t dynamicDelta;   // real elapsed seconds this frame
+  float_t dynamicTime;    // accumulated real time
+} dusktime_t;
+```
+
+## Fixed vs dynamic timestep
+
+### Fixed timestep (default)
+
+`DUSK_TIME_STEP` defaults to `16ms / 1000 = 0.016f` seconds (62.5 Hz).
+Every call to `timeUpdate()` advances `TIME.time` by exactly
+`DUSK_TIME_STEP` and sets `TIME.delta = DUSK_TIME_STEP`. This is the
+safe, deterministic mode for physics and game logic.
+
+### Dynamic timestep (`DUSK_TIME_DYNAMIC`)
+
+When enabled, `timeUpdate()` calls the platform tick hook to measure
+actual elapsed time. It fires a "non-dynamic" step (`dynamicUpdate =
+false`, `delta = DUSK_TIME_STEP`) once per fixed interval, and
+"dynamic" sub-steps (`dynamicUpdate = true`) in between. Systems that
+must run on the fixed interval (physics, networking) skip the dynamic
+sub-steps by checking:
+
+```c
+if(TIME.dynamicUpdate) return;
+```
+
+## Platform hooks
+
+Each platform provides three macros in its `time/timeplatform.h`:
+
+| Macro | Purpose |
+|-------|---------|
+| `timeTickPlatform()` | Sample the hardware timer |
+| `timeGetDeltaPlatform()` | Return seconds since last tick |
+| `timeGetRealPlatform()` | Return epoch seconds since 1970 |
+| `timeGetRealTimeZonePlatform()` | Return local timezone offset (seconds) |
+
+`timeTickPlatform` and `timeGetDeltaPlatform` are only required when
+`DUSK_TIME_DYNAMIC` is defined.
+
+## Platform implementations
+
+| Platform | Tick source | Real time source |
+|----------|------------|-----------------|
+| Linux | `SDL_GetTicks64()` (via SDL2) | `clock_gettime(CLOCK_REALTIME)` |
+| Knulli | `SDL_GetTicks64()` (via SDL2) | `clock_gettime(CLOCK_REALTIME)` |
+| PSP | `SDL_GetTicks64()` (via SDL2) | `sceRtcGetCurrentTick()` (microseconds) |
+| GameCube | none (fixed step only) | `ticks_to_microsecs(__SYS_GetSystemTime())` + 2000->1970 offset |
+| Wii | none (fixed step only) | same as GameCube |
+
+GameCube / Wii note: the hardware timer returns ticks since
+2000-01-01, so an offset of 946684800 seconds is added to convert to
+UNIX epoch. The timezone offset is always returned as 0.0 on Dolphin
+(timezone is not available without network time).
+
+## Epoch time (`timeepoch.h`)
+
+```c
+typedef struct {
+  double_t time;        // raw UTC seconds since 1970
+  double_t timeZone;    // timezone offset in seconds
+  double_t offsetTime;  // time + timeZone
+} dusktimeepoch_t;
+
+dusktimeepoch_t timeGetEpoch(void);
+// Returns current time in local timezone.
+```
+
+### Epoch helpers
+
+```c
+int32_t timeEpochGetYear(epoch);
+int32_t timeEpochGetMonth(epoch);     // 1-12
+int32_t timeEpochGetDayOfMonth(epoch); // 1-31
+int32_t timeEpochGetHours(epoch);     // 0-23
+int32_t timeEpochGetMinutes(epoch);   // 0-59
+int32_t timeEpochGetSeconds(epoch);   // 0-59
+bool_t  timeEpochIsLeapYear(year);
+
+size_t timeEpochFormat(
+  dusktimeepoch_t epoch,
+  const char_t *format,  // %Y %m %d %H %M %S
+  char_t *buffer,
+  size_t bufferSize
+);
+```
+
+## Adding a new platform time implementation
+
+1. Create `src/dusk<platform>/time/time<platform>.h/.c`.
+2. Implement `timeGetReal<Platform>()` and
+   `timeGetRealTimeZone<Platform>()`.
+3. If `DUSK_TIME_DYNAMIC`: also implement `timeTick<Platform>()` and
+   `timeGetDelta<Platform>()`.
+4. Create `src/dusk<platform>/time/timeplatform.h` with the `#define`
+   macros pointing to your functions.

.claude/ui.md

@@ -0,0 +1,226 @@
+# UI System
+
+Source: `src/dusk/ui/`
+
+See also: `.claude/display-spritebatch.md`, `.claude/display-text.md`,
+`.claude/display-color.md`
+
+---
+
+## Overview
+
+The UI system renders overlaid interface elements on top of the scene
+each frame. It is called by the engine after the scene render pipeline
+and before the screen unbind -- game code does not drive it directly.
+
+All UI elements render through the global SpriteBatch.
+
+---
+
+## Lifecycle
+
+```c
+extern ui_t UI;
+
+errorret_t uiInit(void);
+void       uiUpdate(void);
+errorret_t uiRender(void);
+void       uiDispose(void);
+```
+
+`uiUpdate` is called each game tick; `uiRender` is called each render
+tick. The engine calls both automatically -- do not call them from
+game scripts.
+
+---
+
+## Element registration (`uielement.h`)
+
+```c
+typedef struct {
+  uielementtype_t type;  // UI_ELEMENT_TYPE_NULL or UI_ELEMENT_TYPE_NATIVE
+  errorret_t (*draw)();  // draw callback
+} uielement_t;
+
+extern uielement_t UI_ELEMENTS[];  // registered element array
+```
+
+`uiRender` iterates `UI_ELEMENTS` and calls each element's `draw`
+callback. Elements register themselves during `uiInit`.
+
+---
+
+## Elements
+
+### uiframe_t -- 9-slice border (`uiframe.h`)
+
+A resizable bordered panel rendered using 9-slice (9-patch) technique
+from a 3x3 tileset.
+
+```c
+typedef struct {
+  tileset_t tileset;
+  texture_t *texture;
+} uiframe_t;
+
+errorret_t uiFrameInit(uiframe_t *frame);
+
+errorret_t uiFrameDraw(
+  const uiframe_t *frame,
+  const float_t x,
+  const float_t y,
+  const float_t width,
+  const float_t height
+);
+
+void uiFrameDispose(uiframe_t *frame);  // does not dispose texture
+```
+
+`uiFrameDraw` pushes 9 quads (corners + edges + centre) to the
+SpriteBatch without flushing. The caller must call `spriteBatchFlush()`
+after all sprites for a draw pass are buffered.
+
+---
+
+### uitextbox_t -- typewriter dialogue box (`uitextbox.h`)
+
+A global single-instance dialogue box that displays text one character
+at a time with word-wrap and multi-page support.
+
+```c
+extern uitextbox_t UI_TEXTBOX;
+
+errorret_t uiTextboxInit(void);
+void       uiTextboxDispose(void);
+```
+
+**Setting text:**
+
+```c
+uiTextboxSetText("Hello, world!");
+// Automatically word-wraps and paginates.
+// Resets currentPage and scroll to 0.
+```
+
+**Tick update (called from script `update` or uiUpdate):**
+
+```c
+uiTextboxUpdate();
+// Advances typewriter by UI_TEXTBOX_SCROLL_CHARS_PER_TICK (1) each
+// fixed tick. Skipped on dynamic sub-ticks.
+```
+
+**Page control:**
+
+```c
+bool_t uiTextboxPageIsComplete(void);  // scroll revealed full page
+bool_t uiTextboxHasNextPage(void);     // more pages remain
+void   uiTextboxNextPage(void);        // advance; no-op on last page
+int32_t uiTextboxGetPageCharCount(void);
+```
+
+**Events:**
+
+```c
+// Fires when the current page is fully scrolled into view:
+UI_TEXTBOX.onPageComplete
+
+// Fires when the last page has been fully scrolled:
+UI_TEXTBOX.onLastPage
+```
+
+Subscribe via the event system (see `.claude/events.md`).
+
+**Limits:**
+
+| Constant | Value |
+|----------|-------|
+| `UI_TEXTBOX_TEXT_MAX` | 1024 chars |
+| `UI_TEXTBOX_LINES_MAX` | 64 lines |
+| `UI_TEXTBOX_LINES_PER_PAGE_MAX` | 3 lines per page |
+| `UI_TEXTBOX_SCROLL_CHARS_PER_TICK` | 1 char per tick |
+
+---
+
+### uifullbox_t -- full-screen colour overlay (`uifullbox.h`)
+
+An animated solid-colour overlay that covers the entire screen. Used
+for fade-to-black, scene transitions, and flash effects.
+
+Two global instances are provided:
+
+```c
+extern uifullbox_t UI_FULLBOX_UNDER;  // draws below scene content
+extern uifullbox_t UI_FULLBOX_OVER;   // draws above all content
+```
+
+```c
+void uiFullboxInit(uifullbox_t *fullbox);
+
+// Start a colour-to-colour transition:
+void uiFullboxTransition(
+  uifullbox_t *fullbox,
+  color_t from,
+  color_t to,
+  float_t duration,
+  easingtype_t easing
+);
+
+void       uiFullboxUpdate(uifullbox_t *fullbox, float_t delta);
+errorret_t uiFullboxDraw(uifullbox_t *fullbox);
+// Draw is skipped entirely when alpha == 0.
+```
+
+`fullbox.onTransitionEnd` event fires once when the transition
+completes. Subscribe to it to chain scene transitions:
+
+```c
+// Typical fade-out before a scene change:
+uiFullboxTransition(
+  &UI_FULLBOX_OVER,
+  COLOR_TRANSPARENT, COLOR_BLACK,
+  0.5f, EASING_OUT_QUAD
+);
+eventSubscribe(&UI_FULLBOX_OVER.onTransitionEnd, onFadeComplete, NULL);
+```
+
+---
+
+### uiloading_t -- loading indicator (`uiloading.h`)
+
+An animated loading indicator with fade-in / fade-out transitions.
+Shown while asset batches are loading.
+
+```c
+extern uiloading_t UI_LOADING;
+
+void uiLoadingInit(void);
+void uiLoadingUpdate(float_t delta);
+errorret_t uiLoadingDraw(void);
+
+// Fade in; callback fires when fully visible:
+void uiLoadingShow(eventcallback_t callback, void *user);
+
+// Fade out; callback fires when fully hidden:
+void uiLoadingHide(eventcallback_t callback, void *user);
+```
+
+`UI_LOADING_FADE_DURATION` is 0.5 seconds. `UI_LOADING_MARGIN` is 8px.
+`uiLoadingDraw` is a no-op when the indicator is fully transparent.
+
+---
+
+### uifps_t -- FPS counter (`uifps.h`)
+
+Debug FPS display. Measures real elapsed time between ticks and draws
+the average frame rate as text in the corner of the screen.
+
+```c
+extern uifps_t UIFPS;
+
+errorret_t uiFPSDraw();  // also performs the measurement update
+```
+
+Intended for debug builds only. Draw it explicitly from a JS `render`
+hook or from a UI element -- it is not registered in `UI_ELEMENTS` by
+default.

.claude/util.md

@@ -0,0 +1,191 @@
+# Utility Library
+
+Source: `src/dusk/util/`
+
+All C code in the project must use these utilities instead of their
+standard library equivalents. Do not use `malloc`, `free`, `strcmp`,
+`strcpy`, `memcpy`, `memset`, etc. directly.
+
+---
+
+## Memory (`memory.h`)
+
+```c
+void *memoryAllocate(size_t size);
+void *memoryAlign(size_t alignment, size_t size);  // aligned alloc
+void  memoryFree(void *ptr);
+void  memoryCopy(void *dest, const void *src, size_t size);
+void  memoryZero(void *dest, size_t size);
+errorret_t memoryCompare(const void *a, const void *b, size_t size);
+
+size_t memoryGetAllocatedCount(void);
+// Returns the number of live allocations. Must be 0 at test teardown.
+
+void memoryTrack(void *ptr);
+// Register a pointer that was malloc'd outside the engine (e.g. by a
+// third-party library) so it counts toward the allocation tracker.
+```
+
+`MEMORY_POINTERS_IN_USE` is a file-scope static tracking the live count.
+It is incremented by `memoryAllocate` / `memoryTrack` and decremented by
+`memoryFree`. Tests assert this is 0 at teardown to catch leaks.
+
+---
+
+## String (`string.h`)
+
+Use these instead of `<string.h>` / `<ctype.h>` functions:
+
+```c
+void   stringCopy(char_t *dest, const char_t *src, size_t destSize);
+int    stringCompare(const char_t *a, const char_t *b);
+bool_t stringEquals(const char_t *a, const char_t *b);
+int    stringCompareInsensitive(const char_t *a, const char_t *b);
+size_t stringLength(const char_t *str);
+void   stringTrim(char_t *str);
+bool_t stringIsWhitespace(char_t c);
+bool_t stringStartsWith(const char_t *str, const char_t *prefix);
+bool_t stringEndsWith(const char_t *str, const char_t *suffix);
+bool_t stringContains(const char_t *haystack, const char_t *needle);
+char_t *stringFind(const char_t *haystack, const char_t *needle);
+void   stringFormat(char_t *dest, size_t destSize, const char_t *fmt, ...);
+int32_t stringToInt(const char_t *str);
+float_t stringToFloat(const char_t *str);
+void    stringFromInt(char_t *dest, size_t destSize, int32_t value);
+void    stringFromFloat(char_t *dest, size_t destSize, float_t value);
+```
+
+`destSize` in `stringCopy` / `stringFormat` is the buffer capacity
+**excluding** the null terminator.
+
+---
+
+## Math (`math.h`)
+
+```c
+#define MATH_PI M_PI
+
+#define mathMax(a, b)
+#define mathMin(a, b)
+#define mathClamp(x, lower, upper)
+#define mathAbs(amt)
+
+uint32_t mathNextPowTwo(uint32_t value);
+float_t  mathModFloat(float_t x, float_t y);  // always non-negative
+float_t  mathLerp(float_t a, float_t b, float_t t);
+// plus additional trig / remap helpers
+```
+
+The project uses **cglm** for vector and matrix math (`vec3`, `mat4`,
+`glm_vec3_*`, `glm_mat4_*`, etc.). `math.h` provides scalar helpers
+that complement cglm.
+
+---
+
+## Endian (`endian.h`)
+
+GameCube and Wii are big-endian. Any binary data format (asset files,
+network packets) must use the endian utilities when reading multi-byte
+values.
+
+```c
+bool_t  isHostLittleEndian(void);
+uint16_t endianLittleToHost16(uint16_t value);
+uint32_t endianLittleToHost32(uint32_t value);
+uint64_t endianLittleToHost64(uint64_t value);
+float_t  endianLittleToHostFloat(float_t value);
+```
+
+If neither `DUSK_PLATFORM_ENDIAN_LITTLE` nor `DUSK_PLATFORM_ENDIAN_BIG`
+is defined, the implementation falls back to a runtime check
+(`ENDIAN_MAGIC` probe). Prefer setting the compile-time macro for new
+platform targets.
+
+---
+
+## Reference counting (`ref.h`)
+
+`ref_t` is a generic reference-counted handle with optional lock /
+unlock / all-unlocked callbacks.
+
+```c
+void refInit(
+  ref_t *ref,
+  void *data,
+  refcallback_t onLock,
+  refcallback_t onUnlock,
+  refcallback_t onAllUnlocked  // called when count -> 0; do cleanup here
+);
+
+void   refLock(ref_t *ref);      // increment count
+bool_t refUnlock(ref_t *ref);    // decrement; returns true if count == 0
+```
+
+The asset entry system uses `ref_t` internally to track how many
+subsystems have locked a loaded asset.
+
+---
+
+## Array (`array.h`)
+
+```c
+void arrayReverse(void *array, size_t count, size_t elementSize);
+```
+
+Generic in-place reverse using the element stride.
+
+---
+
+## Sort (`sort.h`)
+
+Use these instead of `qsort` for portability across all platforms.
+
+```c
+typedef int_t (*sortcompare_t)(const void *, const void *);
+
+void sortBubble(
+  void *array,
+  const size_t count,
+  const size_t size,
+  const sortcompare_t compare
+);
+
+void sortQuick(
+  void *array,
+  const size_t count,
+  const size_t size,
+  const sortcompare_t compare
+);
+
+#define sort sortQuick  // preferred; use this in new code
+```
+
+Typed convenience helpers for `uint8_t` arrays:
+
+```c
+int  sortArrayU8Compare(const void *a, const void *b);
+void sortArrayU8(uint8_t *array, const size_t count);
+```
+
+---
+
+## Crypt (`crypt.h`)
+
+CRC32 checksum for save file integrity. Not cryptographically secure --
+do not use for security purposes.
+
+```c
+// One-shot checksum:
+uint32_t cryptCRC32(const void *data, const size_t size);
+
+// Streaming (incremental) CRC32:
+uint32_t cryptCRC32Begin(void);
+void     cryptCRC32Update(
+  uint32_t *crc, const void *data, const size_t size
+);
+uint32_t cryptCRC32End(const uint32_t crc);
+```
+
+The streaming API allows computing a checksum across multiple buffers
+or while interleaving other reads -- the save system uses this to
+verify the whole save slot in a single pass.

.github/workflows/build.yml

@@ -0,0 +1,174 @@
+name: Build Dusk
+on:
+  push:
+    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
+      - name: Build Linux
+        run: ./scripts/build-linux-docker.sh
+      - name: Upload Linux binary
+        uses: actions/upload-artifact@v6
+        with:
+          name: dusk-linux
+          path: build-linux/Dusk
+          if-no-files-found: error
+
+  build-psp:
+    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
+      - 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
+        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
+    steps:
+      - 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
+      - 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
+        with:
+          name: dusk-knulli
+          path: ./git-artifcats/Dusk
+          if-no-files-found: error
+
+  build-gamecube:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+      - name: Set up Docker
+        uses: docker/setup-docker-action@v5
+      - name: Build GameCube
+        run: ./scripts/build-gamecube-docker.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
+        with:
+          name: dusk-gamecube
+          path: ./git-artifcats/Dusk
+          if-no-files-found: error
+
+  build-gamecube-iso:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+      - name: Set up Docker
+        uses: docker/setup-docker-action@v5
+      - name: Build GameCube ISO
+        run: ./scripts/build-gamecube-iso-docker.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
+        with:
+          name: dusk-gamecube-iso
+          path: ./git-artifcats/Dusk
+          if-no-files-found: error
+
+  build-wii:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+      - name: Set up Docker
+        uses: docker/setup-docker-action@v5
+      - name: Build Wii
+        run: ./scripts/build-wii-docker.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
+        with:
+          name: dusk-wii
+          path: ./git-artifcats/Dusk
+          if-no-files-found: error
+
+  build-wii-iso:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+      - name: Set up Docker
+        uses: docker/setup-docker-action@v5
+      - name: Build Wii ISO
+        run: ./scripts/build-wii-iso-docker.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
+        with:
+          name: dusk-wii-iso
+          path: ./git-artifcats/Dusk
+          if-no-files-found: error

.gitignore

@@ -83,7 +83,6 @@ assets/borrowed
 .VSCode*
 
 /vita
-
 ._*
 
 *~
@@ -95,3 +94,16 @@ assets/borrowed
 # /archive
 
 __pycache__
+
+package-lock.json
+yarn-error.log
+yarn.lock
+
+.editor
+.venv
+
+/build2
+/build*
+/assets/test
+/tools_old
+/assets/test.png

CLAUDE.md

@@ -0,0 +1,519 @@
+# Dusk -- Claude Code rules
+
+## About Dusk
+
+Dusk is a pure C game and game engine. There is no C++ anywhere in the
+codebase. The engine is built around a data-oriented Entity Component
+System (ECS) and is designed for heavy optimization across a wide range
+of hardware targets, including platforms with very limited RAM and CPU.
+
+**Current and planned platforms:** Linux, Windows, macOS, Sony PSP,
+PlayStation Vita, Nintendo GameCube, Nintendo Wii. Additional platforms
+will be added over time. GameCube and Wii are collectively referred to
+as the **Dolphin** targets throughout the codebase and docs.
+
+**Build system:** CMake exclusively. Every source subdirectory owns its
+own `CMakeLists.txt`.
+
+**Architecture:** Entity Component System (ECS) as the primary pattern.
+All game objects are entities; behaviour and state are attached via
+components. No inheritance hierarchies -- favour composition.
+
+**Optimization:** Performance is a first-class constraint, not an
+afterthought. The engine must run well on hardware as constrained as
+the GameCube (16 MB main RAM, 485 MHz PowerPC) and PSP (32 MB RAM,
+333 MHz MIPS). Every design and implementation decision should consider
+the most constrained target.
+
+**Coding style:** All C code must strictly follow the project style
+rules documented in the [Coding style](#coding-style) section below.
+Deviations are not acceptable.
+
+### Further reading
+
+Detailed documentation on specific topics lives in `.claude/`:
+
+| Topic | File |
+|-------|------|
+| Platform overview, capability macros, quick comparison | `.claude/platforms.md` |
+| Platform -- Linux and Knulli | `.claude/platform-linux.md` |
+| Platform -- Sony PSP | `.claude/platform-psp.md` |
+| Platform -- PlayStation Vita | `.claude/platform-vita.md` |
+| Platform -- GameCube and Wii (Dolphin) | `.claude/platform-dolphin.md` |
+| Platform -- Windows (planned) | `.claude/platform-windows.md` |
+| Platform -- macOS (planned) | `.claude/platform-macos.md` |
+| ECS architecture and conventions | `.claude/ecs.md` |
+| CMake build system and toolchain setup | `.claude/build.md` |
+| Optimization guidelines and platform budgets | `.claude/optimization.md` |
+| Test infrastructure and assertion macros | `.claude/tests.md` |
+| Error handling system (`errorret_t`, macros) | `.claude/errors.md` |
+| Asset system (loading, caching, loaders) | `.claude/assets.md` |
+| Threading (`thread_t`, mutex, thread-local) | `.claude/threading.md` |
+| Input system (actions, buttons, platforms) | `.claude/input.md` |
+| Physics simulation and collision shapes | `.claude/physics.md` |
+| Event system (pub/sub) | `.claude/events.md` |
+| Locale / localisation system | `.claude/locale.md` |
+| Time system (fixed/dynamic, epoch) | `.claude/time.md` |
+| Network system (per-platform status) | `.claude/network.md` |
+| Utility library (memory, string, math, endian, ref) | `.claude/util.md` |
+| Script system (JerryScript, module proto API) | `.claude/script.md` |
+| Script async promises (`scriptpromisepend_t`) | `.claude/script-promises.md` |
+| Engine main loop, system platform API, log | `.claude/engine.md` |
+| Save system (multi-slot, platform storage) | `.claude/save.md` |
+| Animation (keyframes, easing functions) | `.claude/animation.md` |
+| Display (index) | `.claude/display.md` |
+| Display -- screen, framebuffer, size modes | `.claude/display-core.md` |
+| Display -- texture, tileset, font | `.claude/display-texture.md` |
+| Display -- shader, material, display state | `.claude/display-shader.md` |
+| Display -- mesh, vertex format, primitives | `.claude/display-mesh.md` |
+| Display -- SpriteBatch (2D quad renderer) | `.claude/display-spritebatch.md` |
+| Display -- text rendering, FONT_DEFAULT | `.claude/display-text.md` |
+| Display -- color types, macros, constants | `.claude/display-color.md` |
+| UI system (frame, textbox, fullbox, loading, FPS) | `.claude/ui.md` |
+| Console (debug overlay, POSIX stdin mode) | `.claude/console.md` |
+| Scene system (lifecycle, render pipeline, JS hooks) | `.claude/scene.md` |
+
+---
+
+## File headers
+Every C, H, and JS file starts with:
+
+```c
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+```
+
+JS files use `//` comment style instead.
+
+---
+
+## C conventions
+
+### Types
+Always use the project-defined aliases instead of bare C primitives:
+
+| Use       | Not          |
+|-----------|--------------|
+| `bool_t`  | `bool`       |
+| `int_t`   | `int`        |
+| `float_t` | `float`      |
+| `char_t`  | `char`       |
+
+Use `uint8_t`, `uint16_t`, `int32_t`, etc. for fixed-width integers.
+All struct and enum types end in `_t` (`animation_t`, `errorret_t`, …).
+
+### Naming
+- **Functions** — snake_case, prefixed with their module:
+  `assetLock()`, `entityPositionInit()`, `moduleAssetBatchCtor()`
+- **Struct fields** — camelCase: `keyframeCount`, `localPosition`
+- **Macros / constants** — UPPER_SNAKE_CASE:
+  `ENTITY_ID_INVALID`, `ERROR_OK`, `COMPONENT_TYPE_COUNT`
+- **Files** — snake_case matching the primary type: `entityposition.c`,
+  `moduleassetbatch.c`
+
+### Header files (`.h`)
+- Use `#pragma once` — no include guards.
+- Declare every public function, `#define`, and `extern` global.
+- Write a JSDoc block (`/** … */`) above every declaration explaining
+  purpose, `@param`s, and `@returns`.
+- Only include headers that the `.h` file itself strictly requires for
+  the types it exposes. Move everything else to the `.c` file.
+  Do not use forward declarations as a workaround — use the real
+  include in the `.c` file instead.
+
+### Implementation files (`.c`)
+- Contain function bodies only; no declarations.
+- Pull in whatever additional includes the implementation needs.
+- Do not use `static` or `inline` on **functions**. Every function,
+  including internal helpers, must be declared in the matching `.h` and
+  defined in the `.c` file. Internal helpers belong near the bottom of
+  the `.c` file, not at the top with a `static` qualifier.
+  `static` and `inline` on functions are only appropriate when the
+  function body is written directly inside a `.h` file.
+  `static` on **variables** (file-scope state) is fine and expected.
+
+### Formatting
+- Hard-wrap all lines at **80 characters**.
+
+### Error handling
+Return `errorret_t` from fallible functions. Use these macros:
+
+```c
+errorOk();                    // return success
+errorThrow("msg %d", val);    // return failure with message
+errorChain(someCall());       // propagate failure, continue on success
+errorIsOk(ret) / errorIsNotOk(ret)  // test a result
+errorCatch(ret);              // handle + free an error
+```
+
+Never return raw error codes or use `errno` for in-engine errors.
+
+### Memory
+Use the project allocator — never raw `malloc`/`free`:
+
+```c
+memoryAllocate(size)          // allocate
+memoryFree(ptr)               // free
+memoryZero(dest, size)        // zero a block
+memoryCopy(dest, src, size)   // copy
+```
+
+### Asserts
+Prefer specific assert macros over bare `assert()`:
+
+```c
+assertNotNull(ptr, "msg");
+assertTrue(cond, "msg");
+assertFalse(cond, "msg");
+assertUnreachable("msg");
+assertIsMainThread("msg");
+```
+
+---
+
+## Build system
+
+See `.claude/build.md` for extended CMake conventions, platform
+toolchain setup, and adding platform-conditional sources.
+
+Each subdirectory has its own `CMakeLists.txt` that adds sources with:
+
+```cmake
+target_sources(${DUSK_LIBRARY_TARGET_NAME}
+  PUBLIC
+    myfile.c
+)
+```
+
+Never add source files to the root `CMakeLists.txt` directly.
+
+---
+
+## Platform support
+
+See `.claude/platforms.md` for the full platform table (including
+planned Windows / macOS targets), capability macros, toolchain setup,
+and endianness notes.
+
+### Targets
+Set `DUSK_TARGET_SYSTEM` at CMake configure time to select a platform:
+
+| `DUSK_TARGET_SYSTEM` | Macro defined     | Platform         |
+|----------------------|-------------------|------------------|
+| `linux`              | `DUSK_LINUX`      | Linux desktop    |
+| `knulli`             | `DUSK_KNULLI`     | Knulli (handheld)|
+| `psp`                | `DUSK_PSP`        | Sony PSP         |
+| `vita`               | `DUSK_VITA`       | PlayStation Vita |
+| `gamecube`           | `DUSK_GAMECUBE`   | Nintendo GameCube|
+| `wii`                | `DUSK_WII`        | Nintendo Wii     |
+
+### Layer structure
+```
+src/dusk/          core, platform-agnostic game logic
+src/duskgl/        OpenGL abstraction (Linux, Knulli, PSP, Vita)
+src/dusksdl2/      SDL2 window + input (Linux, Knulli, PSP, Vita)
+src/dusklinux/     Linux + Knulli platform impl
+src/duskpsp/       PSP platform impl
+src/duskvita/      Vita platform impl
+src/duskdolphin/   GameCube / Wii platform impl (no SDL2/OpenGL)
+```
+
+Dolphin is the only target that bypasses SDL2 and OpenGL entirely —
+it uses native GameCube/Wii rendering and input APIs.
+
+### Platform guards
+Use the compile-time macros for platform-specific code:
+
+```c
+#ifdef DUSK_PSP
+  // PSP-only path
+#elif defined(DUSK_GAMECUBE) || defined(DUSK_WII)
+  // GameCube / Wii path
+#else
+  // Generic / Linux fallback
+#endif
+```
+
+Additional capability macros set per-target:
+`DUSK_SDL2`, `DUSK_OPENGL`, `DUSK_OPENGL_ES`, `DUSK_OPENGL_LEGACY`,
+`DUSK_INPUT_GAMEPAD`, `DUSK_INPUT_KEYBOARD`, `DUSK_INPUT_POINTER`,
+`DUSK_PLATFORM_ENDIAN_BIG` / `DUSK_PLATFORM_ENDIAN_LITTLE`.
+
+### Abstraction pattern
+Platform-specific implementations are wired in via `#define` macros in
+each platform's `displayplatform.h` / `inputplatform.h` etc., which
+the core calls through. Functions that a platform does not support are
+simply left undefined — the core guards calls with `#ifdef`.
+
+### Adding platform-specific code
+- Put it under `src/dusk<platform>/` in the matching subsystem folder.
+- Gate any core call-site with the appropriate `#ifdef DUSK_<PLATFORM>`
+  or capability macro.
+- Keep the `src/dusk/` core free of platform ifdefs — delegate through
+  the platform header macros instead.
+
+---
+
+## Adding a new entity component
+
+See `.claude/ecs.md` for ECS design rules, component categories, and
+entity lifecycle details.
+
+1. Create `src/dusk/entity/component/<category>/entityMyComp.h/.c` with
+   struct `entityMyComp_t`, `entityMyCompInit()`, and optionally
+   `entityMyCompDispose()`.
+2. Add the include to `src/dusk/entity/componentlist.h` header block.
+3. Add a row to `src/dusk/entity/componentlist.h`:
+   ```c
+   X(MYCOMP, entityMyComp_t, myComp, entityMyCompInit, NULL, NULL)
+   ```
+   This auto-generates the enum, union field, and definition entry.
+4. If JS-facing, create the script module and `.d.ts` (see below).
+
+---
+
+## Adding a new asset loader type
+1. Add an enum value to `assetloadertype_t` (before `_COUNT`) in
+   `src/dusk/asset/loader/assetloader.h`.
+2. Add fields to the input/loading/output unions in `assetloader.h`.
+3. Implement `assetXxxLoaderSync`, `assetXxxLoaderAsync`, and
+   `assetXxxDispose` in a new `src/dusk/asset/loader/xxx/` directory.
+4. Register the three callbacks in `ASSET_LOADER_CALLBACKS[]` in
+   `src/dusk/asset/loader/assetloader.c`.
+5. If user-facing, create a JS module (see below) and a `.d.ts` file.
+
+---
+
+## Adding a new script (JS) module
+1. Create `src/dusk/script/module/<category>/moduleMyMod.h/.c`.
+   - Declare `extern scriptproto_t MODULE_MYMOD_PROTO;` in the header.
+   - Use `moduleBaseFunction(name)` to define JS-callable functions.
+   - Register props/funcs in `moduleMyModInit()` with
+     `scriptProtoDefineProp` / `scriptProtoDefineFunc` /
+     `scriptProtoDefineStaticFunc`.
+2. `#include` the header in
+   `src/dusk/script/module/modulelist.c` and call
+   `moduleMyModInit()` in `moduleListInit()` (and `Dispose` in
+   `moduleListDispose()`).
+3. For component modules also register in
+   `src/dusk/script/module/entity/component/modulecomponentlist.c`
+   so `entity.add()` returns the typed wrapper.
+4. Create `types/<category>/mymod.d.ts` and add a
+   `/// <reference path="..." />` line to `types/index.d.ts`.
+
+---
+
+## Script module type declarations
+Whenever a `src/dusk/script/module/**/*.c` file is created or modified,
+check whether the corresponding `types/**/*.d.ts` needs updating and
+apply any changes before finishing the task.
+
+---
+
+## JavaScript (asset scripts)
+- Use `var` for module-level state; `const` for values that never
+  change.
+- Always use semicolons.
+- Scene objects are plain objects (`var scene = {}`) with assigned
+  methods.
+- Export via `module.exports = scene`.
+- Async scene init should use `async function` and `await`.
+
+---
+
+## Coding style
+
+### ASCII only
+Source files (`.c`, `.h`, `.js`) must contain only ASCII characters (U+0000–U+007F).
+Non-ASCII characters are banned even in comments and string literals.
+Use ASCII-only substitutes instead:
+- `--` or `-` instead of `—` (em dash)
+- `->` instead of `→` (arrow)
+- `x` or `*` instead of `×` (multiplication)
+
+Only non-script asset files (e.g. `.po` locale files) may contain non-ASCII text.
+
+### Indentation
+2 spaces. No tabs.
+
+### Keyword and operator spacing
+No space between a keyword or function name and its opening parenthesis:
+
+```c
+if(!ptr) return;
+for(uint8_t i = 0; i < count; i++) {
+while(entry->state != DONE) {
+switch(type) {
+sizeof(assetbatch_t)
+memoryZero(ptr, size)
+```
+
+Spaces around all binary operators and after every comma:
+
+```c
+pos->flags |= ENTITY_POSITION_FLAG_WORLD_DIRTY;
+(size_t)end - (size_t)start
+foo(a, b, c)
+```
+
+### Braces
+Opening brace on the **same line** as the statement (K&R style) for all
+constructs — functions, `if`, `else`, `for`, `while`, `switch`:
+
+```c
+void assetEntryLock(assetentry_t *entry) {
+  ...
+}
+
+if(dirty) {
+  ...
+} else {
+  ...
+}
+```
+
+### Guard returns
+Short guards go on one line with no braces:
+
+```c
+if(!ptr) return;
+if(!b || !b->batch) return jerry_undefined();
+if(!(flags & DIRTY)) return;
+```
+
+### Blank lines
+- One blank line between functions; no blank line at the start or end of
+  a function body.
+- One blank line between logical blocks inside a function body.
+- No trailing blank lines at the end of a file.
+
+### Pointer placement
+`*` is attached to the variable name, not the type:
+
+```c
+assetentry_t *entry
+const char_t *name
+void *ptr
+uint8_t *d = (uint8_t *)dest;
+```
+
+### Casts
+Space between cast and operand:
+
+```c
+(assetbatch_t *)user
+(uint8_t *)dest
+(textureformat_t)v
+```
+
+### Return
+No parentheses around the return value:
+
+```c
+return ptr;
+return MEMORY_POINTERS_IN_USE;
+```
+
+### switch / case
+`case` indented 2 spaces from `switch`; body indented 2 more from `case`:
+
+```c
+switch(type) {
+  case ASSET_LOADER_TYPE_TEXTURE:
+    descs[i].input.texture = (textureformat_t)v;
+    break;
+  default:
+    break;
+}
+```
+
+### Multi-line function signatures
+When parameters don't fit on one line, put each on its own line indented
+2 spaces; the closing `) {` (definition) or `);` (declaration) goes on
+its own line at column 0:
+
+```c
+void assetEntryInit(
+  assetentry_t *entry,
+  const char_t *name,
+  const assetloadertype_t type,
+  assetloaderinput_t *input
+) {
+
+errorret_t memoryCompare(
+  const void *a,
+  const void *b,
+  const size_t size
+);
+```
+
+### Structs and enums
+Anonymous inner struct or enum with a `typedef`, `_t` suffix, closing
+brace and name on the same line:
+
+```c
+typedef struct {
+  errorcode_t code;
+  char_t *message;
+} errorstate_t;
+
+typedef enum {
+  ASSET_LOADER_TYPE_NULL,
+  ASSET_LOADER_TYPE_COUNT
+} assetloadertype_t;
+```
+
+### Designated initialisers
+Spaces inside braces; `.field = value`:
+
+```c
+jsassetentry_t e = { .entry = entry };
+assetbatchloadedpend_t init = { .batch = batch };
+```
+
+### Ternary operator
+Spaces around `?` and `:`:
+
+```c
+const float val = psx > 0.0f ? pt[0][0] / psx : 0.0f;
+```
+
+### const placement
+`const` before the type, `*` attached to the variable:
+
+```c
+const char_t *name
+const void *src
+const size_t size
+```
+
+### Comments in `.c` files
+- Do not use section dividers (`/* ---- ... ---- */`). Just let the
+  functions follow one another with a single blank line between them.
+- Multi-line explanatory comments inside function bodies use `//` lines:
+  ```c
+  // Script modules are freed; orphaned JS wrapper objects now get GC'd
+  // so their finalizers fire before assetDispose() checks ref counts.
+  jerry_heap_gc(JERRY_GC_PRESSURE_HIGH);
+  ```
+- Do not use `/* */` for inline or inline-block comments inside `.c`
+  function bodies.
+
+### Comments in `.h` files
+Every public declaration gets a Javadoc block (`/** … */`) with
+`@param` and `@returns` where relevant. Keep it on the lines immediately
+above the declaration with no blank line in between.
+
+---
+
+## Tests
+- Tests live in `test/` mirroring `src/dusk/` structure.
+- Use cmocka; include `dusktest.h`.
+- Test functions: `static void test_something(void **state)`.
+- After each test, assert `memoryGetAllocatedCount() == 0` to catch
+  leaks.
+- Build with `-DDUSK_BUILD_TESTS=ON`.

CMakeLists.txt

@@ -5,14 +5,20 @@
 
 # Setup
 cmake_minimum_required(VERSION 3.13)
-set(CMAKE_C_STANDARD 99)
+
+set(CMAKE_C_STANDARD 11)
 set(CMAKE_C_STANDARD_REQUIRED ON)
 set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules)
+cmake_policy(SET CMP0079 NEW)
+# set(FETCHCONTENT_UPDATES_DISCONNECTED ON)
 
-if(NOT DEFINED DUSK_TARGET_SYSTEM)
+option(DUSK_BUILD_TESTS "Enable tests" OFF)
-  set(DUSK_TARGET_SYSTEM "linux")
+
-  # set(DUSK_TARGET_SYSTEM "psp")
+# Game identity — override these per-project
-endif()
+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_LONG_DESCRIPTION  "No description yet." CACHE STRING "Full description")
 
 # Prep cache
 set(DUSK_CACHE_TARGET "dusk-target")
@@ -21,76 +27,105 @@ set(DUSK_CACHE_TARGET "dusk-target")
 set(DUSK_ROOT_DIR "${CMAKE_SOURCE_DIR}")
 set(DUSK_BUILD_DIR "${CMAKE_BINARY_DIR}")
 set(DUSK_SOURCES_DIR "${DUSK_ROOT_DIR}/src")
+set(DUSK_TEST_DIR "${DUSK_ROOT_DIR}/test")
 set(DUSK_TEMP_DIR "${DUSK_BUILD_DIR}/temp")
 set(DUSK_TOOLS_DIR "${DUSK_ROOT_DIR}/tools")
 set(DUSK_DATA_DIR "${DUSK_ROOT_DIR}/data")
+set(DUSK_ASSETS_DIR "${DUSK_ROOT_DIR}/assets")
+set(DUSK_BUILT_ASSETS_DIR "${DUSK_BUILD_DIR}/built_assets" CACHE INTERNAL ${DUSK_CACHE_TARGET})
 set(DUSK_GENERATED_HEADERS_DIR "${DUSK_BUILD_DIR}/generated")
-set(DUSK_TARGET_NAME "Dusk" CACHE INTERNAL ${DUSK_CACHE_TARGET})
 set(DUSK_BUILD_BINARY ${DUSK_BUILD_DIR}/Dusk CACHE INTERNAL ${DUSK_CACHE_TARGET})
 set(DUSK_ASSETS "" CACHE INTERNAL ${DUSK_CACHE_TARGET})
+set(DUSK_LIBRARY_TARGET_NAME "DuskCore" CACHE INTERNAL ${DUSK_CACHE_TARGET})
+set(DUSK_BINARY_TARGET_NAME "Dusk" CACHE INTERNAL ${DUSK_CACHE_TARGET})
+set(DUSK_ASSETS_ZIP "${DUSK_BUILD_DIR}/dusk.dsk" CACHE INTERNAL ${DUSK_CACHE_TARGET})
 
-# Toolchain
+if(NOT DEFINED DUSK_TARGET_SYSTEM)
+  set(DUSK_TARGET_SYSTEM "linux")
+endif()
 
 # Create directories
 file(MAKE_DIRECTORY ${DUSK_GENERATED_HEADERS_DIR})
-file(MAKE_DIRECTORY ${DUSK_ASSETS_BUILD_DIR})
+file(MAKE_DIRECTORY ${DUSK_TEMP_DIR})
+file(MAKE_DIRECTORY ${DUSK_BUILT_ASSETS_DIR})
 
-# Compilers
+# Required build packages
-if(DUSK_TARGET_SYSTEM STREQUAL "psp")
+find_package(Python3 COMPONENTS Interpreter REQUIRED)
-  find_package(pspsdk REQUIRED)
-endif()
 
-# Init Project
+# Init Project.
-project(${DUSK_TARGET_NAME}
+project(${DUSK_LIBRARY_TARGET_NAME}
   VERSION 1.0.0
   LANGUAGES C
 )
 
-# Executable
+# Either, create library and binary separately (used for tests), or make them
-add_executable(${DUSK_TARGET_NAME})
+# one in the same so all code is in the binary only.
+# Binary Executable
+add_executable(${DUSK_BINARY_TARGET_NAME} ${DUSK_SOURCES_DIR}/dusk/null.c)
+
+if(DUSK_BUILD_TESTS)
+  # MainLibrary
+  add_library(${DUSK_LIBRARY_TARGET_NAME} STATIC)
+
+  # Link library to binary
+  target_link_libraries(${DUSK_BINARY_TARGET_NAME}
+    PUBLIC
+      ${DUSK_LIBRARY_TARGET_NAME}
+  )
+else()
+  set(DUSK_LIBRARY_TARGET_NAME "${DUSK_BINARY_TARGET_NAME}" CACHE INTERNAL ${DUSK_CACHE_TARGET})
+endif()
+
+if(NOT DEFINED DUSK_VERSION)
+  string(TIMESTAMP DUSK_VERSION "debug-%y%m%d%H%M%S")
+endif()
+
+# Definitions
+target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME}
+  PUBLIC
+    DUSK_TARGET_SYSTEM="${DUSK_TARGET_SYSTEM}"
+    DUSK_GAME_NAME="${DUSK_GAME_NAME}"
+    DUSK_GAME_AUTHOR="${DUSK_GAME_AUTHOR}"
+    DUSK_GAME_SHORT_DESCRIPTION="${DUSK_GAME_SHORT_DESCRIPTION}"
+    DUSK_GAME_LONG_DESCRIPTION="${DUSK_GAME_LONG_DESCRIPTION}"
+    DUSK_VERSION="${DUSK_VERSION}"
+)
+
+# Toolchains
+include(cmake/targets/${DUSK_TARGET_SYSTEM}.cmake)
 
 # Add tools
 add_subdirectory(tools)
 
-# Add libraries
+# Include generated headers from tools.
-if(DUSK_TARGET_SYSTEM STREQUAL "linux")
+target_include_directories(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
-  find_package(SDL2 REQUIRED)
-  find_package(OpenGL REQUIRED)
-  target_link_libraries(${DUSK_TARGET_NAME} PRIVATE 
-    SDL2
-    OpenGL::GL
-    GL
-  )
-
-elseif(DUSK_TARGET_SYSTEM STREQUAL "psp")
-  find_package(SDL2 REQUIRED)
-  target_link_libraries(${DUSK_TARGET_NAME}
-    PRIVATE
-      # pspsdk
-      ${SDL2_LIBRARIES}
-  )
-  target_include_directories(${DUSK_TARGET_NAME}
-    PRIVATE
-      ${SDL2_INCLUDE_DIRS}
-  )
-endif()
-
-# Add code
-add_subdirectory(src)
-
-# Include generated headers
-target_include_directories(${DUSK_TARGET_NAME} PUBLIC
   ${DUSK_GENERATED_HEADERS_DIR}
 )
 
-# Postbuild, create PBP file for PSP.
+# Add main code
-if(DUSK_TARGET_SYSTEM STREQUAL "psp")
+add_subdirectory(${DUSK_SOURCES_DIR})
-  create_pbp_file(
+
-    TARGET "${DUSK_TARGET_NAME}"
+# Include generated headers
-    ICON_PATH NULL
+target_include_directories(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
-    BACKGROUND_PATH NULL
+  ${DUSK_GENERATED_HEADERS_DIR}
-    PREVIEW_PATH NULL
+)
-    TITLE "${DUSK_TARGET_NAME}"
+
-    VERSION 01.00
+# Handle tests
-  )
+if(DUSK_BUILD_TESTS)
+  enable_testing()
+  add_subdirectory(test)
 endif()
+
+# Build assets
+file(GLOB_RECURSE DUSK_ASSET_FILES CONFIGURE_DEPENDS "${DUSK_ASSETS_DIR}/*")
+add_custom_command(
+  OUTPUT "${DUSK_ASSETS_ZIP}"
+  COMMAND ${CMAKE_COMMAND} -E make_directory "${DUSK_ASSETS_DIR}"
+  COMMAND ${CMAKE_COMMAND} -E rm -f "${DUSK_ASSETS_ZIP}"
+  COMMAND ${CMAKE_COMMAND} -E tar "cf" "${DUSK_ASSETS_ZIP}" --format=zip -- .
+  WORKING_DIRECTORY "${DUSK_ASSETS_DIR}"
+  DEPENDS ${DUSK_ASSET_FILES}
+  VERBATIM
+)
+add_custom_target(DUSK_ASSETS_BUILT DEPENDS "${DUSK_ASSETS_ZIP}")
+add_dependencies(${DUSK_LIBRARY_TARGET_NAME} DUSK_ASSETS_BUILT)

README.md

@@ -0,0 +1,23 @@
+# Dusk
+RPG Game Project, small and able to run on a PSP.
+
+# Building
+Each build target has different requirements. You can take a look at the git
+workflow to see how the builds are done for each target. In addition, for
+accessing the editor and building the game on your host system, install the
+following packages, depending on your system;
+
+Fedora;
+```
+sudo dnf install git make gcc cmake python python-polib python3-pillow python3-dotenv python3-numpy python-qt5 python3-pyopengl SDL2-devel zlib-devel libzip-devel bzip2-devel openssl-devel lzma-sdk-devel xz xz-devel lua-devel
+```
+
+Ubuntu;
+```
+sudo apt-get install git build-essential gcc python python-polib python3-pillow python3-dotenv python3-numpy python3-pyqt5 python3-opengl
+```
+
+Arch Linux;
+```
+sudo pacman -S git base-devel gcc python python-polib python-pillow python-dotenv python-numpy python-pyqt5 python-opengl
+```

archive/asset/args.py

@@ -0,0 +1,12 @@
+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

@@ -0,0 +1,66 @@
+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

@@ -0,0 +1,12 @@
+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

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,33 @@
+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

@@ -0,0 +1,134 @@
+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

@@ -0,0 +1,228 @@
+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

@@ -0,0 +1,154 @@
+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

@@ -0,0 +1,96 @@
+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

@@ -0,0 +1,43 @@
+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

@@ -0,0 +1,178 @@
+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

@@ -0,0 +1,47 @@
+/**
+ * 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

@@ -0,0 +1,30 @@
+/**
+ * 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/CMakeLists.txt

@@ -0,0 +1,10 @@
+# Copyright (c) 2026 Dominic Masters
+#
+# This software is released under the MIT License.
+# https://opensource.org/licenses/MIT
+
+# Sources
+target_sources(${DUSK_LIBRARY_TARGET_NAME}
+  PUBLIC
+    camera.c
+)

archive/camera/camera.c

@@ -0,0 +1,107 @@
+/**
+ * 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

@@ -0,0 +1,97 @@
+/**
+ * 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/CMakeLists.txt

@@ -1,37 +0,0 @@
-# Copyright (c) 2025 Dominic Masters
-#
-# This software is released under the MIT License.
-# https://opensource.org/licenses/MIT
-
-# Libs
-target_link_libraries(${DUSK_TARGET_NAME}
-  PUBLIC
-    m
-)
-
-# Includes
-target_include_directories(${DUSK_TARGET_NAME}
-  PRIVATE
-    ${CMAKE_CURRENT_LIST_DIR}
-)
-
-# Sources
-target_sources(${DUSK_TARGET_NAME}
-  PRIVATE
-    game.c
-    input.c
-    time.c
-)
-
-# Subdirs
-add_subdirectory(assert)
-add_subdirectory(console)
-add_subdirectory(display)
-add_subdirectory(error)
-add_subdirectory(entity)
-add_subdirectory(event)
-add_subdirectory(item)
-add_subdirectory(locale)
-add_subdirectory(ui)
-add_subdirectory(util)
-add_subdirectory(world)

archive/dusk/assert/assert.c

@@ -1,85 +0,0 @@
-/**
- * Copyright (c) 2023 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#include "assert.h"
-
-#ifndef ASSERTIONS_FAKED
-  void assertTrueImpl(
-    const char *file,
-    const int32_t line,
-    const bool x,
-    const char *message
-  ) {
-    if(x != true) {
-      fprintf(
-        stderr,
-        "Assertion Failed in %s:%i\n\n%s\n",
-        file,
-        line,
-        message
-      );
-      abort();
-    }
-  }
-
-  void assertFalseImpl(
-    const char *file,
-    const int32_t line,
-    bool x,
-    const char *message
-  ) {
-    assertTrueImpl(file, line, !x, message);
-  }
-
-  void assertUnreachableImpl(
-    const char *file,
-    const int32_t line,
-    const char *message
-  ) {
-    assertTrueImpl(file, line, false, message);
-  }
-
-  void assertNotNullImpl(
-    const char *file,
-    const int32_t line,
-    const void *pointer,
-    const char *message
-  ) {
-    assertTrueImpl(
-      file,
-      line,
-      pointer != NULL,
-      message
-    );
-
-    // Ensure we can touch it
-    volatile char temp;
-    temp = *((char*)pointer);
-  }
-
-  void assertNullImpl(
-    const char *file,
-    const int32_t line,
-    const void *pointer,
-    const char *message
-  ) {
-    assertTrueImpl(
-      file,
-      line,
-      pointer == NULL,
-      message
-    );
-  }
-
-  void assertDeprecatedImpl(
-    const char *file,
-    const int32_t line,
-    const char *message
-  ) {
-    assertUnreachableImpl(file, line, message);
-  }
-#endif

archive/dusk/assert/assert.h

@@ -1,143 +0,0 @@
-/**
- * Copyright (c) 2023 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#pragma once
-#include "dusk.h"
-
-#ifndef ASSERTIONS_FAKED
-  /**
-   * Assert a given value to be true.
-   * 
-   * @param file File that the assertion is being made from.
-   * @param line Line that the assertion is being made from.
-   * @param x Value to assert as true.
-   * @param message Message to throw against assertion failure.
-   */
-  void assertTrueImpl(
-    const char *file,
-    const int32_t line,
-    const bool_t x,
-    const char *message
-  );
-
-  /**
-   * Asserts a given statement to be false.
-   * 
-   * @param file File that the assertion is being made from.
-   * @param line Line that the assertion is being made from.
-   * @param x Value to assert as false.
-   * @param message Message to throw against assertion failure.
-   */
-  void assertFalseImpl(
-    const char *file,
-    const int32_t line,
-    const bool_t x,
-    const char *message
-  );
-
-  /**
-   * Asserts that a given line of code is unreachable. Essentially a forced
-   * assertion failure, good for "edge cases"
-   * 
-   * @param file File that the assertion is being made from.
-   * @param line Line that the assertion is being made from.
-   * @param message Message to throw against assertion failure.
-   */
-  void assertUnreachableImpl(
-    const char *file,
-    const int32_t line,
-    const char *message
-  );
-
-  /**
-   * Assert a given pointer to not point to a null pointer.
-   * 
-   * @param file File that the assertion is being made from.
-   * @param line Line that the assertion is being made from.
-   * @param pointer Pointer to assert is not a null pointer.
-   * @param message Message to throw against assertion failure.
-   */
-  void assertNotNullImpl(
-    const char *file,
-    const int32_t line,
-    const void *pointer,
-    const char *message
-  );
-
-  /**
-   * Asserts a given pointer to be a nullptr.
-   * 
-   * @param file File that the assertion is being made from.
-   * @param line Line that the assertion is being made from.
-   * @param pointer Pointer to assert is nullptr.
-   * @param message Message to throw against assertion failure.
-   */
-  void assertNullImpl(
-    const char *file,
-    const int32_t line,
-    const void *pointer,
-    const char *message
-  );
-
-  /**
-   * Asserts a function as being deprecated.
-   * 
-   * @param file File that the assertion is being made from.
-   * @param line Line that the assertion is being made from.
-   * @param message Message to throw against assertion failure.
-   */
-  void assertDeprecatedImpl(
-    const char *file,
-    const int32_t line,
-    const char *message
-  );
-
-  void assertMemoryRangeMatchesImpl(
-    const char *file,
-    const int32_t line,
-    const void *start,
-    const void *end,
-    const size_t size,
-    const char *message
-  );
-
-  #define assertTrue(x, message) \
-    assertTrueImpl(__FILE__, __LINE__, x, message)
-
-  #define assertFalse(x, message) \
-    assertFalseImpl(__FILE__, __LINE__, x, message)
-
-  #define assertUnreachable(message) \
-    assertUnreachableImpl(__FILE__, __LINE__, message)
-
-  #define assertNotNull(pointer, message) \
-    assertNotNullImpl(__FILE__, __LINE__, pointer, message)
-
-  #define assertNull(pointer, message) \
-    assertNullImpl(__FILE__, __LINE__, pointer, message)
-
-  #define assertDeprecated(message) \
-    assertDeprecatedImpl(__FILE__, __LINE__, message)
-
-  #define assertStrLenMax(str, len, message) \
-    assertTrue(strlen(str) < len, message)
-
-  #define assertStrLenMin(str, len, message) \
-    assertTrue(strlen(str) >= len, message)
-
-#else
-  // If assertions are faked, we define the macros to do nothing.
-  #define assertTrue(x, message) ((void)0)
-  #define assertFalse(x, message) ((void)0)
-  #define assertUnreachable(message) ((void)0)
-  #define assertNotNull(pointer, message) ((void)0)
-  #define assertNull(pointer, message) ((void)0)
-  #define assertDeprecated(message) ((void)0)
-  #define assertStrLenMax(str, len, message) ((void)0)
-  #define assertStrLenMin(str, len, message) ((void)0)
-
-#endif

archive/dusk/chunk.py

@@ -0,0 +1,158 @@
+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/console/CMakeLists.txt

@@ -1,15 +0,0 @@
-# Copyright (c) 2025 Dominic Masters
-# 
-# This software is released under the MIT License.
-# https://opensource.org/licenses/MIT
-
-# Sources
-target_sources(${DUSK_TARGET_NAME}
-  PRIVATE
-    console.c
-    consolecmd.c
-    consolevar.c
-)
-
-# Subdirectories
-add_subdirectory(cmd)

archive/dusk/console/cmd/cmdecho.h

@@ -1,18 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#pragma once
-#include "console/console.h"
-
-void cmdEcho(const consolecmdexec_t *exec) {
-  assertTrue(
-    exec->argc >= 1,
-    "echo command requires 1 argument."
-  );
-
-  consolePrint("%s", exec->argv[0]);
-}

archive/dusk/console/cmd/cmdget.h

@@ -1,25 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#pragma once
-#include "console/console.h"
-
-void cmdGet(const consolecmdexec_t *exec) {
-  assertTrue(
-    exec->argc >= 1,
-    "Get command requires 1 argument."
-  );
-
-  for(uint32_t i = 0; i < CONSOLE.variableCount; i++) {
-    consolevar_t *var = &CONSOLE.variables[i];
-    if(stringCompare(var->name, exec->argv[0]) != 0) continue;
-    consolePrint("%s", var->value);
-    return;
-  }
-
-  consolePrint("Error: Variable '%s' not found.", exec->argv[0]);
-}

archive/dusk/console/cmd/cmdquit.h

@@ -1,15 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#pragma once
-#include "console/console.h"
-#include "game.h"
-
-void cmdQuit(const consolecmdexec_t *exec) {
-  consolePrint("Quitting application...");
-  GAME.running = false;
-}

archive/dusk/console/cmd/cmdset.h

@@ -1,27 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#pragma once
-#include "console/console.h"
-
-void cmdSet(const consolecmdexec_t *exec) {
-  assertTrue(exec->argc >= 2, "set command requires 2 arguments.");
-
-  for(uint32_t i = 0; i < CONSOLE.variableCount; i++) {
-    consolevar_t *var = &CONSOLE.variables[i];
-    if(stringCompare(var->name, exec->argv[0]) != 0) continue;
-    consoleVarSetValue(var, exec->argv[1]);
-    consolePrint("%s %s", var->name, var->value);
-    for(i = 0; i < var->eventCount; i++) {
-      assertNotNull(var->events[i], "Event is NULL");
-      var->events[i](var);
-    }
-    return;
-  }
-
-  consolePrint("Error: Variable '%s' not found.", exec->argv[0]);
-}

archive/dusk/console/console.c

@@ -1,329 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#include "console.h"
-#include "assert/assert.h"
-#include "util/memory.h"
-#include "util/string.h"
-#include "console/cmd/cmdquit.h"
-#include "console/cmd/cmdecho.h"
-#include "console/cmd/cmdset.h"
-#include "console/cmd/cmdget.h"
-
-#include "input.h"
-
-console_t CONSOLE;
-
-void consoleInit() {
-  memoryZero(&CONSOLE, sizeof(console_t));
-
-  // Register the get and set command.
-  CONSOLE.cmdGet = consoleRegCmd("get", cmdGet);
-  CONSOLE.cmdSet = consoleRegCmd("set", cmdSet);
-  consoleRegCmd("quit", cmdQuit);
-  consoleRegCmd("echo", cmdEcho);
-
-  consolePrint(" = Dawn Console = ");
-}
-
-consolecmd_t * consoleRegCmd(const char_t *name, consolecmdfunc_t function) {
-  consolecmd_t *cmd = &CONSOLE.commands[CONSOLE.commandCount++];
-  consoleCmdInit(cmd, name, function);
-  return cmd;
-}
-
-consolevar_t * consoleRegVar(
-  const char_t *name,
-  const char_t *value,
-  consolevarchanged_t event
-) {
-  consolevar_t *var = &CONSOLE.variables[CONSOLE.variableCount++];
-  consoleVarInitListener(var, name, value, event);
-  return var;
-}
-
-void consolePrint(const char_t *message, ...) {
-  char_t buffer[CONSOLE_LINE_MAX];
-
-  va_list args;
-  va_start(args, message);
-  int32_t len = stringFormatVA(buffer, CONSOLE_LINE_MAX, message, args);
-  va_end(args);
-
-  // Move all lines back
-  memoryMove(
-    CONSOLE.line[0],
-    CONSOLE.line[1],
-    (CONSOLE_HISTORY_MAX - 1) * CONSOLE_LINE_MAX
-  );
-
-  // Copy the new line
-  memoryCopy(
-    CONSOLE.line[CONSOLE_HISTORY_MAX - 1],
-    buffer,
-    len + 1
-  );
-  printf("%s\n", buffer);
-}
-
-void consoleExec(const char_t *line) {
-  assertNotNull(line, "line must not be NULL");
-  assertTrue(
-    CONSOLE.execBufferCount < CONSOLE_EXEC_BUFFER_MAX,
-    "Too many commands in the buffer."
-  );
-
-  char_t buffer[CONSOLE_LINE_MAX];
-  size_t i = 0, j = 0;
-  char_t c;
-  consoleexecstate_t state = CONSOLE_EXEC_STATE_INITIAL;
-  consolecmdexec_t *exec = NULL;
-
-  while(state != CONSOLE_EXEC_STATE_FULLY_PARSED) {
-    c = line[i];
-
-    switch(state) {
-      case CONSOLE_EXEC_STATE_INITIAL:
-        assertTrue(j == 0, "Buffer not empty?");
-
-        if(c == '\0') {
-          state = CONSOLE_EXEC_STATE_FULLY_PARSED;
-          break;
-        }
-
-        if(stringIsWhitespace(c) || c == ';') {
-          i++;
-          continue;
-        }
-
-        state = CONSOLE_EXEC_STATE_PARSE_CMD;
-        break;
-
-      case CONSOLE_EXEC_STATE_PARSE_CMD:
-        if(stringIsWhitespace(c) || c == '\0' || c == ';') {
-          state = CONSOLE_EXEC_STATE_CMD_PARSED;
-          continue;
-        }
-
-        if(c == '"') {
-          // Can't handle quotes within the command.
-          consolePrint("Invalid command");
-          while(c != '\0' && c != ';') c = line[++i];
-          continue;
-        }
-        
-        buffer[j++] = c;
-        i++;
-
-        if(j >= CONSOLE_LINE_MAX) {
-          consolePrint("Command too long");
-          state = CONSOLE_EXEC_STATE_FULLY_PARSED;
-          continue;
-        }
-        break;
-
-      case CONSOLE_EXEC_STATE_CMD_PARSED:
-        if(j == 0) {
-          state = CONSOLE_EXEC_STATE_INITIAL;
-          continue;
-        }
-
-        // Create exec
-        assertNull(exec, "Existing command parsing?");
-
-        exec = &CONSOLE.execBuffer[CONSOLE.execBufferCount];
-        memoryZero(exec, sizeof(consolecmdexec_t));
-
-        buffer[j] = '\0';
-        stringCopy(exec->command, buffer, CONSOLE_LINE_MAX);
-        state = CONSOLE_EXEC_STATE_FIND_ARG;
-
-        j = 0;// Free up buffer
-        break;
-
-      case CONSOLE_EXEC_STATE_FIND_ARG:
-        if(c == '\0' || c == ';') {
-          state = CONSOLE_EXEC_STATE_CMD_FINISHED;
-          continue;
-        }
-
-        if(stringIsWhitespace(c)) {
-          i++;
-          continue;
-        }
-
-        if(c == '"') {
-          state = CONSOLE_EXEC_STATE_PARSE_ARG_QUOTED;
-          i++;
-        } else {
-          state = CONSOLE_EXEC_STATE_PARSE_ARG;
-        }
-        break;
-
-      case CONSOLE_EXEC_STATE_PARSE_ARG:
-        if(stringIsWhitespace(c) || c == '\0' || c == ';') {
-          state = CONSOLE_EXEC_STATE_ARG_PARSED;
-          continue;
-        }
-
-        buffer[j++] = c;
-        i++;
-
-        if(j >= CONSOLE_LINE_MAX) {
-          consolePrint("Arg too long");
-          state = CONSOLE_EXEC_STATE_FULLY_PARSED;
-          continue;
-        }
-        break;
-
-      case CONSOLE_EXEC_STATE_PARSE_ARG_QUOTED:
-        if(c == '"') {
-          state = CONSOLE_EXEC_STATE_ARG_PARSED;
-          i++;
-          continue;
-        }
-
-        if(c == '\0' || c == ';') {
-          consolePrint("Unterminated quote");
-          state = CONSOLE_EXEC_STATE_FULLY_PARSED;
-          continue;
-        }
-
-        if(c == '\\') {
-          c = line[++i];
-
-          if(c == '\0' || c == ';') {
-            consolePrint("Unterminated quote");
-            state = CONSOLE_EXEC_STATE_FULLY_PARSED;
-            continue;
-          }
-        }
-
-        buffer[j++] = c;
-        i++;
-
-        if(j >= CONSOLE_LINE_MAX) {
-          consolePrint("Arg too long");
-          state = CONSOLE_EXEC_STATE_FULLY_PARSED;
-          continue;
-        }
-        break;
-
-      case CONSOLE_EXEC_STATE_ARG_PARSED:
-        buffer[j] = '\0';
-        stringCopy(exec->argv[exec->argc++], buffer, CONSOLE_LINE_MAX);
-        state = CONSOLE_EXEC_STATE_FIND_ARG;
-        j = 0;// Free up buffer
-        break;
-
-      case CONSOLE_EXEC_STATE_CMD_FINISHED:
-        assertNotNull(exec, "No command found?");
-
-        // Now, is there a command that matches?
-        for(uint32_t k = 0; k < CONSOLE.commandCount; k++) {
-          consolecmd_t *cmd = &CONSOLE.commands[k];
-          if(stringCompare(cmd->name, exec->command) != 0) continue;
-          exec->cmd = cmd;
-          break;
-        }
-
-        if(exec->cmd == NULL) {
-          // Command wasn't found, is there a variable that matches?
-          for(uint32_t k = 0; k < CONSOLE.variableCount; k++) {
-            consolevar_t *var = &CONSOLE.variables[k];
-            if(stringCompare(var->name, exec->command) != 0) continue;
-
-            // Matching variable found, is this a GET or a SET?
-            if(exec->argc == 0) {
-              exec->cmd = CONSOLE.cmdGet;
-              stringCopy(exec->argv[0], exec->command, CONSOLE_LINE_MAX);
-              exec->argc = 1;
-            } else {
-              exec->cmd = CONSOLE.cmdSet;
-              stringCopy(exec->argv[1], exec->argv[0], CONSOLE_LINE_MAX);
-              stringCopy(exec->argv[0], exec->command, CONSOLE_LINE_MAX);
-              exec->argc = 2;
-            }
-            break;
-          }
-
-          if(exec->cmd == NULL) {
-            consolePrint("Command not found", exec->command);
-            exec = NULL;
-            state = CONSOLE_EXEC_STATE_INITIAL;
-            break;
-          }
-        }
-        
-        // Prep for next command.
-        exec = NULL;
-        state = CONSOLE_EXEC_STATE_INITIAL;
-        CONSOLE.execBufferCount++;
-        break;
-
-      default:
-        assertUnreachable("Invalid state.");
-        break;
-    }
-  }
-}
-
-// May move these later
-void consoleUpdate() {
-  if(inputPressed(INPUT_BIND_CONSOLE)) {
-    CONSOLE.visible = !CONSOLE.visible;
-    if(CONSOLE.visible) {
-      consolePrint("Console opened.");
-    } else {
-      consolePrint("Console closed.");
-    }
-  }
-
-  for(uint32_t i = 0; i < CONSOLE.execBufferCount; i++) {
-    consolecmdexec_t *exec = &CONSOLE.execBuffer[i];
-    assertNotNull(exec->cmd, "Command execution has no command.");
-    exec->cmd->function(exec);
-  }
-
-  // #if KEYBOARD_SUPPORT == 1
-  //   uint8_t key;
-  //   while((key = inputKeyboardPop()) != 0) {
-  //     printf("Key pressed: %c\n", key);
-  //     switch(key) {
-  //       case 0:
-  //         break;
-
-  //       case INPUT_KEY_ENTER:
-  //         consoleExec(CONSOLE.inputBuffer);
-  //         CONSOLE.inputIndex = 0;
-  //         CONSOLE.inputBuffer[0] = '\0';
-  //         break;
-
-  //       case INPUT_KEY_BACKSPACE:
-  //         if(CONSOLE.inputIndex > 0) {
-  //           CONSOLE.inputIndex--;
-  //           CONSOLE.inputBuffer[CONSOLE.inputIndex] = '\0';
-  //         }
-  //         break;
-
-  //       default:
-  //         if(
-  //           key >= INPUT_KEY_ASCII_START && key <= INPUT_KEY_ASCII_END &&
-  //           CONSOLE.inputIndex < CONSOLE_LINE_MAX - 1
-  //         ) {
-  //           CONSOLE.inputBuffer[CONSOLE.inputIndex++] = key;
-  //           CONSOLE.inputBuffer[CONSOLE.inputIndex] = '\0';
-  //         }
-  //         break;
-
-  //     }
-  //   }
-  // #endif
-
-  // Clear the exec buffer
-  CONSOLE.execBufferCount = 0;
-}

archive/dusk/console/console.h

@@ -1,106 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#pragma once
-#include "consolevar.h"
-#include "consolecmd.h"
-
-typedef enum {
-  CONSOLE_EXEC_STATE_INITIAL,
-  CONSOLE_EXEC_STATE_PARSE_CMD,
-  CONSOLE_EXEC_STATE_CMD_PARSED,
-  
-  CONSOLE_EXEC_STATE_FIND_ARG,
-  CONSOLE_EXEC_STATE_PARSE_ARG,
-  CONSOLE_EXEC_STATE_PARSE_ARG_QUOTED,
-  CONSOLE_EXEC_STATE_ARG_PARSED,
-
-  CONSOLE_EXEC_STATE_CMD_FINISHED,
-  CONSOLE_EXEC_STATE_FULLY_PARSED
-} consoleexecstate_t;
-
-typedef struct {
-  consolecmd_t commands[CONSOLE_COMMANDS_MAX];
-  uint32_t commandCount;
-
-  consolevar_t variables[CONSOLE_VARIABLES_MAX];
-  uint32_t variableCount;
-
-  char_t line[CONSOLE_HISTORY_MAX][CONSOLE_LINE_MAX];
-
-  consolecmdexec_t execBuffer[CONSOLE_EXEC_BUFFER_MAX];
-  uint32_t execBufferCount;
-
-  consolecmd_t *cmdGet;
-  consolecmd_t *cmdSet;
-
-  bool_t visible;
-
-  // May move these later
-  // #if KEYBOARD_SUPPORT == 1
-  //   char_t inputBuffer[CONSOLE_LINE_MAX];
-  //   int32_t inputIndex;
-  // #endif
-} console_t;
-
-extern console_t CONSOLE;
-
-/**
- * Initializes the console.
- */
-void consoleInit();
-
-/**
- * Registers a console command.
- * 
- * @param name The name of the command.
- * @param function The function to execute when the command is called.
- * @return The registered command.
- */
-consolecmd_t * consoleRegCmd(const char_t *name, consolecmdfunc_t function);
-
-/**
- * Registers a console variable.
- * 
- * @param name The name of the variable.
- * @param value The initial value of the variable.
- * @param event The event to register.
- * @return The registered variable.
- */
-consolevar_t * consoleRegVar(
-  const char_t *name,
-  const char_t *value,
-  consolevarchanged_t event
-);
-
-/**
- * Sets the value of a console variable.
- * 
- * @param name The name of the variable.
- * @param value The new value of the variable.
- */
-void consolePrint(
-  const char_t *message,
-  ...
-);
-
-/**
- * Executes a console command.
- * 
- * @param line The line to execute.
- */
-void consoleExec(const char_t *line);
-
-/**
- * Processes the console's pending commands.
- */
-void consoleUpdate();
-
-void cmdGet(const consolecmdexec_t *exec);
-void cmdSet(const consolecmdexec_t *exec);
-void cmdEcho(const consolecmdexec_t *exec);
-void cmdQuit(const consolecmdexec_t *exec);

archive/dusk/console/consolecmd.c

@@ -1,27 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#include "consolecmd.h"
-#include "assert/assert.h"
-#include "util/memory.h"
-#include "util/string.h"
-
-void consoleCmdInit(
-  consolecmd_t *cmd,
-  const char_t *name,
-  consolecmdfunc_t function
-) {
-  assertNotNull(cmd, "Command is NULL.");
-  assertNotNull(name, "Name is NULL.");
-  assertNotNull(function, "Function is NULL.");
-  assertStrLenMin(name, 1, "Name is empty.");
-  assertStrLenMax(name, CONSOLE_CMD_NAME_MAX, "Name is too long.");
-
-  memoryZero(cmd, sizeof(consolecmd_t));
-  stringCopy(cmd->name, name, CONSOLE_CMD_NAME_MAX);
-  cmd->function = function;
-}

archive/dusk/console/consolecmd.h

@@ -1,39 +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 "consoledefs.h"
-
-typedef struct consolecmd_s consolecmd_t;
-
-typedef struct {
-  consolecmd_t *cmd;
-  char_t command[CONSOLE_LINE_MAX];
-  char_t argv[CONSOLE_CMD_ARGC_MAX][CONSOLE_LINE_MAX];
-  uint32_t argc;
-} consolecmdexec_t;
-
-typedef void (*consolecmdfunc_t)(const consolecmdexec_t *exec);
-
-typedef struct consolecmd_s {
-  char_t name[CONSOLE_CMD_NAME_MAX];
-  consolecmdfunc_t function;
-} consolecmd_t;
-
-/**
- * Initializes a console command.
- * 
- * @param cmd Pointer to the console command.
- * @param name The name of the command.
- * @param function The function to execute when the command is called.
- */
-void consoleCmdInit(
-  consolecmd_t *cmd,
-  const char_t *name,
-  consolecmdfunc_t function
-);

archive/dusk/console/consoledefs.h

@@ -1,21 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#pragma once
-
-#define CONSOLE_CMD_NAME_MAX 32
-#define CONSOLE_CMD_ARGC_MAX 16
-
-#define CONSOLE_COMMANDS_MAX 128
-#define CONSOLE_VARIABLES_MAX 128
-#define CONSOLE_LINE_MAX 256
-#define CONSOLE_HISTORY_MAX 32
-#define CONSOLE_EXEC_BUFFER_MAX 16
-
-#define CONSOLE_VAR_NAME_MAX 32
-#define CONSOLE_VAR_VALUE_MAX 128
-#define CONSOLE_VAR_EVENTS_MAX 8

archive/dusk/console/consolevar.c

@@ -1,64 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#include "consolevar.h"
-#include "assert/assert.h"
-#include "util/memory.h"
-#include "util/string.h"
-
-void consoleVarInit(
-  consolevar_t *var,
-  const char_t *name,
-  const char_t *value
-) {
-  assertNotNull(var, "var must not be NULL");
-  assertNotNull(name, "name must not be NULL");
-  assertNotNull(value, "value must not be NULL");
-
-  assertStrLenMin(name, 1, "name must not be empty");
-  assertStrLenMax(name, CONSOLE_VAR_NAME_MAX, "name is too long");
-  assertStrLenMax(value, CONSOLE_VAR_VALUE_MAX, "value is too long");
-
-  memoryZero(var, sizeof(consolevar_t));
-  stringCopy(var->name, name, CONSOLE_VAR_NAME_MAX);
-  stringCopy(var->value, value, CONSOLE_VAR_VALUE_MAX);
-}
-
-void consoleVarInitListener(
-  consolevar_t *var,
-  const char_t *name,
-  const char_t *value,
-  consolevarchanged_t event
-) {
-  consoleVarInit(var, name, value);
-  if(event) consoleVarListen(var, event);
-}
-
-void consoleVarSetValue(consolevar_t *var, const char_t *value) {
-  assertNotNull(var, "var must not be NULL");
-  assertNotNull(value, "value must not be NULL");
-  assertStrLenMax(value, CONSOLE_VAR_VALUE_MAX, "value is too long");
-
-  stringCopy(var->value, value, CONSOLE_VAR_VALUE_MAX);
-  
-  uint8_t i = 0;
-  while (i < var->eventCount) {
-    var->events[i](var);
-    i++;
-  }
-}
-
-void consoleVarListen(consolevar_t *var, consolevarchanged_t event) {
-  assertNotNull(var, "var must not be NULL");
-  assertNotNull(event, "event must not be NULL");
-  assertTrue(
-    var->eventCount < CONSOLE_VAR_EVENTS_MAX,
-    "Event count is too high"
-  );
-  var->events[var->eventCount++] = event;
-}
-

archive/dusk/console/consolevar.h

@@ -1,65 +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 "consoledefs.h"
-
-typedef struct consolevar_s consolevar_t;
-
-typedef void (*consolevarchanged_t)(const consolevar_t *var);
-
-typedef struct consolevar_s {
-  char_t name[CONSOLE_VAR_NAME_MAX];
-  char_t value[CONSOLE_VAR_VALUE_MAX];
-  consolevarchanged_t events[CONSOLE_VAR_EVENTS_MAX];
-  uint8_t eventCount;
-} consolevar_t;
-
-/**
- * Initializes a console variable.
- * 
- * @param var Pointer to the console variable.
- * @param name The name of the variable.
- * @param value The initial value of the variable.
- */
-void consoleVarInit(
-  consolevar_t *var,
-  const char_t *name,
-  const char_t *value
-);
-
-/**
- * Initializes a console variable with a listener.
- * 
- * @param var Pointer to the console variable.
- * @param name The name of the variable.
- * @param value The initial value of the variable.
- * @param event The event to register.
- */
-void consoleVarInitListener(
-  consolevar_t *var,
-  const char_t *name,
-  const char_t *value,
-  consolevarchanged_t event
-);
-
-/**
- * Sets the value of a console variable.
- * 
- * @param var Pointer to the console variable.
- * @param value The new value of the variable.
- */
-void consoleVarSetValue(consolevar_t *var, const char_t *value);
-
-/**
- * Registers an event to be called when the value of a console variable changes.
- * 
- * @param var Pointer to the console variable.
- * @param event The event to register.
- */
-void consoleVarListen(consolevar_t *var, consolevarchanged_t event);

archive/dusk/defs.py

@@ -0,0 +1,49 @@
+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/display/renderbase.h

@@ -1,31 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#pragma once
-#include "error/error.h"
-
-#ifndef RENDER_WIDTH
-  #define RENDER_WIDTH 320
-#endif
-#ifndef RENDER_HEIGHT
-  #define RENDER_HEIGHT 240
-#endif
-
-/**
- * Initializes the rendering system.
- */
-errorret_t renderInit(void);
-
-/**
- * Tells the rendering system to actually draw the frame.
- */
-errorret_t renderDraw(void);
-
-/**
- * Disposes of the rendering system.
- */
-errorret_t renderDispose(void);

archive/dusk/display/scene.c

@@ -1,51 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#include "scene.h"
-#include "world/overworld.h"
-
-scene_t SCENE_CURRENT;
-scenecallback_t SCENE_CALLBACKS[SCENE_COUNT] = {
-  [SCENE_INITIAL] = {
-    .init = NULL,
-    .update = NULL
-  },
-
-  [SCENE_OVERWORLD] = {
-    .init = overworldInit,
-    .update = overworldUpdate,
-    .dispose = NULL
-  }
-};
-
-void sceneInit(void) {
-  for(uint8_t i = 0; i < SCENE_COUNT; i++) {
-    if(SCENE_CALLBACKS[i].init) {
-      SCENE_CALLBACKS[i].init();
-    }
-  }
-
-  SCENE_CURRENT = SCENE_OVERWORLD;
-}
-
-void sceneSet(const scene_t scene) {
-  SCENE_CURRENT = scene;
-}
-
-void sceneUpdate(void) {
-  if(SCENE_CALLBACKS[SCENE_CURRENT].update) {
-    SCENE_CALLBACKS[SCENE_CURRENT].update();
-  }
-}
-
-void sceneDispose(void) {
-  for(uint8_t i = 0; i < SCENE_COUNT; i++) {
-    if(SCENE_CALLBACKS[i].dispose) {
-      SCENE_CALLBACKS[i].dispose();
-    }
-  }
-}

archive/dusk/display/scene.h

@@ -1,47 +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"
-
-typedef enum {
-  SCENE_INITIAL,
-  SCENE_OVERWORLD,
-
-  SCENE_COUNT
-} scene_t;
-
-typedef struct {
-  void (*init)(void);
-  void (*update)(void);
-  void (*dispose)(void);
-} scenecallback_t;
-
-extern scene_t SCENE_CURRENT;
-extern scenecallback_t SCENE_CALLBACKS[SCENE_COUNT];
-
-/**
- * Initializes the scene module.
- */
-void sceneInit(void);
-
-/**
- * Sets the current scene.
- * 
- * @param scene The scene to set.
- */
-void sceneSet(const scene_t scene);
-
-/**
- * Updates the current scene.
- */
-void sceneUpdate(void);
-
-/**
- * Disposes of the current scene.
- */
-void sceneDispose(void);

archive/dusk/dusk.h

@@ -1,23 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#pragma once
-#include <stdint.h>
-#include <stdio.h>
-#include <stdbool.h>
-#include <string.h>
-#include <stdlib.h>
-#include <math.h>
-#include <errno.h>
-#include <ctype.h>
-#include <stdarg.h>
-#include <float.h>
-
-typedef bool bool_t;
-typedef int int_t;
-typedef float float_t;
-typedef char char_t;

archive/dusk/entity.py

@@ -0,0 +1,90 @@
+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/entity/direction.c

@@ -1,53 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#include "direction.h"
-#include "assert/assert.h"
-
-float_t directionToAngle(const direction_t dir) {
-  switch(dir) {
-    case DIRECTION_NORTH: return (M_PI_2);
-    case DIRECTION_SOUTH: return -(M_PI_2);
-    case DIRECTION_EAST: return 0;
-    case DIRECTION_WEST: return (M_PI);
-    default: return 0; // Should never happen
-  }
-}
-
-void directionGetCoordinates(
-  const direction_t dir,
-  int8_t *x, int8_t *y
-) {
-  assertNotNull(x, "X coordinate pointer cannot be NULL");
-  assertNotNull(y, "Y coordinate pointer cannot be NULL");
-
-  switch(dir) {
-    case DIRECTION_NORTH:
-      *x = 0;
-      *y = -1;
-      break;
-
-    case DIRECTION_SOUTH:
-      *x = 0;
-      *y = 1;
-      break;
-
-    case DIRECTION_EAST:
-      *x = 1;
-      *y = 0;
-      break;
-
-    case DIRECTION_WEST:
-      *x = -1;
-      *y = 0;
-      break;
-
-    default:
-      assertUnreachable("Invalid direction");
-      break;
-  }
-}

archive/dusk/entity/direction.h

@@ -1,41 +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"
-
-typedef enum {
-  DIRECTION_SOUTH = 0,
-  DIRECTION_EAST = 1,
-  DIRECTION_WEST = 2,
-  DIRECTION_NORTH = 3,
-
-  DIRECTION_UP = DIRECTION_NORTH,
-  DIRECTION_DOWN = DIRECTION_SOUTH,
-  DIRECTION_LEFT = DIRECTION_WEST,
-  DIRECTION_RIGHT = DIRECTION_EAST,
-} direction_t;
-
-/**
- * Converts a direction to an angle in float_t format.
- * 
- * @param dir The direction to convert.
- * @return The angle corresponding to the direction.
- */
-float_t directionToAngle(const direction_t dir);
-
-/**
- * Gets the relative coordinates for a given direction.
- * 
- * @param dir The direction to get coordinates for.
- * @param x Pointer to store the x coordinate.
- * @param y Pointer to store the y coordinate.
- */
-void directionGetCoordinates(
-  const direction_t dir,
-  int8_t *x, int8_t *y
-);

archive/dusk/entity/entity.c

@@ -1,131 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#include "entity.h"
-#include "assert/assert.h"
-#include "util/memory.h"
-#include "world/world.h"
-#include "world/tiledata.h"
-#include "time.h"
-
-entity_t ENTITIES[ENTITY_COUNT_MAX] = {0};
-
-entitycallback_t ENTITY_CALLBACKS[ENTITY_TYPE_COUNT] = {
-  {NULL}, // ENTITY_TYPE_NULL
-  {
-    .load = playerEntityLoad,
-    .update = playerEntityUpdate,
-  },
-  {
-    .load = npcLoad,
-    .update = npcUpdate,
-    .interact = npcInteract,
-  },
-};
-
-void entityLoad(entity_t *entity, const entity_t *source) {
-  assertNotNull(entity, "Entity pointer cannot be NULL");
-  assertNotNull(source, "Source entity pointer cannot be NULL");
-  assertTrue(source->type != ENTITY_TYPE_NULL, "Source entity type NULL");
-  assertTrue(source->type < ENTITY_TYPE_COUNT, "Source entity type bad");
-  assertNotNull(
-    ENTITY_CALLBACKS[source->type].load,
-    "Entity type has no i nit callback"
-  );
-  
-  memoryZero(entity, sizeof(entity_t));
-
-  entity->type = source->type;
-  entity->x = source->x;
-  entity->y = source->y;
-  entity->dir = source->dir;
-  entity->id = source->id;
-  
-  ENTITY_CALLBACKS[entity->type].load(entity, source);
-}
-
-void entityUpdate(entity_t *entity) {
-  assertNotNull(entity, "Entity pointer cannot be NULL");
-  assertTrue(entity->type != ENTITY_TYPE_NULL, "Entity type NULL");
-  assertTrue(entity->type < ENTITY_TYPE_COUNT, "Entity type out of bounds");
-  assertNotNull(
-    ENTITY_CALLBACKS[entity->type].update,
-    "Entity type has no update callback"
-  );
-
-  ENTITY_CALLBACKS[entity->type].update(entity);
-    
-  if(entity->subX > 0) {
-    entity->subX -= entity->moveSpeed;
-  } else if(entity->subX < 0) {
-    entity->subX += entity->moveSpeed;
-  }
-
-  if(entity->subY > 0) {
-    entity->subY -= entity->moveSpeed;
-  } else if(entity->subY < 0) {
-    entity->subY += entity->moveSpeed;
-  }
-}
-
-void entityMove(entity_t *entity, const uint8_t moveSpeed) {
-  assertNotNull(entity, "Entity pointer cannot be NULL");
-  assertTrue(entity->type != ENTITY_TYPE_NULL, "Entity type NULL");
-  assertTrue(entity->type < ENTITY_TYPE_COUNT, "Entity type out of bounds");
-  assertFalse(
-    entityIsMoving(entity),
-    "Entity is already moving, cannot move again"
-  );
-
-  int8_t x = 0, y = 0;
-  directionGetCoordinates(entity->dir, &x, &y);
-
-  // entity in way?
-  entity_t *ent = entityGetAt(entity->x + x, entity->y + y);
-  if(ent != NULL) return;
-
-  entity->x += x;
-  entity->y += y;
-  entity->subX = TILE_WIDTH_HEIGHT * -x;
-  entity->subY = TILE_WIDTH_HEIGHT * -y;
-  entity->moveSpeed = moveSpeed;
-}
-
-void entityTurn(entity_t *entity, const direction_t dir) {
-  assertNotNull(entity, "Entity pointer cannot be NULL");
-  assertTrue(entity->type != ENTITY_TYPE_NULL, "Entity type NULL");
-  assertTrue(entity->type < ENTITY_TYPE_COUNT, "Entity type out of bounds");
-  assertTrue(
-    dir >= DIRECTION_SOUTH && dir <= DIRECTION_NORTH, "Invalid direction"
-  );
-  assertFalse(
-    entityIsMoving(entity), "Entity is already moving, cannot turn"
-  );
-
-  entity->dir = dir;
-}
-
-bool_t entityIsMoving(const entity_t *entity) {
-  assertNotNull(entity, "Entity pointer cannot be NULL");
-  assertTrue(entity->type != ENTITY_TYPE_NULL, "Entity type NULL");
-  assertTrue(entity->type < ENTITY_TYPE_COUNT, "Entity type out of bounds");
-  return entity->subX != 0 || entity->subY != 0;
-}
-
-entity_t * entityGetAt(
-  const uint32_t tileX,
-  const uint32_t tileY
-) {
-  entity_t *entity = ENTITIES;
-
-  do {
-    if(entity->type == ENTITY_TYPE_NULL) continue;
-    if(entity->x == tileX && entity->y == tileY) return entity;
-  } while((entity++) < &ENTITIES[ENTITY_COUNT_MAX - 1]);
-
-  return NULL;
-}

archive/dusk/entity/entity.h

@@ -1,99 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#pragma once
-#include "direction.h"
-#include "player.h"
-#include "npc.h"
-
-#define ENTITY_COUNT_MAX 32
-#define ENTITY_TURN_DURATION 0.075f // Duration for turning in seconds
-#define ENTITY_MOVE_DURATION 0.1f // Duration for moving 1 tile, in seconds.
-
-typedef enum {
-  ENTITY_TYPE_NULL = 0,
-  ENTITY_TYPE_PLAYER = 1,
-  ENTITY_TYPE_NPC = 2,
-} entitytype_t;
-#define ENTITY_TYPE_COUNT 3
-
-typedef struct _entity_t {
-  uint32_t id;// Completely unique ID for this entity.
-  uint32_t x, y;
-  int8_t subX, subY;
-  uint8_t moveSpeed;
-
-  entitytype_t type;
-  direction_t dir;
-
-
-  union {
-    npc_t npc;
-    playerentity_t player;
-  };
-} entity_t;
-
-typedef struct {
-  void (*load) (entity_t *entity, const entity_t *source);
-  void (*update) (entity_t *entity);
-  void (*interact)(entity_t *player, entity_t *self);
-} entitycallback_t;
-
-extern entity_t ENTITIES[ENTITY_COUNT_MAX];
-extern entitycallback_t ENTITY_CALLBACKS[ENTITY_TYPE_COUNT];
-
-/**
- * Loads an entity from the generated entity data.
- * 
- * @param entity Pointer to the entity to initialize.
- * @param source Pointer to the source entity data.
- */
-void entityLoad(entity_t *entity, const entity_t *source);
-
-/**
- * Updates the entity's state.
- * 
- * @param entity Pointer to the entity to update.
- */
-void entityUpdate(entity_t *entity);
-
-/**
- * Moves the entity by the specified x and y offsets.
- * 
- * @param entity Pointer to the entity to move.
- * @param moveSpeed The speed at which to move the entity.
- */
-void entityMove(entity_t *entity, const uint8_t moveSpeed);
-
-/**
- * Turns the entity to face the specified direction.
- * 
- * @param entity Pointer to the entity to turn.
- * @param dir The direction to turn the entity to.
- */
-void entityTurn(entity_t *entity, const direction_t dir);
-
-/**
- * Returns whether or not an entity is currently moving.
- * 
- * @param entity Pointer to the entity to check.
- * @return True if the entity is moving, false otherwise.
- */
-bool_t entityIsMoving(const entity_t *entity);
-
-/**
- * Gets the entity at the specified tile coordinates.
- * 
- * @param tileX The x coordinate of the tile to get the entity from.
- * @param tileY The y coordinate of the tile to get the entity from.
- * @return Pointer to the entity at the specified coordinates, or NULL if no
- *         entity exists there.
- */
-entity_t *entityGetAt(
-  const uint32_t tileX,
-  const uint32_t tileY
-);

archive/dusk/entity/npc.c

@@ -1,45 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#include "entity.h"
-#include "ui/uitextbox.h"
-#include "locale/language.h"
-#include "assert/assert.h"
-
-void npcLoad(entity_t *entity, const entity_t *source) {
-  assertNotNull(entity, "Entity pointer cannot be NULL");
-  assertNotNull(source, "Source entity pointer cannot be NULL");
-  assertTrue(source->type == ENTITY_TYPE_NPC, "Source entity type must be NPC");
-
-  entity->npc = source->npc;
-}
-
-void npcUpdate(entity_t *entity) {
-}
-
-void npcInteract(entity_t *player, entity_t *self) {
-  assertTrue(self->type == ENTITY_TYPE_NPC, "Entity must be of type NPC");
-
-  switch(self->npc.interactType) {
-    case NPC_INTERACT_TYPE_NONE:
-      break;
-
-    case NPC_INTERACT_TYPE_TEXT:
-      uiTextboxSetText(languageGet(self->npc.text));
-      break;
-
-    case NPC_INTERACT_TYPE_CONVO:
-      break;
-
-    case NPC_INTERACT_TYPE_EVENT:
-      eventSetActive(self->npc.eventData);
-      break;
-
-    default:
-      assertUnreachable("Unknown NPC interaction type");
-  }
-}

archive/dusk/entity/npc.h

@@ -1,44 +0,0 @@
-
-#pragma once
-#include "event/eventlist.h"
-
-typedef struct _entity_t entity_t;
-
-typedef enum {
-  NPC_INTERACT_TYPE_NONE = 0,
-  NPC_INTERACT_TYPE_TEXT = 1,
-  NPC_INTERACT_TYPE_CONVO = 2,
-  NPC_INTERACT_TYPE_EVENT = 3,
-} npcinteracttype_t;
-
-typedef struct {
-  npcinteracttype_t interactType;
-
-  union {
-    const char_t* text;
-    const eventdata_t *eventData;
-  };
-} npc_t;
-
-/**
- * Initializes the NPC entity.
- * 
- * @param entity The entity to initialize.
- * @param source The source entity to copy data from.
- */
-void npcLoad(entity_t *entity, const entity_t *source);
-
-/**
- * Updates the NPC entity.
- * 
- * @param entity The entity to update.
- */
-void npcUpdate(entity_t *entity);
-
-/**
- * Handles interaction between the player and the NPC.
- * 
- * @param player The player entity interacting with the NPC.
- * @param self The NPC entity being interacted with.
- */
-void npcInteract(entity_t *player, entity_t *self);

archive/dusk/entity/player.c

@@ -1,94 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#include "entity.h"
-#include "assert/assert.h"
-#include "input.h"
-#include "display/render.h"
-#include "world/world.h"
-
-#include "ui/uitextbox.h"
-
-inventory_t PLAYER_INVENTORY;
-
-void playerInit() {
-  entity_t *ent = &ENTITIES[0];
-
-  entity_t playerEntityData = {
-    .id = PLAYER_ENTITY_ID,
-    .type = ENTITY_TYPE_PLAYER,
-    .x = WORLD_PLAYER_SPAWN_X,
-    .y = WORLD_PLAYER_SPAWN_Y,
-  };
-
-  entityLoad(ent, &playerEntityData);
-  inventoryInit(&PLAYER_INVENTORY, INVENTORY_SIZE_MAX);
-}
-
-void playerEntityLoad(entity_t *entity, const entity_t *source) {
-  assertNotNull(entity, "Entity pointer cannot be NULL");
-  assertNotNull(source, "Source entity pointer cannot be NULL");
-  assertTrue(entity->type == ENTITY_TYPE_PLAYER, "Entity type must be PLAYER");
-  assertTrue(source->type == entity->type, "Source/Entity type mismatch");
-}
-
-void playerEntityUpdate(entity_t *entity) {
-  assertNotNull(entity, "Entity pointer cannot be NULL");
-  assertTrue(entity->type == ENTITY_TYPE_PLAYER, "Entity type must be PLAYER");
-
-  // TODO: make this just a method somewhere.
-  if(UI_TEXTBOX.visible) return;
-  if(entityIsMoving(entity)) return;
-
-  const uint8_t moveSpeed = inputIsDown(INPUT_BIND_CANCEL) ? PLAYER_SPEED_RUN : PLAYER_SPEED_WALK;
-
-  if(inputIsDown(INPUT_BIND_UP)) {
-    if(entity->dir != DIRECTION_NORTH) {
-      entityTurn(entity, DIRECTION_NORTH);
-      return;
-    }
-    entityMove(entity, moveSpeed);
-    return;
-
-  } else if(inputIsDown(INPUT_BIND_DOWN)) {
-    if(entity->dir != DIRECTION_SOUTH) {
-      entityTurn(entity, DIRECTION_SOUTH);
-      return;
-    }
-
-    entityMove(entity, moveSpeed);
-    return;
-  } else if(inputIsDown(INPUT_BIND_LEFT)) {
-    if(entity->dir != DIRECTION_WEST) {
-      entityTurn(entity, DIRECTION_WEST);
-      return;
-    }
-    entityMove(entity, moveSpeed);
-    return;
-
-  } else if(inputIsDown(INPUT_BIND_RIGHT)) {
-    if(entity->dir != DIRECTION_EAST) {
-      entityTurn(entity, DIRECTION_EAST);
-      return;
-    }
-
-    entityMove(entity, moveSpeed);
-    return;
-  }
-
-  // Interact
-  if(inputPressed(INPUT_BIND_ACTION)) {
-    int8_t x, y;
-    directionGetCoordinates(entity->dir, &x, &y);
-    entity_t *ent = entityGetAt(entity->x + x, entity->y + y);
-
-    if(ent != NULL && ENTITY_CALLBACKS[ent->type].interact != NULL) {
-      assertTrue(ent->type < ENTITY_TYPE_COUNT, "Entity type out of bounds");
-      ENTITY_CALLBACKS[ent->type].interact(entity, ent);
-    }
-  }
-}

archive/dusk/entity/player.h

@@ -1,43 +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 "item/inventory.h"
-
-#define PLAYER_SPEED_WALK 1
-#define PLAYER_SPEED_RUN 2
-
-typedef struct _entity_t entity_t;
-
-typedef struct {
-  uint32_t nothing;
-} playerentity_t;
-
-#define PLAYER_ENTITY_ID (UINT32_MAX-1)
-
-extern inventory_t PLAYER_INVENTORY;
-
-/**
- * Initializes the player and all player-related entities.
- */
-void playerInit(void);
-
-/**
- * Loads the player entity.
- * 
- * @param entity The entity to initialize.
- * @param source The source entity to copy data from.
- */
-void playerEntityLoad(entity_t *entity, const entity_t *source);
-
-/**
- * Updates the player entity.
- * 
- * @param entity The entity to update.
- */
-void playerEntityUpdate(entity_t *entity);

archive/dusk/error/error.c

@@ -1,125 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#include "assert/assert.h"
-#include "error.h"
-#include "util/memory.h"
-#include "util/string.h"
-
-errorret_t errorThrowImpl(
-  errorstate_t *state,
-  errorcode_t code,
-  const char_t *file,
-  const char_t *function,
-  const int32_t line,
-  const char_t *message,
-  ...
-) {
-  assertNotNull(state, "Error state cannot be NULL");
-  assertTrue(code != ERROR_OK, "Error code must not be OK");
-  assertNotNull(file, "File cannot be NULL");
-  assertNotNull(function, "Function cannot be NULL");
-  assertTrue(line >= 0, "File pointer must be valid");
-  assertNotNull(message, "Message cannot be NULL");
-
-  memoryZero(state, sizeof(errorstate_t));
-  state->code = code;
-
-  // Format args.
-  va_list args;
-  va_start(args, message);
-  
-  // Get length of formatted message
-  va_list argsCopy;
-  va_copy(argsCopy, args);
-  int32_t len = stringFormatVA(NULL, 0, message, argsCopy);
-  va_end(argsCopy);
-
-  // Create string to hold the formatted message
-  state->message = (char_t *)memoryAllocate(len + 1);
-  stringFormatVA(state->message, len + 1, message, args);
-  va_end(args);
-
-  // Format lines
-  len = stringFormat(NULL, 0, ERROR_LINE_FORMAT, file, line, function);
-  assertTrue(len >= 0, "Line formatting failed");
-  state->lines = (char_t *)memoryAllocate(len + 1);
-  stringFormat(state->lines, len + 1, ERROR_LINE_FORMAT, file, line, function);
-
-  return (errorret_t) {
-    .code = code,
-    .state = state
-  };
-}
-
-errorret_t errorOkImpl() {
-  return (errorret_t) {
-    .code = ERROR_OK,
-    .state = NULL
-  };
-}
-
-errorret_t errorChainImpl(
-  const errorret_t retval,
-  const char_t *file,
-  const char_t *function,
-  const int32_t line
-) {
-  if (retval.code == ERROR_OK) return retval;
-
-  assertNotNull(retval.state, "Error state cannot be NULL");
-  assertNotNull(retval.state->message, "Message cannot be NULL");
-
-  // Create a new line string.
-  int32_t newLineLen = snprintf(NULL, 0, ERROR_LINE_FORMAT, file, line, function);
-  assertTrue(newLineLen >= 0, "Line formatting failed");
-  char_t *newLine = (char_t *)memoryAllocate(newLineLen + 1);
-  snprintf(newLine, newLineLen + 1, ERROR_LINE_FORMAT, file, line, function);
-
-  // Resize the existing lines to accommodate the new line
-  size_t existingLen = strlen(retval.state->lines);
-  memoryResize(
-    (void**)&retval.state->lines,
-    existingLen,
-    existingLen + newLineLen + 1
-  );
-
-  // Now append the new line to the existing lines
-  memoryCopy(
-    retval.state->lines + existingLen,
-    newLine,
-    newLineLen + 1
-  );
-
-  // Cleanup the temporary new line
-  memoryFree(newLine);
-  return retval;
-}
-
-void errorCatch(const errorret_t retval) {
-  if (retval.code == ERROR_OK) return;
-
-  assertNotNull(retval.state, "Error state cannot be NULL");
-  assertNotNull(retval.state->message, "Message cannot be NULL");
-
-  memoryFree((void*)retval.state->message);
-}
-
-errorret_t errorPrint(const errorret_t retval) {
-  if (retval.code == ERROR_OK) return retval;
-
-  assertNotNull(retval.state, "Error state cannot be NULL");
-  assertNotNull(retval.state->message, "Message cannot be NULL");
-
-  printf(
-    ERROR_PRINT_FORMAT,
-    retval.state->code,
-    retval.state->message,
-    retval.state->lines
-  );
-  return retval;
-}

archive/dusk/error/error.h

@@ -1,137 +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"
-
-typedef uint8_t errorcode_t;
-
-typedef struct {
-  errorcode_t code;
-  char_t *message;
-  char_t *lines;
-} errorstate_t;
-
-typedef struct {
-  errorcode_t code;
-  errorstate_t *state;
-} errorret_t;
-
-static const errorcode_t ERROR_OK = 0;
-static const errorcode_t ERROR_NOT_OK = 1;
-static const char_t *ERROR_PRINT_FORMAT = "Error (%d): %s\n%s";
-static const char_t *ERROR_LINE_FORMAT = "  at %s:%d in function %s\n";
-static errorstate_t ERROR_STATE = {
-  .code = ERROR_OK,
-  .message = NULL,
-  .lines = NULL
-};
-
-/**
- * Sets the error state with the provided code and message.
- * 
- * @param state The error state to initialize.
- * @param code The error code to set.
- * @param file The file where the error occurred.
- * @param function The function where the error occurred.
- * @param line The line number where the error occurred.
- * @param message The error message.
- * @param args The arguments for the error message.
- * @return The error code.
- */
-errorret_t errorThrowImpl(
-  errorstate_t *state,
-  errorcode_t code,
-  const char_t *file,
-  const char_t *function,
-  const int32_t line,
-  const char_t *message,
-  ...
-);
-
-/**
- * Returns an error state with no error.
- * 
- * @return An error state with code ERROR_OK.
- */
-errorret_t errorOkImpl();
-
-/**
- * Chains an error state, allowing for error propagation.
- * 
- * @param retval The return value containing the error state.
- * @param file The file where the error occurred.
- * @param function The function where the error occurred.
- * @param line The line number where the error occurred.
- * @return The error code if an error occurred, otherwise continues execution.
- */
-errorret_t errorChainImpl(
-  const errorret_t retval,
-  const char_t *file,
-  const char_t *function,
-  const int32_t line
-);
-
-/**
- * Catches an error and handles it.
- * 
- * @param retval The return value containing the error state.
- */
-void errorCatch(const errorret_t retval);
-
-/**
- * Prints the error state to the console.
- * 
- * @param retval The return value containing the error state.
- * @return Passed retval for chaining.
- */
-errorret_t errorPrint(const errorret_t retval);
-
-/**
- * Throws an error with a formatted message.
- * 
- * @param code The error code to throw.
- * @param message The format string for the error message.
- * @param ... Additional arguments for the format string.
- * @return The error code.
- */
-#define errorThrowWithCode(code, message, ... ) \
-  return errorThrowImpl(\
-    &ERROR_STATE, (code), __FILE__, __func__, __LINE__, (message), \
-    __VA_ARGS__ \
-  )
-
-/**
- * Throws an error with a default error code of ERROR_NOT_OK.
- * 
- * @param message The format string for the error message.
- * @param ... Additional arguments for the format string.
- * @return The error code.
- */
-#define errorThrow(message, ...) \
-  return errorThrowImpl(\
-    &ERROR_STATE, ERROR_NOT_OK, __FILE__, __func__, __LINE__, (message), \
-    __VA_ARGS__ \
-  )
-
-/**
- * Checks if a child method errored, and if it did, then send it up the chain.
- * @param retval The return value containing the error state.
- * @return The error code if an error occurred, otherwise continues execution.
- */
-#define errorChain(retval) \
-  if ((retval).code != ERROR_OK) { \
-    return errorChainImpl(retval, __FILE__, __func__, __LINE__); \
-  }
-
-/**
- * Returns without an error.
- */
-#define errorOk() \
-  return errorOkImpl()
-
-// EOF

archive/dusk/event.py

@@ -0,0 +1,18 @@
+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/event/CMakeLists.txt

@@ -1,11 +0,0 @@
-# Copyright (c) 2025 Dominic Masters
-#
-# This software is released under the MIT License.
-# https://opensource.org/licenses/MIT
-
-# Sources
-target_sources(${DUSK_TARGET_NAME}
-  PRIVATE
-    event.c
-    eventtext.c
-)

archive/dusk/event/event.c

@@ -1,73 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#include "event.h"
-#include "util/memory.h"
-#include "assert/assert.h"
-
-eventcallback_t EVENT_CALLBACKS[] = {
-  [EVENT_TYPE_NULL] = { NULL, NULL },
-  [EVENT_TYPE_TEXT] = { eventTextStart, eventTextUpdate },
-};
-
-event_t EVENT;
-
-void eventInit() {
-  memoryZero(&EVENT, sizeof(event_t));
-}
-
-void eventUpdate() {
-  if(EVENT.active == NULL) {
-    return; // No active event to update
-  }
-
-  const eventitem_t *item = &EVENT.active->items[EVENT.item];
-  assertNotNull(
-    EVENT_CALLBACKS[item->type].update,
-    "Event type does not have an update callback"
-  );
-
-  EVENT_CALLBACKS[item->type].update(item);
-}
-
-void eventSetActive(const eventdata_t *event) {
-  assertNotNull(event, "Event data cannot be NULL");
-  assertTrue(
-    event->itemCount <= EVENT_ITEM_COUNT_MAX,
-    "Event count too high"
-  );
-  assertTrue(event->itemCount > 0, "Event must have at least one item");
-
-  EVENT.active = event;
-  EVENT.item = 0;
-
-  const eventitem_t *firstItem = &EVENT.active->items[EVENT.item];
-
-  assertNotNull(
-    EVENT_CALLBACKS[firstItem->type].start,
-    "Event type does not have a start callback"
-  );
-  EVENT_CALLBACKS[firstItem->type].start(firstItem);
-}
-
-void eventNext() {
-  assertNotNull(EVENT.active, "No active event to proceed with");
-  assertTrue(EVENT.item < EVENT.active->itemCount, "No more items in the event");
-
-  EVENT.item++;
-  if (EVENT.item >= EVENT.active->itemCount) {
-    EVENT.active = NULL;
-    return;
-  }
-
-  const eventitem_t *nextItem = &EVENT.active->items[EVENT.item];
-  assertNotNull(
-    EVENT_CALLBACKS[nextItem->type].start,
-    "Event type does not have a start callback"
-  );
-  EVENT_CALLBACKS[nextItem->type].start(nextItem);
-}

archive/dusk/event/event.h

@@ -1,46 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#pragma once
-#include "eventdata.h"
-
-typedef struct {
-  eventdata_t data;
-  const eventdata_t *active;
-  uint8_t item;
-} event_t;
-
-typedef struct {
-  void (*start)(const eventitem_t *item);
-  void (*update)(const eventitem_t *item);
-} eventcallback_t;
-
-extern eventcallback_t EVENT_CALLBACKS[EVENT_TYPE_COUNT];
-extern event_t EVENT;
-
-/**
- * Initializes the event system.
- */
-void eventInit();
-
-/**
- * Updates the active event.
- */
-void eventUpdate();
-
-/**
- * Sets the active event.
- * 
- * @param event The event to set as active.
- */
-void eventSetActive(const eventdata_t *eventData);
-
-/**
- * Goes to the next item in the active event. Only meant to be called by
- * event items.
- */
-void eventNext();

archive/dusk/event/eventitem.h

@@ -1,26 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#pragma ocne
-#include "eventtext.h"
-
-typedef enum {
-  EVENT_TYPE_NULL = 0,
-  EVENT_TYPE_TEXT,
-} eventtype_t;
-
-#define EVENT_TYPE_COUNT 2
-
-typedef struct _eventitem_t {
-  eventtype_t type;
-
-  union {
-    eventtext_t text;
-  };
-} eventitem_t;
-
-#define EVENT_ITEM_COUNT_MAX 32

archive/dusk/event/eventtext.c

@@ -1,26 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#include "event.h"
-#include "ui/uitextbox.h"
-#include "assert/assert.h"
-
-void eventTextStart(const eventitem_t *item) {
-  assertNotNull(item, "Event item cannot be NULL");
-  assertTrue(item->type == EVENT_TYPE_TEXT, "Event item must be of type TEXT");
-  assertNotNull(item->text, "Event item must have at least one text");
-  uiTextboxSetText(item->text);
-}
-
-void eventTextUpdate(const eventitem_t *item) {
-  assertNotNull(item, "Event item cannot be NULL");
-  assertTrue(item->type == EVENT_TYPE_TEXT, "Event item must be of type TEXT");
-
-  if(!UI_TEXTBOX.visible) {
-    eventNext();
-  }
-}

archive/dusk/event/eventtext.h

@@ -1,36 +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"
-
-typedef struct _eventitem_t eventitem_t;
-
-#define EVENT_TEXT_STRING_COUNT_MAX 8
-
-typedef const char_t* eventtext_t;
-
-/**
- * Starts the text event for the given item.
- * 
- * @param item The event item to start.
- */
-void eventTextStart(const eventitem_t *item);
-
-/**
- * Updates the text event for the given item.
- * 
- * @param item The event item to update.
- */
-void eventTextUpdate(const eventitem_t *item);
-
-/**
- * Query whether the text event is done or not.
- * 
- * @param item The event item to check.
- */
-bool_t eventTextIsDone(const eventitem_t *item);

archive/dusk/game.c

@@ -1,57 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#include "game.h"
-#include "util/memory.h"
-#include "world/chunk.h"
-#include "display/scene.h"
-#include "world/overworld.h"
-#include "input.h"
-#include "event/event.h"
-#include "ui/uitextbox.h"
-#include "console/console.h"
-#include "util/memory.h"
-#include "time.h"
-
-game_t GAME;
-
-void gameInit(void) {
-  memoryZero(&GAME, sizeof(game_t));
-  GAME.running = true;
-  
-  timeInit();
-  consoleInit();
-  inputInit();
-  eventInit();
-  uiTextboxInit();
-  sceneInit();
-}
-
-void gameUpdate(void) {
-  timeUpdate();
-
-  // Game logic is tied to 60FPS for now, saves me a lot of hassle with float
-  // issues
-  float_t timeSinceLastTick = TIME.time - TIME.lastTick;
-  while(timeSinceLastTick >= TIME_STEP) {
-  
-    sceneUpdate();
-    uiTextboxUpdate();
-    eventUpdate();
-    inputUpdate();
-
-    timeSinceLastTick -= TIME_STEP;
-    TIME.lastTick = TIME.time;
-  }
-
-  if(inputPressed(INPUT_BIND_QUIT)) consoleExec("quit");
-  consoleUpdate();
-}
-
-void gameDispose(void) {
-  sceneDispose();
-}

archive/dusk/game.h

@@ -1,49 +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"
-
-typedef struct {
-  bool_t running;
-} game_t;
-
-extern game_t GAME;
-
-/**
- * Initializes the game, this should be called before any other game functions.
- * This should be called by the parent platform at a time that it deems 
- * appropriate. Any game systems cannot be used until this function has
- * been called.
- * 
- * By the point this is called, we expect;
- * - Rendering has initialized and is ready to draw.
- * - Input has been initialized and is ready to be read.
- * - If your system handles time dynamically, it should be ready to be used.
- * 
- * The systems called (in order) are;
- * - Console.
- * - Input system (Not the platforms input, but the game's input system).
- * - Time system (if applicable).
- * - Event System
- * - UI Systems.
- * - Gameplay systems.
- */
-void gameInit(void);
-
-/**
- * Asks the game to update, this will not do any drawing and should be called
- * in the main loop of the system, ideally either after or before the rendering
- * has occured.
- */
-void gameUpdate(void);
-
-/**
- * Cleans up resources used by the game, rendering really should still be
- * available at this point because we want to cleanup nicely.
- */
-void gameDispose(void);

archive/dusk/input.c

@@ -1,39 +0,0 @@
-/**
- * Copyright (c) 2025 Dominic Masters
- * 
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#include "input.h"
-#include "assert/assert.h"
-#include "util/memory.h"
-
-input_t INPUT;
-
-void inputInit(void) {
-  memoryZero(&INPUT, sizeof(input_t));
-}
-
-void inputUpdate(void) {
-  INPUT.previous = INPUT.current;
-  INPUT.current = inputStateGet();
-}
-
-bool_t inputIsDown(const inputbind_t bind) {
-  assertTrue(bind < INPUT_BIND_COUNT, "Input bind out of bounds");
-  return (INPUT.current & bind) != 0;
-}
-
-bool_t inputWasDown(const inputbind_t bind) {
-  assertTrue(bind < INPUT_BIND_COUNT, "Input bind out of bounds");
-  return (INPUT.previous & bind) != 0;
-}
-
-bool_t inputPressed(const inputbind_t bind) {
-  return inputIsDown(bind) && !inputWasDown(bind);
-}
-
-bool_t inputReleased(const inputbind_t bind) {
-  return !inputIsDown(bind) && inputWasDown(bind);
-}