Bring the entity-component system online: rendering, scene manager, scripting

entityRenderAll() (src/dusk/entity/entityrender.c) ports ac2's scene.c:sceneRender() camera/view-matrix/draw-loop logic as a standalone function - find the active camera, bind SHADER_UNLIT with its projection/ view, draw every COMPONENT_TYPE_RENDERABLE entity. display.c calls it each frame between the screen clear and screenUnbind(), the same spot the old sceneRender() used to sit. A single-scene scene manager (src/dusk/scene/, ported from ac2 minus its prefab system and physics/trigger stepping - that module hasn't been ported yet) sits alongside this but isn't wired into the engine loop yet; only one scene can ever exist (no SCENE_COUNT_MAX array). entitymanager.c/h removed entirely: its three arrays (entities/components/ entitiesWithComponent) are now plain globals in entity.h/.c (ENTITIES/COMPONENTS/ENTITIES_WITH_COMPONENT), and every entity/component function across the whole ECS (entity, component, position, camera, renderable, physics, trigger, animation) drops its entitymanager_t *mgr parameter to operate on them directly - there was only ever one instance of that struct in the whole engine, so the indirection bought nothing. New duskscript bindings (src/dusk/script/native/entity/) expose entityAdd, entityAddComponent/entityGetComponent, entitySetName/entityGetName/ entityFindByName, entityDispose/entityDisposeDeep, entityPositionSetLocalPosition/entityPositionLookAt, entityRenderableSetMesh (by name - cube/plane/sphere/capsule/triprism/quad), and COMPONENT_TYPE_*/ENTITY_ID_INVALID/COMPONENT_ID_INVALID constants. assets/init.ds uses them to spawn a camera (via LookAt from (3,3,3) at the origin), a cube and a plane as the engine's first real content on the new ECS. Co-Authored-By: Claude Sonnet 5 <[email protected]>
Fix the build after archiving rpg/ui/scene: drop their last live dependents
2026-10-15 09:08:20 -05:00 · 2026-10-15 09:08:02 -05:00 · 2026-10-14 23:25:26 -05:00 · 2026-10-14 22:59:42 -05:00 · 2026-10-14 22:33:50 -05:00 · 2026-10-14 22:33:46 -05:00
996 changed files with 47257 additions and 13543 deletions
@@ -4,36 +4,6 @@ on:
    tags:
      - '*'
 jobs:
  run-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            build-essential \
            cmake \
            python3 \
            python3-pip \
            python3-polib \
            python3-pil \
            libsdl2-dev \
            libgl1-mesa-dev \
            libzip-dev \
            python3-dotenv \
            python3-pyqt5 \
            python3-opengl \
            xz-utils \
            liblzma-dev \
            libbz2-dev \
            zlib1g-dev \
            git \
            libssl-dev
      - name: Run tests
        run: ./scripts/test-linux.sh
  build-linux:
    runs-on: ubuntu-latest
    steps:
@@ -0,0 +1,35 @@
 name: Test Dusk
 on:
  pull_request:
    branches:
      - main
 jobs:
  run-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            build-essential \
            cmake \
            python3 \
            python3-pip \
            python3-polib \
            python3-pil \
            libsdl2-dev \
            libgl1-mesa-dev \
            libzip-dev \
            python3-dotenv \
            python3-pyqt5 \
            python3-opengl \
            xz-utils \
            liblzma-dev \
            libbz2-dev \
            zlib1g-dev \
            git \
            libssl-dev
      - name: Run tests
        run: ./scripts/test-linux.sh
@@ -91,7 +91,7 @@ assets/borrowed
 /archive0
 /archive1
-# /archive
+/archive
 __pycache__
@@ -107,3 +107,4 @@ yarn.lock
 /assets/test
 /tools_old
 /assets/test.png
 /assets/audio/boa.mp3
@@ -1,455 +0,0 @@
 # Dusk — Claude Code rules
 ## 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
 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
 ### 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 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 entity component
 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 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.
 ---
 ## Color system
 Colors are defined in `src/dusk/display/color.csv` and code-generated
 into a `color.h` header by `tools/color/csv/__main__.py`.
 Each row in the CSV has `name,r,g,b,a` with channel values in `[0.0, 1.0]`.
 The script emits four `#define` variants per color plus a bare alias:
 ```
 COLOR_<NAME>_4B   color4b(r8, g8, b8, a8)   // default alias target
 COLOR_<NAME>_3B   color3b(r8, g8, b8)
 COLOR_<NAME>_3F   color3f(rf, gf, bf)
 COLOR_<NAME>_4F   color4f(rf, gf, bf, af)
 COLOR_<NAME>      COLOR_<NAME>_4B
 ```
 `color_t` is `color4b_t` (four `uint8_t` channels).
 To add a new color, append a row to `color.csv` and rebuild — do not
 hand-edit the generated header.
 ---
 ## 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`.
@@ -8,16 +8,22 @@ cmake_minimum_required(VERSION 3.13)
 set(CMAKE_C_STANDARD 11)
 set(CMAKE_C_STANDARD_REQUIRED ON)
-set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules)
+set(CMAKE_MODULE_PATH
  ${CMAKE_MODULE_PATH}
  ${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules
 )
 cmake_policy(SET CMP0079 NEW)
 # set(FETCHCONTENT_UPDATES_DISCONNECTED ON)
 option(DUSK_BUILD_TESTS "Enable tests" OFF)
 option(DUSK_NETWORK "Enable network support" ON)
 set(DUSK_GAME_NAME "Dusk" CACHE STRING "Game display name")
 set(DUSK_GAME_AUTHOR "YourWishes" CACHE STRING "Game author / coder")
 set(DUSK_GAME_SHORT_DESCRIPTION "Dusk game" CACHE STRING "One-line description")
-set(DUSK_GAME_LONG_DESCRIPTION  "No description yet." CACHE STRING "Full description")
+set(DUSK_GAME_LONG_DESCRIPTION
  "No description yet." CACHE STRING "Full description"
 )
 # Prep cache
 set(DUSK_CACHE_TARGET "dusk-target")
@@ -31,13 +37,19 @@ 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_BUILT_ASSETS_DIR "${DUSK_BUILD_DIR}/built_assets"
  CACHE INTERNAL ${DUSK_CACHE_TARGET}
 )
 set(DUSK_GENERATED_HEADERS_DIR "${DUSK_BUILD_DIR}/generated")
-set(DUSK_BUILD_BINARY ${DUSK_BUILD_DIR}/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})
+set(DUSK_ASSETS_ZIP "${DUSK_BUILD_DIR}/dusk.dsk"
  CACHE INTERNAL ${DUSK_CACHE_TARGET}
 )
 if(NOT DEFINED DUSK_TARGET_SYSTEM)
  set(DUSK_TARGET_SYSTEM "linux")
@@ -72,7 +84,9 @@ if(DUSK_BUILD_TESTS)
      ${DUSK_LIBRARY_TARGET_NAME}
  )
 else()
-  set(DUSK_LIBRARY_TARGET_NAME "${DUSK_BINARY_TARGET_NAME}" CACHE INTERNAL ${DUSK_CACHE_TARGET})
+  set(DUSK_LIBRARY_TARGET_NAME "${DUSK_BINARY_TARGET_NAME}"
    CACHE INTERNAL ${DUSK_CACHE_TARGET}
  )
 endif()
 if(NOT DEFINED DUSK_VERSION)
@@ -90,6 +104,12 @@ target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME}
    DUSK_VERSION="${DUSK_VERSION}"
 )
 if(DUSK_NETWORK)
  target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
    DUSK_NETWORK
  )
 endif()
 # Toolchains
 include(cmake/targets/${DUSK_TARGET_SYSTEM}.cmake)
@@ -115,16 +135,38 @@ if(DUSK_BUILD_TESTS)
  add_subdirectory(test)
 endif()
-# Build assets
+# Build assets. Runs unconditionally on every build (rather than being
-file(GLOB_RECURSE DUSK_ASSET_FILES CONFIGURE_DEPENDS "${DUSK_ASSETS_DIR}/*")
+# gated behind a custom_command's file-level DEPENDS list) because
-add_custom_command(
+# CONFIGURE_DEPENDS globs only pick up added/removed files on the next
-  OUTPUT "${DUSK_ASSETS_ZIP}"
+# CMake configure, so that approach could miss/lag a rebuild behind an
 # asset edit. tools.asset.pack itself decides whether anything actually
 # changed (see its manifest check) and no-ops quickly when nothing did,
 # so this stays cheap on a build where assets are untouched.
 #
 # A .ds script under assets/ is compiled to .dsb by duskscriptcc as part of
 # packing, so dusk.dsk only ever carries bytecode. duskscriptcc is a host
 # tool, only built when target_system is the build host (linux/knulli, see
 # src/CMakeLists.txt) - a cross-compiled console target has no duskscriptcc
 # of its own to depend on or pass down, so it can only pack assets with no
 # .ds in them until something sets up a host-built duskscriptcc for it too.
 if(DUSK_TARGET_SYSTEM STREQUAL "linux" OR DUSK_TARGET_SYSTEM STREQUAL "knulli")
  set(DUSK_ASSET_PACK_DUSKSCRIPTCC_ARGS --duskscriptcc "$<TARGET_FILE:duskscriptcc>")
  set(DUSK_ASSET_PACK_DEPENDS duskscriptcc)
 else()
  set(DUSK_ASSET_PACK_DUSKSCRIPTCC_ARGS "")
  set(DUSK_ASSET_PACK_DEPENDS "")
 endif()
 add_custom_target(DUSK_ASSETS_BUILT ALL
  COMMAND ${CMAKE_COMMAND} -E make_directory "${DUSK_ASSETS_DIR}"
-  COMMAND ${CMAKE_COMMAND} -E rm -f "${DUSK_ASSETS_ZIP}"
+  COMMAND ${Python3_EXECUTABLE} -m tools.asset.pack
-  COMMAND ${CMAKE_COMMAND} -E tar "cf" "${DUSK_ASSETS_ZIP}" --format=zip -- .
+    --input "${DUSK_ASSETS_DIR}"
-  WORKING_DIRECTORY "${DUSK_ASSETS_DIR}"
+    --output "${DUSK_ASSETS_ZIP}"
-  DEPENDS ${DUSK_ASSET_FILES}
+    ${DUSK_ASSET_PACK_DUSKSCRIPTCC_ARGS}
  WORKING_DIRECTORY "${DUSK_ROOT_DIR}"
  BYPRODUCTS "${DUSK_ASSETS_ZIP}"
  DEPENDS ${DUSK_ASSET_PACK_DEPENDS}
  COMMENT "Packing assets into dusk.dsk"
  VERBATIM
 )
 add_custom_target(DUSK_ASSETS_BUILT DEPENDS "${DUSK_ASSETS_ZIP}")
 add_dependencies(${DUSK_LIBRARY_TARGET_NAME} DUSK_ASSETS_BUILT)
@@ -9,15 +9,18 @@ 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
+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 libmad-devel
 ```
 `libmad-devel` (used for MP3 decoding) is GPL-licensed and ships in the
 [RPM Fusion](https://rpmfusion.org/) free repository rather than Fedora's
 base repos - make sure RPM Fusion is enabled first.
 Ubuntu;
 ```
-sudo apt-get install git build-essential gcc python python-polib python3-pillow python3-dotenv python3-numpy python3-pyqt5 python3-opengl
+sudo apt-get install git build-essential gcc python python-polib python3-pillow python3-dotenv python3-numpy python3-pyqt5 python3-opengl libmad0-dev
 ```
 Arch Linux;
 ```
-sudo pacman -S git base-devel gcc python python-polib python-pillow python-dotenv python-numpy python-pyqt5 python-opengl
+sudo pacman -S git base-devel gcc python python-polib python-pillow python-dotenv python-numpy python-pyqt5 python-opengl libmad
 ```
@@ -0,0 +1,20 @@
 // Entry point, run once by the engine after every other system is ready.
 var camera = entityAdd();
 var cameraPosition = entityAddComponent(camera, COMPONENT_TYPE_POSITION);
 entityAddComponent(camera, COMPONENT_TYPE_CAMERA);
 entityPositionLookAt(camera, cameraPosition, 3, 3, 3, 0, 0, 0);
 var cube = entityAdd();
 var cubePosition = entityAddComponent(cube, COMPONENT_TYPE_POSITION);
 var cubeRenderable = entityAddComponent(cube, COMPONENT_TYPE_RENDERABLE);
 entityRenderableSetMesh(cube, cubeRenderable, "cube");
 entityPositionSetLocalPosition(cube, cubePosition, 0, 0, 0);
 var plane = entityAdd();
 var planePosition = entityAddComponent(plane, COMPONENT_TYPE_POSITION);
 var planeRenderable = entityAddComponent(plane, COMPONENT_TYPE_RENDERABLE);
 entityRenderableSetMesh(plane, planeRenderable, "plane");
 entityPositionSetLocalPosition(plane, planePosition, 0, 0, 0);
 consolePrint("Camera, cube and plane created");
@@ -1,21 +0,0 @@
 // Copyright (c) 2026 Dominic Masters
 //
 // This software is released under the MIT License.
 // https://opensource.org/licenses/MIT
 const platformNames = {
  [System.PLATFORM_LINUX]:    'Linux',
  [System.PLATFORM_KNULLI]:   'Knulli',
  [System.PLATFORM_PSP]:      'PSP',
  [System.PLATFORM_GAMECUBE]: 'GameCube',
  [System.PLATFORM_WII]:      'Wii',
 };
 Console.print('Platform: ' + (platformNames[System.platform] || 'Unknown'));
 UIFullboxOver.setColor(Color.BLACK);
 requireAsync('testscene.js').then(Scene.set).catch(err => {
  Console.print('Error loading scene: ' + err);
  Engine.exit();
 });
@@ -5,56 +5,285 @@ msgstr ""
 "Content-Type: text/plain; charset=UTF-8\n"
 "Plural-Forms: nplurals=4; plural=(n==1 ? 0 : n==2 ? 1 : (n<7 ? 2 : 3));\n"
 # Initial Scene
 msgid "initial.checking_save.title"
 msgstr "Checking for save data"
 msgid "initial.checking_save.message"
 msgstr "Please wait..."
 msgid "initial.no_device.title"
 msgstr "No Save Device Found"
 msgid "initial.no_device.message"
 msgstr "Could not find a save device, ensure it is connected and try again. You can continue, but progress will not be saved."
 msgid "initial.no_device.retry"
 msgstr "Try again"
 msgid "initial.no_device.continue"
 msgstr "Continue without saving"
 # Main Menu Scene
 msgid "main_menu.start_game"
 msgstr "Start Game"
 msgid "main_menu.options"
 msgstr "Options"
 msgid "main_menu.quit"
 msgstr "Quit Game"
 msgid "main_menu.quit_confirm"
 msgstr "Are you sure you want to quit?"
 msgid "main_menu.checking_save.title"
 msgstr "Checking for save data"
 msgid "main_menu.checking_save.message"
 msgstr "Please wait..."
 msgid "main_menu.no_device.title"
 msgstr "No Save Device Found"
 msgid "main_menu.no_device.message"
 msgstr "Could not find a save device, ensure it is connected and try again. You can continue, but progress will not be saved."
 msgid "main_menu.no_device.retry"
 msgstr "Try again"
 msgid "main_menu.no_device.continue"
 msgstr "Continue without saving"
 msgid "main_menu.save_load_error.title"
 msgstr "Error"
 msgid "main_menu.save_load_error.message"
 msgstr "Failed to load save data. Please try again."
 msgid "main_menu.save_load_error.retry"
 msgstr "Try Again"
 # Select Save Screen
 msgid "ui.select_save.title"
 msgstr "Select Save"
 msgid "ui.select_save.empty"
 msgstr "Empty Slot"
 msgid "ui.select_save.corrupt"
 msgstr "Corrupted Save"
 msgid "ui.select_save.corrupt_warning"
 msgstr "This save file is corrupted and could not be loaded. Please contact support if this issue persists."
 msgid "ui.select_save.slot_format"
 msgstr "%s  Lv.%d  %s"
 msgid "ui.select_save.delete_mode"
 msgstr "Delete a Save"
 msgid "ui.select_save.delete_confirm"
 msgstr "Are you sure you want to delete this save?"
 msgid "ui.select_save.name_title"
 msgstr "Enter game save file name"
 msgid "ui.save_slot.number_format"
 msgstr "Slot %d"
 #: ui/menu.c:10
 msgid "ui.title"
 msgstr ""
 "Welcome"
-#: ui/user.c:22
+msgid "save.linux.mkdirp_failed"
-msgid "ui.greeting"
+msgstr "Failed to create save directory, check the disk is not full or write-protected."
 msgstr "Hello, %s!"
-#: ui/files.c:40
+#: src/dusk/ui/frame/settings/uisettings.c
-msgid "ui.file_status"
+msgid "ui.settings.tabs.general"
-msgstr "%s has %d files."
+msgstr "General"
-#: ui/cart.c:55
+#: src/dusk/ui/frame/settings/uisettings.c
-msgid "cart.item_count"
+msgid "ui.settings.tabs.input"
-msgid_plural "cart.item_count"
+msgstr "Input"
 msgstr[0] "%d item"
 msgstr[1] "%d items (dual)"
 msgstr[2] "%d items (few)"
 msgstr[3] "%d items (many)"
-#: ui/notifications.c:71
+#: src/dusk/ui/frame/settings/uisettings.c
-msgid ""
+msgid "ui.settings.tabs.display"
-"ui.multiline_help"
+msgstr "Display"
 msgstr ""
 "Line one of the help text.\n"
 "Line two continues here.\n"
 "Line three ends here."
-#: ui/errors.c:90
+#: src/dusk/ui/frame/settings/uisettings.c
-msgid ""
+msgid "ui.settings.tabs.audio"
-"error.upload_failed.long"
+msgstr "Audio"
 msgstr ""
 "Upload failed for file \"%s\".\n"
 "Please try again later or contact support."
-#: ui/messages.c:110
+msgid "ui.settings.input.deadzone"
-msgid ""
+msgstr "Deadzone"
-"user.invite_status"
+
-msgid_plural ""
+#: src/dusk/ui/frame/settings/uisettingsgeneral.c
-"user.invite_status"
+msgid "ui.settings.general.language"
-msgstr[0] ""
+msgstr "Language"
-"%s invited %d user.\n"
+
-"Please review the request."
+msgid "ui.settings.general.language_detail"
-msgstr[1] ""
+msgstr "Takes effect after restarting the application."
-"%s invited %d users (dual).\n"
+
-"Please review the requests."
+#: src/dusk/ui/frame/settings/uisettings.c
-msgstr[2] ""
+msgid "ui.settings.apply"
-"%s invited %d users (few).\n"
+msgstr "Apply"
-"Please review the requests."
+
-msgstr[3] ""
+#: src/dusk/ui/frame/uiconfirm.c
-"%s invited %d users (many).\n"
+msgid "ui.confirm.discard_changes"
-"Please review the requests."
+msgstr "Discard unsaved changes?"
 #: src/dusk/ui/frame/game/uigamemenu.c
 msgid "ui.game_menu.characters"
 msgstr "Characters"
 #: src/dusk/ui/frame/game/uigamemenu.c
 msgid "ui.game_menu.items"
 msgstr "Items"
 #: src/dusk/ui/frame/game/uigamemenu.c
 msgid "ui.game_menu.settings"
 msgstr "Settings"
 #: src/dusk/ui/frame/game/uigamemenu.c
 msgid "ui.game_menu.save"
 msgstr "Save"
 #: src/dusk/ui/frame/game/uigamemenu.c
 msgid "ui.game_menu.save_success"
 msgstr "Game saved."
 #: src/dusk/ui/frame/game/uigamemenu.c
 msgid "ui.game_menu.save_cancelled"
 msgstr "Save cancelled."
 #: src/dusk/ui/frame/game/uigamemenu.c
 msgid "ui.game_menu.save_unavailable"
 msgstr "Can't save - no save device found."
 #: src/dusk/ui/frame/game/uigamemenu.c
 msgid "ui.game_menu.save_temporary"
 msgstr "This session is temporary - no save device was found, so saving is disabled."
 #: src/dusk/ui/frame/game/uigamemenu.c
 msgid "ui.game_menu.save_create_confirm"
 msgstr "No save data found. Create a new save?"
 #: src/dusk/ui/frame/game/uigamemenu.c
 msgid "ui.game_menu.save_failed_format"
 msgstr "Save failed: %s"
 #: src/dusk/ui/frame/game/uigamemenu.c
 msgid "ui.game_menu.save_check_failed_format"
 msgstr "Can't save: %s"
 #: src/dusk/ui/frame/initial/uiinitialnocard.c
 msgid "ui.initial.no_card.message"
 msgstr "No save device found. You can continue, but\nprogress will not be saved."
 #: src/dusk/ui/frame/initial/uiinitialnocard.c
 msgid "ui.initial.no_card.retry"
 msgstr "Retry"
 #: src/dusk/ui/frame/initial/uiinitialnocard.c
 msgid "ui.initial.no_card.continue"
 msgstr "Continue Anyway"
 #: src/dusk/ui/frame/initial/uiinitialcreatesave.c
 msgid "ui.initial.create_save.message"
 msgstr "No save data found. Create a new save?"
 #: src/dusk/ui/frame/initial/uiinitialcreatesave.c
 msgid "ui.initial.create_save.yes"
 msgstr "Yes"
 #: src/dusk/ui/frame/initial/uiinitialcreatesave.c
 msgid "ui.initial.create_save.no"
 msgstr "No"
 #: src/dusk/ui/frame/uiconfirm.c
 msgid "ui.confirm.confirm"
 msgstr "Confirm"
 #: src/dusk/ui/frame/uiconfirm.c
 msgid "ui.confirm.cancel"
 msgstr "Cancel"
 #: src/dusk/ui/frame/battle/uibattlemenu.c
 msgid "ui.battle.menu.attack"
 msgstr "Attack"
 #: src/dusk/ui/frame/battle/uibattlemenu.c
 msgid "ui.battle.menu.flee"
 msgstr "Flee"
 #: src/dusk/ui/frame/battle/uibattlemenu.c
 msgid "ui.battle.menu.target_format"
 msgstr "Enemy %u (%u/%u HP)"
 #: src/dusk/ui/frame/battle/uibattlehud.c
 msgid "ui.battle.hud.hp_format"
 msgstr "HP %u/%u"
 #: src/dusk/ui/frame/battle/uibattlehud.c
 msgid "ui.battle.hud.mp_format"
 msgstr "MP %u/%u"
 #: src/dusk/ui/frame/settings/uisettingsaudio.c
 msgid "ui.settings.audio.placeholder"
 msgstr "No audio settings yet"
 #: src/dusk/ui/frame/settings/uisettingsdisplay.c
 msgid "ui.settings.display.placeholder"
 msgstr "No display settings yet"
 #: src/dusk/ui/frame/settings/uisettingsinput.c
 msgid "ui.settings.input.placeholder"
 msgstr "No input settings yet"
 #: src/dusk/ui/frame/backpack/uibackpack.c
 msgid "ui.backpack.category_format"
 msgstr "Category %u"
 #: src/dusk/ui/overlay/uiloading.c
 msgid "ui.loading.text"
 msgstr "loading"
 #: src/dusk/ui/overlay/uiautosave.c
 msgid "ui.autosave.saving"
 msgstr "SAVING"
 #
 # Items
 #
 msgid "item.potion.name"
 msgstr "Potion"
 msgid "item.potato.name"
 msgstr "Potato"
 msgid "item.apple.name"
 msgstr "Apple"
 #
 # Moves
 #
 msgid "move.fire.name"
 msgstr "Fire"
 msgid "move.slash.name"
 msgstr "Slash"
@@ -1,63 +0,0 @@
 // Copyright (c) 2026 Dominic Masters
 //
 // This software is released under the MIT License.
 // https://opensource.org/licenses/MIT
 const PLAYER_SPEED = 5.0;
 // 1 world unit = 16 pixels.
 const PIXEL_SCALE = 1.0 / 16.0;
 // Player sprite is 32x32 px (test.png dimensions).
 const PLAYER_W = 32 * PIXEL_SCALE;
 const PLAYER_H = 32 * PIXEL_SCALE;
 var player = {};
 player.getAssets = () => {
  return [
    { path: 'test.png', type: Asset.TYPE_TEXTURE, format: Texture.FORMAT_RGBA }
  ];
 }
 player.init = function(scene) {
  var texture = scene.assets.getAssetByPath('test.png');
  Console.print('Player init: got texture ' + texture);
  _entity   = Entity.create();
  _position = _entity.add(Component.POSITION);
  _physics  = _entity.add(Component.PHYSICS);
  _physics.bodyType   = Physics.DYNAMIC;
  _physics.shape      = Physics.SHAPE_CUBE;
  _physics.gravityScale = 1.0;
  var r       = _entity.add(Component.RENDERABLE);
  r.texture   = texture.texture;
  r.type      = Renderable.SPRITEBATCH;
  r.color     = new Color(220, 80, 80);
  // Upright quad centered on X, bottom-aligned on Y.
  r.sprites = [[-PLAYER_W/2, 0, 0, PLAYER_W/2, PLAYER_H, 0, 0, 1, 1, 0]];
  _position.localPosition = new Vec3(0, PLAYER_H, 0);
 };
 player.getPosition = function() {
  return _position;
 };
 player.update = function() {
  if(!_physics) return;
  var vx = Input.axis(INPUT_ACTION_LEFT, INPUT_ACTION_RIGHT) * PLAYER_SPEED;
  var vz = Input.axis(INPUT_ACTION_DOWN, INPUT_ACTION_UP) * PLAYER_SPEED;
  // Preserve vertical velocity so gravity and landing work correctly.
  var vy = _physics.velocity.y;
  _physics.velocity = new Vec3(vx, vy, vz);
 };
 player.dispose = function() {
  Entity.dispose(_entity);
  _entity   = null;
  _position = null;
  _physics  = null;
 };
 module.exports = player;
@@ -1,42 +0,0 @@
 // Copyright (c) 2026 Dominic Masters
 //
 // This software is released under the MIT License.
 // https://opensource.org/licenses/MIT
 var scene  = {};
 // Pokemon DS-style camera: ~34 degrees elevation (atan(6/9)).
 // CAM_HEIGHT / CAM_DIST ratio controls the tilt - keep it under 0.7 for
 // the characteristically shallow DS angle.
 const CAM_HEIGHT = 6;
 const CAM_DIST   = 9;
 scene.init = async function() {
  // Camera
  scene.cam = Entity.create();
  var camPos = scene.cam.add(Component.POSITION);
  var cam = scene.cam.add(Component.CAMERA);
  camPos.localPosition = new Vec3(3, 3, 3);
  camPos.lookAt(new Vec3(0, 0, 0));
  // Floor - large flat slab, no texture needed.
  scene.floor = Entity.create();
  var floorPos = scene.floor.add(Component.POSITION);
  var floorR = scene.floor.add(Component.RENDERABLE);
  floorR.type  = Renderable.SHADER_MATERIAL;
  floorR.color = Color.BLUE;
  // floorPos.localScale = new Vec3(16, 0.2, 16);
  // floorPos.localPosition = new Vec3(0, -0.1, 0);
  await UIFullboxOver.transition(Color.BLACK, Color.TRANSPARENT, 1.0);
 };
 scene.update = function() {
 };
 scene.dispose = function() {
  Entity.dispose(scene.floor);
  Entity.dispose(scene.cam);
 };
 module.exports = scene;
@@ -1,6 +0,0 @@
 module = {
  render() {
    Text.draw(0, 0, "Hello World");
    SpriteBatch.flush();
  }
 };
@@ -0,0 +1,32 @@
 # Copyright (c) 2026 Dominic Masters
 #
 # This software is released under the MIT License.
 # https://opensource.org/licenses/MIT
 # NOTE: libmad itself is GPL-licensed (see https://www.underbit.com/products/mad/),
 # not MIT like the rest of this project. Any binary linking it must comply
 # with the GPL - a deliberate tradeoff accepted for MP3 decode correctness
 # (see audiostreammp3decodersw.c's own comment on why minimp3 wasn't enough).
 find_path(LIBMAD_INCLUDE_DIR NAMES mad.h)
 mark_as_advanced(LIBMAD_INCLUDE_DIR)
 find_library(LIBMAD_LIBRARY NAMES mad)
 mark_as_advanced(LIBMAD_LIBRARY)
 include(FindPackageHandleStandardArgs)
 find_package_handle_standard_args(
  libmad
  REQUIRED_VARS
    LIBMAD_LIBRARY
    LIBMAD_INCLUDE_DIR
 )
 if(libmad_FOUND AND NOT TARGET libmad::mad)
  add_library(libmad::mad UNKNOWN IMPORTED)
  set_target_properties(libmad::mad
    PROPERTIES
      INTERFACE_INCLUDE_DIRECTORIES ${LIBMAD_INCLUDE_DIR}
      IMPORTED_LOCATION ${LIBMAD_LIBRARY}
  )
 endif()
@@ -16,6 +16,9 @@ target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
  DOL=1
  ISO=2
  DUSK_DOLPHIN_BUILD_TYPE=${DUSK_DOLPHIN_BUILD_TYPE}
  # GameCube/Wii PowerPC is always big-endian; declare it at compile time
  # like every other target instead of relying on endian.h's runtime probe.
  DUSK_PLATFORM_ENDIAN_BIG
 )
 # Custom compiler flags
@@ -58,6 +61,8 @@ target_link_libraries(${DUSK_LIBRARY_TARGET_NAME} PRIVATE
  zstd
  z
  lzma
  asnd
  mad
 )
 if(DUSK_DOLPHIN_BUILD_TYPE STREQUAL "ISO")
@@ -27,6 +27,7 @@ target_link_libraries(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
 )
 set(DUSK_BACKTRACE ON CACHE BOOL "Enable backtrace support for assert failures.")
 set(DUSK_TRACK_MEMORY ON CACHE BOOL "Track memoryAllocate() call sites to help find memory leaks.")
 # Define platform-specific macros.
 target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
@@ -36,7 +37,7 @@ target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
  # DUSK_OPENGL_LEGACY
  DUSK_LINUX
  DUSK_DISPLAY_SIZE_DYNAMIC
-  DUSK_DISPLAY_WIDTH_DEFAULT=640
+  DUSK_DISPLAY_WIDTH_DEFAULT=854
  DUSK_DISPLAY_HEIGHT_DEFAULT=480
  DUSK_DISPLAY_SCREEN_HEIGHT=240
  DUSK_INPUT_KEYBOARD
@@ -30,6 +30,7 @@ target_link_libraries(${DUSK_BINARY_TARGET_NAME} PUBLIC
  pspgu
  pspaudio
  pspaudiolib
  pspmp3
  psputility
  pspvfpu
  pspvram
@@ -55,8 +56,46 @@ target_compile_definitions(${DUSK_BINARY_TARGET_NAME} PUBLIC
  DUSK_DISPLAY_WIDTH=480
  DUSK_DISPLAY_HEIGHT=272
  DUSK_THREAD_PTHREAD
  DUSK_TIME_DYNAMIC
  DUSK_DISPLAY_OVERSCAN=6
 )
 # logDebug()/logError() additionally write every call to a file on the
 # Memory Stick (ms0:/PSP/GAME/Dusk/*.log) - a real, measured source of
 # per-call hitching (fopen+write+fclose every log line), not just a
 # theoretical cost. Default off so a normal build doesn't pay it; opt in
 # with -DDUSK_PSP_LOG_FILE=ON when the log file itself is actually needed
 # (e.g. no way to see stdout on real hardware).
 set(DUSK_PSP_LOG_FILE OFF CACHE BOOL "Also write PSP debug/error logs to ms0:/PSP/GAME/Dusk/*.log (slow - Memory Stick I/O per call).")
 if(DUSK_PSP_LOG_FILE)
  target_compile_definitions(${DUSK_BINARY_TARGET_NAME} PUBLIC
    DUSK_PSP_LOG_FILE
  )
 endif()
 if(NOT CMAKE_BUILD_TYPE STREQUAL "Debug")
  target_compile_definitions(${DUSK_BINARY_TARGET_NAME} PUBLIC
    DUSK_ASSERTIONS_FAKED
  )
 endif()
 # Generate PARAM.SFO as a normal tracked build output (instead of letting
 # create_pbp_file() auto-generate + delete it) so it can be reused below by
 # a properly dependency-tracked EBOOT.PBP repack step.
 set(DUSK_PSP_PARAM_SFO "${DUSK_BUILD_DIR}/PARAM.SFO")
 add_custom_command(
  OUTPUT "${DUSK_PSP_PARAM_SFO}"
  COMMAND "$ENV{PSPDEV}/bin/mksfoex" "-d" "MEMSIZE=1" "-s" "APP_VER=01.00"
          "${DUSK_BINARY_TARGET_NAME}" "${DUSK_PSP_PARAM_SFO}"
  COMMENT "Generating PARAM.SFO for ${DUSK_BINARY_TARGET_NAME}"
  VERBATIM
 )
 add_custom_target(DuskPspParamSfo DEPENDS "${DUSK_PSP_PARAM_SFO}")
 # create_pbp_file()'s own POST_BUILD chain (below) also consumes
 # DUSK_PSP_PARAM_SFO, so make sure it exists before that chain runs.
 add_dependencies(${DUSK_BINARY_TARGET_NAME} DuskPspParamSfo)
 # Postbuild, create .pbp file for PSP.
 create_pbp_file(
  TARGET "${DUSK_BINARY_TARGET_NAME}"
@@ -66,4 +105,33 @@ create_pbp_file(
  TITLE "${DUSK_BINARY_TARGET_NAME}"
  PSAR_PATH ${DUSK_ASSETS_ZIP}
  VERSION 01.00
  SFO_PATH "${DUSK_PSP_PARAM_SFO}"
  OUTPUT_DIR "${DUSK_BUILD_DIR}"
 )
 # CreatePBP.cmake's pack-pbp step is a POST_BUILD command tied to the
 # executable target, so it only reruns when the ELF itself relinks. That
 # means regenerating dusk.dsk (assets) alone, without touching any C
 # source, silently leaves EBOOT.PBP embedding a stale asset pak. Repack it
 # here as a normal file-tracked custom command depending on both the
 # executable and the asset zip, so EBOOT.PBP always reflects the current
 # assets even when nothing else about the build changed.
 set(DUSK_PSP_EBOOT "${DUSK_BUILD_DIR}/EBOOT.PBP")
 if(BUILD_PRX)
  set(DUSK_PSP_EXECUTABLE "$<TARGET_FILE:${DUSK_BINARY_TARGET_NAME}>.prx")
 else()
  set(DUSK_PSP_EXECUTABLE "$<TARGET_FILE:${DUSK_BINARY_TARGET_NAME}>")
 endif()
 add_custom_command(
  OUTPUT "${DUSK_PSP_EBOOT}"
  COMMAND "$ENV{PSPDEV}/bin/pack-pbp" "${DUSK_PSP_EBOOT}" "${DUSK_PSP_PARAM_SFO}"
          "NULL" "NULL" "NULL" "NULL" "NULL"
          "${DUSK_PSP_EXECUTABLE}" "${DUSK_ASSETS_ZIP}"
  DEPENDS
    "$<TARGET_FILE:${DUSK_BINARY_TARGET_NAME}>"
    "${DUSK_PSP_PARAM_SFO}"
    "${DUSK_ASSETS_ZIP}"
  COMMENT "Repacking EBOOT.PBP (tracks executable + asset pak freshness)"
  VERBATIM
 )
 add_custom_target(DuskPspEbootRepack ALL DEPENDS "${DUSK_PSP_EBOOT}")
@@ -4,6 +4,17 @@ target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
  DUSK_WII
 )
 # Wii save storage method - see src/duskdolphin/save/savedeviceplatform.h.
 set(DUSK_SAVE_WII_METHOD "SD" CACHE STRING
  "Wii save storage: NAND (internal storage via ISFS), CARD (GameCube-\
 compatible memory card emulation), or SD (SD card via libfat)"
 )
 set_property(CACHE DUSK_SAVE_WII_METHOD PROPERTY STRINGS "NAND" "CARD" "SD")
 target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
  DUSK_SAVE_WII_METHOD_${DUSK_SAVE_WII_METHOD}
 )
 # Generate Homebrew Channel meta.xml from project identity variables
 string(TIMESTAMP DUSK_BUILD_DATE "%Y%m%d000000" UTC)
 configure_file(
@@ -0,0 +1,159 @@
 // Copyright (c) 2026 Dominic Masters
 //
 // This software is released under the MIT License.
 // https://opensource.org/licenses/MIT
 "use strict";
 // ChunkTerrain - JS port of the terrain-quad generation performed by
 // tools/asset/chunk/__main__.py (build_terrain_verts / _tile_quad /
 // _RAMP_CORNERS) so the editor's 3D preview can show the same geometry the
 // Python compiler will bake into the chunk's terrain mesh, without waiting
 // for a compile pass. Vertex layout matches DMF: interleaved [u, v, x, y, z].
 const ChunkTerrain = (() => {
  const CHUNK_WIDTH  = 16;
  const CHUNK_HEIGHT = 16;
  const CHUNK_DEPTH  = 4;
  const TILE_COUNT   = CHUNK_WIDTH * CHUNK_HEIGHT * CHUNK_DEPTH;
  // World-space Z distance of one Z-layer/story, in world-float space.
  // Must match WORLD_LAYER_HEIGHT in src/dusk/rpg/overworld/worldpos.h.
  const WORLD_LAYER_HEIGHT = Math.SQRT1_2;
  const TILE_SHAPE_NULL           = 0;
  const TILE_SHAPE_GROUND         = 1;
  const TILE_SHAPE_RAMP_NORTH     = 2;
  const TILE_SHAPE_RAMP_EAST      = 3;
  const TILE_SHAPE_RAMP_SOUTH     = 4;
  const TILE_SHAPE_RAMP_WEST      = 5;
  const TILE_SHAPE_RAMP_NORTHEAST = 6;
  const TILE_SHAPE_RAMP_NORTHWEST = 7;
  const TILE_SHAPE_RAMP_SOUTHEAST = 8;
  const TILE_SHAPE_RAMP_SOUTHWEST = 9;
  const TILE_SHAPE_RAMP_NORTHEAST_INNER = 10;
  const TILE_SHAPE_RAMP_NORTHWEST_INNER = 11;
  const TILE_SHAPE_RAMP_SOUTHEAST_INNER = 12;
  const TILE_SHAPE_RAMP_SOUTHWEST_INNER = 13;
  // Per-shape corner heights as [sw, se, ne, nw] offsets from tile base Z.
  // NORTH=+Y, EAST=+X. Cardinal ramps: low face at 0, high face at 1.
  // Diagonal outer-corner ramps: only the named corner raised, rest at 0.
  // Diagonal inner-corner ramps: only the corner opposite the named one is
  // lowered to 0, the rest (including the named corner) stay raised at 1.
  const RAMP_CORNERS = {
    [TILE_SHAPE_GROUND]:         [0.0, 0.0, 0.0, 0.0],
    [TILE_SHAPE_RAMP_NORTH]:     [0.0, 0.0, 1.0, 1.0],
    [TILE_SHAPE_RAMP_SOUTH]:     [1.0, 1.0, 0.0, 0.0],
    [TILE_SHAPE_RAMP_EAST]:      [0.0, 1.0, 1.0, 0.0],
    [TILE_SHAPE_RAMP_WEST]:      [1.0, 0.0, 0.0, 1.0],
    [TILE_SHAPE_RAMP_NORTHEAST]: [0.0, 0.0, 1.0, 0.0],
    [TILE_SHAPE_RAMP_NORTHWEST]: [0.0, 0.0, 0.0, 1.0],
    [TILE_SHAPE_RAMP_SOUTHEAST]: [0.0, 1.0, 0.0, 0.0],
    [TILE_SHAPE_RAMP_SOUTHWEST]: [1.0, 0.0, 0.0, 0.0],
    [TILE_SHAPE_RAMP_NORTHEAST_INNER]: [0.0, 1.0, 1.0, 1.0],
    [TILE_SHAPE_RAMP_NORTHWEST_INNER]: [1.0, 0.0, 1.0, 1.0],
    [TILE_SHAPE_RAMP_SOUTHEAST_INNER]: [1.0, 1.0, 1.0, 0.0],
    [TILE_SHAPE_RAMP_SOUTHWEST_INNER]: [1.0, 1.0, 0.0, 1.0],
  };
  function tileIndex(x, y, z) {
    return x + y * CHUNK_WIDTH + z * CHUNK_WIDTH * CHUNK_HEIGHT;
  }
  // Six vertices (2 CCW triangles) for a quad with per-corner Z heights.
  // Corner order: SW=(fx,fy), SE=(fx+1,fy), NE=(fx+1,fy+1), NW=(fx,fy+1).
  function pushTileQuad(out, u0, u1, v0, v1, fx, fy, swZ, seZ, neZ, nwZ) {
    out.push(
      u0, v0, fx,     fy,     swZ,
      u1, v0, fx + 1, fy,     seZ,
      u1, v1, fx + 1, fy + 1, neZ,
      u0, v0, fx,     fy,     swZ,
      u1, v1, fx + 1, fy + 1, neZ,
      u0, v1, fx,     fy + 1, nwZ,
    );
  }
  // Generate terrain quads for every non-null tile in a flat tiles array
  // (length TILE_COUNT, indexed via tileIndex). Returns a Float32Array of
  // interleaved [u, v, x, y, z] vertices, matching DMF.VERTEX_FLOATS.
  function buildTerrainVerts(tiles) {
    const out = [];
    for(let z = 0; z < CHUNK_DEPTH; z++) {
      for(let y = 0; y < CHUNK_HEIGHT; y++) {
        for(let x = 0; x < CHUNK_WIDTH; x++) {
          const type = tiles[tileIndex(x, y, z)] || TILE_SHAPE_NULL;
          const corners = RAMP_CORNERS[type];
          if(!corners) continue;
          const u0 = x / CHUNK_WIDTH;
          const u1 = (x + 1) / CHUNK_WIDTH;
          const v0 = y / CHUNK_HEIGHT;
          const v1 = (y + 1) / CHUNK_HEIGHT;
          const [sw, se, ne, nw] = corners;
          pushTileQuad(
            out, u0, u1, v0, v1, x, y,
            (z + sw) * WORLD_LAYER_HEIGHT,
            (z + se) * WORLD_LAYER_HEIGHT,
            (z + ne) * WORLD_LAYER_HEIGHT,
            (z + nw) * WORLD_LAYER_HEIGHT
          );
        }
      }
    }
    return new Float32Array(out);
  }
  // Four edges (SW-SE, SE-NE, NE-NW, NW-SW) of a tile's quad as line
  // segments, lifted slightly above the terrain surface to avoid
  // z-fighting - same corner-height convention as pushTileQuad().
  function pushTileGridLines(out, fx, fy, swZ, seZ, neZ, nwZ) {
    const eps = 0.01;
    const sw = [fx,     fy,     swZ + eps];
    const se = [fx + 1, fy,     seZ + eps];
    const ne = [fx + 1, fy + 1, neZ + eps];
    const nw = [fx,     fy + 1, nwZ + eps];
    const edges = [sw, se, se, ne, ne, nw, nw, sw];
    for(const [x, y, z] of edges) out.push(0, 0, x, y, z);
  }
  // Generate grid-outline line segments for every non-null tile, following
  // the same per-corner heights as buildTerrainVerts() so lines hug ramps
  // instead of cutting through them. Returns a Float32Array of interleaved
  // [u, v, x, y, z] vertices meant to be drawn with gl.LINES (pairs).
  function buildGridLines(tiles) {
    const out = [];
    for(let z = 0; z < CHUNK_DEPTH; z++) {
      for(let y = 0; y < CHUNK_HEIGHT; y++) {
        for(let x = 0; x < CHUNK_WIDTH; x++) {
          const type = tiles[tileIndex(x, y, z)] || TILE_SHAPE_NULL;
          const corners = RAMP_CORNERS[type];
          if(!corners) continue;
          const [sw, se, ne, nw] = corners;
          pushTileGridLines(
            out, x, y,
            (z + sw) * WORLD_LAYER_HEIGHT,
            (z + se) * WORLD_LAYER_HEIGHT,
            (z + ne) * WORLD_LAYER_HEIGHT,
            (z + nw) * WORLD_LAYER_HEIGHT
          );
        }
      }
    }
    return new Float32Array(out);
  }
  return Object.freeze({
    CHUNK_WIDTH, CHUNK_HEIGHT, CHUNK_DEPTH, TILE_COUNT, WORLD_LAYER_HEIGHT,
    TILE_SHAPE_NULL, TILE_SHAPE_GROUND,
    TILE_SHAPE_RAMP_NORTH, TILE_SHAPE_RAMP_EAST,
    TILE_SHAPE_RAMP_SOUTH, TILE_SHAPE_RAMP_WEST,
    TILE_SHAPE_RAMP_NORTHEAST, TILE_SHAPE_RAMP_NORTHWEST,
    TILE_SHAPE_RAMP_SOUTHEAST, TILE_SHAPE_RAMP_SOUTHWEST,
    TILE_SHAPE_RAMP_NORTHEAST_INNER, TILE_SHAPE_RAMP_NORTHWEST_INNER,
    TILE_SHAPE_RAMP_SOUTHEAST_INNER, TILE_SHAPE_RAMP_SOUTHWEST_INNER,
    RAMP_CORNERS, tileIndex, buildTerrainVerts, buildGridLines,
  });
 })();
@@ -0,0 +1,64 @@
 // Copyright (c) 2026 Dominic Masters
 //
 // This software is released under the MIT License.
 // https://opensource.org/licenses/MIT
 "use strict";
 // DMF - Dusk Mesh Format
 //
 // Header (12 bytes):
 //   [0-3]   "DMF\0"  magic
 //   [4-7]   uint32   version (little-endian)
 //   [8-11]  uint32   vertCount (little-endian)
 //
 // Followed by vertCount vertices, each 20 bytes:
 //   [0-7]   float32[2]  uv  (little-endian)
 //   [8-19]  float32[3]  pos (little-endian)
 const DMF = (() => {
  const MAGIC          = [0x44, 0x4d, 0x46, 0x00]; // "DMF\0"
  const VERSION        = 1;
  const HEADER_SIZE    = 12;
  const VERTEX_FLOATS  = 5; // uv[2] + pos[3]
  const VERTEX_SIZE    = VERTEX_FLOATS * 4;
  // Decode a DMF ArrayBuffer into { version, vertexCount, floats }, where
  // floats is a Float32Array of tightly interleaved [u, v, x, y, z] per
  // vertex - ready to hand straight to gl.bufferData().
  function decode(buffer) {
    const bytes = new Uint8Array(buffer);
    const view  = new DataView(buffer);
    if(bytes.length < HEADER_SIZE) throw new Error("File too small to be a valid DMF");
    if(
      bytes[0] !== MAGIC[0] || bytes[1] !== MAGIC[1] ||
      bytes[2] !== MAGIC[2] || bytes[3] !== MAGIC[3]
    ) {
      throw new Error("Invalid DMF magic bytes - not a DMF file");
    }
    const version = view.getUint32(4, true);
    if(version !== VERSION) {
      throw new Error(`Unsupported DMF version: ${version}`);
    }
    const vertexCount = view.getUint32(8, true);
    const expected = HEADER_SIZE + vertexCount * VERTEX_SIZE;
    if(bytes.length < expected) {
      throw new Error(`DMF vertex data truncated (expected ${expected} bytes, got ${bytes.length})`);
    }
    const floats = new Float32Array(vertexCount * VERTEX_FLOATS);
    for(let i = 0; i < floats.length; i++) {
      floats[i] = view.getFloat32(HEADER_SIZE + i * 4, true);
    }
    return { version, vertexCount, floats };
  }
  return Object.freeze({
    decode,
    VERSION, HEADER_SIZE, VERTEX_FLOATS, VERTEX_SIZE,
  });
 })();
@@ -0,0 +1,6 @@
 <div class="row">
  <div class="col-12">
    <h1>Dusk Map Editor</h1>
    <p class="text-muted">Browse and edit project assets.</p>
  </div>
 </div>
@@ -0,0 +1,92 @@
 <link rel="stylesheet" href="/map/map.css">
 <div class="row g-3">
  <div class="col-12">
    <div class="d-flex flex-wrap align-items-end gap-2 mb-2">
      <div>
        <label class="form-label mb-0">X</label>
        <input type="number" id="coordX" class="form-control form-control-sm" style="width:5rem" value="0">
      </div>
      <div>
        <label class="form-label mb-0">Y</label>
        <input type="number" id="coordY" class="form-control form-control-sm" style="width:5rem" value="0">
      </div>
      <div>
        <label class="form-label mb-0">Z</label>
        <input type="number" id="coordZ" class="form-control form-control-sm" style="width:5rem" value="0">
      </div>
      <button id="btnLoad" type="button" class="btn btn-sm btn-secondary">Load</button>
      <div class="dropdown">
        <button
          class="btn btn-sm btn-outline-secondary dropdown-toggle"
          type="button" data-bs-toggle="dropdown"
        >Browse</button>
        <ul class="dropdown-menu" id="chunkBrowseList"></ul>
      </div>
      <div class="dpad" title="Navigate to the neighboring chunk">
        <button type="button" class="btn btn-sm btn-outline-secondary dpad-n" id="navN" title="North (+Y)">N</button>
        <button type="button" class="btn btn-sm btn-outline-secondary dpad-w" id="navW" title="West (-X)">W</button>
        <button type="button" class="btn btn-sm btn-outline-secondary dpad-e" id="navE" title="East (+X)">E</button>
        <button type="button" class="btn btn-sm btn-outline-secondary dpad-s" id="navS" title="South (-Y)">S</button>
      </div>
      <div class="d-flex flex-column gap-1">
        <button type="button" class="btn btn-sm btn-outline-secondary" id="navUp" title="Up (+Z)">Up</button>
        <button type="button" class="btn btn-sm btn-outline-secondary" id="navDown" title="Down (-Z)">Down</button>
      </div>
      <button id="btnSave" type="button" class="btn btn-sm btn-primary ms-auto">
        Save &amp; Compile
      </button>
    </div>
    <div id="statusLine" class="small text-muted mb-2">&nbsp;</div>
  </div>
  <div class="col-12 col-lg-6">
    <div class="d-flex align-items-center gap-2 mb-2">
      <label class="form-label mb-0">Z-Level</label>
      <button type="button" class="btn btn-sm btn-outline-secondary" id="zLevelDown">-</button>
      <input type="range" id="zLevel" class="form-range" style="width:150px" min="0" max="3" value="0">
      <button type="button" class="btn btn-sm btn-outline-secondary" id="zLevelUp">+</button>
      <span id="zLevelLabel">0</span>
    </div>
    <div class="d-flex gap-3">
      <div id="toolPalette" class="tile-palette"></div>
      <div id="tilePalette" class="tile-palette"></div>
      <canvas id="gridCanvas" class="border tile-grid" width="512" height="512"></canvas>
    </div>
    <h5 class="mt-3">Meshes</h5>
    <ul id="meshList" class="list-group mb-2"></ul>
    <div class="d-flex gap-2 align-items-end flex-wrap">
      <div style="min-width:220px">
        <label class="form-label mb-0">Model</label>
        <select id="meshPicker" class="form-select form-select-sm"></select>
      </div>
      <div>
        <label class="form-label mb-0">X</label>
        <input id="meshX" type="number" class="form-control form-control-sm" style="width:5rem" value="0">
      </div>
      <div>
        <label class="form-label mb-0">Y</label>
        <input id="meshY" type="number" class="form-control form-control-sm" style="width:5rem" value="0">
      </div>
      <div>
        <label class="form-label mb-0">Z</label>
        <input id="meshZ" type="number" class="form-control form-control-sm" style="width:5rem" value="0">
      </div>
      <button id="btnAddMesh" type="button" class="btn btn-sm btn-outline-primary">Add</button>
    </div>
  </div>
  <div class="col-12 col-lg-6">
    <p class="small text-muted mb-2">Preview (scroll to zoom)</p>
    <canvas id="previewCanvas" class="border" width="512" height="512"></canvas>
  </div>
 </div>
 <script src="/common/dmf.js"></script>
 <script src="/common/chunkterrain.js"></script>
 <script src="/map/renderer.js"></script>
 <script src="/map/map.js"></script>
@@ -0,0 +1,65 @@
 /* Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 .tile-palette {
  display: flex;
  flex-direction: column;
  flex-wrap: wrap;
  gap: 6px;
  max-height: 600px;
 }
 .tile-swatch {
  position: relative;
  width: 32px;
  height: 32px;
  border: 2px solid transparent;
  border-radius: 4px;
  cursor: pointer;
  padding: 0;
 }
 .tile-swatch.active {
  border-color: #fff;
 }
 .tile-swatch-icon {
  position: absolute;
  top: 0;
  left: 0;
  pointer-events: none;
 }
 .dpad {
  display: grid;
  grid-template-columns: repeat(3, 2rem);
  grid-template-rows: repeat(3, 2rem);
  grid-template-areas:
    ".  n  ."
    "w  .  e"
    ".  s  .";
  gap: 2px;
 }
 .dpad-n { grid-area: n; }
 .dpad-w { grid-area: w; }
 .dpad-e { grid-area: e; }
 .dpad-s { grid-area: s; }
 .dpad button { padding: 0; }
 .tile-grid {
  image-rendering: pixelated;
  cursor: crosshair;
  touch-action: none;
  max-width: 100%;
  height: auto;
 }
 #previewCanvas {
  width: 100%;
  aspect-ratio: 1 / 1;
  height: auto;
 }
@@ -0,0 +1,920 @@
 // Copyright (c) 2026 Dominic Masters
 //
 // This software is released under the MIT License.
 // https://opensource.org/licenses/MIT
 "use strict";
 (() => {
  const SHAPES = [
    { type: ChunkTerrain.TILE_SHAPE_NULL, name: "Erase", color: "#20232a" },
    { type: ChunkTerrain.TILE_SHAPE_GROUND, name: "Ground", color: "#4caf50" },
    { type: ChunkTerrain.TILE_SHAPE_RAMP_NORTH, name: "Ramp North", color: "#2196f3" },
    { type: ChunkTerrain.TILE_SHAPE_RAMP_EAST, name: "Ramp East", color: "#03a9f4" },
    { type: ChunkTerrain.TILE_SHAPE_RAMP_SOUTH, name: "Ramp South", color: "#00bcd4" },
    { type: ChunkTerrain.TILE_SHAPE_RAMP_WEST, name: "Ramp West", color: "#009688" },
    { type: ChunkTerrain.TILE_SHAPE_RAMP_NORTHEAST, name: "Ramp NE", color: "#ff9800" },
    { type: ChunkTerrain.TILE_SHAPE_RAMP_NORTHWEST, name: "Ramp NW", color: "#ff5722" },
    { type: ChunkTerrain.TILE_SHAPE_RAMP_SOUTHEAST, name: "Ramp SE", color: "#9c27b0" },
    { type: ChunkTerrain.TILE_SHAPE_RAMP_SOUTHWEST, name: "Ramp SW", color: "#e91e63" },
    { type: ChunkTerrain.TILE_SHAPE_RAMP_NORTHEAST_INNER, name: "Ramp NE Inner", color: "#795548" },
    { type: ChunkTerrain.TILE_SHAPE_RAMP_NORTHWEST_INNER, name: "Ramp NW Inner", color: "#607d8b" },
    { type: ChunkTerrain.TILE_SHAPE_RAMP_SOUTHEAST_INNER, name: "Ramp SE Inner", color: "#8bc34a" },
    { type: ChunkTerrain.TILE_SHAPE_RAMP_SOUTHWEST_INNER, name: "Ramp SW Inner", color: "#ffc107" },
  ];
  const SHAPE_COLORS = Object.fromEntries(SHAPES.map((s) => [s.type, s.color]));
  // Arrow direction per ramp, in canvas/screen space: north is up (dy < 0),
  // east is right (dx > 0) - matches renderGrid()'s north-is-up convention.
  const SHAPE_DIRECTIONS = {
    [ChunkTerrain.TILE_SHAPE_RAMP_NORTH]:     { dx: 0, dy: -1 },
    [ChunkTerrain.TILE_SHAPE_RAMP_SOUTH]:     { dx: 0, dy: 1 },
    [ChunkTerrain.TILE_SHAPE_RAMP_EAST]:      { dx: 1, dy: 0 },
    [ChunkTerrain.TILE_SHAPE_RAMP_WEST]:      { dx: -1, dy: 0 },
    [ChunkTerrain.TILE_SHAPE_RAMP_NORTHEAST]: { dx: 1, dy: -1 },
    [ChunkTerrain.TILE_SHAPE_RAMP_NORTHWEST]: { dx: -1, dy: -1 },
    [ChunkTerrain.TILE_SHAPE_RAMP_SOUTHEAST]: { dx: 1, dy: 1 },
    [ChunkTerrain.TILE_SHAPE_RAMP_SOUTHWEST]: { dx: -1, dy: 1 },
    [ChunkTerrain.TILE_SHAPE_RAMP_NORTHEAST_INNER]: { dx: 1, dy: -1 },
    [ChunkTerrain.TILE_SHAPE_RAMP_NORTHWEST_INNER]: { dx: -1, dy: -1 },
    [ChunkTerrain.TILE_SHAPE_RAMP_SOUTHEAST_INNER]: { dx: 1, dy: 1 },
    [ChunkTerrain.TILE_SHAPE_RAMP_SOUTHWEST_INNER]: { dx: -1, dy: 1 },
  };
  const INNER_CORNER_SHAPES = new Set([
    ChunkTerrain.TILE_SHAPE_RAMP_NORTHEAST_INNER,
    ChunkTerrain.TILE_SHAPE_RAMP_NORTHWEST_INNER,
    ChunkTerrain.TILE_SHAPE_RAMP_SOUTHEAST_INNER,
    ChunkTerrain.TILE_SHAPE_RAMP_SOUTHWEST_INNER,
  ]);
  // Draws a single-headed arrow from (tailX, tailY) to (tipX, tipY).
  function drawArrowSegment(ctx, tailX, tailY, tipX, tipY, size) {
    ctx.strokeStyle = "#ffffff";
    ctx.fillStyle = "#ffffff";
    ctx.lineWidth = Math.max(1, size * 0.08);
    ctx.lineCap = "round";
    ctx.beginPath();
    ctx.moveTo(tailX, tailY);
    ctx.lineTo(tipX, tipY);
    ctx.stroke();
    const headLen = size * 0.18;
    const angle = Math.atan2(tipY - tailY, tipX - tailX);
    const leftAngle = angle + Math.PI * 0.8;
    const rightAngle = angle - Math.PI * 0.8;
    ctx.beginPath();
    ctx.moveTo(tipX, tipY);
    ctx.lineTo(tipX + Math.cos(leftAngle) * headLen, tipY + Math.sin(leftAngle) * headLen);
    ctx.lineTo(tipX + Math.cos(rightAngle) * headLen, tipY + Math.sin(rightAngle) * headLen);
    ctx.closePath();
    ctx.fill();
  }
  // Draws an arrow centered at (cx, cy) pointing toward the ramp's high
  // side, so ramp direction is visible at a glance on both the palette
  // swatches and the tile grid. Used for cardinal ramps and outer-corner
  // ramps (a single raised corner).
  function drawArrow(ctx, cx, cy, size, dx, dy) {
    const mag = Math.hypot(dx, dy) || 1;
    const ux = dx / mag, uy = dy / mag;
    const len = size * 0.32;
    drawArrowSegment(ctx, cx - ux * len, cy - uy * len, cx + ux * len, cy + uy * len, size);
  }
  // Draws a plain right-angle bracket - two line segments meeting at 90
  // degrees at the tile's corner, one running along each of the two edges
  // adjacent to it - so inner-corner ramps (three corners raised, one
  // dropped) read as "the adjacent sides meeting in a 90-degree corner",
  // distinct from the single diagonal arrow used for outer-corner ramps.
  function drawCornerBracket(ctx, cx, cy, size, dx, dy) {
    const cornerDist = size * 0.42;
    const armLen = size * 0.34;
    const cornerX = cx + dx * cornerDist;
    const cornerY = cy + dy * cornerDist;
    ctx.strokeStyle = "#ffffff";
    ctx.lineWidth = Math.max(1, size * 0.08);
    ctx.lineCap = "round";
    ctx.lineJoin = "round";
    ctx.beginPath();
    ctx.moveTo(cornerX - dx * armLen, cornerY);
    ctx.lineTo(cornerX, cornerY);
    ctx.lineTo(cornerX, cornerY - dy * armLen);
    ctx.stroke();
  }
  // Draws the direction icon for a ramp tile `type` in a `size`x`size` area
  // centered at (cx, cy): a diagonal arrow for cardinal/outer-corner ramps,
  // or a right-angle bracket for inner-corner ramps. No-op for shapes with
  // no direction (ground, erase).
  function drawShapeIcon(ctx, cx, cy, size, type) {
    const dir = SHAPE_DIRECTIONS[type];
    if(!dir) return;
    if(INNER_CORNER_SHAPES.has(type)) {
      drawCornerBracket(ctx, cx, cy, size, dir.dx, dir.dy);
    } else {
      drawArrow(ctx, cx, cy, size, dir.dx, dir.dy);
    }
  }
  // Draws a small pencil icon centered in a `size`x`size` canvas.
  function drawPencilIcon(ctx, size) {
    ctx.save();
    ctx.translate(size / 2, size / 2);
    ctx.rotate(-Math.PI / 4);
    const shaftW = size * 0.18;
    const shaftH = size * 0.62;
    ctx.fillStyle = "#e0e0e0";
    ctx.fillRect(-shaftW / 2, shaftH * 0.28, shaftW, shaftH * 0.22);
    ctx.fillStyle = "#f0c419";
    ctx.fillRect(-shaftW / 2, -shaftH * 0.5, shaftW, shaftH * 0.78);
    ctx.fillStyle = "#8d6e63";
    ctx.beginPath();
    ctx.moveTo(-shaftW / 2, -shaftH * 0.5);
    ctx.lineTo(shaftW / 2, -shaftH * 0.5);
    ctx.lineTo(0, -shaftH * 0.5 - shaftW);
    ctx.closePath();
    ctx.fill();
    ctx.restore();
  }
  // Draws a small paint bucket icon centered in a `size`x`size` canvas.
  function drawBucketIcon(ctx, size) {
    ctx.save();
    ctx.translate(size / 2, size / 2);
    const w = size * 0.5, h = size * 0.34;
    ctx.strokeStyle = "#e0e0e0";
    ctx.lineWidth = Math.max(1, size * 0.06);
    ctx.beginPath();
    ctx.arc(0, -h * 0.4, w * 0.4, Math.PI, 0);
    ctx.stroke();
    ctx.fillStyle = "#03a9f4";
    ctx.beginPath();
    ctx.moveTo(-w / 2, -h * 0.2);
    ctx.lineTo(w / 2, -h * 0.2);
    ctx.lineTo(w * 0.32, h * 0.6);
    ctx.lineTo(-w * 0.32, h * 0.6);
    ctx.closePath();
    ctx.fill();
    ctx.beginPath();
    ctx.arc(-w * 0.55, h * 0.75, size * 0.06, 0, Math.PI * 2);
    ctx.fill();
    ctx.restore();
  }
  const TOOLS = [
    { id: "pencil", name: "Pencil", draw: drawPencilIcon },
    { id: "bucket", name: "Paint Bucket", draw: drawBucketIcon },
  ];
  let coord = { x: 0, y: 0, z: 0 };
  let tiles = new Int32Array(ChunkTerrain.TILE_COUNT);
  let meshes = [];
  let chunkExists = false;
  let currentZLevel = 0;
  let selectedShape = ChunkTerrain.TILE_SHAPE_GROUND;
  let zoomWorldH = 20;
  let dirty = false;
  let hoverTile = null;
  let activeTool = "pencil";
  let mapRenderer = null;
  let terrainMesh = null;
  let gridLinesMesh = null;
  let terrainTexturePromise = null;
  let modelIndex = null;
  let neighborChunks = [];
  const modelCache = new Map();
  const UNDO_LIMIT = 100;
  let undoStack = [];
  function markDirty() {
    dirty = true;
  }
  function snapshotState() {
    return {
      tiles: tiles.slice(),
      meshes: meshes.map((m) => ({ file: m.file, pos: m.pos.slice() })),
    };
  }
  function pushUndo() {
    undoStack.push(snapshotState());
    if(undoStack.length > UNDO_LIMIT) undoStack.shift();
  }
  function undo() {
    if(!undoStack.length) return;
    const snap = undoStack.pop();
    tiles = snap.tiles;
    meshes = snap.meshes;
    dirty = true;
    renderGrid();
    renderMeshList();
    renderPreview();
    updateStatus("Undid last change.");
  }
  // Returns true if it's OK to proceed (no unsaved changes, or the user
  // confirmed discarding them).
  function confirmDiscardIfDirty() {
    if(!dirty) return true;
    return window.confirm("You have unsaved changes to this chunk. Discard them?");
  }
  function statusLine() {
    return document.getElementById("statusLine");
  }
  function updateStatus(msg, isError) {
    const el = statusLine();
    el.textContent = msg;
    el.classList.toggle("text-danger", !!isError);
    el.classList.toggle("text-muted", !isError);
  }
  async function apiReadJson(path) {
    const res = await fetch(`/api/read?path=${encodeURIComponent(path)}`);
    const data = await res.json();
    return { ok: res.ok, data };
  }
  async function apiWrite(path, content) {
    return fetch(`/api/write?path=${encodeURIComponent(path)}`, {
      method: "POST",
      body: JSON.stringify({ content }),
    });
  }
  async function apiDelete(path) {
    return fetch(`/api/delete?path=${encodeURIComponent(path)}`, { method: "POST" });
  }
  async function apiCompileChunk(x, y, z) {
    const res = await fetch(`/api/compile-chunk?x=${x}&y=${y}&z=${z}`, { method: "POST" });
    return res.json();
  }
  async function apiLs(path) {
    const res = await fetch(`/api/ls?path=${encodeURIComponent(path)}`);
    return res.json();
  }
  async function apiFind(path, ext) {
    const res = await fetch(`/api/find?path=${encodeURIComponent(path)}&ext=${encodeURIComponent(ext)}`);
    return res.json();
  }
  function base64ToBuffer(base64) {
    const bytes = Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
    return bytes.buffer;
  }
  async function loadImageTexture(assetPath) {
    const { ok, data } = await apiReadJson(assetPath);
    if(!ok || data.error) return null;
    const blob = new Blob([base64ToBuffer(data.content)], { type: "image/png" });
    const bitmap = await createImageBitmap(blob);
    return mapRenderer.createTextureFromImage(bitmap);
  }
  async function readDmfVertices(assetPath) {
    const { ok, data } = await apiReadJson(assetPath);
    if(!ok || data.error) throw new Error(`Failed to read ${assetPath}`);
    return DMF.decode(base64ToBuffer(data.content)).floats;
  }
  async function ensureModelIndex() {
    if(modelIndex) return modelIndex;
    const res = await apiFind("assets/models", ".json");
    modelIndex = new Map();
    for(const file of res.files || []) {
      const base = file.split("/").pop().replace(/\.json$/, "");
      modelIndex.set(base, file);
    }
    return modelIndex;
  }
  // Scales a mesh's stored [x, y, z] offset for preview, matching the
  // Z scaling mapChunkLoaded() applies at runtime (chunk.meshOffsets[m][2]
  // * WORLD_LAYER_HEIGHT) - x/y stay 1:1 since only Z is height-scaled.
  function scaledMeshOffset(pos) {
    return [pos[0], pos[1], pos[2] * ChunkTerrain.WORLD_LAYER_HEIGHT];
  }
  // Resolves a chunk mesh entry's bare filename (e.g. "house_5_3.dmf") to
  // its model JSON by basename, mirroring find_model() in
  // tools/asset/chunk/__main__.py - the chunk JSON only ever stores a bare
  // filename, not a path.
  async function resolveModelForMeshFile(file) {
    await ensureModelIndex();
    const base = file.replace(/\.[^.]+$/, "");
    const rel = modelIndex.get(base);
    if(!rel) return null;
    const modelPath = `assets/models/${rel}`;
    if(modelCache.has(modelPath)) return modelCache.get(modelPath);
    const promise = (async () => {
      const { ok, data } = await apiReadJson(modelPath);
      if(!ok || data.error) throw new Error(`Failed to read model ${modelPath}`);
      const modelDef = JSON.parse(data.content);
      const meshFloats = await readDmfVertices(`assets/${modelDef.mesh}`);
      const mesh = mapRenderer.createMesh(meshFloats);
      const texture = modelDef.texture ? await loadImageTexture(`assets/${modelDef.texture}`) : null;
      const colorBytes = modelDef.color || [255, 255, 255, 255];
      const color = colorBytes.map((c) => c / 255);
      return { mesh, texture, color };
    })();
    modelCache.set(modelPath, promise);
    return promise;
  }
  const MAP_NAME = "overworld";
  function chunkPaths(x, y, z) {
    return {
      raw: `assetsraw/maps/${MAP_NAME}/chunks/chunk_${x}_${y}_${z}.json`,
      dcf: `assets/maps/${MAP_NAME}/chunks/${x}_${y}_${z}.dcf`,
      terrainDmf: `assets/maps/${MAP_NAME}/meshes/chunks/chunk_${x}_${y}_${z}_0.dmf`,
      terrainModel: `assets/maps/${MAP_NAME}/models/chunks/chunk_${x}_${y}_${z}_0.json`,
    };
  }
  // Loads the 8 same-Z neighbors around `coord` (read-only, for context in
  // the 3D preview) and pre-builds their render data so renderPreview()
  // doesn't have to rebuild GL buffers on every paint stroke.
  async function loadNeighborChunks() {
    const offsets = [];
    for(let dy = -1; dy <= 1; dy++) {
      for(let dx = -1; dx <= 1; dx++) {
        if(dx || dy) offsets.push({ dx, dy });
      }
    }
    const results = await Promise.all(offsets.map(async ({ dx, dy }) => {
      const nx = coord.x + dx, ny = coord.y + dy, nz = coord.z;
      const { ok, data } = await apiReadJson(chunkPaths(nx, ny, nz).raw);
      if(!ok || data.error) return null;
      const json = JSON.parse(data.content);
      const neighborTiles = new Int32Array(ChunkTerrain.TILE_COUNT);
      for(const t of json.tiles || []) {
        const [tx, ty, tz] = t.pos;
        neighborTiles[ChunkTerrain.tileIndex(tx, ty, tz)] = t.type;
      }
      const neighborMeshes = (json.meshes || []).map((m) => ({ file: m.file, pos: m.pos || [0, 0, 0] }));
      const floats = ChunkTerrain.buildTerrainVerts(neighborTiles);
      const terrain = floats.length ? { mesh: mapRenderer.createMesh(floats) } : null;
      const models = [];
      for(const m of neighborMeshes) {
        try {
          const resolved = await resolveModelForMeshFile(m.file);
          if(resolved) models.push({ ...resolved, offset: scaledMeshOffset(m.pos) });
        } catch(e) {
          console.warn("Failed to load neighbor mesh preview", m.file, e);
        }
      }
      return {
        offset: [dx * ChunkTerrain.CHUNK_WIDTH, dy * ChunkTerrain.CHUNK_HEIGHT, 0],
        terrain,
        models,
      };
    }));
    neighborChunks = results.filter(Boolean);
  }
  async function loadChunk(x, y, z) {
    coord = { x, y, z };
    tiles = new Int32Array(ChunkTerrain.TILE_COUNT);
    meshes = [];
    chunkExists = false;
    const { ok, data } = await apiReadJson(chunkPaths(x, y, z).raw);
    if(ok && !data.error) {
      chunkExists = true;
      const json = JSON.parse(data.content);
      for(const t of json.tiles || []) {
        const [tx, ty, tz] = t.pos;
        tiles[ChunkTerrain.tileIndex(tx, ty, tz)] = t.type;
      }
      meshes = (json.meshes || []).map((m) => ({ file: m.file, pos: m.pos || [0, 0, 0] }));
    }
    await loadNeighborChunks();
    dirty = false;
    undoStack = [];
    renderGrid();
    renderMeshList();
    renderPreview();
    updateStatus(chunkExists
      ? `Loaded chunk_${x}_${y}_${z}.json`
      : `New (empty) chunk at ${x}, ${y}, ${z} - paint a tile and save to create it.`);
  }
  async function saveChunk() {
    const tilesArr = [];
    for(let z = 0; z < ChunkTerrain.CHUNK_DEPTH; z++) {
      for(let y = 0; y < ChunkTerrain.CHUNK_HEIGHT; y++) {
        for(let x = 0; x < ChunkTerrain.CHUNK_WIDTH; x++) {
          const type = tiles[ChunkTerrain.tileIndex(x, y, z)];
          if(type && type !== ChunkTerrain.TILE_SHAPE_NULL) {
            tilesArr.push({ pos: [x, y, z], type, tile: 0 });
          }
        }
      }
    }
    const paths = chunkPaths(coord.x, coord.y, coord.z);
    if(tilesArr.length === 0 && meshes.length === 0) {
      await Promise.all(Object.values(paths).map((p) => apiDelete(p)));
      chunkExists = false;
      dirty = false;
      updateStatus(`Chunk ${coord.x}, ${coord.y}, ${coord.z} is empty - deleted.`);
      return;
    }
    const json = { tiles: tilesArr, meshes: meshes.map((m) => ({ file: m.file, pos: m.pos })) };
    await apiWrite(paths.raw, JSON.stringify(json, null, 2));
    chunkExists = true;
    dirty = false;
    updateStatus("Saved. Compiling...");
    const result = await apiCompileChunk(coord.x, coord.y, coord.z);
    if(result.ok) {
      updateStatus(`Compiled OK.\n${result.stdout}`);
    } else {
      updateStatus(`Compile FAILED (code ${result.returncode}):\n${result.stderr}`, true);
    }
  }
  function buildPalette() {
    const el = document.getElementById("tilePalette");
    el.innerHTML = "";
    for(const s of SHAPES) {
      const btn = document.createElement("button");
      btn.type = "button";
      btn.className = "tile-swatch" + (s.type === selectedShape ? " active" : "");
      btn.style.background = s.color;
      btn.title = s.name;
      btn.addEventListener("click", () => {
        selectedShape = s.type;
        buildPalette();
      });
      if(SHAPE_DIRECTIONS[s.type]) {
        const icon = document.createElement("canvas");
        icon.width = 32;
        icon.height = 32;
        icon.className = "tile-swatch-icon";
        drawShapeIcon(icon.getContext("2d"), 16, 16, 32, s.type);
        btn.appendChild(icon);
      }
      el.appendChild(btn);
    }
  }
  function buildToolPalette() {
    const el = document.getElementById("toolPalette");
    el.innerHTML = "";
    for(const tool of TOOLS) {
      const btn = document.createElement("button");
      btn.type = "button";
      btn.className = "tile-swatch" + (tool.id === activeTool ? " active" : "");
      btn.style.background = "#2a2d33";
      btn.title = tool.name;
      btn.addEventListener("click", () => {
        activeTool = tool.id;
        buildToolPalette();
      });
      const icon = document.createElement("canvas");
      icon.width = 32;
      icon.height = 32;
      icon.className = "tile-swatch-icon";
      tool.draw(icon.getContext("2d"), 32);
      btn.appendChild(icon);
      el.appendChild(btn);
    }
  }
  function canvasToTile(e, canvas) {
    const rect = canvas.getBoundingClientRect();
    const cell = canvas.width / ChunkTerrain.CHUNK_WIDTH;
    const px = (e.clientX - rect.left) * (canvas.width / rect.width);
    const py = (e.clientY - rect.top) * (canvas.height / rect.height);
    const x = Math.floor(px / cell);
    const yFromTop = Math.floor(py / cell);
    const y = ChunkTerrain.CHUNK_HEIGHT - 1 - yFromTop;
    if(x < 0 || x >= ChunkTerrain.CHUNK_WIDTH || y < 0 || y >= ChunkTerrain.CHUNK_HEIGHT) return null;
    return { x, y };
  }
  function renderGrid() {
    const canvas = document.getElementById("gridCanvas");
    const ctx = canvas.getContext("2d");
    const cell = canvas.width / ChunkTerrain.CHUNK_WIDTH;
    ctx.clearRect(0, 0, canvas.width, canvas.height);
    for(let y = 0; y < ChunkTerrain.CHUNK_HEIGHT; y++) {
      for(let x = 0; x < ChunkTerrain.CHUNK_WIDTH; x++) {
        const type = tiles[ChunkTerrain.tileIndex(x, y, currentZLevel)];
        const sy = (ChunkTerrain.CHUNK_HEIGHT - 1 - y) * cell;
        ctx.fillStyle = SHAPE_COLORS[type] || "#15171b";
        ctx.fillRect(x * cell, sy, cell, cell);
        ctx.strokeStyle = "rgba(255, 255, 255, 0.25)";
        ctx.strokeRect(x * cell, sy, cell, cell);
        drawShapeIcon(ctx, x * cell + cell / 2, sy + cell / 2, cell, type);
      }
    }
    ctx.fillStyle = "#ffffff";
    for(const m of meshes) {
      const [mx, my, mz] = m.pos;
      if(Math.round(mz) !== currentZLevel) continue;
      const sy = (ChunkTerrain.CHUNK_HEIGHT - 1 - my) * cell;
      ctx.beginPath();
      ctx.arc(mx * cell + cell / 2, sy + cell / 2, cell * 0.3, 0, Math.PI * 2);
      ctx.fill();
    }
    if(hoverTile) {
      const sy = (ChunkTerrain.CHUNK_HEIGHT - 1 - hoverTile.y) * cell;
      ctx.strokeStyle = "#ffeb3b";
      ctx.lineWidth = 2;
      ctx.strokeRect(hoverTile.x * cell + 1, sy + 1, cell - 2, cell - 2);
    }
  }
  function hitTestMesh(e, canvas) {
    const rect = canvas.getBoundingClientRect();
    const cell = canvas.width / ChunkTerrain.CHUNK_WIDTH;
    const px = (e.clientX - rect.left) * (canvas.width / rect.width);
    const py = (e.clientY - rect.top) * (canvas.height / rect.height);
    let closest = -1;
    let closestDist = cell * 0.5;
    meshes.forEach((m, i) => {
      const [mx, my, mz] = m.pos;
      if(Math.round(mz) !== currentZLevel) return;
      const cx = mx * cell + cell / 2;
      const cy = (ChunkTerrain.CHUNK_HEIGHT - 1 - my) * cell + cell / 2;
      const dist = Math.hypot(px - cx, py - cy);
      if(dist < closestDist) { closestDist = dist; closest = i; }
    });
    return closest;
  }
  function moveMeshTo(e, index) {
    const canvas = document.getElementById("gridCanvas");
    const t = canvasToTile(e, canvas);
    if(!t) return;
    meshes[index].pos[0] = t.x;
    meshes[index].pos[1] = t.y;
    markDirty();
    renderGrid();
    renderMeshList();
    renderPreview();
  }
  function paintAt(e) {
    const canvas = document.getElementById("gridCanvas");
    const t = canvasToTile(e, canvas);
    if(!t) return;
    tiles[ChunkTerrain.tileIndex(t.x, t.y, currentZLevel)] = selectedShape;
    markDirty();
    renderGrid();
    renderPreview();
  }
  // 4-connected flood fill of same-type tiles at the current Z-level,
  // starting from (startX, startY), replacing them with selectedShape.
  function floodFill(startX, startY) {
    const targetType = tiles[ChunkTerrain.tileIndex(startX, startY, currentZLevel)];
    if(targetType === selectedShape) return;
    const stack = [[startX, startY]];
    const visited = new Set();
    while(stack.length) {
      const [x, y] = stack.pop();
      const key = `${x},${y}`;
      if(visited.has(key)) continue;
      if(x < 0 || x >= ChunkTerrain.CHUNK_WIDTH || y < 0 || y >= ChunkTerrain.CHUNK_HEIGHT) continue;
      visited.add(key);
      const idx = ChunkTerrain.tileIndex(x, y, currentZLevel);
      if(tiles[idx] !== targetType) continue;
      tiles[idx] = selectedShape;
      stack.push([x + 1, y], [x - 1, y], [x, y + 1], [x, y - 1]);
    }
  }
  function fillAt(e) {
    const canvas = document.getElementById("gridCanvas");
    const t = canvasToTile(e, canvas);
    if(!t) return;
    pushUndo();
    floodFill(t.x, t.y);
    markDirty();
    renderGrid();
    renderPreview();
  }
  function rebuildTerrainMesh() {
    const floats = ChunkTerrain.buildTerrainVerts(tiles);
    terrainMesh = floats.length ? mapRenderer.createMesh(floats) : null;
    const lineFloats = ChunkTerrain.buildGridLines(tiles);
    gridLinesMesh = lineFloats.length ? mapRenderer.createMesh(lineFloats) : null;
  }
  // Keeps the preview canvas's backing-store resolution matched to its
  // actual displayed CSS size (times devicePixelRatio) - the canvas
  // otherwise stays at its fixed width/height attributes (512x512) while
  // CSS stretches it to fill the column, which upscales and blurs the
  // WebGL output on wider or high-DPI screens.
  function resizePreviewCanvas() {
    const canvas = document.getElementById("previewCanvas");
    const dpr = window.devicePixelRatio || 1;
    const displayWidth = Math.max(1, Math.round(canvas.clientWidth * dpr));
    const displayHeight = Math.max(1, Math.round(canvas.clientHeight * dpr));
    if(canvas.width !== displayWidth || canvas.height !== displayHeight) {
      canvas.width = displayWidth;
      canvas.height = displayHeight;
    }
  }
  async function renderPreview() {
    if(!mapRenderer) return;
    resizePreviewCanvas();
    rebuildTerrainMesh();
    const models = [];
    for(const m of meshes) {
      try {
        const resolved = await resolveModelForMeshFile(m.file);
        if(resolved) models.push({ ...resolved, offset: scaledMeshOffset(m.pos) });
      } catch(e) {
        console.warn("Failed to load mesh preview", m.file, e);
      }
    }
    let terrainTexture = null;
    if(terrainMesh || neighborChunks.some((n) => n.terrain)) {
      if(!terrainTexturePromise) terrainTexturePromise = loadImageTexture("assets/tiles.png");
      terrainTexture = await terrainTexturePromise;
    }
    const neighbors = neighborChunks.map((n) => ({
      offset: n.offset,
      terrain: n.terrain ? { mesh: n.terrain.mesh, texture: terrainTexture } : null,
      models: n.models,
    }));
    const zLevelHeight = currentZLevel * ChunkTerrain.WORLD_LAYER_HEIGHT;
    mapRenderer.render({
      target: [ChunkTerrain.CHUNK_WIDTH / 2, ChunkTerrain.CHUNK_HEIGHT / 2, zLevelHeight],
      worldH: zoomWorldH,
      terrain: terrainMesh ? { mesh: terrainMesh, texture: terrainTexture } : null,
      gridLines: gridLinesMesh ? { mesh: gridLinesMesh } : null,
      models,
      neighbors,
      highlight: hoverTile ? { x: hoverTile.x, y: hoverTile.y, z: zLevelHeight } : null,
    });
  }
  function renderMeshList() {
    const ul = document.getElementById("meshList");
    ul.innerHTML = "";
    meshes.forEach((m, i) => {
      const li = document.createElement("li");
      li.className = "list-group-item d-flex align-items-center gap-2 flex-wrap";
      const label = document.createElement("span");
      label.className = "me-auto";
      label.textContent = m.file;
      li.appendChild(label);
      ["X", "Y", "Z"].forEach((axis, axisIndex) => {
        const input = document.createElement("input");
        input.type = "number";
        input.className = "form-control form-control-sm";
        input.style.width = "5rem";
        input.title = axis;
        input.value = m.pos[axisIndex];
        input.addEventListener("change", () => {
          pushUndo();
          m.pos[axisIndex] = parseFloat(input.value) || 0;
          markDirty();
          renderGrid();
          renderPreview();
        });
        li.appendChild(input);
      });
      const btn = document.createElement("button");
      btn.type = "button";
      btn.className = "btn btn-sm btn-outline-danger";
      btn.textContent = "Remove";
      btn.addEventListener("click", () => {
        pushUndo();
        meshes.splice(i, 1);
        markDirty();
        renderMeshList();
        renderGrid();
        renderPreview();
      });
      li.appendChild(btn);
      ul.appendChild(li);
    });
  }
  async function buildMeshPicker() {
    await ensureModelIndex();
    const select = document.getElementById("meshPicker");
    select.innerHTML = "";
    for(const [base, rel] of [...modelIndex.entries()].sort()) {
      const opt = document.createElement("option");
      opt.value = base;
      opt.textContent = rel;
      select.appendChild(opt);
    }
  }
  async function buildChunkBrowseList() {
    const list = document.getElementById("chunkBrowseList");
    list.innerHTML = "";
    const res = await apiLs(`assetsraw/maps/${MAP_NAME}/chunks`);
    for(const entry of res.entries || []) {
      const m = entry.name.match(/^chunk_(-?\d+)_(-?\d+)_(-?\d+)\.json$/);
      if(!m) continue;
      const [, x, y, z] = m;
      const li = document.createElement("li");
      const a = document.createElement("a");
      a.className = "dropdown-item";
      a.href = "#";
      a.textContent = `${x}, ${y}, ${z}`;
      a.addEventListener("click", (e) => {
        e.preventDefault();
        goToChunk(parseInt(x, 10), parseInt(y, 10), parseInt(z, 10));
      });
      li.appendChild(a);
      list.appendChild(li);
    }
  }
  function setCoordInputs(x, y, z) {
    document.getElementById("coordX").value = x;
    document.getElementById("coordY").value = y;
    document.getElementById("coordZ").value = z;
  }
  function goToChunk(x, y, z) {
    if(!confirmDiscardIfDirty()) return;
    setCoordInputs(x, y, z);
    loadChunk(x, y, z);
  }
  function bindEvents() {
    const gridCanvas = document.getElementById("gridCanvas");
    let painting = false;
    let draggingMeshIndex = -1;
    gridCanvas.addEventListener("mousedown", (e) => {
      if(activeTool === "bucket") {
        fillAt(e);
        return;
      }
      const hit = hitTestMesh(e, gridCanvas);
      pushUndo();
      if(hit !== -1) {
        draggingMeshIndex = hit;
        return;
      }
      painting = true;
      paintAt(e);
    });
    window.addEventListener("mouseup", () => { painting = false; draggingMeshIndex = -1; });
    gridCanvas.addEventListener("mousemove", (e) => {
      hoverTile = canvasToTile(e, gridCanvas);
      if(draggingMeshIndex !== -1) { moveMeshTo(e, draggingMeshIndex); return; }
      if(painting) { paintAt(e); return; }
      renderGrid();
      renderPreview();
    });
    gridCanvas.addEventListener("mouseleave", () => {
      hoverTile = null;
      renderGrid();
      renderPreview();
    });
    function setZLevel(z) {
      currentZLevel = Math.max(0, Math.min(ChunkTerrain.CHUNK_DEPTH - 1, z));
      document.getElementById("zLevel").value = currentZLevel;
      document.getElementById("zLevelLabel").textContent = currentZLevel;
      renderGrid();
      renderPreview();
    }
    document.getElementById("zLevel").addEventListener("input", (e) => {
      setZLevel(parseInt(e.target.value, 10));
    });
    document.getElementById("zLevelDown").addEventListener("click", () => setZLevel(currentZLevel - 1));
    document.getElementById("zLevelUp").addEventListener("click", () => setZLevel(currentZLevel + 1));
    document.getElementById("btnLoad").addEventListener("click", () => {
      const x = parseInt(document.getElementById("coordX").value, 10) || 0;
      const y = parseInt(document.getElementById("coordY").value, 10) || 0;
      const z = parseInt(document.getElementById("coordZ").value, 10) || 0;
      goToChunk(x, y, z);
    });
    // NORTH=+Y, EAST=+X (matches tile-shape convention used by the tile
    // grid and tools/asset/chunk/__main__.py).
    document.getElementById("navN").addEventListener("click", () => goToChunk(coord.x, coord.y + 1, coord.z));
    document.getElementById("navS").addEventListener("click", () => goToChunk(coord.x, coord.y - 1, coord.z));
    document.getElementById("navE").addEventListener("click", () => goToChunk(coord.x + 1, coord.y, coord.z));
    document.getElementById("navW").addEventListener("click", () => goToChunk(coord.x - 1, coord.y, coord.z));
    document.getElementById("navUp").addEventListener("click", () => goToChunk(coord.x, coord.y, coord.z + 1));
    document.getElementById("navDown").addEventListener("click", () => goToChunk(coord.x, coord.y, coord.z - 1));
    function runSave() {
      saveChunk().catch((e) => updateStatus(`Save failed: ${e.message}`, true));
    }
    document.getElementById("btnSave").addEventListener("click", runSave);
    document.getElementById("btnAddMesh").addEventListener("click", () => {
      const base = document.getElementById("meshPicker").value;
      if(!base) return;
      const pos = [
        parseFloat(document.getElementById("meshX").value) || 0,
        parseFloat(document.getElementById("meshY").value) || 0,
        parseFloat(document.getElementById("meshZ").value) || 0,
      ];
      pushUndo();
      meshes.push({ file: `${base}.dmf`, pos });
      markDirty();
      renderMeshList();
      renderGrid();
      renderPreview();
    });
    document.getElementById("previewCanvas").addEventListener("wheel", (e) => {
      e.preventDefault();
      zoomWorldH = Math.min(60, Math.max(4, zoomWorldH + Math.sign(e.deltaY)));
      renderPreview();
    }, { passive: false });
    window.addEventListener("resize", () => renderPreview());
    window.addEventListener("keydown", (e) => {
      if(!(e.ctrlKey || e.metaKey)) return;
      const key = e.key.toLowerCase();
      if(key === "z") {
        e.preventDefault();
        undo();
      } else if(key === "s") {
        e.preventDefault();
        runSave();
      }
    });
  }
  document.addEventListener("DOMContentLoaded", async () => {
    buildPalette();
    buildToolPalette();
    mapRenderer = MapRenderer.create(document.getElementById("previewCanvas"));
    bindEvents();
    await Promise.all([buildChunkBrowseList(), buildMeshPicker()]);
    await loadChunk(coord.x, coord.y, coord.z);
  });
 })();
@@ -0,0 +1,298 @@
 // Copyright (c) 2026 Dominic Masters
 //
 // This software is released under the MIT License.
 // https://opensource.org/licenses/MIT
 "use strict";
 // MapRenderer - a minimal, dependency-free WebGL renderer for the chunk
 // preview pane. The camera formula is ported 1:1 from
 // src/dusk/scene/overworld/sceneoverworld.c (lines 62-81) so the preview
 // approximates the game's own fixed-angle 3rd-person camera: the eye sits
 // worldH units "behind" the target along Y and a proportional distance
 // "above" along Z, always looking at the target, up = (0, 1, 0).
 //
 // The material model mirrors SHADER_UNLIT: a texture sampler multiplied by
 // a flat RGBA tint, with a 1x1 white fallback texture standing in for
 // untextured models.
 const MapRenderer = (() => {
  const VERT_SRC = `
    attribute vec2 aUV;
    attribute vec3 aPos;
    uniform mat4 uModel;
    uniform mat4 uView;
    uniform mat4 uProjection;
    varying vec2 vUV;
    void main() {
      vUV = aUV;
      gl_Position = uProjection * uView * uModel * vec4(aPos, 1.0);
    }
  `;
  const FRAG_SRC = `
    precision mediump float;
    varying vec2 vUV;
    uniform sampler2D uTexture;
    uniform vec4 uColor;
    void main() {
      gl_FragColor = texture2D(uTexture, vUV) * uColor;
    }
  `;
  function mat4Identity(out) {
    out.fill(0);
    out[0] = out[5] = out[10] = out[15] = 1;
    return out;
  }
  function mat4Translation(out, v) {
    mat4Identity(out);
    out[12] = v[0];
    out[13] = v[1];
    out[14] = v[2];
    return out;
  }
  function mat4Perspective(out, fovy, aspect, near, far) {
    const f = 1.0 / Math.tan(fovy / 2);
    out.fill(0);
    out[0] = f / aspect;
    out[5] = f;
    out[10] = (far + near) / (near - far);
    out[11] = -1;
    out[14] = (2 * far * near) / (near - far);
    return out;
  }
  function vec3Sub(a, b) {
    return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
  }
  function vec3Cross(a, b) {
    return [
      a[1] * b[2] - a[2] * b[1],
      a[2] * b[0] - a[0] * b[2],
      a[0] * b[1] - a[1] * b[0],
    ];
  }
  function vec3Normalize(a) {
    const len = Math.hypot(a[0], a[1], a[2]) || 1;
    return [a[0] / len, a[1] / len, a[2] / len];
  }
  function mat4LookAt(out, eye, center, up) {
    const zAxis = vec3Normalize(vec3Sub(eye, center));
    const xAxis = vec3Normalize(vec3Cross(up, zAxis));
    const yAxis = vec3Cross(zAxis, xAxis);
    out[0] = xAxis[0]; out[1] = yAxis[0]; out[2] = zAxis[0]; out[3] = 0;
    out[4] = xAxis[1]; out[5] = yAxis[1]; out[6] = zAxis[1]; out[7] = 0;
    out[8] = xAxis[2]; out[9] = yAxis[2]; out[10] = zAxis[2]; out[11] = 0;
    out[12] = -(xAxis[0] * eye[0] + xAxis[1] * eye[1] + xAxis[2] * eye[2]);
    out[13] = -(yAxis[0] * eye[0] + yAxis[1] * eye[1] + yAxis[2] * eye[2]);
    out[14] = -(zAxis[0] * eye[0] + zAxis[1] * eye[1] + zAxis[2] * eye[2]);
    out[15] = 1;
    return out;
  }
  // Ported from sceneoverworld.c:62-81. Returns { eye, view }.
  function computeCamera(target, worldH) {
    const fov = Math.PI / 4; // glm_rad(45.0f)
    const zDist = (worldH * 0.5) / Math.tan(fov * 0.5);
    const offset = -worldH;
    const eye = [target[0], target[1] + offset, target[2] + zDist];
    const view = mat4LookAt(new Float32Array(16), eye, target, [0, 1, 0]);
    return { eye, view, fov };
  }
  function compileShader(gl, type, src) {
    const shader = gl.createShader(type);
    gl.shaderSource(shader, src);
    gl.compileShader(shader);
    if(!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
      const info = gl.getShaderInfoLog(shader);
      gl.deleteShader(shader);
      throw new Error(`Shader compile failed: ${info}`);
    }
    return shader;
  }
  function create(canvas) {
    const gl = canvas.getContext("webgl") || canvas.getContext("experimental-webgl");
    if(!gl) throw new Error("WebGL is not available in this browser");
    const program = gl.createProgram();
    gl.attachShader(program, compileShader(gl, gl.VERTEX_SHADER, VERT_SRC));
    gl.attachShader(program, compileShader(gl, gl.FRAGMENT_SHADER, FRAG_SRC));
    gl.linkProgram(program);
    if(!gl.getProgramParameter(program, gl.LINK_STATUS)) {
      throw new Error(`Program link failed: ${gl.getProgramInfoLog(program)}`);
    }
    const attribs = {
      aUV: gl.getAttribLocation(program, "aUV"),
      aPos: gl.getAttribLocation(program, "aPos"),
    };
    const uniforms = {
      uModel: gl.getUniformLocation(program, "uModel"),
      uView: gl.getUniformLocation(program, "uView"),
      uProjection: gl.getUniformLocation(program, "uProjection"),
      uTexture: gl.getUniformLocation(program, "uTexture"),
      uColor: gl.getUniformLocation(program, "uColor"),
    };
    const whiteTexture = gl.createTexture();
    gl.bindTexture(gl.TEXTURE_2D, whiteTexture);
    gl.texImage2D(
      gl.TEXTURE_2D, 0, gl.RGBA, 1, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE,
      new Uint8Array([255, 255, 255, 255]),
    );
    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
    gl.enable(gl.DEPTH_TEST);
    gl.enable(gl.BLEND);
    gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
    // Terrain/mesh winding isn't guaranteed consistent relative to this
    // preview's fixed camera angle, so backface culling stays off - this
    // is an authoring preview, not a performance-sensitive renderer, and
    // an invisible mesh is a worse failure mode than a visible backface.
    // Uploads interleaved [u, v, x, y, z] float data (DMF/terrain layout)
    // into a GL buffer. Returns { buffer, vertexCount }.
    function createMesh(floats) {
      const buffer = gl.createBuffer();
      gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
      gl.bufferData(gl.ARRAY_BUFFER, floats, gl.STATIC_DRAW);
      return { buffer, vertexCount: floats.length / 5 };
    }
    function createTextureFromImage(image) {
      const texture = gl.createTexture();
      gl.bindTexture(gl.TEXTURE_2D, texture);
      gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
      gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, image);
      gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
      return texture;
    }
    function drawMesh(mesh, model, texture, color, depthWrite, mode) {
      gl.depthMask(depthWrite !== false);
      gl.bindBuffer(gl.ARRAY_BUFFER, mesh.buffer);
      gl.enableVertexAttribArray(attribs.aUV);
      gl.vertexAttribPointer(attribs.aUV, 2, gl.FLOAT, false, 20, 0);
      gl.enableVertexAttribArray(attribs.aPos);
      gl.vertexAttribPointer(attribs.aPos, 3, gl.FLOAT, false, 20, 8);
      gl.uniformMatrix4fv(uniforms.uModel, false, model);
      gl.uniform4f(uniforms.uColor, color[0], color[1], color[2], color[3]);
      gl.activeTexture(gl.TEXTURE0);
      gl.bindTexture(gl.TEXTURE_2D, texture || whiteTexture);
      gl.uniform1i(uniforms.uTexture, 0);
      gl.drawArrays(mode || gl.TRIANGLES, 0, mesh.vertexCount);
    }
    // Builds a 4-vertex outline of the tile at (x, y, z), lifted slightly
    // to avoid z-fighting with the terrain surface beneath it.
    function buildHighlightMesh(x, y, z) {
      const eps = 0.02;
      return createMesh(new Float32Array([
        0, 0, x,     y,     z + eps,
        0, 0, x + 1, y,     z + eps,
        0, 0, x + 1, y + 1, z + eps,
        0, 0, x,     y + 1, z + eps,
      ]));
    }
    // Neighboring chunks are drawn dimmer and semi-transparent, so they
    // read as context rather than part of the chunk being edited.
    const NEIGHBOR_ALPHA = 0.35;
    const NEIGHBOR_DARKEN = 0.5;
    // scene = {
    //   target: [x, y, z], worldH: number,
    //   terrain: { mesh, texture } | null,
    //   gridLines: { mesh } | null,
    //   models: [{ mesh, texture, color: [r,g,b,a in 0..1], offset: [x,y,z] }],
    //   neighbors: [{
    //     offset: [x,y,z],
    //     terrain: { mesh, texture } | null,
    //     models: [{ mesh, texture, color, offset }],
    //   }],
    //   highlight: { x, y, z } | null,
    // }
    function render(scene) {
      const width = canvas.width, height = canvas.height;
      gl.viewport(0, 0, width, height);
      gl.clearColor(0.16, 0.18, 0.22, 1);
      gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
      gl.useProgram(program);
      gl.depthMask(true);
      const { view, fov } = computeCamera(scene.target, scene.worldH);
      const projection = mat4Perspective(new Float32Array(16), fov, width / height, 0.1, 1000);
      gl.uniformMatrix4fv(uniforms.uProjection, false, projection);
      gl.uniformMatrix4fv(uniforms.uView, false, view);
      const identity = mat4Identity(new Float32Array(16));
      if(scene.terrain) {
        drawMesh(scene.terrain.mesh, identity, scene.terrain.texture, [1, 1, 1, 1], true);
      }
      if(scene.gridLines) {
        drawMesh(scene.gridLines.mesh, identity, null, [0, 0, 0, 0.35], false, gl.LINES);
      }
      for(const model of scene.models) {
        const modelMatrix = mat4Translation(new Float32Array(16), model.offset);
        drawMesh(model.mesh, modelMatrix, model.texture, model.color, true);
      }
      for(const neighbor of scene.neighbors || []) {
        if(neighbor.terrain) {
          const modelMatrix = mat4Translation(new Float32Array(16), neighbor.offset);
          drawMesh(
            neighbor.terrain.mesh, modelMatrix, neighbor.terrain.texture,
            [NEIGHBOR_DARKEN, NEIGHBOR_DARKEN, NEIGHBOR_DARKEN, NEIGHBOR_ALPHA], false,
          );
        }
        for(const model of neighbor.models) {
          const worldOffset = [
            neighbor.offset[0] + model.offset[0],
            neighbor.offset[1] + model.offset[1],
            neighbor.offset[2] + model.offset[2],
          ];
          const modelMatrix = mat4Translation(new Float32Array(16), worldOffset);
          const color = [
            model.color[0] * NEIGHBOR_DARKEN,
            model.color[1] * NEIGHBOR_DARKEN,
            model.color[2] * NEIGHBOR_DARKEN,
            model.color[3] * NEIGHBOR_ALPHA,
          ];
          drawMesh(model.mesh, modelMatrix, model.texture, color, false);
        }
      }
      if(scene.highlight) {
        const { x, y, z } = scene.highlight;
        const highlightMesh = buildHighlightMesh(x, y, z);
        drawMesh(highlightMesh, identity, null, [1, 0.92, 0.23, 1], false, gl.LINE_LOOP);
      }
    }
    return { gl, createMesh, createTextureFromImage, render };
  }
  return Object.freeze({ create, computeCamera });
 })();
@@ -0,0 +1,23 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Dusk Map Editor</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css">
 </head>
 <body>
  <nav class="navbar navbar-expand navbar-dark bg-dark">
    <div class="container-fluid">
      <a class="navbar-brand" href="/">Dusk Map Editor</a>
      <ul class="navbar-nav flex-row">
        <li class="nav-item">
          <a class="nav-link" href="/map">Map Editor</a>
        </li>
      </ul>
    </div>
  </nav>
  <div id="editor" class="container-fluid py-3"></div>
  <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js"></script>
 </body>
 </html>
@@ -0,0 +1,298 @@
 """
 Map Editor HTTP Server
 Serves editor/client/public/ as static files with smart routing:
  /          -> index.html
  /page      -> page.html or page/index.html
  /index     -> index.html
 API endpoints (all paths relative to project root):
  GET  /api/ls?path=<dir>                  directory listing
  GET  /api/read?path=<file>               file contents
  GET  /api/find?path=<dir>&ext=<.json>    recursive file listing by extension
  POST /api/write?path=<file>              write file (JSON body: {"content":"..."})
  POST /api/mkdir?path=<dir>               create directory
  POST /api/delete?path=<file>             delete a file
  POST /api/compile-chunk?x=&y=&z=         recompile a chunk JSON to .dcf
 """
 import os
 import re
 import sys
 import json
 import mimetypes
 import subprocess
 from http.server import HTTPServer, BaseHTTPRequestHandler
 from urllib.parse import urlparse, parse_qs, unquote
 from pathlib import Path
 CHUNK_COORD_RE = re.compile(r"^-?\d+$")
 PORT = 3000
 SCRIPT_DIR = Path(__file__).parent.resolve()
 PUBLIC_DIR = SCRIPT_DIR.parent / "client" / "public"
 PROJECT_ROOT = SCRIPT_DIR.parent.parent.resolve()
 class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        parsed = urlparse(self.path)
        path = unquote(parsed.path)
        if path.startswith("/api/"):
            params = parse_qs(parsed.query)
            if path == "/api/ls":
                self.api_ls(params)
            elif path == "/api/read":
                self.api_read(params)
            elif path == "/api/find":
                self.api_find(params)
            else:
                self.send_error(404)
        else:
            self.serve_static(path)
    def do_POST(self):
        parsed = urlparse(self.path)
        params = parse_qs(parsed.query)
        if parsed.path == "/api/write":
            self.api_write(params)
        elif parsed.path == "/api/mkdir":
            self.api_mkdir(params)
        elif parsed.path == "/api/delete":
            self.api_delete(params)
        elif parsed.path == "/api/compile-chunk":
            self.api_compile_chunk(params)
        else:
            self.send_error(404)
    # ------------------------------------------------------------------
    # Helpers
    # ------------------------------------------------------------------
    def resolve_project_path(self, rel):
        rel = rel.lstrip("/")
        target = (PROJECT_ROOT / rel).resolve()
        if not str(target).startswith(str(PROJECT_ROOT)):
            return None
        return target
    def send_json(self, data, code=200):
        body = json.dumps(data, indent=2).encode("utf-8")
        self.send_response(code)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", len(body))
        self.end_headers()
        self.wfile.write(body)
    def read_body(self):
        length = int(self.headers.get("Content-Length", 0))
        return self.rfile.read(length)
    # ------------------------------------------------------------------
    # API handlers
    # ------------------------------------------------------------------
    def api_ls(self, params):
        rel = params.get("path", [""])[0]
        target = self.resolve_project_path(rel)
        if target is None:
            self.send_json({"error": "invalid path"}, 400)
            return
        if not target.exists():
            self.send_json({"error": "path not found"}, 404)
            return
        if not target.is_dir():
            self.send_json({"error": "not a directory"}, 400)
            return
        entries = []
        for entry in sorted(target.iterdir(), key=lambda e: (e.is_file(), e.name)):
            entries.append({
                "name": entry.name,
                "type": "dir" if entry.is_dir() else "file",
                "size": entry.stat().st_size if entry.is_file() else None,
            })
        self.send_json({
            "path": str(target.relative_to(PROJECT_ROOT)),
            "entries": entries,
        })
    def api_read(self, params):
        rel = params.get("path", [""])[0]
        target = self.resolve_project_path(rel)
        if target is None:
            self.send_json({"error": "invalid path"}, 400)
            return
        if not target.exists():
            self.send_json({"error": "file not found"}, 404)
            return
        if not target.is_file():
            self.send_json({"error": "not a file"}, 400)
            return
        try:
            content = target.read_text(encoding="utf-8")
            self.send_json({
                "path": str(target.relative_to(PROJECT_ROOT)),
                "content": content,
            })
        except UnicodeDecodeError:
            import base64
            content = base64.b64encode(target.read_bytes()).decode("ascii")
            self.send_json({
                "path": str(target.relative_to(PROJECT_ROOT)),
                "content": content,
                "encoding": "base64",
            })
    def api_write(self, params):
        rel = params.get("path", [""])[0]
        target = self.resolve_project_path(rel)
        if target is None:
            self.send_json({"error": "invalid path"}, 400)
            return
        body = self.read_body()
        try:
            data = json.loads(body)
            content = data.get("content", "")
        except (json.JSONDecodeError, UnicodeDecodeError):
            content = body.decode("utf-8")
        target.parent.mkdir(parents=True, exist_ok=True)
        target.write_text(content, encoding="utf-8")
        self.send_json({"ok": True, "path": str(target.relative_to(PROJECT_ROOT))})
    def api_mkdir(self, params):
        rel = params.get("path", [""])[0]
        target = self.resolve_project_path(rel)
        if target is None:
            self.send_json({"error": "invalid path"}, 400)
            return
        target.mkdir(parents=True, exist_ok=True)
        self.send_json({"ok": True, "path": str(target.relative_to(PROJECT_ROOT))})
    def api_delete(self, params):
        rel = params.get("path", [""])[0]
        target = self.resolve_project_path(rel)
        if target is None:
            self.send_json({"error": "invalid path"}, 400)
            return
        if target.is_file():
            target.unlink()
        self.send_json({"ok": True, "path": str(target.relative_to(PROJECT_ROOT))})
    def api_find(self, params):
        rel = params.get("path", [""])[0]
        ext = params.get("ext", [""])[0]
        target = self.resolve_project_path(rel)
        if target is None:
            self.send_json({"error": "invalid path"}, 400)
            return
        if not target.is_dir():
            self.send_json({"error": "not a directory"}, 400)
            return
        pattern = f"*{ext}" if ext else "*"
        paths = sorted(
            str(p.relative_to(target)).replace(os.sep, "/")
            for p in target.rglob(pattern)
            if p.is_file()
        )
        self.send_json({"path": str(target.relative_to(PROJECT_ROOT)), "files": paths})
    def api_compile_chunk(self, params):
        x = params.get("x", [""])[0]
        y = params.get("y", [""])[0]
        z = params.get("z", [""])[0]
        if not (CHUNK_COORD_RE.match(x) and CHUNK_COORD_RE.match(y) and CHUNK_COORD_RE.match(z)):
            self.send_json({"error": "invalid chunk coordinates"}, 400)
            return
        json_path = (
            PROJECT_ROOT / "assetsraw" / "maps" / "overworld" / "chunks"
            / f"chunk_{x}_{y}_{z}.json"
        )
        if not json_path.is_file():
            self.send_json({"error": "chunk json not found"}, 404)
            return
        result = subprocess.run(
            [sys.executable, "-m", "tools.asset.chunk", str(json_path)],
            cwd=str(PROJECT_ROOT),
            capture_output=True,
            text=True,
        )
        self.send_json({
            "ok": result.returncode == 0,
            "returncode": result.returncode,
            "stdout": result.stdout,
            "stderr": result.stderr,
        })
    # ------------------------------------------------------------------
    # Static file serving
    # ------------------------------------------------------------------
    def serve_static(self, path):
        clean = path.lstrip("/")
        candidates = []
        if clean == "" or clean == "index" or clean == "index.html":
            candidates = ["index.html"]
        else:
            candidates.append(clean)
            if "." not in Path(clean).name:
                candidates.append(clean + ".html")
                candidates.append(clean + "/index.html")
        for candidate in candidates:
            file_path = PUBLIC_DIR / candidate
            if file_path.is_file():
                self.serve_file(file_path)
                return
        self.send_error(404)
    def serve_file(self, file_path):
        mime, _ = mimetypes.guess_type(str(file_path))
        mime = mime or "application/octet-stream"
        template = PUBLIC_DIR / "template.html"
        if (
            mime == "text/html"
            and file_path.name != "template.html"
            and template.is_file()
        ):
            fragment = file_path.read_text(encoding="utf-8")
            shell = template.read_text(encoding="utf-8")
            marker = shell.find('id="editor"')
            if marker == -1:
                content = shell.encode("utf-8")
            else:
                tag_end = shell.index(">", marker) + 1
                close_idx = shell.index("</div>", tag_end)
                content = (shell[:tag_end] + fragment + shell[close_idx:]).encode("utf-8")
        else:
            content = file_path.read_bytes()
        self.send_response(200)
        self.send_header("Content-Type", mime)
        self.send_header("Content-Length", len(content))
        self.end_headers()
        self.wfile.write(content)
    def log_message(self, fmt, *args):
        print(f"  {self.address_string()} {fmt % args}")
 if __name__ == "__main__":
    print(f"Map Editor")
    print(f"  http://localhost:{PORT}")
    print(f"  public : {PUBLIC_DIR}")
    print(f"  project: {PROJECT_ROOT}")
    server = HTTPServer(("", PORT), Handler)
    try:
        server.serve_forever()
    except KeyboardInterrupt:
        print("\nStopped.")
@@ -0,0 +1,4 @@
 #!/usr/bin/env bash
 set -e
 cd "$(dirname "$0")"
 python3 server/server.py
@@ -6,7 +6,7 @@ fi
 mkdir -p build-psp
 cd build-psp
-psp-cmake -DDUSK_TARGET_SYSTEM=psp -DCMAKE_TOOLCHAIN_FILE=$PSPDEV/psp/share/pspdev.cmake -DBUILD_PRX=1 ..
+psp-cmake -DDUSK_TARGET_SYSTEM=psp -DCMAKE_TOOLCHAIN_FILE=$PSPDEV/psp/share/pspdev.cmake -DBUILD_PRX=1 .. CMAKE_BUILD_TYPE=Release
 make -j$(nproc)
 # psp-cmake -DDUSK_TARGET_SYSTEM=psp -DCMAKE_TOOLCHAIN_FILE=$PSPDEV/psp/share/pspdev.cmake -DBUILD_PRX=1 -DCMAKE_BUILD_TYPE=Debug ..
 # make
@@ -5,10 +5,22 @@
 add_subdirectory(dusk)
 if(DUSK_NETWORK)
  add_subdirectory(dusknetwork)
 endif()
 if(DUSK_TARGET_SYSTEM STREQUAL "linux" OR DUSK_TARGET_SYSTEM STREQUAL "knulli")
  # The duskscript runtime itself lives in src/dusk/script, added
  # unconditionally of platform there since it is plain, portable C; this is
  # just the duskscriptcc compiler, a host tool only built on the dev machine.
  add_subdirectory(duskscriptcc)
 endif()
 if(DUSK_TARGET_SYSTEM STREQUAL "linux" OR DUSK_TARGET_SYSTEM STREQUAL "knulli")
  add_subdirectory(dusklinux)
  add_subdirectory(dusksdl2)
  add_subdirectory(duskgl)
  add_subdirectory(duskmad)
 elseif(DUSK_TARGET_SYSTEM STREQUAL "psp")
  add_subdirectory(duskpsp)
@@ -20,7 +32,11 @@ elseif(DUSK_TARGET_SYSTEM STREQUAL "vita")
  add_subdirectory(dusksdl2)
  add_subdirectory(duskgl)
-elseif(DUSK_TARGET_SYSTEM STREQUAL "wii" OR DUSK_TARGET_SYSTEM STREQUAL "gamecube")
+elseif(
  DUSK_TARGET_SYSTEM STREQUAL "wii" OR
  DUSK_TARGET_SYSTEM STREQUAL "gamecube"
 )
  add_subdirectory(duskdolphin)
  add_subdirectory(duskmad)
 endif()
@@ -14,12 +14,21 @@ if(NOT libzip_FOUND)
  target_link_libraries(${DUSK_LIBRARY_TARGET_NAME} PUBLIC zip)
 endif()
 # assetdsk.c calls crc32() directly (to verify dusk.dsk archive checksums).
 # find_package(libzip) above already resolves ZLIB as a side effect, so
 # ZLIB_FOUND may already be true without ZLIB::ZLIB having been linked to
 # our target - link it unconditionally rather than guarding on ZLIB_FOUND.
 find_package(ZLIB REQUIRED)
 target_link_libraries(${DUSK_LIBRARY_TARGET_NAME} PUBLIC ZLIB::ZLIB)
 if(NOT stb_image_FOUND)
  find_package(stb REQUIRED)
  if(STB_IMAGE_FOUND)
    target_link_libraries(${DUSK_LIBRARY_TARGET_NAME} PUBLIC stb_image)
  else()
-    message(FATAL_ERROR "stb_image not found. Please ensure stb is correctly fetched.")
+    message(FATAL_ERROR
      "stb_image not found. Please ensure stb is correctly fetched."
    )
  endif()
 endif()
@@ -28,7 +37,9 @@ if(NOT yyjson_FOUND)
  if(yyjson_FOUND)
    target_link_libraries(${DUSK_LIBRARY_TARGET_NAME} PUBLIC yyjson::yyjson)
  else()
-    message(FATAL_ERROR "yyjson not found. Please ensure yyjson is correctly fetched.")
+    message(FATAL_ERROR
      "yyjson not found. Please ensure yyjson is correctly fetched."
    )
  endif()
 endif()
@@ -39,6 +50,12 @@ if(DUSK_BACKTRACE)
  )
 endif()
 if(DUSK_TRACK_MEMORY)
  target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
    DUSK_TRACK_MEMORY
  )
 endif()
 # Includes
 target_include_directories(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
@@ -53,22 +70,22 @@ target_sources(${DUSK_BINARY_TARGET_NAME}
 # Subdirs
 add_subdirectory(animation)
 add_subdirectory(event)
 add_subdirectory(assert)
 add_subdirectory(asset)
 add_subdirectory(audio)
 add_subdirectory(console)
 add_subdirectory(display)
 add_subdirectory(log)
 add_subdirectory(engine)
 add_subdirectory(entity)
 add_subdirectory(error)
 add_subdirectory(input)
 add_subdirectory(locale)
-add_subdirectory(rpg)
+add_subdirectory(perf)
 add_subdirectory(scene)
 add_subdirectory(script)
 add_subdirectory(system)
 add_subdirectory(time)
 add_subdirectory(ui)
 add_subdirectory(network)
 add_subdirectory(save)
 add_subdirectory(util)
 add_subdirectory(thread)
@@ -7,4 +7,5 @@ target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    easing.c
    animation.c
    keyframe.c
 )
@@ -11,42 +11,122 @@
 void animationInit(
  animation_t *anim,
  keyframe_t *keyframes,
-  uint16_t keyframeCount
+  uint16_t *keyframeCounts,
  const uint16_t layerCount
 ) {
  assertNotNull(anim, "Animation pointer cannot be null.");
  assertNotNull(keyframes, "Keyframes pointer cannot be null.");
-  assertTrue(keyframeCount > 0, "Keyframe count must be more than 0.");
+  assertNotNull(keyframeCounts, "Keyframe counts pointer cannot be null.");
  assertTrue(layerCount > 0, "Layer count must be greater than zero.");
  memoryZero(anim, sizeof(animation_t));
  anim->keyframes = keyframes;
-  anim->keyframeCount = keyframeCount;
+  anim->keyframeCounts = keyframeCounts;
  anim->layerCount = layerCount;
  // Determine duration
  float_t duration = 0.0f;
  for(uint16_t layer = 0; layer < layerCount; layer++) {
    uint16_t keyframeCount = keyframeCounts[layer];
    assertTrue(keyframeCount > 0, "Keyframe count invalid.");
    keyframe_t *layerKeyframes = keyframes + layer * keyframeCount;
    #ifdef DUSK_ASSERTIONS
      // Check that the keyframes are sorted by time.
      for(uint16_t i = 1; i < keyframeCount; i++) {
        assertTrue(
          layerKeyframes[i].time >= layerKeyframes[i - 1].time,
          "Keyframes must be sorted by time."
        );
      }
    #endif
    keyframe_t *lastKeyframe = layerKeyframes + keyframeCount - 1;
    duration = mathMax(duration, lastKeyframe->time);
  }
  assertTrue(duration > 0, "Animation duration must be greater than 0.");
  anim->duration = duration;
 }
-float_t animationGetValue(animation_t *anim, const float_t time) {
+float_t animationGetLayerValue(const animation_t *anim, const uint16_t layer) {
  assertNotNull(anim, "Animation pointer cannot be null.");
-  assertNotNull(anim->keyframes, "Keyframes pointer cannot be null.");
+  assertTrue(layer < anim->layerCount, "Layer index out of bounds.");
  assertTrue(anim->keyframeCount > 0, "Keyframe count invalid.");
  assertTrue(time >= 0, "Time must be non-negative.");
-  keyframe_t *start;
+  uint16_t keyframeCount = anim->keyframeCounts[layer];
-  keyframe_t *end;
+  keyframe_t *layerKeyframes = anim->keyframes + layer * keyframeCount;
-  keyframe_t *last = anim->keyframes + anim->keyframeCount - 1;
+  return keyframeGetValue(layerKeyframes, keyframeCount, anim->time);
-  keyframe_t *current = anim->keyframes;
+}
  start = current;
-  do {
+void animationUpdate(
-    if(current->time > time) {
+  animation_t *anim,
-      end = current;
+  const float_t deltaTime
 ) {
  assertNotNull(anim, "Animation pointer cannot be null.");
  assertTrue(deltaTime >= 0, "Delta time must be non-negative.");
  bool_t justCompleted = false;
  if(!(anim->flags & ANIMATION_FLAG_INTERNAL_COMPLETED)) {
    bool_t loop = (anim->flags & ANIMATION_FLAG_LOOP) != 0;
    bool_t pingpong = (anim->flags & ANIMATION_FLAG_PINGPONG) != 0;
    assertFalse(
      loop && pingpong,
      "Cannot set both ANIMATION_FLAG_LOOP and ANIMATION_FLAG_PINGPONG."
    );
    bool_t backward;
    if(pingpong) {
      backward = (anim->flags & ANIMATION_FLAG_INTERNAL_PINGPONG_BACKWARD) != 0;
    } else {
      backward = (anim->flags & ANIMATION_FLAG_REVERSE) != 0;
    }
    // Resolve boundary crossings one at a time, so a single large deltaTime
    // can correctly loop/pingpong across multiple boundaries in one call.
    float_t remaining = deltaTime;
    while(remaining > 0.0f) {
      float_t toBoundary = (
        backward ? anim->time : (anim->duration - anim->time)
      );
      if(remaining < toBoundary) {
        anim->time += backward ? -remaining : remaining;
        break;
      }
    start = current;
    current++;
-    if(current > last) {
+      remaining -= toBoundary;
-      end = start;
+      anim->time = backward ? 0.0f : anim->duration;
      bool_t stopHere;
      if(backward) {
        stopHere = (anim->flags & ANIMATION_FLAG_STOP_BEGINNING) != 0;
      } else {
        stopHere = (anim->flags & ANIMATION_FLAG_STOP_END) != 0;
      }
      if(stopHere) {
        justCompleted = true;
        break;
      } else if(pingpong) {
        backward = !backward;
        if(backward) anim->flags |= ANIMATION_FLAG_INTERNAL_PINGPONG_BACKWARD;
        else anim->flags &= ~ANIMATION_FLAG_INTERNAL_PINGPONG_BACKWARD;
      } else if(loop) {
        anim->time = backward ? anim->duration : 0.0f;
        if(anim->onLoop) anim->onLoop(anim->user);
      } else {
        justCompleted = true;
        break;
      }
-  } while(true);
+    }
-  float_t t = (time - start->time) / (end->time - start->time);
+    if(justCompleted) anim->flags |= ANIMATION_FLAG_INTERNAL_COMPLETED;
-  return mathLerp(start->value, end->value, easingApply(start->easing, t));
+  }
  // Call onUpdate for each layer.
  for(uint16_t layer = 0; layer < anim->layerCount; layer++) {
    float_t value = animationGetLayerValue(anim, layer);
    if(anim->onUpdate) anim->onUpdate(layer, value, anim->user);
  }
  if(justCompleted && anim->onComplete) anim->onComplete(anim->user);
 }
@@ -6,29 +6,89 @@
 #pragma once
 #include "keyframe.h"
 #define ANIMATION_FLAG_LOOP (1 << 0)
 #define ANIMATION_FLAG_REVERSE (1 << 1)
 #define ANIMATION_FLAG_PINGPONG (1 << 2)
 #define ANIMATION_FLAG_STOP_BEGINNING (1 << 3)
 #define ANIMATION_FLAG_STOP_END (1 << 4)
 // Internal - tracks which direction a pingponging animation is currently
 // travelling. Do not set this manually, it is managed by animationUpdate().
 #define ANIMATION_FLAG_INTERNAL_PINGPONG_BACKWARD (1 << 7)
 // Internal - set once the animation has stopped advancing (see
 // animationUpdate()). Do not set this manually. There is currently no way to
 // restart a completed animation short of clearing this bit and resetting
 // anim->time by hand.
 #define ANIMATION_FLAG_INTERNAL_COMPLETED (1 << 6)
 typedef struct {
  keyframe_t *keyframes;
-  uint16_t keyframeCount;
+  uint16_t *keyframeCounts;
  uint16_t layerCount;
  float_t time;
  float_t duration;
  uint8_t flags;
  void *user;
  void (*onUpdate)(const uint16_t layer, const float_t value, void *user);
  void (*onComplete)(void *user);
  void (*onLoop)(void *user);
 } animation_t;
 /**
- * Initializes an animation.
+ * Initializes an animation with the given keyframes and layer count.
 *
- * @param anim The animation to initialize.
+ * @param anim Pointer to the animation to initialize.
- * @param keyframes The keyframes to use for the animation.
+ * @param keyframes Pointer to the array of keyframes for each layer.
- * @param keyframeCount The number of keyframes in the animation.
+ * @param keyframeCount Number of keyframes in each layer.
 * @param layerCount Number of layers in the animation.
 */
 void animationInit(
  animation_t *anim,
  keyframe_t *keyframes,
-  uint16_t keyframeCount
+  uint16_t *keyframeCounts,
  const uint16_t layerCount
 );
 /**
- * Gets the value of the animation at a given time.
+ * Sets the current time of the animation, clamping it to the valid range.
 * This will call the onUpdate callback but none of the other callbacks.
 * 
- * @param anim The animation to get the value from.
+ * @param anim Pointer to the animation to set the time for.
- * @param time The time at which to get the value, in seconds.
+ * @param time The new time to set for the animation.
 * @return The value of the animation at the given time.
 */
-float_t animationGetValue(animation_t *anim, const float_t time);
+void animationSetTime(animation_t *anim, const float_t time);
 /**
 * Gets the current value of a specific layer in the animation based on the
 * current animation time.
 */
 float_t animationGetLayerValue(const animation_t *anim, const uint16_t layer);
 /**
 * Updates the animation state based on the elapsed time. Advances anim->time
 * by deltaTime (or against it, if ANIMATION_FLAG_REVERSE is set), then
 * resolves whatever happens when it reaches the 0 or duration boundary:
 *
 * - ANIMATION_FLAG_PINGPONG: reflects off the boundary and continues playing
 *   in the opposite direction, forever, unless stopped (see below).
 * - ANIMATION_FLAG_LOOP: wraps back around to the other boundary and keeps
 *   playing in the same direction, forever, unless stopped (see below).
 * - ANIMATION_FLAG_STOP_BEGINNING / ANIMATION_FLAG_STOP_END: when the
 *   animation reaches that specific boundary, it clamps there and stops
 *   (firing onComplete) instead of looping/pingponging past it.
 * - If none of the above apply at a boundary, the animation clamps there and
 *   stops, firing onComplete.
 *
 * onUpdate is called for every layer on every call. onLoop is called each
 * time a loop wraps around. onComplete is called at most once, the moment
 * the animation stops advancing.
 *
 * @param anim Pointer to the animation to update.
 * @param deltaTime Time elapsed since the last update (in seconds).
 */
 void animationUpdate(
  animation_t *anim,
  const float_t deltaTime
 );
@@ -0,0 +1,45 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "keyframe.h"
 #include "assert/assert.h"
 #include "util/math.h"
 float_t keyframeGetValue(
  const keyframe_t *keyframes,
  const uint32_t keyframeCount,
  const float_t time
 ) {
  assertNotNull(keyframes, "Keyframes pointer cannot be null.");
  assertTrue(keyframeCount > 0, "Keyframe count must be more than 0.");
  assertTrue(time >= 0, "Time must be non-negative.");
  #ifdef DUSK_ASSERTIONS
    // Checks that the keyframes are sorted by time.
    for(uint32_t i = 1; i < keyframeCount; i++) {
      assertTrue(
        keyframes[i].time >= keyframes[i - 1].time,
        "Keyframes must be sorted by time."
      );
    }
  #endif
  keyframe_t *last = (keyframe_t *)(keyframes + keyframeCount - 1);
  if(time >= last->time) return last->value;
  // Since time < last->time (checked above), current is guaranteed to stop
  // at or before reaching last, so no separate end-of-array check is needed.
  keyframe_t *current = (keyframe_t *)keyframes;
  keyframe_t *start = current;
  while(current->time <= time) {
    start = current;
    current++;
  }
  keyframe_t *end = current;
  float_t t = (time - start->time) / (end->time - start->time);
  return mathLerp(start->value, end->value, easingApply(start->easing, t));
 }
@@ -11,3 +11,17 @@ typedef struct {
  float_t value;
  easingtype_t easing;
 } keyframe_t;
 /**
 * Gets the value of a keyframe at a given time.
 * 
 * @param keyframes The keyframes to get the value from.
 * @param keyframeCount The number of keyframes in the array.
 * @param time The time at which to get the value, in seconds.
 * @return The value of the keyframe at the given time.
 */
 float_t keyframeGetValue(
  const keyframe_t *keyframes,
  const uint32_t keyframeCount,
  const float_t time
 );
@@ -22,6 +22,8 @@
 #endif
 #ifndef DUSK_ASSERTIONS_FAKED
  #define DUSK_ASSERTIONS 1
  /**
   * Initializes the assert system. Must be the very first call in engine
   * startup.
@@ -7,7 +7,7 @@
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    asset.c
-    assetbatch.c
+    assetdsk.c
    assetfile.c
 )
@@ -19,6 +19,8 @@ asset_t ASSET;
 errorret_t assetInit(void) {
  memoryZero(&ASSET, sizeof(asset_t));
  threadMutexInit(&ASSET.zipLock);
  for(size_t i = 0; i < ASSET_LOADING_COUNT_MAX; i++) {
    threadMutexInit(&ASSET.loading[i].mutex);
  }
@@ -35,9 +37,10 @@ errorret_t assetInit(void) {
 bool_t assetFileExists(const char_t *filename) {
  assertStrLenMax(filename, ASSET_FILE_NAME_MAX, "Filename too long.");
-  zip_int64_t idx = zip_name_locate(ASSET.zip, filename, 0);
+  threadMutexLock(&ASSET.zipLock);
-  if(idx < 0) return false;
+  bool_t found = zip_name_locate(ASSET.zip, filename, 0) >= 0;
-  return true;
+  threadMutexUnlock(&ASSET.zipLock);
  return found;
 }
 assetentry_t * assetGetEntry(
@@ -59,7 +62,10 @@ assetentry_t * assetGetEntry(
    entry++;
  } while(entry < ASSET.entries + ASSET_ENTRY_COUNT_MAX);
-  // We did not find one existing, Find first available slot.
+  // We did not find one existing. Find first available slot, reaping
  // zero-ref entries to make room if none are immediately available.
  bool_t reaped = false;
  for(;;) {
    entry = ASSET.entries;
    do {
      if(entry->type != ASSET_LOADER_TYPE_NULL) {
@@ -74,6 +80,11 @@ assetentry_t * assetGetEntry(
      entry++;
    } while(entry < ASSET.entries + ASSET_ENTRY_COUNT_MAX);
    if(reaped) break;
    reaped = true;
    errorCatch(assetReapUnused());
  }
  assertUnreachable("No available asset entry slots.");
  return NULL;
 }
@@ -109,6 +120,15 @@ errorret_t assetRequireLoaded(assetentry_t *entry) {
  assetEntryLock(entry);
  while(entry->state != ASSET_ENTRY_STATE_LOADED) {
    // A failed load transitions to ERROR, not LOADED - without this check
    // this loop spins forever on any load failure (assetUpdate() itself
    // still returns OK, since a single asset failing isn't meant to halt
    // the whole update loop - see its ASSET_ENTRY_STATE_ERROR handling).
    if(entry->state == ASSET_ENTRY_STATE_ERROR) {
      assetEntryUnlock(entry);
      errorThrow("Failed to load asset: %s", entry->name);
    }
    usleep(1000);
    errorret_t ret = assetUpdate();
    if(errorIsNotOk(ret)) {
@@ -191,6 +211,32 @@ void assetUnlockEntry(assetentry_t *entry) {
  assetEntryUnlock(entry);
 }
 errorret_t assetReapUnused(void) {
  assertIsMainThread("assetReapUnused must be called from the main thread.");
  // Repeatedly find and dispose zero-ref LOADED entries until none remain.
  // This handles dependency chains where an entry (e.g. a model) holds refs
  // on child entries (mesh, texture): dispose parents first so child ref
  // counts drop to zero, then pick up the children on the next pass. Without
  // this, a forward-only scan fails when a shared child entry appears before
  // a parent that still holds a ref to it.
  bool_t any;
  do {
    any = false;
    assetentry_t *entry = ASSET.entries;
    do {
      if(entry->type == ASSET_LOADER_TYPE_NULL) { entry++; continue; }
      if(entry->state != ASSET_ENTRY_STATE_LOADED) { entry++; continue; }
      if(entry->refs.count > 0) { entry++; continue; }
      errorChain(assetEntryDispose(entry));
      any = true;
      entry++;
    } while(entry < ASSET.entries + ASSET_ENTRY_COUNT_MAX);
  } while(any);
  errorOk();
 }
 errorret_t assetUpdate(void) {
  assertIsMainThread("assetUpdate must be called from the main thread.");
@@ -286,7 +332,11 @@ errorret_t assetUpdate(void) {
            "Loader did not set entry state to error on failed load."
          );
        } else if(loading->entry->state == ASSET_ENTRY_STATE_LOADED) {
-          eventInvoke(&loading->entry->onLoaded, loading->entry);
+          assetentry_t *loadedEntry = loading->entry;
          loading->entry = NULL;
          if(loadedEntry->onLoaded) {
            loadedEntry->onLoaded(loadedEntry, loadedEntry->onLoadedUser);
          }
        }
        loading++;
@@ -310,8 +360,10 @@ errorret_t assetUpdate(void) {
        assetentry_t *errEntry = loading->entry;
        loading->entry = NULL;
        threadMutexUnlock(&loading->mutex);
-        eventInvoke(&errEntry->onError, errEntry);
+        if(errEntry->onError) {
-        errorThrow("Failed to load asset asynchronously.");
+          errEntry->onError(errEntry, errEntry->onErrorUser);
        }
        loading++;
        break;
      }
@@ -322,30 +374,6 @@ errorret_t assetUpdate(void) {
    }
  } while(loading < ASSET.loading + ASSET_LOADING_COUNT_MAX);
  // Reap unused entries.
  entry = ASSET.entries;
  do {
    if(entry->state != ASSET_ENTRY_STATE_LOADED) {
      entry++;
      continue;
    }
    if(entry->type == ASSET_LOADER_TYPE_NULL) {
      entry++;
      continue;
    }
    if(entry->refs.count > 0) {
      entry++;
      continue;
    }
    consolePrint("Reaping asset %s", entry->name);
    errorChain(assetEntryDispose(entry));
    entry++;
  } while(entry < ASSET.entries + ASSET_ENTRY_COUNT_MAX);
  errorOk();
 }
@@ -411,16 +439,7 @@ errorret_t assetDispose(void) {
  assertIsMainThread("Must be called from the main thread.");
  threadStop(&ASSET.loadThread);
-  // Dispose every non-null entry so type-specific dispose callbacks
+  errorChain(assetReapUnused());
  // (e.g. assetScriptDispose freeing jerry values) run before the
  // scripting engine is torn down.
  assetentry_t *entry = ASSET.entries;
  do {
    if(entry->type != ASSET_LOADER_TYPE_NULL) {
      errorChain(assetEntryDispose(entry));
    }
    entry++;
  } while(entry < ASSET.entries + ASSET_ENTRY_COUNT_MAX);
  // Cleanup zip file.
  if(ASSET.zip != NULL) {
@@ -431,5 +450,6 @@ errorret_t assetDispose(void) {
  }
  errorChain(assetDisposePlatform());
  threadMutexDispose(&ASSET.zipLock);
  errorOk();
 }
@@ -23,13 +23,43 @@
 #define ASSET_FILE_NAME "dusk.dsk"
 #define ASSET_HEADER_SIZE 3
-#define ASSET_LOADING_COUNT_MAX 4
+#define ASSET_LOADING_COUNT_MAX 10
-#define ASSET_ENTRY_COUNT_MAX 128
+#define ASSET_ENTRY_COUNT_MAX 64
 #define ASSET_BASE_DIRECTORY_MAX 256
 typedef struct asset_s {
  // The dusk.dsk archive - a single uncompressed (ZIP_STORED) zip, so
  // every entry gets the reliable repeated seeking/re-opening that
  // libzip only supports reliably for uncompressed entries (locale
  // strings, MP3 loop restarts, etc.).
  zip_t *zip;
  // Directory dusk.dsk was actually found/opened in (on PSP, the directory
  // EBOOT.PBP lives in, since dusk.dsk is embedded inside it rather than a
  // loose file) - populated by each platform's own assetInitXxx() once it
  // locates the file. Save devices that persist to a real filesystem path
  // (Linux, PSP, Wii SD) use this as their base directory instead of a
  // separate hardcoded location, so saves live next to wherever the game
  // itself was actually launched from rather than some unrelated fixed
  // path. Not meaningful for devices with no filesystem-path concept at
  // all (GameCube/Wii memory card, Wii NAND's ISFS namespace).
  char_t baseDirectory[ASSET_BASE_DIRECTORY_MAX];
  assetplatform_t platform;
  // Guards every libzip call against ASSET.zip (zip_fopen,
  // zip_fread, zip_fclose, zip_fseek, zip_stat, zip_name_locate - see
  // assetfile.c/assetFileExists). libzip is documented as not thread-safe,
  // and this asset system genuinely calls it from multiple real threads at
  // once (main thread, the background load thread below, and - on
  // platforms that stream PCM from an asset on their own thread, like PSP
  // - an audio feeder thread too). Confirmed necessary on real PSP
  // hardware: without this lock, concurrent zip_fopen/zip_fread calls from
  // different threads corrupted reads (EINVAL, then zlib data errors) once
  // dusk.dsk stopped being read entirely into memory up front.
  threadmutex_t zipLock;
  // Background loading thread.
  thread_t loadThread;
@@ -112,6 +142,16 @@ void assetUnlock(const char_t *name);
 */
 void assetUnlockEntry(assetentry_t *entry);
 /**
 * Frees every currently unreferenced (zero-ref) loaded asset entry. Repeats
 * until a full pass frees nothing further, since disposing a parent entry
 * (e.g. a model) may drop a child entry's (e.g. a mesh) ref count to zero,
 * making it eligible for reaping too.
 *
 * @return An error code if any entry could not be disposed properly.
 */
 errorret_t assetReapUnused(void);
 /**
 * Requires an asset entry to be loaded. This will block until the asset entry
 * is fully loaded.
@@ -1,165 +0,0 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "assetbatch.h"
 #include "asset.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include <unistd.h>
 void assetBatchInit(
  assetbatch_t *batch,
  const uint16_t count,
  const assetbatchdesc_t *descs
 ) {
  assertNotNull(batch, "Batch cannot be NULL.");
  assertNotNull(descs, "Descs cannot be NULL.");
  assertTrue(count > 0, "Count must be greater than 0.");
  assertTrue(
    count <= ASSET_BATCH_COUNT_MAX, "Count exceeds ASSET_BATCH_COUNT_MAX."
  );
  memoryZero(batch, sizeof(assetbatch_t));
  batch->count = count;
  eventInit(
    &batch->onLoaded,
    batch->onLoadedCallbacks, batch->onLoadedUsers, ASSET_BATCH_EVENT_MAX
  );
  eventInit(
    &batch->onEntryLoaded,
    batch->onEntryLoadedCallbacks,
    batch->onEntryLoadedUsers,
    ASSET_BATCH_EVENT_MAX
  );
  eventInit(
    &batch->onError,
    batch->onErrorCallbacks, batch->onErrorUsers, ASSET_BATCH_EVENT_MAX
  );
  eventInit(
    &batch->onEntryError,
    batch->onEntryErrorCallbacks,
    batch->onEntryErrorUsers,
    ASSET_BATCH_EVENT_MAX
  );
  for(uint16_t i = 0; i < count; i++) {
    batch->inputs[i] = descs[i].input;
    batch->entries[i] = assetLock(
      descs[i].path, descs[i].type, &batch->inputs[i]
    );
    if(batch->entries[i]->state == ASSET_ENTRY_STATE_LOADED) {
      // Already loaded (cached) - count it now, no subscription needed.
      batch->loadedCount++;
    } else if(batch->entries[i]->state == ASSET_ENTRY_STATE_ERROR) {
      batch->errorCount++;
    } else {
      eventSubscribe(
        &batch->entries[i]->onLoaded, assetBatchEntryOnLoadedCb, batch
      );
      eventSubscribe(
        &batch->entries[i]->onError, assetBatchEntryOnErrorCb, batch
      );
    }
  }
 }
 void assetBatchLock(assetbatch_t *batch) {
  assertNotNull(batch, "Batch cannot be NULL.");
  for(uint16_t i = 0; i < batch->count; i++) {
    assetEntryLock(batch->entries[i]);
  }
 }
 void assetBatchUnlock(assetbatch_t *batch) {
  assertNotNull(batch, "Batch cannot be NULL.");
  for(uint16_t i = 0; i < batch->count; i++) {
    assetEntryUnlock(batch->entries[i]);
  }
 }
 bool_t assetBatchIsLoaded(const assetbatch_t *batch) {
  assertNotNull(batch, "Batch cannot be NULL.");
  for(uint16_t i = 0; i < batch->count; i++) {
    if(batch->entries[i]->state != ASSET_ENTRY_STATE_LOADED) return false;
  }
  return true;
 }
 bool_t assetBatchHasError(const assetbatch_t *batch) {
  assertNotNull(batch, "Batch cannot be NULL.");
  for(uint16_t i = 0; i < batch->count; i++) {
    if(batch->entries[i]->state == ASSET_ENTRY_STATE_ERROR) return true;
  }
  return false;
 }
 errorret_t assetBatchRequireLoaded(assetbatch_t *batch) {
  assertNotNull(batch, "Batch cannot be NULL.");
  bool_t allDone;
  do {
    allDone = true;
    for(uint16_t i = 0; i < batch->count; i++) {
      const assetentrystate_t state = batch->entries[i]->state;
      if(state == ASSET_ENTRY_STATE_ERROR) {
        errorThrow("Asset '%s' failed to load.", batch->entries[i]->name);
      }
      if(state != ASSET_ENTRY_STATE_LOADED) {
        allDone = false;
      }
    }
    if(!allDone) {
      usleep(1000);
      errorChain(assetUpdate());
    }
  } while(!allDone);
  errorOk();
 }
 void assetBatchDispose(assetbatch_t *batch) {
  assertNotNull(batch, "Batch cannot be NULL.");
  for(uint16_t i = 0; i < batch->count; i++) {
    if(batch->entries[i]) {
      // Unsubscribe while we still hold a lock so the entry is live.
      eventUnsubscribe(&batch->entries[i]->onLoaded, assetBatchEntryOnLoadedCb);
      eventUnsubscribe(&batch->entries[i]->onError, assetBatchEntryOnErrorCb);
      assetUnlockEntry(batch->entries[i]);
    }
  }
  memoryZero(batch, sizeof(assetbatch_t));
 }
 void assetBatchEntryOnLoadedCb(void *params, void *user) {
  assetentry_t *entry = (assetentry_t *)params;
  assetbatch_t *batch = (assetbatch_t *)user;
  batch->loadedCount++;
  eventInvoke(&batch->onEntryLoaded, entry);
  if((uint16_t)(batch->loadedCount + batch->errorCount) >= batch->count) {
    if(batch->errorCount == 0) {
      eventInvoke(&batch->onLoaded, batch);
    } else {
      eventInvoke(&batch->onError, batch);
    }
  }
 }
 void assetBatchEntryOnErrorCb(void *params, void *user) {
  assetentry_t *entry = (assetentry_t *)params;
  assetbatch_t *batch = (assetbatch_t *)user;
  batch->errorCount++;
  eventInvoke(&batch->onEntryError, entry);
  if((uint16_t)(batch->loadedCount + batch->errorCount) >= batch->count) {
    eventInvoke(&batch->onError, batch);
  }
 }
@@ -1,124 +0,0 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "asset/loader/assetentry.h"
 #include "asset/loader/assetloader.h"
 #include "event/event.h"
 #define ASSET_BATCH_COUNT_MAX  64
 #define ASSET_BATCH_EVENT_MAX  4
 typedef struct {
  const char_t *path;
  assetloadertype_t type;
  assetloaderinput_t input;
 } assetbatchdesc_t;
 typedef struct {
  assetentry_t *entries[ASSET_BATCH_COUNT_MAX];
  assetloaderinput_t inputs[ASSET_BATCH_COUNT_MAX];
  uint16_t count;
  uint16_t loadedCount;
  uint16_t errorCount;
  /** Fires once when every entry loaded. params = assetbatch_t * */
  event_t onLoaded;
  eventcallback_t onLoadedCallbacks[ASSET_BATCH_EVENT_MAX];
  void *onLoadedUsers[ASSET_BATCH_EVENT_MAX];
  /** Fires each time a single entry loads. params = assetentry_t * */
  event_t onEntryLoaded;
  eventcallback_t onEntryLoadedCallbacks[ASSET_BATCH_EVENT_MAX];
  void *onEntryLoadedUsers[ASSET_BATCH_EVENT_MAX];
  /** Fires when all entries finish (any with errors). params: assetbatch_t * */
  event_t onError;
  eventcallback_t onErrorCallbacks[ASSET_BATCH_EVENT_MAX];
  void *onErrorUsers[ASSET_BATCH_EVENT_MAX];
  /** Fires each time a single entry errors. params = assetentry_t * */
  event_t onEntryError;
  eventcallback_t onEntryErrorCallbacks[ASSET_BATCH_EVENT_MAX];
  void *onEntryErrorUsers[ASSET_BATCH_EVENT_MAX];
 } assetbatch_t;
 /**
 * Initialises the batch from an array of descriptors. Each entry is locked
 * and queued for loading immediately.
 *
 * @param batch  Batch to initialise.
 * @param descs  Array of entry descriptors (need not outlive this call).
 * @param count  Number of descriptors (must be <= ASSET_BATCH_COUNT_MAX).
 */
 void assetBatchInit(
  assetbatch_t *batch,
  uint16_t count,
  const assetbatchdesc_t *descs
 );
 /**
 * Acquires one additional lock on every entry in the batch.
 *
 * @param batch Batch to lock.
 */
 void assetBatchLock(assetbatch_t *batch);
 /**
 * Releases one lock from every entry in the batch. When an entry's lock
 * count reaches zero it will be reaped on the next assetUpdate.
 *
 * @param batch Batch to unlock.
 */
 void assetBatchUnlock(assetbatch_t *batch);
 /**
 * Returns true if every entry in the batch has finished loading.
 *
 * @param batch Batch to query.
 */
 bool_t assetBatchIsLoaded(const assetbatch_t *batch);
 /**
 * Returns true if any entry in the batch is in an error state.
 *
 * @param batch Batch to query.
 */
 bool_t assetBatchHasError(const assetbatch_t *batch);
 /**
 * Blocks until every entry is loaded. Returns an error if any entry fails.
 *
 * @param batch Batch to wait on.
 */
 errorret_t assetBatchRequireLoaded(assetbatch_t *batch);
 /**
 * Releases the batch's lock on every entry and clears the batch. After this
 * call the batch struct may be reused with assetBatchInit.
 *
 * @param batch Batch to dispose.
 */
 void assetBatchDispose(assetbatch_t *batch);
 /**
 * Event trampoline invoked when a batch entry finishes loading.
 * Increments the loaded counter and fires batch-level events.
 *
 * @param params The loaded assetentry_t pointer.
 * @param user   The owning assetbatch_t pointer.
 */
 void assetBatchEntryOnLoadedCb(void *params, void *user);
 /**
 * Event trampoline invoked when a batch entry fails to load.
 * Increments the error counter and fires batch-level events.
 *
 * @param params The errored assetentry_t pointer.
 * @param user   The owning assetbatch_t pointer.
 */
 void assetBatchEntryOnErrorCb(void *params, void *user);
@@ -0,0 +1,165 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "assetdsk.h"
 #include "util/memory.h"
 #include "util/endian.h"
 #include "assert/assert.h"
 #include <zlib.h>
 errorret_t assetDskParseHeader(
  const uint8_t *bytes,
  const size_t bytesSize,
  assetdskheader_t *outHeader
 ) {
  assertNotNull(bytes, "Bytes cannot be NULL.");
  assertNotNull(outHeader, "Out header cannot be NULL.");
  if(bytesSize < ASSET_DSK_HEADER_SIZE) {
    errorThrow("dusk.dsk header is truncated.");
  }
  if(memoryCompare(bytes, ASSET_DSK_MAGIC, ASSET_DSK_MAGIC_SIZE) != 0) {
    errorThrow("dusk.dsk has an invalid magic header.");
  }
  // Every field is a little-endian uint32_t regardless of host - convert
  // to host order (a no-op on little-endian hosts, a real byteswap on
  // Dolphin's big-endian PowerPC).
  uint32_t fields[3];
  memoryCopy(fields, bytes + ASSET_DSK_MAGIC_SIZE, sizeof(fields));
  for(uint8_t i = 0; i < 3; i++) {
    fields[i] = endianLittleToHost32(fields[i]);
  }
  const uint32_t version = fields[0];
  if(version != ASSET_DSK_VERSION) {
    errorThrow("dusk.dsk has an unsupported version: %u", version);
  }
  outHeader->size = fields[1];
  outHeader->checksum = fields[2];
  errorOk();
 }
 errorret_t assetDskOpenFromPath(
  const char_t *path,
  zip_t **outZip
 ) {
  errorChain(assetDskOpenFromPathRange(path, 0, SIZE_MAX, outZip));
  errorOk();
 }
 errorret_t assetDskOpenFromPathRange(
  const char_t *path,
  const size_t baseOffset,
  const size_t baseSize,
  zip_t **outZip
 ) {
  assertNotNull(path, "Path cannot be NULL.");
  assertNotNull(outZip, "Out zip cannot be NULL.");
  *outZip = NULL;
  FILE *headerFile = fopen(path, "rb");
  if(headerFile == NULL) {
    errorThrow("Failed to open dusk.dsk: %s", path);
  }
  if(fseek(headerFile, (long) baseOffset, SEEK_SET) != 0) {
    fclose(headerFile);
    errorThrow("Failed to seek to dusk.dsk range in file: %s", path);
  }
  uint8_t headerBytes[ASSET_DSK_HEADER_SIZE];
  size_t headerRead = fread(headerBytes, 1, sizeof(headerBytes), headerFile);
  fclose(headerFile);
  if(headerRead != sizeof(headerBytes)) {
    errorThrow("Failed to read dusk.dsk header: %s", path);
  }
  assetdskheader_t header;
  errorChain(assetDskParseHeader(headerBytes, sizeof(headerBytes), &header));
  if((size_t) ASSET_DSK_HEADER_SIZE + header.size > baseSize) {
    errorThrow("dusk.dsk header describes a range beyond its containing file.");
  }
  zip_error_t zipError;
  zip_error_init(&zipError);
  zip_source_t *source = zip_source_file_create(
    path,
    (zip_uint64_t) (baseOffset + ASSET_DSK_HEADER_SIZE),
    (zip_int64_t) header.size,
    &zipError
  );
  if(source == NULL) {
    errorThrow(
      "Failed to create dusk.dsk source: %s", zip_error_strerror(&zipError)
    );
  }
  *outZip = zip_open_from_source(source, ZIP_RDONLY, &zipError);
  if(*outZip == NULL) {
    zip_source_free(source);
    errorThrow(
      "Failed to open dusk.dsk archive: %s", zip_error_strerror(&zipError)
    );
  }
  errorOk();
 }
 errorret_t assetDskOpenFromBuffer(
  uint8_t *buffer,
  const size_t bufferSize,
  zip_t **outZip
 ) {
  assertNotNull(buffer, "Buffer cannot be NULL.");
  assertNotNull(outZip, "Out zip cannot be NULL.");
  *outZip = NULL;
  assetdskheader_t header;
  errorChain(assetDskParseHeader(buffer, bufferSize, &header));
  if((size_t) ASSET_DSK_HEADER_SIZE + header.size > bufferSize) {
    errorThrow("dusk.dsk header describes a range beyond the buffer.");
  }
  uint8_t *data = buffer + ASSET_DSK_HEADER_SIZE;
  uint32_t checksum = (uint32_t) crc32(0L, data, (uInt) header.size);
  if(checksum != header.checksum) {
    errorThrow("dusk.dsk archive failed checksum verification.");
  }
  zip_error_t zipError;
  zip_error_init(&zipError);
  // freep=0 - this is a non-owning window into the same caller-owned
  // buffer, not an independent allocation libzip should free.
  zip_source_t *source = zip_source_buffer_create(
    data, header.size, 0, &zipError
  );
  if(source == NULL) {
    errorThrow(
      "Failed to create dusk.dsk source: %s", zip_error_strerror(&zipError)
    );
  }
  *outZip = zip_open_from_source(source, ZIP_RDONLY, &zipError);
  if(*outZip == NULL) {
    zip_source_free(source);
    errorThrow(
      "Failed to open dusk.dsk archive: %s", zip_error_strerror(&zipError)
    );
  }
  errorOk();
 }
@@ -0,0 +1,120 @@
 /**
 * 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 <zip.h>
 // "DSK2" - distinct from a plain zip's "PK\x03\x04" so a stray plain zip
 // never gets misread as a valid dusk.dsk.
 #define ASSET_DSK_MAGIC_SIZE 4
 #define ASSET_DSK_MAGIC "DSK"
 #define ASSET_DSK_VERSION 2
 // Magic + version + size + checksum
 #define ASSET_DSK_HEADER_SIZE ( \
  ASSET_DSK_MAGIC_SIZE + \
  sizeof(uint32_t) + \
  sizeof(uint32_t) + \
  sizeof(uint32_t) \
 )
 /**
 * Parsed dusk.dsk (DSK2 format) header. dusk.dsk is a single uncompressed
 * (ZIP_STORED) zip archive (see tools/asset/pack) rather than DEFLATEd -
 * the bulk of what's packed (audio, images) is already compressed at the
 * file level, so DEFLATE-ing the whole archive on top buys negligible
 * space for real CPU cost, and every entry gets the reliable repeated
 * seeking/re-opening that libzip only supports for uncompressed entries
 * (locale line-by-line reads, MP3 loop restarts, etc.) instead of just a
 * hand-picked subset of files.
 */
 typedef struct {
  uint32_t size;
  uint32_t checksum;
 } assetdskheader_t;
 /**
 * Parses a DSK2 header from a raw byte buffer (at least
 * ASSET_DSK_HEADER_SIZE bytes), validating the magic/version and
 * byte-swapping the little-endian fields to host order.
 *
 * @param bytes Buffer containing the header (and beyond).
 * @param bytesSize Number of bytes available at `bytes`.
 * @param outHeader Filled with the parsed header on success.
 * @return OK on success, error if too short, bad magic, or unsupported version.
 */
 errorret_t assetDskParseHeader(
  const uint8_t *bytes,
  const size_t bytesSize,
  assetdskheader_t *outHeader
 );
 /**
 * Opens the dusk.dsk archive given a filesystem path, using a lazy/
 * windowed file-backed zip source - no more memory used than the
 * existing per-platform small read buffers, matching the memory
 * characteristics of a plain zip_open() on the whole file. The checksum
 * is intentionally not verified here since doing so would require
 * reading the whole (potentially large) archive just to compute it.
 *
 * See assetDskOpenFromPathRange() for the case where the DSK2 blob isn't
 * the whole file (e.g. embedded inside another container).
 *
 * @param path Filesystem path to the dusk.dsk file.
 * @param outZip Set to the opened archive on success.
 * @return OK on success, error if the file is missing, too short, has a
 *         bad header, or the archive fails to open.
 */
 errorret_t assetDskOpenFromPath(
  const char_t *path,
  zip_t **outZip
 );
 /**
 * Same as assetDskOpenFromPath(), but the DSK2 blob doesn't start at the
 * beginning of `path` - it's a byte range embedded inside a larger
 * container file (e.g. the PSAR region of an EBOOT.PBP). Every offset the
 * header describes is relative to `baseOffset`; `baseSize` bounds them
 * (the size of the embedded blob, not the whole container file) - pass
 * SIZE_MAX to skip that check when the caller doesn't know/care.
 *
 * @param path Filesystem path to the container file.
 * @param baseOffset Byte offset within `path` where the DSK2 blob starts.
 * @param baseSize Number of bytes available at `baseOffset`.
 * @param outZip Set to the opened archive on success.
 * @return OK on success, error if the file is missing, too short, has a
 *         bad header, or the archive fails to open.
 */
 errorret_t assetDskOpenFromPathRange(
  const char_t *path,
  const size_t baseOffset,
  const size_t baseSize,
  zip_t **outZip
 );
 /**
 * Opens the dusk.dsk archive already fully resident in memory (e.g. a
 * PSAR embedded in an EBOOT.PBP, or an ISO-embedded file already read via
 * DVD_ReadAbs - platforms that already buffer the whole file for reasons
 * unrelated to this format). The returned archive doesn't take ownership
 * of `buffer` (it's opened as a non-owning sub-range of it) - the caller
 * remains responsible for freeing it, and must keep it alive for as long
 * as the archive stays open. Verifies the checksum, since the bytes are
 * already resident.
 *
 * @param buffer The whole dusk.dsk file's bytes.
 * @param bufferSize Number of bytes at `buffer`.
 * @param outZip Set to the opened archive on success.
 * @return OK on success, error if too short, has a bad header/checksum, or
 *         the archive fails to open.
 */
 errorret_t assetDskOpenFromBuffer(
  uint8_t *buffer,
  const size_t bufferSize,
  zip_t **outZip
 );
@@ -24,9 +24,11 @@ errorret_t assetFileInit(
  file->params = params;
  file->output = output;
  // Stat the file
  zip_stat_init(&file->stat);
-  if(!zip_stat(ASSET.zip, filename, 0, &file->stat) == 0) {
+  threadMutexLock(&ASSET.zipLock);
  int statResult = zip_stat(ASSET.zip, filename, 0, &file->stat);
  threadMutexUnlock(&ASSET.zipLock);
  if(statResult != 0) {
    errorThrow("Failed to stat asset file: %s", filename);
  }
@@ -47,6 +49,25 @@ errorret_t assetFileRewind(assetfile_t *file) {
    errorOk();
  }
  // Prefer seeking within the still-open handle over closing and
  // re-opening it. Repeatedly closing/re-opening the same compressed zip
  // entry (once per rewind - e.g. once per locale string lookup) was
  // confirmed unreliable on at least one platform's zip backend, silently
  // skipping ranges of the decompressed content on some re-opens after
  // the first. A real seek avoids that failure mode entirely, with no
  // extra memory cost over the close+reopen fallback.
  threadMutexLock(&ASSET.zipLock);
  bool_t seekable = zip_file_is_seekable(file->zipFile);
  int seekResult = seekable ? zip_fseek(file->zipFile, 0, SEEK_SET) : -1;
  threadMutexUnlock(&ASSET.zipLock);
  if(seekable) {
    if(seekResult != 0) {
      errorThrow("Failed to seek asset file: %s", file->filename);
    }
    file->position = 0;
    errorOk();
  }
  errorChain(assetFileClose(file));
  errorChain(assetFileOpen(file));
  errorOk();
@@ -55,10 +76,11 @@ errorret_t assetFileRewind(assetfile_t *file) {
 errorret_t assetFileOpen(assetfile_t *file) {
  assertNotNull(file, "Asset file cannot be NULL.");
  assertNotNull(file->filename, "Asset file filename cannot be NULL.");
  assertNotNull(ASSET.zip, "Asset zip cannot be NULL.");
  assertNull(file->zipFile, "Asset file already open.");
  threadMutexLock(&ASSET.zipLock);
  file->zipFile = zip_fopen(ASSET.zip, file->filename, 0);
  threadMutexUnlock(&ASSET.zipLock);
  if(file->zipFile == NULL) {
    errorThrow("Failed to open asset file: %s", file->filename);
  }
@@ -79,21 +101,52 @@ errorret_t assetFileRead(
    uint8_t tempBuffer[256];
    while(bytesRemaining > 0) {
      size_t chunkSize = mathMin(bytesRemaining, sizeof(tempBuffer));
      // The recursive call below already advances file->position by
      // chunkSize (the non-NULL branch does this itself) - do not also
      // advance it here, or every skip ends up double-counted.
      errorChain(assetFileRead(file, tempBuffer, chunkSize));
      file->position += chunkSize;
      bytesRemaining -= chunkSize;
    }
    file->lastRead = bufferSize;
    errorOk();
  }
-  // I assume zip_fread takes buffer NULL for skipping?
+  // Some zip_fread() implementations (seen on PSP) reject a single call
-  zip_int64_t bytesRead = zip_fread(file->zipFile, buffer, bufferSize);
+  // asking for the entire (potentially large) file at once with EINVAL;
  // the line reader above only ever asks for up to 1024 bytes per call and
  // works fine, so read in bounded chunks here too.
  size_t totalRead = 0;
  uint8_t *dest = (uint8_t *)buffer;
  while(totalRead < bufferSize) {
    size_t chunkSize = mathMin(
      bufferSize - totalRead, ASSET_FILE_READ_CHUNK_MAX
    );
    threadMutexLock(&ASSET.zipLock);
    zip_int64_t bytesRead = zip_fread(
      file->zipFile, dest + totalRead, chunkSize
    );
    errorret_t readError = errorOkImpl();
    if(bytesRead < 0) {
-    errorThrow("Failed to read from asset file: %s", file->filename);
+      // Built (not thrown) while still holding the lock, so
      // zip_file_strerror() reads the just-failed zipFile's error state
      // before another thread can touch it - errorThrow() itself isn't
      // used here since it returns immediately, which would leave
      // ASSET.zipLock held forever.
      readError = errorThrowImpl(
        &ERROR_STATE, ERROR_NOT_OK, __FILE__, __func__, __LINE__,
        "Failed to read from asset file: %s (%s)",
        file->filename, zip_file_strerror(file->zipFile)
      );
    }
-  file->position += bytesRead;
+    threadMutexUnlock(&ASSET.zipLock);
-  file->lastRead = bytesRead;
+    if(errorIsNotOk(readError)) {
      errorChain(readError);
    }
    if(bytesRead == 0) break;
    totalRead += (size_t)bytesRead;
  }
  file->position += totalRead;
  file->lastRead = totalRead;
  errorOk();
 }
@@ -101,7 +154,10 @@ errorret_t assetFileClose(assetfile_t *file) {
  assertNotNull(file, "Asset file cannot be NULL.");
  assertNotNull(file->zipFile, "Asset file must be opened before closing.");
-  if(zip_fclose(file->zipFile) != 0) {
+  threadMutexLock(&ASSET.zipLock);
  int closeResult = zip_fclose(file->zipFile);
  threadMutexUnlock(&ASSET.zipLock);
  if(closeResult != 0) {
    errorThrow("Failed to close asset file: %s", file->filename);
  }
  file->zipFile = NULL;
@@ -201,7 +257,7 @@ const uint8_t *assetFileLineReaderUnreadPtr(
  return reader->readBuffer + reader->bufferStart;
 }
-static errorret_t assetFileLineReaderAppend(
+errorret_t assetFileLineReaderAppend(
  assetfilelinereader_t *reader,
  const uint8_t *src,
  size_t srcLength
@@ -223,7 +279,7 @@ static errorret_t assetFileLineReaderAppend(
  errorOk();
 }
-static void assetFileLineReaderTerminate(assetfilelinereader_t *reader) {
+void assetFileLineReaderTerminate(assetfilelinereader_t *reader) {
  assertNotNull(reader, "Reader cannot be NULL.");
  assertNotNull(reader->outBuffer, "Out buffer cannot be NULL.");
  assertTrue(
@@ -233,7 +289,7 @@ static void assetFileLineReaderTerminate(assetfilelinereader_t *reader) {
  reader->outBuffer[reader->lineLength] = '\0';
 }
-static ssize_t assetFileLineReaderFindNewline(
+ssize_t assetFileLineReaderFindNewline(
  const assetfilelinereader_t *reader
 ) {
  size_t i;
@@ -9,7 +9,13 @@
 #include "error/error.h"
 #include <zip.h>
-#define ASSET_FILE_NAME_MAX 48
+#define ASSET_FILE_NAME_MAX 128
 // Max bytes requested per zip_fread() call in assetFileRead(). Some
 // zip_fread() implementations (seen on PSP) reject a single call asking
 // for very large amounts of data at once; the locale line reader has
 // always used 1024-byte reads successfully, so that's the proven-safe cap.
 #define ASSET_FILE_READ_CHUNK_MAX 1024
 typedef struct assetfile_s assetfile_t;
@@ -144,6 +150,63 @@ void assetFileLineReaderInit(
  const size_t outBufferSize
 );
 /**
 * Returns the number of bytes still unread in the line reader's read buffer.
 *
 * @param reader The line reader to check.
 * @return Number of unread bytes remaining in the read buffer.
 */
 size_t assetFileLineReaderUnreadBytes(const assetfilelinereader_t *reader);
 /**
 * Returns a pointer to the first unread byte in the line reader's read
 * buffer.
 *
 * @param reader The line reader to check.
 * @return Pointer to the first unread byte.
 */
 const uint8_t *assetFileLineReaderUnreadPtr(
  const assetfilelinereader_t *reader
 );
 /**
 * Appends src to the line reader's current line buffer, growing lineLength.
 *
 * @param reader The line reader whose out buffer to append to.
 * @param src Bytes to append.
 * @param srcLength Number of bytes in src.
 * @return Error state if any (the line would exceed the output buffer).
 */
 errorret_t assetFileLineReaderAppend(
  assetfilelinereader_t *reader,
  const uint8_t *src,
  size_t srcLength
 );
 /**
 * Null-terminates the line reader's current line buffer at lineLength.
 *
 * @param reader The line reader whose out buffer to terminate.
 */
 void assetFileLineReaderTerminate(assetfilelinereader_t *reader);
 /**
 * Searches the line reader's unread buffered bytes for a newline character.
 *
 * @param reader The line reader to search.
 * @return The index of the newline within readBuffer, or -1 if not found.
 */
 ssize_t assetFileLineReaderFindNewline(const assetfilelinereader_t *reader);
 /**
 * Refills the line reader's read buffer from the underlying file once its
 * buffered bytes are fully consumed. A no-op once the file is at EOF.
 *
 * @param reader The line reader to refill.
 * @return Error state if any.
 */
 errorret_t assetFileLineReaderFill(assetfilelinereader_t *reader);
 /**
 * Reads the next line from the asset file into the line buffer. The line
 * buffer is null-terminated and does not include the newline character.
@@ -15,4 +15,6 @@ target_sources(${DUSK_LIBRARY_TARGET_NAME}
 add_subdirectory(display)
 add_subdirectory(locale)
 add_subdirectory(json)
-add_subdirectory(chunk)
+add_subdirectory(dmf)
 add_subdirectory(wav)
 add_subdirectory(mp3)
@@ -35,22 +35,6 @@ void assetEntryInit(
    entry->input = NULL;
  }
  refInit(&entry->refs, entry, NULL, NULL, NULL);
  eventInit(
    &entry->onLoaded,
    entry->onLoadedCallbacks, entry->onLoadedUsers,
    ASSET_ENTRY_EVENT_MAX
  );
  eventInit(
    &entry->onUnloaded,
    entry->onUnloadedCallbacks, entry->onUnloadedUsers,
    ASSET_ENTRY_EVENT_MAX
  );
  eventInit(
    &entry->onError,
    entry->onErrorCallbacks, entry->onErrorUsers,
    ASSET_ENTRY_EVENT_MAX
  );
 }
 void assetEntryLock(assetentry_t *entry) {
@@ -97,7 +81,7 @@ errorret_t assetEntryDispose(assetentry_t *entry) {
    "Asset entry still refed at dispose time."
  );
-  eventInvoke(&entry->onUnloaded, entry);
+  if(entry->onUnloaded) entry->onUnloaded(entry, entry->onUnloadedUser);
  errorChain(ASSET_LOADER_CALLBACKS[entry->type].dispose(entry));
  memoryZero(entry, sizeof(assetentry_t));
  errorOk();
@@ -7,7 +7,6 @@
 #pragma once
 #include "asset/loader/assetloading.h"
 #include "event/event.h"
 #include "util/ref.h"
 typedef enum {
@@ -20,11 +19,17 @@ typedef enum {
  ASSET_ENTRY_STATE_ERROR
 } assetentrystate_t;
 /** Maximum number of subscribers for each per-entry event. */
 #define ASSET_ENTRY_EVENT_MAX 2
 typedef struct assetentry_s assetentry_t;
 /**
 * A single asset entry callback. Each entry supports at most one subscriber
 * per event - a second assignment without clearing the first is a bug.
 *
 * @param entry The assetentry_t the event fired on.
 * @param user The user pointer passed alongside the callback.
 */
 typedef void (*assetentrycallback_t)(assetentry_t *entry, void *user);
 struct assetentry_s {
  char_t name[ASSET_FILE_NAME_MAX];
  assetloadertype_t type;
@@ -33,30 +38,27 @@ struct assetentry_s {
  ref_t refs;
  assetloaderinput_t *input;
  assetloaderinput_t inputData;
  /**
   * Fired once when loading completes successfully (params = assetentry_t *).
   * Always invoked on the main thread.
   */
  event_t onLoaded;
  eventcallback_t onLoadedCallbacks[ASSET_ENTRY_EVENT_MAX];
  void *onLoadedUsers[ASSET_ENTRY_EVENT_MAX];
  /**
-   * Fired once when the entry is disposed/reaped (params = assetentry_t *).
+   * Fired once when loading completes successfully.
   * The asset data is still accessible when the callback runs.
   * Always invoked on the main thread.
   */
-  event_t onUnloaded;
+  assetentrycallback_t onLoaded;
-  eventcallback_t onUnloadedCallbacks[ASSET_ENTRY_EVENT_MAX];
+  void *onLoadedUser;
  void *onUnloadedUsers[ASSET_ENTRY_EVENT_MAX];
  /**
-   * Fired once when loading fails (params = assetentry_t *).
+   * Fired once when the entry is disposed/reaped. The asset data is still
   * accessible when the callback runs. Always invoked on the main thread.
   */
  assetentrycallback_t onUnloaded;
  void *onUnloadedUser;
  /**
   * Fired once when loading fails.
   * Always invoked on the main thread.
   */
-  event_t onError;
+  assetentrycallback_t onError;
-  eventcallback_t onErrorCallbacks[ASSET_ENTRY_EVENT_MAX];
+  void *onErrorUser;
  void *onErrorUsers[ASSET_ENTRY_EVENT_MAX];
 };
 /**
@@ -16,6 +16,12 @@ assetloadercallbacks_t ASSET_LOADER_CALLBACKS[ASSET_LOADER_TYPE_COUNT] = {
    .dispose = assetMeshDispose
  },
  [ASSET_LOADER_TYPE_MODEL] = {
    .loadSync = assetModelLoaderSync,
    .loadAsync = assetModelLoaderAsync,
    .dispose = assetModelDispose
  },
  [ASSET_LOADER_TYPE_TEXTURE] = {
    .loadSync = assetTextureLoaderSync,
    .loadAsync = assetTextureLoaderAsync,
@@ -40,9 +46,15 @@ assetloadercallbacks_t ASSET_LOADER_CALLBACKS[ASSET_LOADER_TYPE_COUNT] = {
    .dispose = assetJsonDispose
  },
-  [ASSET_LOADER_TYPE_CHUNK] = {
+  [ASSET_LOADER_TYPE_WAV] = {
-    .loadSync = assetChunkLoaderSync,
+    .loadSync = assetWavLoaderSync,
-    .loadAsync = assetChunkLoaderAsync,
+    .loadAsync = assetWavLoaderAsync,
-    .dispose = assetChunkDispose
+    .dispose = assetWavDispose
  },
  [ASSET_LOADER_TYPE_MP3] = {
    .loadSync = assetMp3LoaderSync,
    .loadAsync = assetMp3LoaderAsync,
    .dispose = assetMp3Dispose
  },
 };
@@ -6,53 +6,61 @@
 */
 #pragma once
-#include "asset/loader/display/assetmeshloader.h"
+#include "asset/loader/dmf/assetmeshloader.h"
 #include "asset/loader/dmf/assetmodelloader.h"
 #include "asset/loader/display/assettextureloader.h"
 #include "asset/loader/display/assettilesetloader.h"
 #include "asset/loader/locale/assetlocaleloader.h"
 #include "asset/loader/json/assetjsonloader.h"
-#include "asset/loader/chunk/assetchunkloader.h"
+#include "asset/loader/wav/assetwavloader.h"
 #include "asset/loader/mp3/assetmp3loader.h"
 typedef enum {
  ASSET_LOADER_TYPE_NULL,
  ASSET_LOADER_TYPE_MESH,
  ASSET_LOADER_TYPE_MODEL,
  ASSET_LOADER_TYPE_TEXTURE,
  ASSET_LOADER_TYPE_TILESET,
  ASSET_LOADER_TYPE_LOCALE,
  ASSET_LOADER_TYPE_JSON,
-  ASSET_LOADER_TYPE_CHUNK,
+  ASSET_LOADER_TYPE_WAV,
  ASSET_LOADER_TYPE_MP3,
  ASSET_LOADER_TYPE_COUNT
 } assetloadertype_t;
 typedef union {
  assetmeshloaderinput_t mesh;
  assettextureloaderinput_t texture;
  assettilesetloaderinput_t tileset;
  assetlocaleloaderinput_t locale;
  assetjsonloaderinput_t json;
  assetchunkloaderinput_t chunk;
 } assetloaderinput_t;
 typedef union {
  assetmeshloaderloading_t mesh;
  assetmodelloaderloading_t model;
  assettextureloaderloading_t texture;
  assettilesetloaderloading_t tileset;
  assetlocaleloaderloading_t locale;
  assetjsonloaderloading_t json;
-  assetchunkloaderloading_t chunk;
+  assetwavloaderloading_t wav;
  assetmp3loaderloading_t mp3;
 } assetloaderloading_t;
 typedef union {
  assetmeshoutput_t mesh;
  assetmodeloutput_t model;
  assettextureoutput_t texture;
  assettilesetoutput_t tileset;
  assetlocaleoutput_t locale;
  assetjsonoutput_t json;
-  assetchunkoutput_t chunk;
+  assetwavoutput_t wav;
  assetmp3output_t mp3;
 } assetloaderoutput_t;
 typedef union {
  assettextureloaderinput_t texture;
  assettilesetloaderinput_t tileset;
  assetlocaleloaderinput_t locale;
  assetjsonloaderinput_t json;
  assetwavloaderinput_t wav;
  assetmp3loaderinput_t mp3;
 } assetloaderinput_t;
 typedef struct assetloading_s assetloading_t;
 typedef struct assetentry_s assetentry_t;
@@ -1,115 +0,0 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "assetchunkloader.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "util/endian.h"
 #include "asset/loader/assetloading.h"
 #include "asset/loader/assetentry.h"
 errorret_t assetChunkLoaderAsync(assetloading_t *loading) {
  assertNotNull(loading, "Loading cannot be NULL");
  assertNotMainThread("Should be called from an async thread.");
  if(loading->loading.chunk.state != ASSET_CHUNK_LOADING_STATE_READ_FILE) {
    errorOk();
  }
  assertNull(loading->loading.chunk.data, "Data already defined?");
  assetfile_t *file = &loading->loading.chunk.file;
  assetLoaderErrorChain(loading,
    assetFileInit(file, loading->entry->name, NULL, NULL)
  );
  uint8_t *data = memoryAllocate(file->size);
  assetLoaderErrorChain(loading, assetFileOpen(file));
  assetLoaderErrorChain(loading, assetFileRead(file, data, file->size));
  assetLoaderErrorChain(loading, assetFileClose(file));
  assetLoaderErrorChain(loading, assetFileDispose(file));
  assertTrue(
    file->lastRead == file->size,
    "Failed to read entire chunk file."
  );
  loading->loading.chunk.data = data;
  loading->loading.chunk.state = ASSET_CHUNK_LOADING_STATE_PARSE;
  loading->entry->state = ASSET_ENTRY_STATE_PENDING_SYNC;
  errorOk();
 }
 errorret_t assetChunkLoaderSync(assetloading_t *loading) {
  assertNotNull(loading, "Loading cannot be NULL");
  assertTrue(loading->type == ASSET_LOADER_TYPE_CHUNK, "Invalid type.");
  assertIsMainThread("Must be called from the main thread.");
  switch(loading->loading.chunk.state) {
    case ASSET_CHUNK_LOADING_STATE_INITIAL:
      loading->loading.chunk.state = ASSET_CHUNK_LOADING_STATE_READ_FILE;
      loading->entry->state = ASSET_ENTRY_STATE_PENDING_ASYNC;
      errorOk();
      break;
    case ASSET_CHUNK_LOADING_STATE_PARSE:
      break;
    default:
      errorOk();
  }
  uint8_t *data = loading->loading.chunk.data;
  assertNotNull(data, "Chunk data should have been loaded by now.");
  if(data[0] != 'D' || data[1] != 'C' || data[2] != 'F') {
    memoryFree(data);
    assetLoaderErrorThrow(loading, "Invalid chunk file header");
  }
  uint32_t version = endianLittleToHost32(*(uint32_t *)(data + 4));
  if(version != ASSET_CHUNK_FILE_VERSION) {
    memoryFree(data);
    assetLoaderErrorThrow(
      loading, "Unsupported chunk file version %u", version
    );
  }
  assetchunkoutput_t *out = &loading->entry->data.chunk;
  size_t offset = 8;
  size_t tileSize = CHUNK_TILE_COUNT * sizeof(tile_t);
  memoryCopy(out->tiles, data + offset, tileSize);
  offset += tileSize;
  out->vertCount = endianLittleToHost32(*(uint32_t *)(data + offset));
  offset += sizeof(uint32_t);
  assertTrue(
    out->vertCount <= CHUNK_VERTEX_COUNT,
    "Chunk vertex count exceeds maximum."
  );
  memoryCopy(
    out->vertices,
    data + offset,
    out->vertCount * sizeof(meshvertex_t)
  );
  memoryFree(data);
  loading->loading.chunk.data = NULL;
  loading->entry->state = ASSET_ENTRY_STATE_LOADED;
  errorOk();
 }
 errorret_t assetChunkDispose(assetentry_t *entry) {
  assertNotNull(entry, "Entry cannot be NULL");
  assertTrue(entry->type == ASSET_LOADER_TYPE_CHUNK, "Invalid type.");
  assertIsMainThread("Must be called from the main thread.");
  errorOk();
 }
@@ -1,65 +0,0 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "asset/assetfile.h"
 #include "rpg/overworld/chunk.h"
 #define ASSET_CHUNK_FILE_VERSION 1
 typedef struct assetloading_s assetloading_t;
 typedef struct assetentry_s assetentry_t;
 typedef struct {
  void *nothing;
 } assetchunkloaderinput_t;
 typedef enum {
  ASSET_CHUNK_LOADING_STATE_INITIAL,
  ASSET_CHUNK_LOADING_STATE_READ_FILE,
  ASSET_CHUNK_LOADING_STATE_PARSE,
  ASSET_CHUNK_LOADING_STATE_DONE
 } assetchunkloadingstate_t;
 typedef struct {
  assetfile_t file;
  assetchunkloadingstate_t state;
  uint8_t *data;
 } assetchunkloaderloading_t;
 typedef struct {
  tile_t tiles[CHUNK_TILE_COUNT];
  uint32_t vertCount;
  meshvertex_t vertices[CHUNK_VERTEX_COUNT];
 } assetchunkoutput_t;
 /**
 * Asynchronous loader for chunk assets. Reads the raw DCF file bytes into
 * the loading buffer so the sync phase can parse without blocking the
 * main thread on I/O.
 *
 * @param loading Loading information for the asset being loaded.
 * @return Error code indicating success or failure of the load operation.
 */
 errorret_t assetChunkLoaderAsync(assetloading_t *loading);
 /**
 * Synchronous loader for chunk assets. Validates the DCF binary previously
 * read by the async phase and populates the output assetchunkoutput_t.
 *
 * @param loading Loading information for the asset being loaded.
 * @return Error code indicating success or failure of the load operation.
 */
 errorret_t assetChunkLoaderSync(assetloading_t *loading);
 /**
 * Disposer for chunk assets.
 *
 * @param entry Asset entry containing the chunk data to dispose.
 * @return Error code indicating success or failure of the dispose operation.
 */
 errorret_t assetChunkDispose(assetentry_t *entry);
@@ -6,7 +6,6 @@
 # Sources
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    assetmeshloader.c
    assettextureloader.c
    assettilesetloader.c
 )
@@ -1,180 +0,0 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "assetmeshloader.h"
 #include "assert/assert.h"
 #include "util/endian.h"
 #include "util/memory.h"
 #include "asset/loader/assetloading.h"
 #include "asset/loader/assetentry.h"
 errorret_t assetMeshLoaderAsync(assetloading_t *loading) {
  assertNotNull(loading, "Loading cannot be NULL");
  if(loading->loading.mesh.state != ASSET_MESH_LOADING_STATE_READ_FILE) {
    errorOk();
  }
  assetmeshoutput_t *out = &loading->entry->data.mesh;
  assetfile_t *file = &loading->loading.mesh.file;
  assetmeshinputaxis_t axis = loading->entry->inputData.mesh;
  assetLoaderErrorChain(loading,
    assetFileInit(file, loading->entry->name, NULL, NULL)
  );
  assetLoaderErrorChain(loading, assetFileOpen(file));
  // Skip the 80-byte STL header.
  assetLoaderErrorChain(loading, assetFileRead(file, NULL, 80));
  if(file->lastRead != 80) {
    assetLoaderErrorThrow(loading, "Failed to skip STL header.");
  }
  uint32_t triangleCount;
  assetLoaderErrorChain(loading,
    assetFileRead(file, &triangleCount, sizeof(uint32_t))
  );
  if(file->lastRead != sizeof(uint32_t)) {
    assetLoaderErrorThrow(loading, "Failed to read tri count");
  }
  triangleCount = endianLittleToHost32(triangleCount);
  out->vertices = memoryAllocate(sizeof(meshvertex_t) * triangleCount * 3);
  meshvertex_t *verts = out->vertices;
  errorret_t ret;
  for(uint32_t i = 0; i < triangleCount; i++) {
    assetmeshstltriangle_t triData;
    ret = assetFileRead(file, &triData, sizeof(triData));
    if(errorIsNotOk(ret)) {
      memoryFree(verts);
      out->vertices = NULL;
      assetLoaderErrorChain(loading, ret);
    }
    if(file->lastRead != sizeof(triData)) {
      memoryFree(verts);
      out->vertices = NULL;
      assetLoaderErrorThrow(loading, "Failed to read triangle data");
    }
    for(uint8_t j = 0; j < 3; j++) {
      #if MESH_ENABLE_COLOR
        verts[i * 3 + j].color.r = (
          (uint8_t)(endianLittleToHostFloat(triData.normal[0]) * 255.0f)
        );
        verts[i * 3 + j].color.g = (
          (uint8_t)(endianLittleToHostFloat(triData.normal[1]) * 255.0f)
        );
        verts[i * 3 + j].color.b = (
          (uint8_t)(endianLittleToHostFloat(triData.normal[2]) * 255.0f)
        );
        verts[i * 3 + j].color.a = 0xFF;
      #endif
      verts[i * 3 + j].uv[0] = 0.0f;
      verts[i * 3 + j].uv[1] = 0.0f;
      for(uint8_t k = 0; k < 3; k++) {
        verts[i * 3 + j].pos[k] = endianLittleToHostFloat(
          triData.positions[j][k]
        );
      }
      switch(axis) {
        case MESH_INPUT_AXIS_Z_UP: {
          float_t temp = verts[i * 3 + j].pos[1];
          verts[i * 3 + j].pos[1] = verts[i * 3 + j].pos[2];
          verts[i * 3 + j].pos[2] = temp;
          break;
        }
        case MESH_INPUT_AXIS_X_UP: {
          float_t temp = verts[i * 3 + j].pos[0];
          verts[i * 3 + j].pos[0] = verts[i * 3 + j].pos[1];
          verts[i * 3 + j].pos[1] = temp;
          break;
        }
        case MESH_INPUT_AXIS_Y_DOWN:
          verts[i * 3 + j].pos[1] = -verts[i * 3 + j].pos[1];
          break;
        case MESH_INPUT_AXIS_Z_DOWN: {
          float_t temp = verts[i * 3 + j].pos[1];
          verts[i * 3 + j].pos[1] = -verts[i * 3 + j].pos[2];
          verts[i * 3 + j].pos[2] = temp;
          break;
        }
        case MESH_INPUT_AXIS_X_DOWN: {
          float_t temp = verts[i * 3 + j].pos[0];
          verts[i * 3 + j].pos[0] = verts[i * 3 + j].pos[1];
          verts[i * 3 + j].pos[1] = -temp;
          break;
        }
        case MESH_INPUT_AXIS_Y_UP:
        default:
          break;
      }
    }
  }
  ret = assetFileClose(file);
  if(errorIsNotOk(ret)) {
    memoryFree(verts);
    out->vertices = NULL;
    assetLoaderErrorChain(loading, ret);
  }
  assetFileDispose(file);
  loading->loading.mesh.triangleCount = triangleCount;
  loading->loading.mesh.state = ASSET_MESH_LOADING_STATE_CREATE_MESH;
  loading->entry->state = ASSET_ENTRY_STATE_PENDING_SYNC;
  errorOk();
 }
 errorret_t assetMeshLoaderSync(assetloading_t *loading) {
  assertNotNull(loading, "Loading cannot be NULL");
  assertTrue(loading->type == ASSET_LOADER_TYPE_MESH, "Invalid type.");
  switch(loading->loading.mesh.state) {
    case ASSET_MESH_LOADING_STATE_INITIAL:
      loading->loading.mesh.state = ASSET_MESH_LOADING_STATE_READ_FILE;
      loading->entry->state = ASSET_ENTRY_STATE_PENDING_ASYNC;
      errorOk();
      break;
    case ASSET_MESH_LOADING_STATE_CREATE_MESH:
      break;
    default:
      errorOk();
  }
  assetmeshoutput_t *out = &loading->entry->data.mesh;
  assertNotNull(out->vertices, "Mesh vertices should have been loaded by now.");
  errorret_t ret = meshInit(
    &out->mesh,
    MESH_PRIMITIVE_TYPE_TRIANGLES,
    loading->loading.mesh.triangleCount * 3,
    out->vertices
  );
  if(errorIsNotOk(ret)) {
    loading->entry->state = ASSET_ENTRY_STATE_ERROR;
    memoryFree(out->vertices);
    out->vertices = NULL;
    assetLoaderErrorChain(loading, ret);
  }
  loading->entry->state = ASSET_ENTRY_STATE_LOADED;
  errorOk();
 }
 errorret_t assetMeshDispose(assetentry_t *entry) {
  assertNotNull(entry, "Asset entry cannot be NULL");
  assertTrue(entry->type == ASSET_LOADER_TYPE_MESH, "Invalid type.");
  errorChain(meshDispose(&entry->data.mesh.mesh));
  memoryFree(entry->data.mesh.vertices);
  errorOk();
 }
@@ -1,58 +0,0 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "asset/assetfile.h"
 #include "display/mesh/mesh.h"
 #include "assert/assert.h"
 typedef struct assetloading_s assetloading_t;
 typedef struct assetentry_s assetentry_t;
 typedef enum {
  MESH_INPUT_AXIS_Y_UP,
  MESH_INPUT_AXIS_Z_UP,
  MESH_INPUT_AXIS_X_UP,
  MESH_INPUT_AXIS_Y_DOWN,
  MESH_INPUT_AXIS_Z_DOWN,
  MESH_INPUT_AXIS_X_DOWN,
 } assetmeshinputaxis_t;
 typedef assetmeshinputaxis_t assetmeshloaderinput_t;
 typedef enum {
  ASSET_MESH_LOADING_STATE_INITIAL,
  ASSET_MESH_LOADING_STATE_READ_FILE,
  ASSET_MESH_LOADING_STATE_CREATE_MESH,
  ASSET_MESH_LOADING_STATE_DONE
 } assetmeshloadingstate_t;
 typedef struct {
  assetfile_t file;
  assetmeshloadingstate_t state;
  uint32_t triangleCount;
 } assetmeshloaderloading_t;
 typedef struct {
  mesh_t mesh;
  meshvertex_t *vertices;
 } assetmeshoutput_t;
 #pragma pack(push, 1)
 typedef struct {
  vec3 normal;
  float_t positions[3][3];
  uint16_t attributeByteCount;
 } assetmeshstltriangle_t;
 #pragma pack(pop)
 assertStructSize(assetmeshstltriangle_t, 50);
 errorret_t assetMeshLoaderAsync(assetloading_t *loading);
 errorret_t assetMeshLoaderSync(assetloading_t *loading);
 errorret_t assetMeshDispose(assetentry_t *entry);
@@ -0,0 +1,10 @@
 # Copyright (c) 2026 Dominic Masters
 #
 # This software is released under the MIT License.
 # https://opensource.org/licenses/MIT
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    assetmeshloader.c
    assetmodelloader.c
 )
@@ -0,0 +1,157 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "assetmeshloader.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "util/endian.h"
 #include "asset/loader/assetloading.h"
 #include "asset/loader/assetentry.h"
 errorret_t assetMeshLoaderAsync(assetloading_t *loading) {
  assertNotNull(loading, "Loading cannot be NULL");
  assertNotMainThread("Should be called from an async thread.");
  if(loading->loading.mesh.state != ASSET_MESH_LOADING_STATE_READ_FILE) {
    errorOk();
  }
  assertNull(loading->loading.mesh.data, "Data already defined?");
  assetfile_t *file = &loading->loading.mesh.file;
  assetLoaderErrorChain(loading,
    assetFileInit(file, loading->entry->name, NULL, NULL)
  );
  uint8_t *raw = memoryAllocate(file->size);
  assetLoaderErrorChain(loading, assetFileOpen(file));
  assetLoaderErrorChain(loading, assetFileRead(file, raw, file->size));
  assetLoaderErrorChain(loading, assetFileClose(file));
  assetLoaderErrorChain(loading, assetFileDispose(file));
  assertTrue(file->lastRead == file->size, "Failed to read entire DMF file.");
  if(raw[0] != 'D' || raw[1] != 'M' || raw[2] != 'F') {
    memoryFree(raw);
    assetLoaderErrorThrow(loading, "Invalid DMF file header");
  }
  uint32_t version = endianLittleToHost32(*(uint32_t *)(raw + 4));
  if(version != ASSET_MESH_FILE_VERSION) {
    memoryFree(raw);
    assetLoaderErrorThrow(loading, "Unsupported DMF version %u", version);
  }
  uint32_t vertCount = endianLittleToHost32(*(uint32_t *)(raw + 8));
  meshvertex_t *vertices = NULL;
  if(vertCount > 0) {
    // 32-byte (cache-line) aligned: GX_SetArray + DCFlushRange on Dolphin
    // require this for the DMA'd vertex data to actually reach the GPU
    // coherently. Static compiled-in vertex arrays happen to get this from
    // the linker; a plain memoryAllocate here would not.
    vertices = memoryAlign(32, vertCount * sizeof(meshvertex_t));
    memoryCopy(vertices, raw + 12, vertCount * sizeof(meshvertex_t));
    for(uint32_t v = 0; v < vertCount; v++) {
      vertices[v].uv[0] = endianLittleToHostFloat(vertices[v].uv[0]);
      vertices[v].uv[1] = endianLittleToHostFloat(vertices[v].uv[1]);
      vertices[v].pos[0] = endianLittleToHostFloat(vertices[v].pos[0]);
      vertices[v].pos[1] = endianLittleToHostFloat(vertices[v].pos[1]);
      vertices[v].pos[2] = endianLittleToHostFloat(vertices[v].pos[2]);
    }
  }
  memoryFree(raw);
  loading->loading.mesh.vertCount = vertCount;
  loading->loading.mesh.data = (uint8_t *)vertices;
  loading->loading.mesh.state = ASSET_MESH_LOADING_STATE_CREATE_MESH;
  loading->entry->state = ASSET_ENTRY_STATE_PENDING_SYNC;
  errorOk();
 }
 errorret_t assetMeshLoaderSync(assetloading_t *loading) {
  assertNotNull(loading, "Loading cannot be NULL");
  assertTrue(loading->type == ASSET_LOADER_TYPE_MESH, "Invalid type.");
  assertIsMainThread("Must be called from the main thread.");
  switch(loading->loading.mesh.state) {
    case ASSET_MESH_LOADING_STATE_INITIAL:
      loading->loading.mesh.state = ASSET_MESH_LOADING_STATE_READ_FILE;
      loading->entry->state = ASSET_ENTRY_STATE_PENDING_ASYNC;
      errorOk();
      break;
    case ASSET_MESH_LOADING_STATE_CREATE_MESH:
      break;
    default:
      errorOk();
  }
  uint32_t vertCount = loading->loading.mesh.vertCount;
  meshvertex_t *vertices = (meshvertex_t *)loading->loading.mesh.data;
  loading->loading.mesh.data = NULL;
  assetmeshoutput_t *out = &loading->entry->data.mesh;
  out->vertices = vertices;
  if(vertCount == 0) {
    loading->entry->state = ASSET_ENTRY_STATE_LOADED;
    errorOk();
  }
  errorret_t ret = meshInit(
    &out->mesh,
    MESH_PRIMITIVE_TYPE_TRIANGLES,
    (int32_t)vertCount,
    out->vertices
  );
  if(errorIsNotOk(ret)) {
    loading->entry->state = ASSET_ENTRY_STATE_ERROR;
    memoryFree(out->vertices);
    out->vertices = NULL;
    errorChain(ret);
  }
  out->meshInitialized = true;
  ret = meshFlush(&out->mesh, 0, (int32_t)vertCount);
  if(errorIsNotOk(ret)) {
    loading->entry->state = ASSET_ENTRY_STATE_ERROR;
    meshDispose(&out->mesh);
    out->meshInitialized = false;
    memoryFree(out->vertices);
    out->vertices = NULL;
    errorChain(ret);
  }
  #if defined(DUSK_OPENGL) && !defined(DUSK_OPENGL_LEGACY)
    // VBO owns the data now; CPU copy is no longer needed. The platform
    // mesh object itself still needs meshDispose later - tracked via
    // out->meshInitialized, independent of the CPU buffer's lifetime.
    memoryFree(out->vertices);
    out->vertices = NULL;
  #endif
  loading->entry->state = ASSET_ENTRY_STATE_LOADED;
  errorOk();
 }
 errorret_t assetMeshDispose(assetentry_t *entry) {
  assertNotNull(entry, "Entry cannot be NULL");
  assertTrue(entry->type == ASSET_LOADER_TYPE_MESH, "Invalid type.");
  assertIsMainThread("Must be called from the main thread.");
  assetmeshoutput_t *out = &entry->data.mesh;
  if(out->meshInitialized) {
    errorChain(meshDispose(&out->mesh));
    out->meshInitialized = false;
  }
  if(out->vertices != NULL) {
    memoryFree(out->vertices);
    out->vertices = NULL;
  }
  errorOk();
 }
@@ -0,0 +1,63 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "asset/assetfile.h"
 #include "display/mesh/mesh.h"
 #define ASSET_MESH_FILE_VERSION 1
 typedef struct assetloading_s assetloading_t;
 typedef struct assetentry_s assetentry_t;
 typedef enum {
  ASSET_MESH_LOADING_STATE_INITIAL,
  ASSET_MESH_LOADING_STATE_READ_FILE,
  ASSET_MESH_LOADING_STATE_CREATE_MESH,
  ASSET_MESH_LOADING_STATE_DONE
 } assetmeshloadingstate_t;
 typedef struct {
  assetfile_t file;
  assetmeshloadingstate_t state;
  uint32_t vertCount;
  uint8_t *data;
 } assetmeshloaderloading_t;
 typedef struct {
  mesh_t mesh;
  bool_t meshInitialized;
  meshvertex_t *vertices;
 } assetmeshoutput_t;
 /**
 * Asynchronous loader for DMF mesh assets. Reads the file, validates the
 * header, and prepares a ready-to-use vertex buffer so the sync phase only
 * needs to upload to the GPU.
 *
 * @param loading Loading information for the asset being loaded.
 * @return Error code indicating success or failure.
 */
 errorret_t assetMeshLoaderAsync(assetloading_t *loading);
 /**
 * Synchronous loader for DMF mesh assets. Initializes the mesh from the
 * vertex buffer prepared by the async phase and flushes it to the GPU.
 *
 * @param loading Loading information for the asset being loaded.
 * @return Error code indicating success or failure.
 */
 errorret_t assetMeshLoaderSync(assetloading_t *loading);
 /**
 * Disposer for DMF mesh assets. Disposes the mesh and frees the vertex
 * buffer.
 *
 * @param entry Asset entry containing the mesh data to dispose.
 * @return Error code indicating success or failure.
 */
 errorret_t assetMeshDispose(assetentry_t *entry);
@@ -0,0 +1,172 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "assetmodelloader.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "util/string.h"
 #include "asset/asset.h"
 #include "asset/loader/assetloading.h"
 #include "asset/loader/assetentry.h"
 #include "asset/loader/json/assetjsonloader.h"
 #include "display/texture/texture.h"
 #include "yyjson.h"
 errorret_t assetModelLoaderAsync(assetloading_t *loading) {
  assertNotNull(loading, "Loading cannot be NULL");
  assertNotMainThread("Should be called from an async thread.");
  errorOk();
 }
 errorret_t assetModelLoaderSync(assetloading_t *loading) {
  assertNotNull(loading, "Loading cannot be NULL");
  assertTrue(loading->type == ASSET_LOADER_TYPE_MODEL, "Invalid type.");
  assertIsMainThread("Must be called from the main thread.");
  switch(loading->loading.model.state) {
    case ASSET_MODEL_LOADING_STATE_INITIAL:
      loading->loading.model.state = ASSET_MODEL_LOADING_STATE_LOCK_ASSETS;
      loading->entry->state = ASSET_ENTRY_STATE_PENDING_SYNC;
      errorOk();
      break;
    case ASSET_MODEL_LOADING_STATE_LOCK_ASSETS: {
      // Lock the model's JSON descriptor as a JSON sub-asset. The entry
      // key is prefixed with "json:" to avoid a type-collision with the
      // model entry itself (both share the same filename). The JSON loader
      // reads the real file path supplied in the input.
      char_t jsonKey[ASSET_FILE_NAME_MAX];
      stringFormat(
        jsonKey, sizeof(jsonKey), "json:%s", loading->entry->name
      );
      assetloaderinput_t jsonInput;
      memoryZero(&jsonInput, sizeof(jsonInput));
      stringCopy(
        jsonInput.json.path, loading->entry->name, ASSET_FILE_NAME_MAX
      );
      assetentry_t *jsonEntry = assetLock(
        jsonKey, ASSET_LOADER_TYPE_JSON, &jsonInput
      );
      errorret_t ret = assetRequireLoaded(jsonEntry);
      if(errorIsNotOk(ret)) {
        assetUnlockEntry(jsonEntry);
        loading->entry->state = ASSET_ENTRY_STATE_ERROR;
        errorChain(ret);
      }
      yyjson_val *root = yyjson_doc_get_root(jsonEntry->data.json);
      // Parse required mesh path.
      yyjson_val *meshVal = yyjson_obj_get(root, "mesh");
      if(!meshVal || !yyjson_is_str(meshVal)) {
        assetUnlockEntry(jsonEntry);
        loading->entry->state = ASSET_ENTRY_STATE_ERROR;
        errorThrow("Model JSON missing 'mesh' string");
      }
      const char *meshStr = yyjson_get_str(meshVal);
      size_t meshLen = yyjson_get_len(meshVal);
      if(meshLen >= ASSET_FILE_NAME_MAX) {
        assetUnlockEntry(jsonEntry);
        loading->entry->state = ASSET_ENTRY_STATE_ERROR;
        errorThrow("Model mesh path exceeds max length");
      }
      char_t meshName[ASSET_FILE_NAME_MAX];
      memoryCopy(meshName, meshStr, meshLen + 1);
      // Parse optional texture path (absent = color only, no texture).
      char_t textureName[ASSET_FILE_NAME_MAX];
      textureName[0] = '\0';
      yyjson_val *texVal = yyjson_obj_get(root, "texture");
      if(texVal && yyjson_is_str(texVal)) {
        const char *texStr = yyjson_get_str(texVal);
        size_t texLen = yyjson_get_len(texVal);
        if(texLen >= ASSET_FILE_NAME_MAX) {
          assetUnlockEntry(jsonEntry);
          loading->entry->state = ASSET_ENTRY_STATE_ERROR;
          errorThrow("Model texture path exceeds max length");
        }
        memoryCopy(textureName, texStr, texLen + 1);
      }
      // Parse optional color (RGBA array 0-255, default white).
      color_t color = COLOR_WHITE;
      yyjson_val *colorVal = yyjson_obj_get(root, "color");
      if(colorVal && yyjson_is_arr(colorVal)) {
        uint8_t ch[4] = {255, 255, 255, 255};
        size_t colorIdx, colorLen;
        yyjson_val *colorElem;
        yyjson_arr_foreach(colorVal, colorIdx, colorLen, colorElem) {
          if(colorIdx >= 4) break;
          if(yyjson_is_int(colorElem)) {
            ch[colorIdx] = (uint8_t)yyjson_get_int(colorElem);
          }
        }
        color.r = ch[0];
        color.g = ch[1];
        color.b = ch[2];
        color.a = ch[3];
      }
      // Release JSON entry; all needed fields are now in local variables.
      assetUnlockEntry(jsonEntry);
      // Lock and load the mesh sub-asset.
      assetentry_t *meshEntry =
        assetLock(meshName, ASSET_LOADER_TYPE_MESH, NULL);
      ret = assetRequireLoaded(meshEntry);
      if(errorIsNotOk(ret)) {
        assetUnlockEntry(meshEntry);
        loading->entry->state = ASSET_ENTRY_STATE_ERROR;
        errorChain(ret);
      }
      // Lock and load the optional texture sub-asset.
      assetentry_t *texEntry = NULL;
      if(textureName[0] != '\0') {
        assetloaderinput_t texInput = { .texture = TEXTURE_FORMAT_RGBA };
        texEntry = assetLock(textureName, ASSET_LOADER_TYPE_TEXTURE, &texInput);
        ret = assetRequireLoaded(texEntry);
        if(errorIsNotOk(ret)) {
          assetUnlockEntry(texEntry);
          assetUnlockEntry(meshEntry);
          loading->entry->state = ASSET_ENTRY_STATE_ERROR;
          errorChain(ret);
        }
      }
      assetmodeloutput_t *out = &loading->entry->data.model;
      out->meshEntry = meshEntry;
      out->texEntry = texEntry;
      out->color = color;
      loading->entry->state = ASSET_ENTRY_STATE_LOADED;
      errorOk();
      break;
    }
    default:
      errorOk();
  }
  errorOk();
 }
 errorret_t assetModelDispose(assetentry_t *entry) {
  assertNotNull(entry, "Entry cannot be NULL");
  assertTrue(entry->type == ASSET_LOADER_TYPE_MODEL, "Invalid type.");
  assertIsMainThread("Must be called from the main thread.");
  assetmodeloutput_t *out = &entry->data.model;
  if(out->meshEntry != NULL) {
    assetUnlockEntry(out->meshEntry);
    out->meshEntry = NULL;
  }
  if(out->texEntry != NULL) {
    assetUnlockEntry(out->texEntry);
    out->texEntry = NULL;
  }
  errorOk();
 }
@@ -0,0 +1,58 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "display/color.h"
 typedef struct assetloading_s assetloading_t;
 typedef struct assetentry_s assetentry_t;
 typedef enum {
  ASSET_MODEL_LOADING_STATE_INITIAL,
  ASSET_MODEL_LOADING_STATE_LOCK_ASSETS
 } assetmodelloadingstate_t;
 typedef struct {
  assetmodelloadingstate_t state;
 } assetmodelloaderloading_t;
 typedef struct {
  assetentry_t *meshEntry;
  assetentry_t *texEntry;
  color_t color;
 } assetmodeloutput_t;
 /**
 * Async loader stub for model assets. Model loading is performed entirely
 * on the main thread; this callback is never reached.
 *
 * @param loading Loading information for the asset being loaded.
 * @returns Always success.
 */
 errorret_t assetModelLoaderAsync(assetloading_t *loading);
 /**
 * Synchronous loader for model assets. Locks the JSON descriptor file as
 * a sub-asset, waits for it to load, parses the mesh path, optional
 * texture path, and color tint, then releases the JSON entry. Locks and
 * waits for mesh and optional texture sub-assets sequentially to stay
 * within ASSET_LOADING_COUNT_MAX slot limits.
 *
 * @param loading Loading information for the asset being loaded.
 * @returns Error code indicating success or failure.
 */
 errorret_t assetModelLoaderSync(assetloading_t *loading);
 /**
 * Disposer for model assets. Releases the locks on the mesh and texture
 * sub-asset entries.
 *
 * @param entry Asset entry containing the model to dispose.
 * @returns Error code indicating success or failure.
 */
 errorret_t assetModelDispose(assetentry_t *entry);
@@ -22,9 +22,11 @@ errorret_t assetJsonLoaderAsync(assetloading_t *loading) {
  assertNull(loading->loading.json.buffer, "Buffer already defined?");
  assetfile_t *file = &loading->loading.json.file;
-  assetLoaderErrorChain(loading,
+  const char_t *filePath = (
-    assetFileInit(file, loading->entry->name, NULL, NULL)
+    loading->entry->input != NULL &&
-  );
+    loading->entry->input->json.path[0] != '\0'
  ) ? loading->entry->input->json.path : loading->entry->name;
  assetLoaderErrorChain(loading, assetFileInit(file, filePath, NULL, NULL));
  if(file->size > ASSET_JSON_FILE_SIZE_MAX) {
    assetLoaderErrorThrow(loading, "JSON exceeds maximum allowed size");
@@ -14,7 +14,16 @@
 typedef struct assetloading_s assetloading_t;
 typedef struct assetentry_s assetentry_t;
-typedef struct { void *nothing; } assetjsonloaderinput_t;
+/**
 * Optional file path override. When path[0] is non-zero the JSON loader
 * reads this path from the archive instead of loading->entry->name. Use
 * this to decouple the asset pool key from the actual file location (e.g.
 * when a parent loader locks a JSON entry under a synthetic key to avoid
 * a type-collision with an entry of the same name but different type).
 */
 typedef struct {
  char_t path[ASSET_FILE_NAME_MAX];
 } assetjsonloaderinput_t;
 typedef enum {
  ASSET_JSON_LOADING_STATE_INITIAL,
@@ -30,8 +30,8 @@ errorret_t assetLocaleLoaderAsync(assetloading_t *loading) {
  assetLoaderErrorChain(loading, assetFileOpen(&localeFile->file));
  char_t buffer[1024];
-  assetLoaderErrorChain(loading, assetLocaleGetString(
+  assetLoaderErrorChain(loading, assetLocaleGetHeader(
-    localeFile, "", 0, buffer, sizeof(buffer)
+    localeFile, buffer, sizeof(buffer)
  ));
  assetLoaderErrorChain(loading, assetLocaleParseHeader(
    localeFile, buffer, sizeof(buffer)
@@ -71,6 +71,12 @@ errorret_t assetLocaleDispose(assetentry_t *entry) {
  assertIsMainThread("Must be called from the main thread.");
  assetlocalefile_t *localeFile = &entry->data.locale;
  if(localeFile->cache != NULL) {
    memoryFree(localeFile->cache);
    localeFile->cache = NULL;
  }
  errorChain(assetFileClose(&localeFile->file));
  return assetFileDispose(&localeFile->file);
 }
@@ -470,7 +476,94 @@ errorret_t assetLocaleLineUnbuffer(
  errorOk();
 }
-errorret_t assetLocaleGetString(
+errorret_t assetLocaleCacheFind(
  assetlocalefile_t *file,
  const char_t *messageId,
  const int32_t pluralCount,
  char_t *stringBuffer,
  const size_t stringBufferSize,
  bool_t *outHit
 ) {
  assertNotNull(file, "Asset file cannot be NULL.");
  assertNotNull(messageId, "Message ID cannot be NULL.");
  assertNotNull(outHit, "outHit cannot be NULL.");
  assertStrLenMin(messageId, 1, "Message ID cannot be empty.");
  *outHit = false;
  if(file->cache == NULL) errorOk();
  assetlocalecache_t *cache = file->cache;
  for(uint8_t i = 0; i < ASSET_LOCALE_CACHE_COUNT; i++) {
    assetlocalecacheentry_t *entry = &cache->entries[i];
    if(entry->messageId[0] == '\0') break;// unused tail - nothing further
    if(entry->pluralCount != pluralCount) continue;
    if(!stringEquals(entry->messageId, messageId)) continue;
    // Move to the front of the LRU order (a no-op when already there).
    if(i > 0) {
      assetlocalecacheentry_t hit = *entry;
      memoryMove(
        &cache->entries[1], &cache->entries[0],
        i * sizeof(assetlocalecacheentry_t)
      );
      cache->entries[0] = hit;
    }
    size_t len = strlen(cache->entries[0].value);
    if(len >= stringBufferSize) errorThrow("String buffer overflow");
    memoryCopy(stringBuffer, cache->entries[0].value, len + 1);
    *outHit = true;
    errorOk();
  }
  errorOk();
 }
 void assetLocaleCacheInsert(
  assetlocalefile_t *file,
  const char_t *messageId,
  const int32_t pluralCount,
  const char_t *value
 ) {
  assertNotNull(file, "Asset file cannot be NULL.");
  assertNotNull(messageId, "Message ID cannot be NULL.");
  assertNotNull(value, "Value cannot be NULL.");
  assertStrLenMin(messageId, 1, "Message ID cannot be empty.");
  // Caching is a pure optimization - a message ID or value too long for a
  // fixed cache slot is just never cached, not an error.
  if(strlen(messageId) >= ASSET_LOCALE_CACHE_KEY_MAX) return;
  if(strlen(value) >= ASSET_LOCALE_CACHE_VALUE_MAX) return;
  if(file->cache == NULL) {
    file->cache =
      (assetlocalecache_t *)memoryAllocate(sizeof(assetlocalecache_t));
    memoryZero(file->cache, sizeof(assetlocalecache_t));
  }
  // Shift every entry down one slot, dropping the least-recently-used one
  // off the end, to make room for the new entry at the front. This assumes
  // messageId is never already present elsewhere in the cache, which holds
  // as long as callers only insert after a confirmed assetLocaleCacheFind
  // miss (a hit would have returned before reaching this point).
  memoryMove(
    &file->cache->entries[1], &file->cache->entries[0],
    (ASSET_LOCALE_CACHE_COUNT - 1) * sizeof(assetlocalecacheentry_t)
  );
  assetlocalecacheentry_t *entry = &file->cache->entries[0];
  stringCopy(entry->messageId, messageId, ASSET_LOCALE_CACHE_KEY_MAX);
  entry->pluralCount = pluralCount;
  stringCopy(entry->value, value, ASSET_LOCALE_CACHE_VALUE_MAX);
 }
 // Shared by assetLocaleGetString (external callers, messageId required
 // non-empty) and assetLocaleGetHeader (messageId "", the PO format's own
 // sentinel for its header entry - see assetLocaleGetHeader). Caching is
 // skipped entirely for an empty messageId: assetLocaleCacheFind/Insert
 // both reject one outright (same guard as assetLocaleGetString's own),
 // and it's a one-shot boot-time read anyway, not worth caching.
 errorret_t assetLocaleGetStringLookup(
  assetlocalefile_t *file,
  const char_t *messageId,
  const int32_t pluralCount,
@@ -482,6 +575,15 @@ errorret_t assetLocaleGetString(
  assertTrue(pluralCount >= 0, "Plural index cannot be negative.");
  assertNotNull(stringBuffer, "String buffer cannot be NULL.");
  assertTrue(stringBufferSize > 0, "String buffer size must be > 0");
  bool_t cacheHit = false;
  if(messageId[0] != '\0') {
    errorChain(assetLocaleCacheFind(
      file, messageId, pluralCount, stringBuffer, stringBufferSize, &cacheHit
    ));
    if(cacheHit) errorOk();
  }
  assetfilelinereader_t reader;
  bool_t msgidFound = false, msgidPluralFound = false, msgstrFound = false;
@@ -506,12 +608,17 @@ errorret_t assetLocaleGetString(
    sizeof(lineBuffer)
  );
  // Prime the reader with the first line before scanning; outBuffer holds
  // uninitialized memory until the first Next() call fills it.
  errorChain(assetFileLineReaderNext(&reader));
  // Skip blanks, comments, etc and start looking for msgid's
  errorChain(assetLocaleLineSkipBlanks(&reader, lineBuffer));
-  while(!reader.eof) {
+  while(true) {
    // Is this msgid?
    if(memoryCompare(lineBuffer, "msgid", 5) != 0) {
      if(reader.eof) break;
      errorChain(assetFileLineReaderNext(&reader));
      msgidBuffer[0] = '\0';
      continue;
@@ -535,7 +642,7 @@ errorret_t assetLocaleGetString(
  }
  // We are either going to see a msgstr or a msgid_plural
-  while(!reader.eof) {
+  while(true) {
    errorChain(assetLocaleLineSkipBlanks(&reader, lineBuffer));
    // Is msgid_plural?
@@ -620,9 +727,38 @@ errorret_t assetLocaleGetString(
    errorThrow("Failed to find msgstr for message ID: %s", messageId);
  }
  if(messageId[0] != '\0') {
    assetLocaleCacheInsert(file, messageId, pluralCount, stringBuffer);
  }
  errorOk();
 }
 errorret_t assetLocaleGetString(
  assetlocalefile_t *file,
  const char_t *messageId,
  const int32_t pluralCount,
  char_t *stringBuffer,
  const size_t stringBufferSize
 ) {
  assertNotNull(messageId, "Message ID cannot be NULL.");
  assertStrLenMin(messageId, 1, "Message ID cannot be empty.");
  return assetLocaleGetStringLookup(
    file, messageId, pluralCount, stringBuffer, stringBufferSize
  );
 }
 errorret_t assetLocaleGetHeader(
  assetlocalefile_t *file,
  char_t *stringBuffer,
  const size_t stringBufferSize
 ) {
  return assetLocaleGetStringLookup(
    file, "", 0, stringBuffer, stringBufferSize
  );
 }
 errorret_t assetLocaleGetStringWithVA(
  assetlocalefile_t *file,
  const char_t *messageId,
@@ -70,6 +70,41 @@ typedef struct {
  };
 } assetlocalearg_t;
 /** Number of recently resolved strings @ref assetlocalecache_t remembers. */
 #define ASSET_LOCALE_CACHE_COUNT 128
 /** Max length (excluding null terminator) of a cacheable message ID. */
 #define ASSET_LOCALE_CACHE_KEY_MAX 64
 /** Max length (excluding null terminator) of a cacheable resolved string. */
 #define ASSET_LOCALE_CACHE_VALUE_MAX 256
 /** One (messageId, pluralCount) -> resolved string cache slot. */
 typedef struct {
  char_t messageId[ASSET_LOCALE_CACHE_KEY_MAX];
  int32_t pluralCount;
  char_t value[ASSET_LOCALE_CACHE_VALUE_MAX];
 } assetlocalecacheentry_t;
 /**
 * Fixed-size move-to-front LRU cache of recently resolved locale strings.
 * assetLocaleGetString() re-scans and re-decompresses the whole PO file on
 * every miss, which is expensive to repeat for strings a screen fetches
 * every time it opens (menu labels, etc) - this cache lets identical
 * (messageId, pluralCount) lookups skip that entirely.
 *
 * Lazily allocated on the first cache insert (see assetlocalefile_t.cache)
 * so locale entries that are never queried, or a file that's disposed
 * before anything is cached, never pay for it.
 */
 typedef struct {
  /**
   * Entries ordered most-recently-used first. An entry with
   * messageId[0] == '\0' (and every entry after it) is unused.
   */
  assetlocalecacheentry_t entries[ASSET_LOCALE_CACHE_COUNT];
 } assetlocalecache_t;
 /**
 * Runtime state for an open locale file.
 *
@@ -98,6 +133,16 @@ typedef struct {
  /** Form index used when no conditional clause matches. */
  uint8_t pluralDefaultIndex;
  /**
   * Recently resolved string cache, or NULL if nothing has been cached yet.
   * Heap-allocated rather than embedded because assetlocalefile_t lives
   * inside the shared assetloaderoutput_t union alongside every other
   * asset type - embedding a 128-entry cache there would size that union
   * (and therefore every one of the ASSET_ENTRY_COUNT_MAX asset slots,
   * regardless of what type of asset occupies it) up by the same amount.
   */
  assetlocalecache_t *cache;
 } assetlocalefile_t;
 /** Convenience alias - the loaded output type of a locale asset entry. */
@@ -204,14 +249,92 @@ errorret_t assetLocaleLineUnbuffer(
 );
 /**
- * Looks up a translated string by message ID from the open locale file.
+ * Searches a locale file's cache for a previously resolved
 * (messageId, pluralCount) pair.
 *
- * Rewinds the file and scans from the beginning on every call. For plural
+ * On a hit, copies the cached value into `stringBuffer` (erroring if it
- * entries (`msgid_plural`) the `pluralCount` is evaluated against the loaded
+ * doesn't fit, same contract as @ref assetLocaleGetString) and moves the
- * plural rules to select the correct `msgstr[N]` form.
+ * entry to the front of the cache's move-to-front LRU order. On a miss,
 * `stringBuffer` is left untouched.
 *
 * @param file  Locale file whose cache to search. Its cache may be NULL
 *              (nothing cached yet), which is treated as a miss.
 * @param messageId  Message ID to look up.
 * @param pluralCount  Plural count the original lookup used.
 * @param stringBuffer  Destination buffer, filled only on a hit.
 * @param stringBufferSize  Capacity of `stringBuffer` in bytes.
 * @param outHit  Set to true on a cache hit, false on a miss.
 * @return OK on success (hit or miss), error if a hit's cached value does
 *         not fit `stringBuffer`.
 */
 errorret_t assetLocaleCacheFind(
  assetlocalefile_t *file,
  const char_t *messageId,
  const int32_t pluralCount,
  char_t *stringBuffer,
  const size_t stringBufferSize,
  bool_t *outHit
 );
 /**
 * Records a resolved (messageId, pluralCount) -> value string at the front
 * of the cache's move-to-front LRU order, evicting the least-recently-used
 * entry if the cache is already full. Lazily allocates the cache (see
 * assetlocalefile_t.cache) on the first call.
 *
 * Caching is a pure optimization: if `messageId` or `value` is too long to
 * fit the cache's fixed-size slots, this silently does nothing rather than
 * erroring or growing the cache.
 *
 * @param file  Locale file whose cache to insert into.
 * @param messageId  Message ID that was looked up.
 * @param pluralCount  Plural count the lookup was made with.
 * @param value  Resolved string to cache.
 */
 void assetLocaleCacheInsert(
  assetlocalefile_t *file,
  const char_t *messageId,
  const int32_t pluralCount,
  const char_t *value
 );
 /**
 * Shared lookup core behind assetLocaleGetString and assetLocaleGetHeader:
 * checks the file's cache first (see @ref assetLocaleCacheFind; skipped
 * entirely for an empty messageId, since the cache rejects one), on a
 * miss rewinds the file and scans from the beginning, then caches the
 * result (see @ref assetLocaleCacheInsert, same empty-messageId skip)
 * before returning. For plural entries (`msgid_plural`) the
 * `pluralCount` is evaluated against the loaded plural rules to select
 * the correct `msgstr[N]` form.
 *
 * Unlike assetLocaleGetString, messageId may be `""` here (see
 * assetLocaleGetHeader) - this is the shared implementation both of
 * them delegate to, not a public entry point of its own in practice.
 *
 * @param file  Locale file to search. Must be open.
- * @param messageId  PO message ID to find (`""` retrieves the header entry).
+ * @param messageId  PO message ID to find, or `""` for the header entry.
 * @param pluralCount  Count used to select the plural form (ignored for
 *                     singular entries).
 * @param stringBuffer  Buffer to receive the translated string.
 * @param stringBufferSize  Capacity of `stringBuffer` in bytes.
 * @return OK on success, error if the message ID is not found or I/O fails.
 */
 errorret_t assetLocaleGetStringLookup(
  assetlocalefile_t *file,
  const char_t *messageId,
  const int32_t pluralCount,
  char_t *stringBuffer,
  const size_t stringBufferSize
 );
 /**
 * Looks up a translated string by message ID from the open locale file.
 * See @ref assetLocaleGetStringLookup for the lookup/caching mechanics.
 *
 * @param file  Locale file to search. Must be open.
 * @param messageId  PO message ID to find. Must be non-empty - use
 *                    @ref assetLocaleGetHeader to read the header entry.
 * @param pluralCount  Count used to select the plural form (ignored for
 *                     singular entries).
 * @param stringBuffer  Buffer to receive the translated string.
@@ -226,6 +349,27 @@ errorret_t assetLocaleGetString(
  const size_t stringBufferSize
 );
 /**
 * Reads the PO file's header entry (the `msgid ""` block every PO file
 * starts with, holding metadata like the plural-forms rule) - see @ref
 * assetLocaleParseHeader, its caller. A dedicated function rather than
 * calling assetLocaleGetString(file, "", ...) since messageId "" is a
 * PO-format-internal sentinel, not a real (untrusted) caller-supplied
 * message ID, so it doesn't go through assetLocaleGetString's normal
 * non-empty validation.
 *
 * @param file  Locale file to search. Must be open.
 * @param stringBuffer  Buffer to receive the raw header block.
 * @param stringBufferSize  Capacity of `stringBuffer` in bytes.
 * @return OK on success, error if the header entry is missing or I/O
 * fails.
 */
 errorret_t assetLocaleGetHeader(
  assetlocalefile_t *file,
  char_t *stringBuffer,
  const size_t stringBufferSize
 );
 /**
 * Looks up a translated string and formats it with a `printf`-style variadic
 * argument list.
@@ -5,5 +5,5 @@
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
-    entityinteract.c
+    assetmp3loader.c
 )
@@ -0,0 +1,255 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "assetmp3loader.h"
 #include "util/memory.h"
 #include "util/math.h"
 #include "assert/assert.h"
 #include "asset/loader/assetloading.h"
 #include "asset/loader/assetentry.h"
 // How far into the file (after any ID3v2 tag) assetMp3ParseHeader() will
 // search for the first valid MPEG frame sync. Real encoders write it
 // within the first handful of bytes; this is a generous sane upper bound
 // (matching assetwavloader.c's own approach to bounding a stack buffer)
 // rather than a real expectation of needing that much.
 #define ASSET_MP3_HEADER_SEARCH_MAX 8192
 // MPEG-1 Layer III bitrates (kbps), indexed by the header's 4-bit bitrate
 // index. Index 0 ("free format") and 15 (reserved) aren't supported.
 static const uint16_t ASSET_MP3_BITRATE_MPEG1_L3[16] = {
  0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 0
 };
 // MPEG-2/2.5 Layer III bitrates (kbps) - a different table from MPEG-1's.
 static const uint16_t ASSET_MP3_BITRATE_MPEG2_L3[16] = {
  0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160, 0
 };
 static const uint32_t ASSET_MP3_SAMPLE_RATE_MPEG1[4] = {
  44100, 48000, 32000, 0
 };
 static const uint32_t ASSET_MP3_SAMPLE_RATE_MPEG2[4] = {
  22050, 24000, 16000, 0
 };
 static const uint32_t ASSET_MP3_SAMPLE_RATE_MPEG25[4] = {
  11025, 12000, 8000, 0
 };
 errorret_t assetMp3LoaderAsync(assetloading_t *loading) {
  assertNotNull(loading, "Loading cannot be NULL");
  assertNotMainThread("Async loader should not be on main thread.");
  if(loading->loading.mp3.state != ASSET_MP3_LOADER_STATE_READ_HEADER) {
    errorOk();
  }
  assetmp3file_t *mp3File = &loading->entry->data.mp3;
  memoryZero(mp3File, sizeof(assetmp3file_t));
  assetfile_t file;
  assetLoaderErrorChain(loading, assetFileInit(
    &file, loading->entry->name, NULL, NULL
  ));
  assetLoaderErrorChain(loading, assetFileOpen(&file));
  assetLoaderErrorChain(loading, assetMp3ParseHeader(&file, mp3File));
  assetLoaderErrorChain(loading, assetFileClose(&file));
  assetLoaderErrorChain(loading, assetFileDispose(&file));
  loading->loading.mp3.state = ASSET_MP3_LOADER_STATE_DONE;
  loading->entry->state = ASSET_ENTRY_STATE_PENDING_SYNC;
  errorOk();
 }
 errorret_t assetMp3LoaderSync(assetloading_t *loading) {
  assertNotNull(loading, "Loading cannot be NULL");
  assertTrue(loading->type == ASSET_LOADER_TYPE_MP3, "Invalid type.");
  assertIsMainThread("Must be called from the main thread.");
  switch(loading->loading.mp3.state) {
    case ASSET_MP3_LOADER_STATE_INITIAL:
      loading->loading.mp3.state = ASSET_MP3_LOADER_STATE_READ_HEADER;
      loading->entry->state = ASSET_ENTRY_STATE_PENDING_ASYNC;
      errorOk();
      break;
    case ASSET_MP3_LOADER_STATE_DONE:
      break;
    default:
      errorOk();
  }
  loading->entry->state = ASSET_ENTRY_STATE_LOADED;
  errorOk();
 }
 errorret_t assetMp3Dispose(assetentry_t *entry) {
  assertNotNull(entry, "Asset entry cannot be NULL");
  assertTrue(entry->type == ASSET_LOADER_TYPE_MP3, "Invalid type.");
  assertIsMainThread("Must be called from the main thread.");
  errorOk();
 }
 errorret_t assetMp3ParseHeader(assetfile_t *file, assetmp3file_t *mp3File) {
  assertNotNull(file, "Asset file cannot be NULL.");
  assertNotNull(mp3File, "Mp3 file cannot be NULL.");
  memoryZero(mp3File, sizeof(assetmp3file_t));
  // Skip a leading ID3v2 tag if present: "ID3" + version(2) + flags(1) + a
  // 4-byte syncsafe (7 usable bits/byte) size covering everything after
  // this 10-byte header.
  uint8_t id3Header[10];
  errorChain(assetFileRead(file, id3Header, sizeof(id3Header)));
  size_t searchBase;
  if(memoryCompare(id3Header, "ID3", 3) == 0) {
    const uint32_t tagSize = (
      ((uint32_t) (id3Header[6] & 0x7F) << 21) |
      ((uint32_t) (id3Header[7] & 0x7F) << 14) |
      ((uint32_t) (id3Header[8] & 0x7F) << 7) |
      ((uint32_t) (id3Header[9] & 0x7F))
    );
    errorChain(assetFileRead(file, NULL, tagSize));
    searchBase = sizeof(id3Header) + tagSize;
  } else {
    // No ID3v2 tag - rewind the probe bytes just consumed so the frame
    // sync search below starts from the true beginning of the file.
    errorChain(assetFileRewind(file));
    searchBase = 0;
  }
  const size_t searchWindowSize = mathMin(
    (size_t) ASSET_MP3_HEADER_SEARCH_MAX,
    (size_t) file->size > searchBase ? (size_t) file->size - searchBase : 0
  );
  if(searchWindowSize < 4) {
    errorThrow(
      "MP3 file is too short to contain a frame header: %s", file->filename
    );
  }
  uint8_t *window = (uint8_t *) memoryAllocate(searchWindowSize);
  errorret_t readRet = assetFileRead(file, window, searchWindowSize);
  if(errorIsNotOk(readRet)) {
    memoryFree(window);
    errorChain(readRet);
  }
  bool_t found = false;
  size_t frameIndex = 0;
  for(size_t i = 0; i + 4 <= searchWindowSize; i++) {
    if(window[i] != 0xFF || (window[i + 1] & 0xE0) != 0xE0) continue;
    const uint8_t versionBits = (window[i + 1] >> 3) & 0x3;
    const uint8_t layerBits = (window[i + 1] >> 1) & 0x3;
    // reserved version, or not Layer III
    if(versionBits == 1 || layerBits != 1) continue;
    const uint8_t bitrateIndex = (window[i + 2] >> 4) & 0xF;
    const uint8_t sampleRateIndex = (window[i + 2] >> 2) & 0x3;
    if(
      bitrateIndex == 0 || bitrateIndex == 15 || sampleRateIndex == 3
    ) continue;
    const uint8_t channelMode = (window[i + 3] >> 6) & 0x3;
    const bool_t isMpeg1 = versionBits == 3;
    mp3File->bitrateKbps = isMpeg1
      ? ASSET_MP3_BITRATE_MPEG1_L3[bitrateIndex]
      : ASSET_MP3_BITRATE_MPEG2_L3[bitrateIndex];
    mp3File->sampleRate = isMpeg1
      ? ASSET_MP3_SAMPLE_RATE_MPEG1[sampleRateIndex]
      : (versionBits == 2
          ? ASSET_MP3_SAMPLE_RATE_MPEG2[sampleRateIndex]
          : ASSET_MP3_SAMPLE_RATE_MPEG25[sampleRateIndex]);
    mp3File->samplesPerFrame = isMpeg1 ? 1152 : 576;
    mp3File->channels = channelMode == 3 ? 1 : 2;
    // A Xing/Info header, if present, sits right after the side info -
    // whose size depends on MPEG version and channel mode - immediately
    // following the 4-byte header (plus a 2-byte CRC, if the protection
    // bit says one follows).
    const bool_t hasCrc = (window[i + 1] & 0x1) == 0;
    const size_t sideInfoSize = isMpeg1
      ? (mp3File->channels == 1 ? 17 : 32)
      : (mp3File->channels == 1 ? 9 : 17);
    const size_t xingOffset = i + 4 + (hasCrc ? 2 : 0) + sideInfoSize;
    if(
      xingOffset + 8 <= searchWindowSize &&
      (
        memoryCompare(window + xingOffset, "Xing", 4) == 0 ||
        memoryCompare(window + xingOffset, "Info", 4) == 0
      )
    ) {
      const uint8_t *flagsBytes = window + xingOffset + 4;
      const uint32_t flags = (
        ((uint32_t) flagsBytes[0] << 24) | ((uint32_t) flagsBytes[1] << 16) |
        ((uint32_t) flagsBytes[2] << 8) | (uint32_t) flagsBytes[3]
      );
      if((flags & 0x1) != 0 && xingOffset + 12 <= searchWindowSize) {
        const uint8_t *framesBytes = window + xingOffset + 8;
        const uint32_t xingFrameCount = (
          ((uint32_t) framesBytes[0] << 24) |
          ((uint32_t) framesBytes[1] << 16) |
          ((uint32_t) framesBytes[2] << 8) |
          (uint32_t) framesBytes[3]
        );
        // The Xing/Info header's frame count includes the header's own
        // frame (this one, at `i`) - which libmad (and sceMp3) will
        // attempt to decode like any other, but which doesn't contribute a
        // real decodable frame of audio the way every other one does.
        // Confirmed against a real LAME-encoded file: its Xing header
        // declared 40 frames, but decoding actually produced exactly 39
        // frames' worth of real PCM - without this -1, playback would
        // permanently stall one frame short of the declared total (audible
        // as "never loops"), since real decode output can never catch up
        // to an overstated total.
        if(xingFrameCount > 0) {
          mp3File->totalFrames =
            (size_t) (xingFrameCount - 1) * mp3File->samplesPerFrame;
        }
      }
    }
    frameIndex = i;
    found = true;
    break;
  }
  memoryFree(window);
  if(!found) {
    errorThrow(
      "MP3 file has no valid MPEG-1/2/2.5 Layer III frame within the first "
      "%u bytes: %s",
      (uint32_t) searchWindowSize, file->filename
    );
  }
  mp3File->dataOffset = searchBase + frameIndex;
  mp3File->dataSize = (size_t) file->size - mp3File->dataOffset;
  // No Xing/Info header found - estimate assuming constant bitrate (the
  // common case when one's genuinely absent; a real VBR file without one
  // is rare and will just get an approximate duration/loop point instead
  // of an exact one).
  if(mp3File->totalFrames == 0) {
    const float_t durationSeconds = (
      ((float_t) mp3File->dataSize * 8.0f) /
      ((float_t) mp3File->bitrateKbps * 1000.0f)
    );
    mp3File->totalFrames =
      (size_t) (durationSeconds * (float_t) mp3File->sampleRate);
  }
  errorOk();
 }
@@ -0,0 +1,113 @@
 /**
 * 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 "asset/assetfile.h"
 typedef struct assetloading_s assetloading_t;
 typedef struct assetentry_s assetentry_t;
 typedef struct { void *nothing; } assetmp3loaderinput_t;
 typedef enum {
  ASSET_MP3_LOADER_STATE_INITIAL,
  ASSET_MP3_LOADER_STATE_READ_HEADER,
  ASSET_MP3_LOADER_STATE_DONE
 } assetmp3loaderstate_t;
 typedef struct {
  assetmp3loaderstate_t state;
 } assetmp3loaderloading_t;
 /**
 * Parsed metadata for an MP3 asset - deliberately just enough to configure
 * a decoder and know the clip's total length, not anything about its
 * actual compressed content (which is read/decoded on demand at playback
 * time - see audiostreammp3.c). Only MPEG-1/2/2.5 Layer III ("MP3" in the
 * everyday sense) is supported; Layers I/II are rejected.
 */
 typedef struct {
  uint32_t sampleRate;
  uint8_t channels;
  // 1152 for MPEG-1, 576 for MPEG-2/2.5 - how many PCM samples (per
  // channel) one compressed MPEG frame decodes to.
  uint16_t samplesPerFrame;
  // The first frame's bitrate, in kbps. Used only as a fallback duration
  // estimate (assuming CBR) when no Xing/Info header is found - see
  // assetMp3ParseHeader()'s own comment.
  uint32_t bitrateKbps;
  // Byte offset (from the start of the file) of the first real MPEG
  // frame, i.e. right after any leading ID3v2 tag.
  size_t dataOffset;
  // Bytes of compressed MPEG data, from dataOffset to the end of the file.
  size_t dataSize;
  // Decoded PCM frame count for the whole clip - exact if a Xing/Info
  // header was found (the common case for anything encoded with a modern
  // tool), otherwise estimated from bitrateKbps/dataSize assuming CBR (see
  // assetMp3ParseHeader()'s own comment) - unlike assetwavfile_t.dataSize,
  // MP3 has no header field that gives this directly.
  size_t totalFrames;
 } assetmp3file_t;
 typedef assetmp3file_t assetmp3output_t;
 /**
 * Async (background-thread) half of the MP3 loader - opens the asset file,
 * parses its header (see assetMp3ParseHeader()), and closes it again. Never
 * buffers the compressed MPEG data itself; that's read on demand at
 * playback time by audiostreammp3.c via its own independent file handle.
 *
 * @param loading The asset loading slot.
 * @return Error indicating success or failure.
 */
 errorret_t assetMp3LoaderAsync(assetloading_t *loading);
 /**
 * Sync (main-thread) half of the MP3 loader - a simple state machine that
 * schedules the async header parse and marks the entry loaded once it's
 * done, mirroring assetWavLoaderSync()'s shape exactly.
 *
 * @param loading The asset loading slot.
 * @return Error indicating success or failure.
 */
 errorret_t assetMp3LoaderSync(assetloading_t *loading);
 /**
 * Disposes an MP3 asset entry. A no-op - an assetmp3file_t owns no heap
 * allocations, and playback streams open their own independent file
 * handles (see audiostreammp3.c).
 *
 * @param entry The asset entry to dispose.
 * @return Error indicating success or failure.
 */
 errorret_t assetMp3Dispose(assetentry_t *entry);
 /**
 * Parses an MP3 file's metadata from an already-opened asset file
 * positioned at its very start: skips a leading ID3v2 tag if present,
 * scans forward for the first valid MPEG-1/2/2.5 Layer III frame header
 * (rejecting anything else - other layers, or no valid frame found within
 * a sane search window), and checks that frame for a Xing/Info header
 * (found in the vast majority of real-world MP3s, VBR or CBR) to get an
 * exact total-frame count; falls back to a CBR estimate from the first
 * frame's bitrate and the file's remaining size if absent.
 *
 * Never reads more than a bounded lookahead window into memory - the bulk
 * of the file (the actual compressed audio, following the parsed frame's
 * position) is left untouched, exactly like assetWavParseHeader().
 *
 * @param file Asset file to parse, positioned at offset 0.
 * @param mp3File Filled with the parsed metadata on success.
 * @return Error indicating success or failure.
 */
 errorret_t assetMp3ParseHeader(assetfile_t *file, assetmp3file_t *mp3File);
@@ -6,5 +6,5 @@
 # Sources
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
-    assetchunkloader.c
+    assetwavloader.c
 )
@@ -0,0 +1,181 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "assetwavloader.h"
 #include "util/memory.h"
 #include "util/endian.h"
 #include "assert/assert.h"
 #include "asset/loader/assetloading.h"
 #include "asset/loader/assetentry.h"
 // "RIFF" + chunkSize + "WAVE", before any sub-chunks begin.
 #define ASSET_WAV_RIFF_HEADER_SIZE 12
 // A sub-chunk header is a 4-byte id followed by a 4-byte little-endian size.
 #define ASSET_WAV_CHUNK_HEADER_SIZE 8
 #define ASSET_WAV_FMT_CHUNK_SIZE_MIN 16
 // Sane upper bound for a stack buffer - real fmt chunks (PCM or otherwise)
 // never come close to this; anything bigger is treated as malformed.
 #define ASSET_WAV_FMT_CHUNK_SIZE_MAX 64
 errorret_t assetWavLoaderAsync(assetloading_t *loading) {
  assertNotNull(loading, "Loading cannot be NULL");
  assertNotMainThread("Async loader should not be on main thread.");
  if(loading->loading.wav.state != ASSET_WAV_LOADER_STATE_READ_HEADER) {
    errorOk();
  }
  assetwavfile_t *wavFile = &loading->entry->data.wav;
  memoryZero(wavFile, sizeof(assetwavfile_t));
  assetfile_t file;
  assetLoaderErrorChain(loading, assetFileInit(
    &file, loading->entry->name, NULL, NULL
  ));
  assetLoaderErrorChain(loading, assetFileOpen(&file));
  assetLoaderErrorChain(loading, assetWavParseHeader(&file, wavFile));
  assetLoaderErrorChain(loading, assetFileClose(&file));
  assetLoaderErrorChain(loading, assetFileDispose(&file));
  loading->loading.wav.state = ASSET_WAV_LOADER_STATE_DONE;
  loading->entry->state = ASSET_ENTRY_STATE_PENDING_SYNC;
  errorOk();
 }
 errorret_t assetWavLoaderSync(assetloading_t *loading) {
  assertNotNull(loading, "Loading cannot be NULL");
  assertTrue(loading->type == ASSET_LOADER_TYPE_WAV, "Invalid type.");
  assertIsMainThread("Must be called from the main thread.");
  switch(loading->loading.wav.state) {
    case ASSET_WAV_LOADER_STATE_INITIAL:
      loading->loading.wav.state = ASSET_WAV_LOADER_STATE_READ_HEADER;
      loading->entry->state = ASSET_ENTRY_STATE_PENDING_ASYNC;
      errorOk();
      break;
    case ASSET_WAV_LOADER_STATE_DONE:
      break;
    default:
      errorOk();
  }
  loading->entry->state = ASSET_ENTRY_STATE_LOADED;
  errorOk();
 }
 errorret_t assetWavDispose(assetentry_t *entry) {
  assertNotNull(entry, "Asset entry cannot be NULL");
  assertTrue(entry->type == ASSET_LOADER_TYPE_WAV, "Invalid type.");
  assertIsMainThread("Must be called from the main thread.");
  errorOk();
 }
 errorret_t assetWavParseHeader(
  assetfile_t *file,
  assetwavfile_t *wavFile
 ) {
  assertNotNull(file, "Asset file cannot be NULL.");
  assertNotNull(wavFile, "Wav file cannot be NULL.");
  uint8_t riffHeader[ASSET_WAV_RIFF_HEADER_SIZE];
  errorChain(assetFileRead(file, riffHeader, sizeof(riffHeader)));
  if(memoryCompare(riffHeader, "RIFF", 4) != 0) {
    errorThrow("WAV file has an invalid RIFF header: %s", file->filename);
  }
  if(memoryCompare(riffHeader + 8, "WAVE", 4) != 0) {
    errorThrow("WAV file has an invalid WAVE header: %s", file->filename);
  }
  bool_t foundFormat = false;
  bool_t foundData = false;
  uint16_t audioFormat = 0;
  // Walk the chunk list, reading only chunk headers (and the small "fmt "
  // body) - every other chunk, "data"'s sample bytes included, is skipped
  // via a NULL-buffer read rather than buffered into memory. Stops as soon
  // as "data" is found; nothing after it matters here.
  while(!foundData && (size_t) file->position < (size_t) file->size) {
    uint8_t chunkHeader[ASSET_WAV_CHUNK_HEADER_SIZE];
    errorChain(assetFileRead(file, chunkHeader, sizeof(chunkHeader)));
    uint32_t chunkSizeLE;
    memoryCopy(&chunkSizeLE, chunkHeader + 4, sizeof(chunkSizeLE));
    const uint32_t chunkSize = endianLittleToHost32(chunkSizeLE);
    // Chunks are padded to an even total size - the pad byte (if any)
    // isn't included in chunkSize but still needs to be skipped over.
    const uint32_t chunkSizePadded = chunkSize + (chunkSize % 2);
    if(memoryCompare(chunkHeader, "fmt ", 4) == 0) {
      if(
        chunkSize < ASSET_WAV_FMT_CHUNK_SIZE_MIN ||
        chunkSize > ASSET_WAV_FMT_CHUNK_SIZE_MAX
      ) {
        errorThrow("WAV 'fmt ' chunk has an unsupported size: %u", chunkSize);
      }
      uint8_t fmtBuffer[ASSET_WAV_FMT_CHUNK_SIZE_MAX];
      errorChain(assetFileRead(file, fmtBuffer, chunkSize));
      if(chunkSize % 2 != 0) {
        errorChain(assetFileRead(file, NULL, 1));
      }
      uint16_t u16;
      uint32_t u32;
      memoryCopy(&u16, fmtBuffer + 0, sizeof(u16));
      audioFormat = endianLittleToHost16(u16);
      memoryCopy(&u16, fmtBuffer + 2, sizeof(u16));
      wavFile->channels = (uint8_t) endianLittleToHost16(u16);
      memoryCopy(&u32, fmtBuffer + 4, sizeof(u32));
      wavFile->sampleRate = endianLittleToHost32(u32);
      memoryCopy(&u16, fmtBuffer + 14, sizeof(u16));
      wavFile->bitsPerSample = (uint8_t) endianLittleToHost16(u16);
      foundFormat = true;
    } else if(memoryCompare(chunkHeader, "data", 4) == 0) {
      wavFile->dataOffset = (size_t) file->position;
      wavFile->dataSize = chunkSize;
      foundData = true;
    } else {
      errorChain(assetFileRead(file, NULL, chunkSizePadded));
    }
  }
  if(!foundFormat) {
    errorThrow("WAV file is missing its 'fmt ' chunk: %s", file->filename);
  }
  if(!foundData) {
    errorThrow("WAV file is missing its 'data' chunk: %s", file->filename);
  }
  if(audioFormat != 1) {
    errorThrow(
      "Unsupported WAV audio format: %u (only PCM is supported): %s",
      audioFormat, file->filename
    );
  }
  if(wavFile->bitsPerSample != 16 && wavFile->bitsPerSample != 24) {
    errorThrow(
      "Unsupported WAV bits per sample: %u (only 16/24-bit is supported): %s",
      wavFile->bitsPerSample, file->filename
    );
  }
  if(wavFile->channels == 0) {
    errorThrow("WAV file declares 0 channels: %s", file->filename);
  }
  errorOk();
 }
@@ -0,0 +1,117 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "asset/assetfile.h"
 typedef struct assetloading_s assetloading_t;
 typedef struct assetentry_s assetentry_t;
 /** Input passed to the wav loader - currently unused. */
 typedef struct { void *nothing; } assetwavloaderinput_t;
 typedef enum {
  ASSET_WAV_LOADER_STATE_INITIAL,
  ASSET_WAV_LOADER_STATE_READ_HEADER,
  ASSET_WAV_LOADER_STATE_DONE
 } assetwavloaderstate_t;
 /** Per-slot scratch data used while the wav file is loading. */
 typedef struct {
  assetwavloaderstate_t state;
 } assetwavloaderloading_t;
 /**
 * Parsed metadata for a WAV asset - only the RIFF/WAVE/fmt/data chunk
 * headers are ever read; the PCM sample data itself is never loaded here
 * (see @ref assetWavParseHeader). Playback reads sample data directly
 * from the archive on demand instead - see audiostreampcm.h.
 */
 typedef struct {
  /** Sample rate of the PCM data, in Hz. */
  uint32_t sampleRate;
  /** Number of interleaved channels in the PCM data. */
  uint8_t channels;
  /**
   * Bits per sample of the *source* file data - 16 or 24 (see
   * assetWavParseHeader). Playback always reads 16-bit samples out via
   * audioStreamPcmRead() regardless of this - a 24-bit source is
   * truncated to 16-bit there, since none of this project's audio
   * backends (PSP/Dolphin hardware, SDL2 on Linux) accept anything wider.
   */
  uint8_t bitsPerSample;
  /** Byte offset from the start of the file to the first PCM sample. */
  size_t dataOffset;
  /** Size of the PCM data, in bytes. */
  size_t dataSize;
 } assetwavfile_t;
 /** Convenience alias - the loaded output type of a wav asset entry. */
 typedef assetwavfile_t assetwavoutput_t;
 /**
 * Asynchronous loader callback. Opens the WAV file and reads just enough of
 * it to locate and parse the `fmt ` chunk and locate (not read) the `data`
 * chunk - see @ref assetWavParseHeader. All I/O happens here so the main
 * thread is not blocked. Sets entry state to `ASSET_ENTRY_STATE_PENDING_SYNC`
 * on success or `ASSET_ENTRY_STATE_ERROR` on failure.
 *
 * @param loading The loading slot for this asset entry.
 * @return OK on success, error otherwise.
 */
 errorret_t assetWavLoaderAsync(assetloading_t *loading);
 /**
 * Synchronous loader callback. Confirms the async phase completed and marks
 * the entry as `ASSET_ENTRY_STATE_LOADED`.
 *
 * @param loading The loading slot for this asset entry.
 * @return OK on success, error otherwise.
 */
 errorret_t assetWavLoaderSync(assetloading_t *loading);
 /**
 * Dispose callback. The wav asset owns no allocations of its own (its data
 * chunk is read directly from the archive by whichever streams are playing
 * it, each through their own handle - see audiostreampcm.h), so this is
 * currently a no-op beyond the standard asserts.
 *
 * @param entry The asset entry to dispose.
 * @return OK on success, error otherwise.
 */
 errorret_t assetWavDispose(assetentry_t *entry);
 /**
 * Parses a RIFF/WAVE file's chunk structure from an already-open asset
 * file, reading only chunk headers (and the small `fmt ` chunk body) -
 * every other chunk, including `data`'s actual sample bytes, is skipped
 * over via `assetFileRead(file, NULL, size)` rather than read into memory,
 * so this never buffers the (potentially large) PCM payload.
 *
 * Stops as soon as the `data` chunk header is found, recording its file
 * offset and declared size in `wavFile` without reading any of its bytes -
 * the file is left positioned at the start of the PCM data.
 *
 * Only PCM (audio format 1), 16- or 24-bit-per-sample WAV data is
 * supported - see audiostreampcm.h's audioStreamPcmRead() for how a
 * 24-bit source gets truncated to the 16-bit output every platform
 * backend expects. Requires the `fmt ` chunk to appear before `data`, per
 * the WAV spec's recommended ordering.
 *
 * @param file An open asset file, positioned at the start of the WAV data.
 * @param wavFile Struct whose fields will be filled in.
 * @return OK on success, error if the file is malformed or an unsupported
 *         format.
 */
 errorret_t assetWavParseHeader(
  assetfile_t *file,
  assetwavfile_t *wavFile
 );
@@ -0,0 +1,14 @@
 # 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
    audio.c
 )
 # Subdirs
 add_subdirectory(mixer)
 add_subdirectory(stream)
@@ -0,0 +1,73 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "audio.h"
 #include "audio/mixer/audiomixer.h"
 #include "util/memory.h"
 #include "assert/assert.h"
 audio_t AUDIO;
 errorret_t audioInit() {
  memoryZero(&AUDIO, sizeof(audio_t));
  errorChain(audioPlatformInit());
  errorChain(audioMixerInit());
  errorOk();
 }
 audiostream_t * audioAquireStream(assetentry_t *asset) {
  assertNotNull(asset, "Asset cannot be NULL.");
  // Same check audioStreamInit() makes - see its own comment on why this
  // is an assert (a programmer error, not untrusted data). Checking here
  // too catches the mistake as early as possible, before any stream slot
  // is handed out for it.
  assertTrue(
    audioStreamTypeForAssetType(asset->type) != AUDIO_STREAM_TYPE_NULL,
    "Unsupported asset type for an audio stream."
  );
  for(uint8_t i = 0; i < AUDIO_STREAMS_MAX; i++) {
    audiostream_t *stream = &AUDIO.streams[i];
    if(stream->type == AUDIO_STREAM_TYPE_NULL) {
      return stream;
    }
  }
  return NULL;
 }
 errorret_t audioUpdateEarly() {
  errorChain(audioPlatformUpdate());
  errorChain(audioMixerUpdateEarly());
  for(uint8_t i = 0; i < AUDIO_STREAMS_MAX; i++) {
    audiostream_t *stream = &AUDIO.streams[i];
    errorChain(audioStreamUpdate(stream));
  }
  errorOk();
 }
 errorret_t audioUpdateLate() {
  errorChain(audioMixerUpdateLate());
  errorOk();
 }
 errorret_t audioDispose() {
  for(uint8_t i = 0; i < AUDIO_STREAMS_MAX; i++) {
    audiostream_t *stream = &AUDIO.streams[i];
    errorChain(audioStreamDispose(stream));
  }
  errorChain(audioMixerDispose());
  errorChain(audioPlatformDispose());
  errorOk();
 }
@@ -0,0 +1,77 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "dusk.h"
 #include "audio/stream/audiostream.h"
 #include "audio/audioplatform.h"
 #ifndef audioPlatformInit
  #error "audioPlatformInit is not defined"
 #endif
 #ifndef audioPlatformUpdate
  #error "audioPlatformUpdate is not defined"
 #endif
 #ifndef audioPlatformDispose
  #error "audioPlatformDispose is not defined"
 #endif
 typedef struct {
  audiostream_t streams[AUDIO_STREAMS_MAX];
 } audio_t;
 extern audio_t AUDIO;
 /**
 * Initializes the audio subsystem.
 *
 * @return Error indicating success or failure of the operation.
 */
 errorret_t audioInit();
 /**
 * Aquires an available audio stream for playing the given asset. Can return
 * NULL if there is no available stream slot.
 *
 * The returned stream is not yet configured to play `asset` - call
 * audioStreamInit(stream, asset) next.
 *
 * @param asset The asset the caller intends to play - validated eagerly so
 *              an unsupported asset type is caught here rather than only
 *              once audioStreamInit() is called.
 * @return Pointer to an available audio stream, or NULL if none are free.
 */
 audiostream_t * audioAquireStream(assetentry_t *asset);
 /**
 * Updates the audio subsystem, updating every active stream. Should be
 * called once per frame, before rendering - keeps stream buffering/decode
 * work off the render thread's critical path (see duskmad's MP3 decode
 * ring for why this matters).
 *
 * @return Error indicating success or failure of the operation.
 */
 errorret_t audioUpdateEarly();
 /**
 * Updates the audio subsystem's end-of-frame work - currently just starting
 * whatever the audio mixer queued this frame (see
 * audioMixerUpdateLate()'s own comment). Should be called once per frame,
 * after rendering.
 *
 * @return Error indicating success or failure of the operation.
 */
 errorret_t audioUpdateLate();
 /**
 * Disposes the audio subsystem, stopping and disposing every active stream.
 *
 * @return Error indicating success or failure of the operation.
 */
 errorret_t audioDispose();
@@ -6,6 +6,6 @@
 # Sources
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
-    savevita.c
+    audiomixer.c
-    savestreamvita.c
+    audiomixerchannel.c
 )
@@ -0,0 +1,199 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "audiomixer.h"
 #include "audio/stream/audiostream.h"
 #include "util/memory.h"
 #include "util/string.h"
 #include "assert/assert.h"
 audiomixer_t AUDIO_MIXER;
 errorret_t audioMixerInit() {
  memoryZero(&AUDIO_MIXER, sizeof(audiomixer_t));
  audiomixerchannel_t channel = 0;
  while(channel < AUDIO_MIXER_CHANNEL_COUNT) {
    AUDIO_MIXER.channels[channel].fade = 1.0f;
    // -1 means "no fade in progress" - see its own comment; zero-init
    // would otherwise look like an active fade at time 0.
    AUDIO_MIXER.channels[channel].fadeTime = -1.0f;
    channel++;
  }
  errorOk();
 }
 errorret_t audioMixerUpdateEarly() {
  audiomixerchannel_t channel = 0;
  while(channel < AUDIO_MIXER_CHANNEL_COUNT) {
    // One channel's error (e.g. a failed asset load) must not stop every
    // other channel from being updated this frame - caught and logged
    // rather than propagated, same as audioStream*IsFinished()'s own
    // per-stream error handling.
    errorret_t ret = audioMixerChannelUpdateEarly(
      channel, &AUDIO_MIXER.channels[channel]
    );
    if(errorIsNotOk(ret)) errorCatch(errorPrint(ret));
    channel++;
  }
  errorOk();
 }
 errorret_t audioMixerUpdateLate() {
  audiomixerchannel_t channel = 0;
  while(channel < AUDIO_MIXER_CHANNEL_COUNT) {
    errorret_t ret =
      audioMixerChannelUpdateLate(&AUDIO_MIXER.channels[channel]);
    if(errorIsNotOk(ret)) errorCatch(errorPrint(ret));
    channel++;
  }
  errorOk();
 }
 void audioMixerPlay(
  const char_t *file,
  const audiomixerchannel_t channel,
  const float_t volume,
  const float_t pan
 ) {
  audioMixerQueuePlay(file, channel, volume, pan, false, 0, -1.0f, 0.0f);
 }
 void audioMixerPlayLooped(
  const char_t *file,
  const audiomixerchannel_t channel,
  const float_t volume,
  const float_t pan,
  const uint8_t loopCount,
  const float_t loopStart,
  const float_t loopTo
 ) {
  audioMixerQueuePlay(
    file, channel, volume, pan, true, loopCount, loopStart, loopTo
  );
 }
 void audioMixerQueuePlay(
  const char_t *file,
  const audiomixerchannel_t channel,
  const float_t volume,
  const float_t pan,
  const bool_t looping,
  const uint8_t loopCount,
  const float_t loopStart,
  const float_t loopTo
 ) {
  assertStrLenMin(file, 1, "File is required, to stop use audioMixerStop");
  assertTrue(channel < AUDIO_MIXER_CHANNEL_COUNT, "Channel is out of range");
  assertTrue(volume > 0.0f && volume <= 1.0f, "Volume is out of range");
  assertTrue(
    pan >= AUDIO_STREAM_LEFT && pan <= AUDIO_STREAM_RIGHT,
    "Pan is out of range"
  );
  assertTrue(
    !looping || loopStart < 0.0f || loopTo < loopStart,
    "Loop points incorrect"
  );
  audiomixercommand_t *command = &AUDIO_MIXER.channels[channel].pending;
  command->command = AUDIO_MIXER_COMMAND_PLAY;
  stringCopy(command->file, file, AUDIO_PATH_MAX);
  command->volume = volume;
  command->pan = pan;
  command->looping = looping;
  command->loopCount = loopCount;
  command->loopStart = loopStart;
  command->loopTo = loopTo;
 }
 void audioMixerStop(const audiomixerchannel_t channel) {
  assertTrue(channel < AUDIO_MIXER_CHANNEL_COUNT, "Channel is out of range");
  AUDIO_MIXER.channels[channel].pending.command = AUDIO_MIXER_COMMAND_STOP;
 }
 void audioMixerPause(const audiomixerchannel_t channel) {
  assertTrue(channel < AUDIO_MIXER_CHANNEL_COUNT, "Channel is out of range");
  audiostream_t *stream = AUDIO_MIXER.channels[channel].stream;
  if(stream != NULL) audioStreamPause(stream);
 }
 void audioMixerResume(const audiomixerchannel_t channel) {
  assertTrue(channel < AUDIO_MIXER_CHANNEL_COUNT, "Channel is out of range");
  audiostream_t *stream = AUDIO_MIXER.channels[channel].stream;
  if(stream != NULL) audioStreamPlay(stream);
 }
 void audioMixerSetPan(const audiomixerchannel_t channel, const float_t pan) {
  assertTrue(channel < AUDIO_MIXER_CHANNEL_COUNT, "Channel is out of range");
  assertTrue(
    pan >= AUDIO_STREAM_LEFT && pan <= AUDIO_STREAM_RIGHT,
    "Pan is out of range"
  );
  audiostream_t *stream = AUDIO_MIXER.channels[channel].stream;
  if(stream != NULL) audioStreamSetDirectionality(stream, pan);
 }
 void audioMixerSetLoop(
  const audiomixerchannel_t channel,
  const bool_t looping,
  const uint8_t loopCount,
  const float_t loopStart,
  const float_t loopTo
 ) {
  assertTrue(channel < AUDIO_MIXER_CHANNEL_COUNT, "Channel is out of range");
  assertTrue(
    !looping || loopStart < 0.0f || loopTo < loopStart,
    "Loop points incorrect"
  );
  audiostream_t *stream = AUDIO_MIXER.channels[channel].stream;
  if(stream == NULL) return;
  audioStreamSetLooping(stream, looping);
  if(looping) {
    audioStreamSetLoopPoints(stream, loopStart, loopTo);
    audioStreamSetLoopLimit(stream, loopCount);
  }
 }
 void audioMixerFadeTo(
  const audiomixerchannel_t channel,
  const float_t from,
  const float_t to,
  const float_t duration,
  const easingtype_t easing
 ) {
  assertTrue(channel < AUDIO_MIXER_CHANNEL_COUNT, "Channel is out of range");
  audioMixerChannelFadeTo(
    &AUDIO_MIXER.channels[channel], from, to, duration, easing
  );
 }
 bool_t audioMixerIsFading(const audiomixerchannel_t channel) {
  assertTrue(channel < AUDIO_MIXER_CHANNEL_COUNT, "Channel is out of range");
  return audioMixerChannelIsFading(&AUDIO_MIXER.channels[channel]);
 }
 errorret_t audioMixerDispose() {
  audiomixerchannel_t channel = 0;
  while(channel < AUDIO_MIXER_CHANNEL_COUNT) {
    errorChain(audioMixerChannelStopStream(&AUDIO_MIXER.channels[channel]));
    channel++;
  }
  errorOk();
 }
@@ -0,0 +1,204 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "audio/mixer/audiomixerchannel.h"
 typedef struct {
  audiomixerchannelstate_t channels[AUDIO_MIXER_CHANNEL_COUNT];
 } audiomixer_t;
 extern audiomixer_t AUDIO_MIXER;
 /**
 * Initializes the audio mixer.
 */
 errorret_t audioMixerInit();
 /**
 * Updates the audio mixer, called before rendering (the start of the
 * frame) - see audioMixerChannelUpdateEarly()'s own comment, run for every
 * channel.
 */
 errorret_t audioMixerUpdateEarly();
 /**
 * Updates the audio mixer, called at the end of each frame - see
 * audioMixerChannelUpdateLate()'s own comment, run for every channel.
 */
 errorret_t audioMixerUpdateLate();
 /**
 * Same as audioMixerPlayLooped() but with no looping.
 *
 * @param file File to be played.
 * @param channel Channel you want to play this sound on.
 * @param volume Volume of the sound, from 0.0 (silent) to 1.0 (loudest).
 * @param pan Stereo panning of the sound, from AUDIO_STREAM_LEFT to
 *            AUDIO_STREAM_RIGHT.
 */
 void audioMixerPlay(
  const char_t *file,
  const audiomixerchannel_t channel,
  const float_t volume,
  const float_t pan
 );
 /**
 * Queues a sound to be played on the next audio mixer update, which occurs at
 * the end of each frame.
 *
 * Mixer channels can only hold one voice (audio stream) at a time. If you try
 * to queue multiple sounds on the same channel only the last one will be played
 * and will stop any actively playing on that channel currently.
 *
 * Volume is also mixed based on the channel, so supplying volume 1.0 is then
 * multiplied by the channel's volume, e.g. 0.5*1.0 = 0.5.
 *
 * @param file File to be played.
 * @param channel Channel you want to play this sound on.
 * @param volume Volume of the sound, from 0.0 (silent) to 1.0 (loudest).
 * @param pan Stereo panning of the sound, from AUDIO_STREAM_LEFT to
 *            AUDIO_STREAM_RIGHT.
 * @param loopCount How many times to loop the sound, 0 for infinite looping.
 * @param loopStart Where the loop segment ends, in seconds, or -1 to loop
 *                   the whole stream (the default).
 * @param loopTo Where the loop segment starts, in seconds.
 */
 void audioMixerPlayLooped(
  const char_t *file,
  const audiomixerchannel_t channel,
  const float_t volume,
  const float_t pan,
  const uint8_t loopCount,
  const float_t loopStart,
  const float_t loopTo
 );
 /**
 * Shared implementation behind audioMixerPlay()/audioMixerPlayLooped() -
 * queues an AUDIO_MIXER_COMMAND_PLAY for the given channel, to be loaded at
 * the end of this frame and started at the start of the next (see
 * audioMixerUpdateLate()/audioMixerUpdateEarly()).
 *
 * @param file File to be played.
 * @param channel Channel you want to play this sound on.
 * @param volume Volume of the sound, from 0.0 (silent) to 1.0 (loudest).
 * @param pan Stereo panning of the sound, from AUDIO_STREAM_LEFT to
 *            AUDIO_STREAM_RIGHT.
 * @param looping Whether the stream should loop once it finishes.
 * @param loopCount How many times to loop the sound, 0 for infinite looping.
 *                   Ignored unless looping is true.
 * @param loopStart Where the loop segment ends, in seconds, or -1 to loop
 *                   the whole stream. Ignored unless looping is true.
 * @param loopTo Where the loop segment starts, in seconds. Ignored unless
 *                looping is true.
 */
 void audioMixerQueuePlay(
  const char_t *file,
  const audiomixerchannel_t channel,
  const float_t volume,
  const float_t pan,
  const bool_t looping,
  const uint8_t loopCount,
  const float_t loopStart,
  const float_t loopTo
 );
 /**
 * Stops playing sound on the given channel.
 *
 * @param channel Channel to stop.
 */
 void audioMixerStop(const audiomixerchannel_t channel);
 /**
 * Pauses the given channel's currently playing stream, if any - a safe
 * no-op if the channel isn't playing anything. Playback position is
 * retained, so audioMixerResume() continues from the same point.
 *
 * @param channel Channel to pause.
 */
 void audioMixerPause(const audiomixerchannel_t channel);
 /**
 * Resumes the given channel's currently paused stream, if any - a safe
 * no-op if the channel isn't playing anything.
 *
 * @param channel Channel to resume.
 */
 void audioMixerResume(const audiomixerchannel_t channel);
 /**
 * Sets the stereo panning of the given channel's currently playing stream,
 * if any - a safe no-op if the channel isn't playing anything. Only
 * affects what's playing right now; a later audioMixerPlay()/
 * audioMixerPlayLooped() call on this channel uses its own `pan` argument
 * instead.
 *
 * @param channel Channel to update.
 * @param pan Stereo panning, from AUDIO_STREAM_LEFT to AUDIO_STREAM_RIGHT.
 */
 void audioMixerSetPan(const audiomixerchannel_t channel, const float_t pan);
 /**
 * Sets the looping behaviour of the given channel's currently playing
 * stream, if any - a safe no-op if the channel isn't playing anything.
 * Only affects what's playing right now; a later audioMixerPlay()/
 * audioMixerPlayLooped() call on this channel uses its own loop arguments
 * instead.
 *
 * @param channel Channel to update.
 * @param looping Whether the stream should loop.
 * @param loopCount How many times to loop, 0 for infinite. Ignored unless
 *                   looping is true.
 * @param loopStart Where the loop segment ends, in seconds, or -1 to loop
 *                   the whole stream. Ignored unless looping is true.
 * @param loopTo Where the loop segment starts, in seconds. Ignored unless
 *                looping is true.
 */
 void audioMixerSetLoop(
  const audiomixerchannel_t channel,
  const bool_t looping,
  const uint8_t loopCount,
  const float_t loopStart,
  const float_t loopTo
 );
 /**
 * Starts fading the given channel from `from` to `to` over `duration`
 * seconds, eased by `easing` - see audioMixerChannelFadeTo()'s own
 * comment. Continues running (advanced every audioMixerUpdateEarly()) even
 * if the channel isn't currently playing anything.
 *
 * @param channel Channel to fade.
 * @param from Starting fade value, from 0.0 (silent) to 1.0 (loudest).
 * @param to Ending fade value, from 0.0 (silent) to 1.0 (loudest).
 * @param duration How long the fade takes, in seconds.
 * @param easing Easing curve to apply to the fade's progress.
 */
 void audioMixerFadeTo(
  const audiomixerchannel_t channel,
  const float_t from,
  const float_t to,
  const float_t duration,
  const easingtype_t easing
 );
 /**
 * Whether the given channel currently has a fade in progress (started via
 * audioMixerFadeTo() and not yet finished).
 *
 * @param channel Channel to check.
 * @return true if a fade is still in progress.
 */
 bool_t audioMixerIsFading(const audiomixerchannel_t channel);
 /**
 * Disposes the audio mixer.
 */
 errorret_t audioMixerDispose();
@@ -0,0 +1,223 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "audiomixerchannel.h"
 #include "asset/asset.h"
 #include "audio/audio.h"
 #include "audio/stream/audiostream.h"
 #include "audio/stream/audiostreamtype.h"
 #include "save/save.h"
 #include "time/time.h"
 #include "util/math.h"
 #include "assert/assert.h"
 errorret_t audioMixerChannelStopStream(audiomixerchannelstate_t *state) {
  assertNotNull(state, "State cannot be NULL.");
  if(state->stream == NULL) errorOk();
  errorChain(audioStreamDispose(state->stream));
  state->stream = NULL;
  errorOk();
 }
 void audioMixerChannelFadeTo(
  audiomixerchannelstate_t *state,
  const float_t from,
  const float_t to,
  const float_t duration,
  const easingtype_t easing
 ) {
  assertNotNull(state, "State cannot be NULL.");
  state->fade = from;
  state->fadeFrom = from;
  state->fadeTo = to;
  state->fadeDuration = duration;
  state->fadeEasing = easing;
  // A non-positive duration finishes instantly - marked inactive right
  // away (fadeTime < 0) rather than left at 0 to progress next frame,
  // since there's nothing left to progress.
  if(duration <= 0.0f) {
    state->fade = to;
    state->fadeTime = -1.0f;
  } else {
    state->fadeTime = 0.0f;
  }
 }
 bool_t audioMixerChannelIsFading(const audiomixerchannelstate_t *state) {
  assertNotNull(state, "State cannot be NULL.");
  return state->fadeTime >= 0.0f;
 }
 void audioMixerChannelApplyVolume(
  const audiomixerchannel_t channel,
  audiomixerchannelstate_t *state
 ) {
  assertNotNull(state, "State cannot be NULL.");
  if(state->stream == NULL) return;
  // Advances any in-progress fade before it's read below - see
  // audioMixerChannelFadeTo()'s own comment on fadeTime's meaning.
  if(state->fadeTime >= 0.0f) {
    state->fadeTime += TIME.delta;
    const float_t t = mathClamp(
      state->fadeTime / state->fadeDuration, 0.0f, 1.0f
    );
    state->fade = state->fadeFrom +
      (state->fadeTo - state->fadeFrom) * easingApply(state->fadeEasing, t);
    if(state->fadeTime >= state->fadeDuration) {
      state->fade = state->fadeTo;
      state->fadeTime = -1.0f;
    }
  }
  // state->fade and both SAVE.settings volumes have no setter - written
  // directly by callers - so this is the only place any of them ever gets
  // validated, rather than at the point they're set.
  assertTrue(
    state->fade >= 0.0f && state->fade <= 1.0f,
    "Channel fade is out of range."
  );
  assertTrue(
    SAVE.settings.audioChannelVolume[channel] >= 0.0f &&
    SAVE.settings.audioChannelVolume[channel] <= 1.0f,
    "Channel volume is out of range."
  );
  assertTrue(
    SAVE.settings.audioMasterVolume >= 0.0f &&
    SAVE.settings.audioMasterVolume <= 1.0f,
    "Master volume is out of range."
  );
  // Final computed volume.
  float_t volume = (
    state->baseVolume *
    state->fade *
    SAVE.settings.audioChannelVolume[channel] *
    SAVE.settings.audioMasterVolume
  );
  audioStreamSetVolume(state->stream, volume);
 }
 errorret_t audioMixerChannelUpdateEarly(
  const audiomixerchannel_t channel,
  audiomixerchannelstate_t *state
 ) {
  assertNotNull(state, "State cannot be NULL.");
  audiomixercommand_t *command = &state->pending;
  if(command->command == AUDIO_MIXER_COMMAND_STOP) {
    errorChain(audioMixerChannelStopStream(state));
    command->command = AUDIO_MIXER_COMMAND_NONE;
    audioMixerChannelApplyVolume(channel, state);
    errorOk();
  }
  if(
    command->command != AUDIO_MIXER_COMMAND_PLAY ||
    command->loadingAsset == NULL
  ) {
    // A PLAY command with no loadingAsset yet (command->loadingAsset ==
    // NULL) was queued too late for the audioMixerChannelUpdateLate() that
    // just ran immediately before this call to have locked it - the only
    // way that happens is a command queued outside the normal per-frame
    // cycle, e.g. during engine startup before any
    // audioMixerChannelUpdateLate() has run yet. Left alone (still
    // AUDIO_MIXER_COMMAND_PLAY) rather than treated as an error: the very
    // next audioMixerChannelUpdateLate() will lock it, and the frame after
    // that will reach here and apply it normally.
    audioMixerChannelApplyVolume(channel, state);
    errorOk();
  }
  // Blocks here if audioMixerChannelUpdateLate()'s load (kicked off at the
  // end of the previous frame) hasn't finished yet - see this function's
  // own doc comment on why that's accepted for now.
  errorret_t loadRet = assetRequireLoaded(command->loadingAsset);
  if(errorIsNotOk(loadRet)) {
    assetUnlockEntry(command->loadingAsset);
    command->loadingAsset = NULL;
    command->command = AUDIO_MIXER_COMMAND_NONE;
    errorChain(loadRet);
  }
  errorChain(audioMixerChannelStopStream(state));
  audiostream_t *stream = audioAquireStream(command->loadingAsset);
  assertNotNull(stream, "No free audio stream slots available.");
  errorret_t initRet = audioStreamInit(stream, command->loadingAsset);
  // The stream holds its own lock on the asset once initialized (or, on
  // failure, audioStreamInit() has already released it itself) - either
  // way this call's own lock is no longer needed.
  assetUnlockEntry(command->loadingAsset);
  command->loadingAsset = NULL;
  command->command = AUDIO_MIXER_COMMAND_NONE;
  errorChain(initRet);
  // Forwards to this channel's own onLoop/onEnd (persistent across every
  // play on this channel) rather than this one stream instance's own -
  // see audiomixerchannelstate_t.onLoop's own comment.
  stream->user = state;
  stream->onLoop = audioMixerChannelOnStreamLoop;
  stream->onEnd = audioMixerChannelOnStreamEnd;
  audioStreamSetDirectionality(stream, command->pan);
  if(command->looping) {
    audioStreamSetLooping(stream, true);
    audioStreamSetLoopPoints(stream, command->loopStart, command->loopTo);
    audioStreamSetLoopLimit(stream, command->loopCount);
  }
  audioStreamPlay(stream);
  state->stream = stream;
  state->baseVolume = command->volume;
  audioMixerChannelApplyVolume(channel, state);
  errorOk();
 }
 errorret_t audioMixerChannelUpdateLate(audiomixerchannelstate_t *state) {
  assertNotNull(state, "State cannot be NULL.");
  audiomixercommand_t *command = &state->pending;
  if(command->command != AUDIO_MIXER_COMMAND_PLAY) errorOk();
  assetloadertype_t assetType = audioStreamAssetTypeForPath(command->file);
  assertTrue(
    assetType != ASSET_LOADER_TYPE_NULL, "Unsupported audio file extension."
  );
  // Begins loading now - kicked off at the end of this frame so it has
  // until the start of the next (audioMixerChannelUpdateEarly()) to finish
  // before that has to block on it.
  command->loadingAsset = assetLock(command->file, assetType, NULL);
  errorOk();
 }
 void audioMixerChannelOnStreamLoop(audiostream_t *stream) {
  assertNotNull(stream, "Stream cannot be NULL.");
  audiomixerchannelstate_t *state = (audiomixerchannelstate_t *) stream->user;
  if(state->onLoop != NULL) state->onLoop(state);
 }
 void audioMixerChannelOnStreamEnd(audiostream_t *stream) {
  assertNotNull(stream, "Stream cannot be NULL.");
  audiomixerchannelstate_t *state = (audiomixerchannelstate_t *) stream->user;
  if(state->onEnd != NULL) state->onEnd(state);
 }
@@ -0,0 +1,241 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "dusk.h"
 #include "error/error.h"
 #include "animation/easing.h"
 // Forward-declared rather than including asset/asset.h - this header only
 // ever needs a pointer to it, and pulling in the full asset module here
 // risks an include cycle for anything that reaches this header via a
 // cutscene item (cutscene.h -> cutsceneitem.h -> the audio cutscene items
 // -> this header -> asset/asset.h, mid-parse). audiomixerchannel.c itself
 // still includes the full header.
 typedef struct assetentry_s assetentry_t;
 typedef struct audiostream_s audiostream_t;
 #define AUDIO_PATH_MAX 256
 typedef enum {
  AUDIO_MIXER_CHANNEL_BGM_0,
  AUDIO_MIXER_CHANNEL_VOICE_0,
  AUDIO_MIXER_CHANNEL_VOICE_1,
  AUDIO_MIXER_CHANNEL_SFX_0,
  AUDIO_MIXER_CHANNEL_SFX_1,
  AUDIO_MIXER_CHANNEL_SFX_2,
  AUDIO_MIXER_CHANNEL_SFX_3,
  AUDIO_MIXER_CHANNEL_COUNT
 } audiomixerchannel_t;
 typedef enum {
  AUDIO_MIXER_COMMAND_NONE,
  AUDIO_MIXER_COMMAND_PLAY,
  AUDIO_MIXER_COMMAND_STOP
 } audiomixercommandtype_t;
 typedef struct {
  // What audioMixerChannelUpdateEarly() should do to this channel at the
  // start of the next frame - AUDIO_MIXER_COMMAND_NONE if nothing's
  // queued. Set by audioMixerPlay()/audioMixerPlayLooped()/
  // audioMixerStop(); queuing a new command on a channel replaces, rather
  // than stacks on top of, whatever was already queued for it this frame -
  // only the most recent survives.
  audiomixercommandtype_t command;
  // AUDIO_MIXER_COMMAND_PLAY only, below.
  char_t file[AUDIO_PATH_MAX];
  float_t volume;
  float_t pan;
  bool_t looping;
  uint8_t loopCount;
  float_t loopStart;
  float_t loopTo;
  // Set by audioMixerChannelUpdateLate() (the end of the frame this PLAY
  // command was queued on), once it locks the requested file and kicks off
  // its load. audioMixerChannelUpdateEarly() (the start of the next frame)
  // blocks on this being fully loaded before actually starting playback -
  // see its own comment. NULL except in that in-between window.
  assetentry_t *loadingAsset;
 } audiomixercommand_t;
 typedef struct audiomixerchannelstate_s audiomixerchannelstate_t;
 typedef struct audiomixerchannelstate_s {
  // Queued action for the next audioMixerChannelUpdateEarly() to apply.
  audiomixercommand_t pending;
  // This channel's currently playing stream, or NULL if nothing is -
  // acquired from AUDIO.streams by audioMixerChannelUpdateEarly() when it
  // applies an AUDIO_MIXER_COMMAND_PLAY, disposed the same way on
  // AUDIO_MIXER_COMMAND_STOP or before a new AUDIO_MIXER_COMMAND_PLAY
  // replaces it.
  audiostream_t *stream;
  // The per-sound volume `stream` was last started with (the `volume`
  // argument to whichever audioMixerPlay()/audioMixerPlayLooped() call
  // started it) - combined with this channel's fade, its own volume
  // (SAVE.settings.audioChannelVolume) and the mixer's master volume
  // (SAVE.settings.audioMasterVolume), every frame, to get the volume
  // actually passed to audioStreamSetVolume(). Meaningless while `stream`
  // is NULL.
  float_t baseVolume;
  // This channel's own fade multiplier, from 0.0 (fully faded out) to 1.0
  // (no fade applied, the default) - transient runtime state, unlike the
  // channel/master volumes below (which are persisted user preferences).
  // No setter - write it directly; audioMixerChannelApplyVolume() asserts
  // it's in range the next time it reads it, rather than validating at the
  // point it's set.
  float_t fade;
  // Fade transition state, set by audioMixerChannelFadeTo() and advanced
  // every frame by audioMixerChannelApplyVolume(), before it reads `fade`
  // to compute the mixed volume. fadeTime < 0 means no fade is in progress
  // (audioMixerChannelIsFading() is just `fadeTime >= 0`) - audioMixerInit()
  // explicitly sets this to -1.0f, since zero-initializing it would
  // otherwise look like an active fade at time 0.
  float_t fadeFrom;
  float_t fadeTo;
  float_t fadeDuration;
  float_t fadeTime;
  easingtype_t fadeEasing;
  // Arbitrary caller data, handed back as-is to onLoop/onEnd below - never
  // read or written by the mixer itself. NULL by default.
  void *user;
  // Fired (from the main thread - safe to do arbitrary work, same
  // guarantee as audiostream_t's own onLoop/onEnd) whenever this channel's
  // currently playing stream loops, or reaches its natural end (including
  // hitting its loop limit - see audioStreamSetLoopLimit()) and stops.
  // Wired onto every stream this channel starts via
  // audioMixerChannelOnStreamLoop()/OnStreamEnd() - not called directly by
  // anything else. No setter - write these fields directly; NULL (the
  // default) means not notified. Unlike `stream`/`pending`, these persist
  // across every play on this channel, not just one.
  void (*onLoop)(audiomixerchannelstate_t *state);
  void (*onEnd)(audiomixerchannelstate_t *state);
 } audiomixerchannelstate_t;
 /**
 * Stops and disposes the given channel's currently playing stream, if any -
 * a safe no-op if the channel is already idle. Shared by
 * audioMixerChannelUpdateEarly() (AUDIO_MIXER_COMMAND_STOP, and replacing a
 * channel's stream before a new AUDIO_MIXER_COMMAND_PLAY starts) and
 * audioMixerDispose().
 *
 * @param state The channel state to stop.
 */
 errorret_t audioMixerChannelStopStream(audiomixerchannelstate_t *state);
 /**
 * Computes the given channel's actual playback volume - its currently
 * playing sound's own volume (baseVolume), this channel's fade, this
 * channel's own volume (SAVE.settings.audioChannelVolume[channel]) and the
 * mixer's master volume (SAVE.settings.audioMasterVolume) - and applies it
 * via audioStreamSetVolume(). Asserts fade and both save-settings volumes
 * are each within [0.0, 1.0] - the only validation any of them ever gets,
 * since none of them have a setter. A safe no-op if the channel isn't
 * playing anything. Called every audioMixerChannelUpdateEarly(), not just
 * when a PLAY command starts a new stream - see its own comment.
 *
 * @param channel Which channel `state` is, to index
 *                SAVE.settings.audioChannelVolume with.
 * @param state The channel state to update.
 */
 void audioMixerChannelApplyVolume(
  const audiomixerchannel_t channel,
  audiomixerchannelstate_t *state
 );
 /**
 * Starts fading the given channel's `fade` multiplier from `from` to `to`
 * over `duration` seconds, eased by `easing` - snaps `fade` to `from`
 * immediately, then audioMixerChannelApplyVolume() advances it every frame
 * from here on. A `duration` of 0 or less snaps straight to `to` and marks
 * the fade as already finished (audioMixerChannelIsFading() returns
 * false on the very next call).
 *
 * @param state The channel state to fade.
 * @param from Starting fade value, from 0.0 (silent) to 1.0 (loudest).
 * @param to Ending fade value, from 0.0 (silent) to 1.0 (loudest).
 * @param duration How long the fade takes, in seconds.
 * @param easing Easing curve to apply to the fade's progress.
 */
 void audioMixerChannelFadeTo(
  audiomixerchannelstate_t *state,
  const float_t from,
  const float_t to,
  const float_t duration,
  const easingtype_t easing
 );
 /**
 * Whether the given channel currently has a fade in progress (started via
 * audioMixerChannelFadeTo() and not yet finished).
 *
 * @param state The channel state to check.
 * @return true if a fade is still in progress.
 */
 bool_t audioMixerChannelIsFading(const audiomixerchannelstate_t *state);
 /**
 * Updates a single mixer channel, called before rendering (the start of
 * the frame): applies whatever command (play, stop - including everything
 * a play carries, pan/looping) audioMixerChannelUpdateLate() queued for
 * loading at the end of the previous frame. If that load hasn't finished
 * yet, this blocks (via assetRequireLoaded()) until it has - a deliberate
 * stall for now rather than skipping a frame, since there's currently no
 * way to only partially apply a channel's command. Also recomputes and
 * reapplies this channel's mixed volume (see
 * audioMixerChannelApplyVolume()) every time, regardless of whether a
 * command was queued this frame, so a live change to this channel's fade,
 * its own volume, or the master volume takes effect on whatever's already
 * playing too.
 *
 * @param channel Which channel `state` is - see
 *                audioMixerChannelApplyVolume()'s own comment.
 * @param state The channel state to update.
 */
 errorret_t audioMixerChannelUpdateEarly(
  const audiomixerchannel_t channel,
  audiomixerchannelstate_t *state
 );
 /**
 * Updates a single mixer channel, called at the end of each frame, once
 * every other system has had a chance to queue a command via
 * audioMixerPlay()/audioMixerPlayLooped()/audioMixerStop(). For a queued
 * AUDIO_MIXER_COMMAND_PLAY, locks its file and begins loading it (see
 * assetLock()) - giving it from now until the next
 * audioMixerChannelUpdateEarly() to finish before that has to block on it.
 * Actually starting/stopping playback happens there, not here.
 *
 * @param state The channel state to update.
 */
 errorret_t audioMixerChannelUpdateLate(audiomixerchannelstate_t *state);
 /**
 * Trampoline wired onto every stream a channel starts (as that stream's
 * onLoop) - forwards to the channel's own onLoop (see
 * audiomixerchannelstate_t.onLoop's own comment) via stream->user, which
 * audioMixerChannelUpdateEarly() points at the channel's own state.
 *
 * @param stream The stream that looped.
 */
 void audioMixerChannelOnStreamLoop(audiostream_t *stream);
 /**
 * Same as audioMixerChannelOnStreamLoop() but wired onto onEnd, forwarding
 * to the channel's own onEnd.
 *
 * @param stream The stream that ended.
 */
 void audioMixerChannelOnStreamEnd(audiostream_t *stream);
@@ -0,0 +1,13 @@
 # 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
    audiostream.c
    audiostreampcm.c
    audiostreammp3.c
    audiostreamtype.c
 )
@@ -0,0 +1,312 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "audiostream.h"
 #include "assert/assert.h"
 #include "util/math.h"
 errorret_t audioStreamInit(audiostream_t *stream, assetentry_t *asset) {
  assertNotNull(stream, "Stream cannot be NULL.");
  assertNotNull(asset, "Asset cannot be NULL.");
  assertTrue(
    asset->state == ASSET_ENTRY_STATE_LOADED,
    "Asset must be loaded before it can back an audio stream."
  );
  // A caller passing an asset type that can't back an audio stream is a
  // programmer error, not something that can happen from untrusted data, so
  // this is an assert rather than an errorThrow (see
  // feedback_assert_vs_error convention).
  assertTrue(
    audioStreamTypeForAssetType(asset->type) != AUDIO_STREAM_TYPE_NULL,
    "Unsupported asset type for an audio stream."
  );
  stream->state = 0;
  stream->volume = 1.0f;
  stream->directionality = AUDIO_STREAM_CENTER;
  stream->loopStart = -1;
  stream->loopTo = 0;
  stream->duration = 0;
  stream->startFrame = 0;
  stream->seeking = false;
  stream->user = NULL;
  stream->onLoop = NULL;
  stream->onEnd = NULL;
  stream->loopCount = 0;
  stream->lastLoopCount = 0;
  stream->loopLimit = 0;
  stream->loopRestartCount = 0;
  // Locked for as long as the stream is in use (see audiostream_t.asset's
  // own comment) - released in audioStreamDispose().
  stream->asset = asset;
  assetEntryLock(asset);
  // Type-specific setup (audioStreamPcmInit() / audioStreamMp3Init())
  // determines stream->type, sets stream->sampleRate/channels, and asks
  // the platform implementation to set up its state.
  errorret_t ret = asset->type == ASSET_LOADER_TYPE_MP3
    ? audioStreamMp3Init(stream)
    : audioStreamPcmInit(stream);
  if(errorIsNotOk(ret)) {
    assetEntryUnlock(asset);
    stream->asset = NULL;
    errorChain(ret);
  }
  errorOk();
 }
 size_t audioStreamGetTotalFrames(const audiostream_t *stream) {
  assertNotNull(stream, "Stream cannot be NULL.");
  return stream->type == AUDIO_STREAM_TYPE_MP3
    ? audioStreamMp3GetTotalFrames(stream)
    : audioStreamPcmGetTotalFrames(stream);
 }
 errorret_t audioStreamSeek(audiostream_t *stream, const size_t frame) {
  assertNotNull(stream, "Stream cannot be NULL.");
  errorChain(
    stream->type == AUDIO_STREAM_TYPE_MP3
      ? audioStreamMp3Seek(stream, frame)
      : audioStreamPcmSeek(stream, frame)
  );
  errorOk();
 }
 errorret_t audioStreamRead(
  audiostream_t *stream,
  int16_t *buffer,
  const size_t frameCount,
  size_t *outFramesRead
 ) {
  assertNotNull(stream, "Stream cannot be NULL.");
  errorChain(
    stream->type == AUDIO_STREAM_TYPE_MP3
      ? audioStreamMp3Read(stream, buffer, frameCount, outFramesRead)
      : audioStreamPcmRead(stream, buffer, frameCount, outFramesRead)
  );
  errorOk();
 }
 void audioStreamPlay(audiostream_t *stream) {
  assertNotNull(stream, "Stream cannot be NULL.");
  stream->state |= AUDIO_STREAM_STATE_PLAYING;
 }
 void audioStreamPause(audiostream_t *stream) {
  assertNotNull(stream, "Stream cannot be NULL.");
  stream->state &= ~AUDIO_STREAM_STATE_PLAYING;
 }
 void audioStreamSetPosition(audiostream_t *stream, const float_t position) {
  assertNotNull(stream, "Stream cannot be NULL.");
  // Wrap into [0, duration).
  float_t t = position;
  while(t < 0) t += stream->duration;
  while(t >= stream->duration) t -= stream->duration;
  stream->startFrame = (size_t) (t * stream->sampleRate);
  stream->seeking = true;
  // Force the next audioStreamUpdate() to re-buffer from startFrame instead
  // of continuing whatever was already buffered - see the platform Buffer()
  // implementations for how each one applies startFrame; PSP is the one
  // exception (see audioStreamSetPosition's own doc comment).
  stream->state &= ~AUDIO_STREAM_STATE_BUFFERED;
 }
 void audioStreamSetLoopPoints(
  audiostream_t *stream,
  const float_t loopStart,
  const float_t loopTo
 ) {
  assertNotNull(stream, "Stream cannot be NULL.");
  assertTrue(
    loopStart < 0 || loopTo < loopStart,
    "loopTo must be before loopStart."
  );
  stream->loopStart = loopStart;
  stream->loopTo = loopTo;
 }
 void audioStreamGetPanFactors(
  const audiostream_t *stream,
  float_t *outLeft,
  float_t *outRight
 ) {
  assertNotNull(stream, "Stream cannot be NULL.");
  assertNotNull(outLeft, "outLeft cannot be NULL.");
  assertNotNull(outRight, "outRight cannot be NULL.");
  // directionality is already a pan factor in AUDIO_STREAM_LEFT..RIGHT
  // (-1.0..1.0) - assertTrue'd here rather than clamped, since a caller
  // passing something outside that range is a programmer error (see
  // audioStreamSetDirectionality()'s own assert).
  const float_t pan = stream->directionality;
  *outLeft = pan > 0 ? (1.0f - pan) : 1.0f;
  *outRight = pan < 0 ? (1.0f + pan) : 1.0f;
 }
 size_t audioStreamComputeEndFrame(
  const audiostream_t *stream,
  const size_t startFrame,
  const size_t totalFrames
 ) {
  assertNotNull(stream, "Stream cannot be NULL.");
  size_t endFrame = totalFrames;
  if((stream->state & AUDIO_STREAM_STATE_LOOPING) && stream->loopStart >= 0) {
    endFrame = mathMin(
      (size_t) (stream->loopStart * stream->sampleRate), totalFrames
    );
  }
  if(startFrame >= endFrame) endFrame = totalFrames;
  return endFrame;
 }
 void audioStreamSetVolume(audiostream_t *stream, const float_t volume) {
  assertNotNull(stream, "Stream cannot be NULL.");
  assertTrue(volume >= 0.0f && volume <= 1.0f, "Volume is out of range.");
  stream->volume = volume;
  // TODO: Do I need to update the device output? PSP may require this
 }
 void audioStreamSetDirectionality(
  audiostream_t *stream,
  const float_t directionality
 ) {
  assertNotNull(stream, "Stream cannot be NULL.");
  assertTrue(
    directionality >= AUDIO_STREAM_LEFT && directionality <= AUDIO_STREAM_RIGHT,
    "Directionality is out of range."
  );
  stream->directionality = directionality;
  // TODO: Need to update internal decoder?
 }
 void audioStreamSetLooping(audiostream_t *stream, const bool_t looping) {
  assertNotNull(stream, "Stream cannot be NULL.");
  if(looping) {
    stream->state |= AUDIO_STREAM_STATE_LOOPING;
  } else {
    stream->state &= ~AUDIO_STREAM_STATE_LOOPING;
  }
 }
 void audioStreamSetLoopLimit(audiostream_t *stream, const uint32_t loopLimit) {
  assertNotNull(stream, "Stream cannot be NULL.");
  stream->loopLimit = loopLimit;
  stream->loopRestartCount = 0;
 }
 errorret_t audioStreamUpdate(audiostream_t *stream) {
  assertNotNull(stream, "Stream cannot be NULL.");
  if(stream->type == AUDIO_STREAM_TYPE_NULL) {
    errorOk();
  }
  // Some platforms (PSP) loop entirely on their own background thread for
  // gaplessness and can only safely notify onLoop by incrementing this
  // counter from there, rather than calling onLoop directly off the main
  // thread - see loopCount's own comment. Firing it here, unconditionally,
  // catches up to the latest count in one call even if multiple loops
  // happened between two Update() calls.
  if(stream->loopCount != stream->lastLoopCount) {
    stream->lastLoopCount = stream->loopCount;
    if(stream->onLoop != NULL) {
      stream->onLoop(stream);
    }
  }
  // TODO: Once streamed (rather than fully in-memory) sources exist, this is
  // where new data would be decoded/read in and re-buffered as playback
  // consumes it.
  // Checked in this order (finished-check before needs-buffering) so that a
  // loop restart falls straight through into re-buffering within this same
  // call, instead of leaving BUFFERED cleared for the caller to notice and
  // act on next frame - that extra frame of latency was audible as a gap
  // at every loop boundary.
  if(
    (stream->state & AUDIO_STREAM_STATE_PLAYING) &&
    (stream->state & AUDIO_STREAM_STATE_BUFFERED) &&
    audioStreamPlatformIsFinished(stream)
  ) {
    // A limit of 0 means unlimited; otherwise this pass's restart only goes
    // ahead while fewer than loopLimit restarts have already happened -
    // once it's reached, fall through to the same stop/onEnd path as a
    // non-looping stream instead of restarting again.
    const bool_t loopLimitReached = stream->loopLimit > 0 &&
      stream->loopRestartCount >= stream->loopLimit;
    if((stream->state & AUDIO_STREAM_STATE_LOOPING) && !loopLimitReached) {
      stream->state &= ~AUDIO_STREAM_STATE_BUFFERED;
      stream->loopRestartCount++;
      // Resume from loopTo rather than the very start of the buffer - only
      // matters for platforms that reach this generic restart path at all
      // (Linux and Dolphin, both of which re-buffer per pass and report
      // "finished" at every loop boundary); PSP loops entirely on its own
      // read-ahead ring instead (see loopRestartCount's own comment).
      stream->startFrame = (size_t) (stream->loopTo * stream->sampleRate);
      if(stream->onLoop != NULL) {
        stream->onLoop(stream);
      }
    } else {
      stream->state &=
        ~(AUDIO_STREAM_STATE_PLAYING | AUDIO_STREAM_STATE_BUFFERED);
      if(stream->onEnd != NULL) {
        stream->onEnd(stream);
      }
    }
  }
  if(
    (stream->state & AUDIO_STREAM_STATE_PLAYING) &&
    !(stream->state & AUDIO_STREAM_STATE_BUFFERED)
  ) {
    errorChain(audioStreamPlatformBuffer(stream));
    stream->state |= AUDIO_STREAM_STATE_BUFFERED;
  }
  errorOk();
 }
 errorret_t audioStreamDispose(audiostream_t *stream) {
  assertNotNull(stream, "Stream cannot be NULL.");
  if(stream->type != AUDIO_STREAM_TYPE_NULL) {
    errorChain(audioStreamPlatformDispose(stream));
  }
  if(stream->type == AUDIO_STREAM_TYPE_PCM) {
    errorChain(audioStreamPcmDispose(stream));
  } else if(stream->type == AUDIO_STREAM_TYPE_MP3) {
    errorChain(audioStreamMp3Dispose(stream));
  }
  if(stream->asset != NULL) {
    assetEntryUnlock(stream->asset);
    stream->asset = NULL;
  }
  stream->type = AUDIO_STREAM_TYPE_NULL;
  errorOk();
 }
@@ -0,0 +1,360 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "audio/stream/audiostreamtype.h"
 #include "audio/stream/audiostreampcm.h"
 #include "audio/stream/audiostreammp3.h"
 #include "audio/audiostreamplatform.h"
 #include "asset/loader/assetentry.h"
 #ifndef audioStreamPlatformInit
  #error "audioStreamPlatformInit is not defined"
 #endif
 #ifndef audioStreamPlatformDispose
  #error "audioStreamPlatformDispose is not defined"
 #endif
 #ifndef audioStreamPlatformBuffer
  #error "audioStreamPlatformBuffer is not defined"
 #endif
 #ifndef audioStreamPlatformIsFinished
  #error "audioStreamPlatformIsFinished is not defined"
 #endif
 #define AUDIO_STREAMS_MAX 8
 #define AUDIO_STREAM_STATE_PLAYING (1 << 0)
 #define AUDIO_STREAM_STATE_LOOPING (1 << 1)
 #define AUDIO_STREAM_STATE_BUFFERED (1 << 2)
 #define AUDIO_STREAM_CENTER 0.0f
 #define AUDIO_STREAM_LEFT -1.0f
 #define AUDIO_STREAM_RIGHT 1.0f
 typedef struct audiostream_s audiostream_t;
 typedef struct audiostream_s {
  // Used for aquiring new data.
  audistreamtype_t type;
  // What state the stream is in. volatile: PSP's output thread reads
  // AUDIO_STREAM_STATE_PLAYING directly to honor a pause promptly instead
  // of only reacting once the main thread's own per-frame gate notices -
  // see audioStreamPSPThreadFeed()'s own comment.
  volatile uint8_t state;
  // The asset backing this stream's data (e.g. a WAV file) - determines
  // `type` (see audioStreamInit()) and is read from on demand by the
  // type-specific module (e.g. audiostreampcm.h) rather than ever being
  // fully decoded into memory up front. The stream holds its own lock on
  // this entry (assetEntryLock()/assetEntryUnlock()) for as long as it's
  // in use, independent of whatever lock(s) the caller that requested
  // playback may also be holding.
  assetentry_t *asset;
  // Loudness, from 0.0 (silent) to 1.0 (loudest).
  float_t volume;
  // In stereo space, where do we send the audio - from AUDIO_STREAM_LEFT
  // (-1.0) to AUDIO_STREAM_RIGHT (1.0), AUDIO_STREAM_CENTER (0.0) by
  // default.
  // TODO: Can we use a 3D vector + Pro Logic II?
  float_t directionality;
  // In seconds, where the loop segment ends and playback jumps back to
  // loopTo - -1 (the default) means "at the end of the stream", i.e. loop
  // the whole buffer. Set via audioStreamSetLoopPoints().
  float_t loopStart;
  // In seconds, where a loop jumps back to once it reaches loopStart.
  // Defaults to 0 (start of stream). Set via audioStreamSetLoopPoints().
  float_t loopTo;
  // Cached duration of the stream in seconds.
  float_t duration;
  // Frame offset the next platform Buffer() call should start playback
  // from - set by audioStreamSetPosition() (an explicit seek) and by
  // audioStreamUpdate() itself (to loopTo's frame offset, for platforms
  // that re-enter Buffer() on every loop restart rather than looping
  // natively). Each platform's Buffer()-invoking entry point must read and
  // reset this to 0 synchronously, in the same call that decided to
  // (re)buffer - not later/asynchronously (e.g. from a feeder thread),
  // since audioStreamUpdate() may already have moved on to something else
  // that touches this field by the time an async reader gets to it.
  size_t startFrame;
  // True when startFrame came from an explicit audioStreamSetPosition()
  // seek rather than a natural loop restart. Platforms whose Buffer() call
  // can leave previously-queued audio still playing underneath the new
  // pass (currently just Linux's SDL queue, kept deliberately overlapping
  // across a loop restart to avoid a gap) need this to tell "jump now,
  // discarding whatever's still playing" (seek) apart from "let the old
  // tail keep playing while the new pass queues underneath it" (loop
  // restart) - both look identical as just "a pending startFrame"
  // otherwise. Consumed (reset to false) the same way as startFrame.
  bool_t seeking;
  // Callbacks
  void *user;
  void (*onLoop)(audiostream_t *stream);
  void (*onEnd)(audiostream_t *stream);
  // Incremented by platform code (from whatever thread/context it runs in)
  // each time a loop happens, instead of calling onLoop directly - onLoop
  // may do arbitrary, possibly-slow work (console printing, game logic),
  // which is only safe to run from the main thread inside audioStreamUpdate().
  // Calling it straight from a real-time audio thread risks starving the
  // hardware buffer if it takes too long - confirmed as the real cause of
  // a loud crackle on PSP once its feeder thread called onLoop inline.
  volatile uint32_t loopCount;
  // audioStreamUpdate()'s own record of the last loopCount it fired
  // onLoop for - only ever touched from the main thread.
  uint32_t lastLoopCount;
  // Maximum number of times this stream is allowed to loop before stopping
  // (firing onEnd) instead of restarting again - 0 (the default) means loop
  // forever. Has no effect unless looping is also enabled via
  // audioStreamSetLooping(). Set via audioStreamSetLoopLimit().
  uint32_t loopLimit;
  // How many loop restarts this stream has already committed to - compared
  // against loopLimit each time a restart is considered, then incremented
  // if it goes ahead; reset to 0 by audioStreamSetLoopLimit(). Distinct
  // from loopCount (which tracks when a loop becomes audible, purely for
  // onLoop notification, and is PSP-only) - this counts decided restarts,
  // main-thread-only on every platform (PSP decides whether to loop from
  // its own read-ahead ring, itself driven from the main thread via
  // audioStreamPSPIsFinished() - see its own comment).
  uint32_t loopRestartCount;
  // PCM format of the stream's decoded output - read identically by every
  // platform backend regardless of stream type (PCM decodes straight
  // through; MP3 decodes to this same format), so it lives here rather
  // than duplicated in both audiostreampcm_t and audiostreammp3_t. Set by
  // whichever type-specific Init function runs (audioStreamPcmInit() /
  // audioStreamMp3Init()).
  uint32_t sampleRate;
  uint8_t channels;
  // Stream type specific data.
  union {
    audiostreampcm_t pcm;
    audiostreammp3_t mp3;
  };
  // Platform-specific playback state (e.g. SDL2 device, PSP channel, ASND
  // voice). Defined by each platform's audiostreamplatform.h.
  audiostreamplatform_t platform;
 } audiostream_t;
 /**
 * Initializes an audio stream to play the given asset, determining the
 * stream's type from the asset's loader type (e.g. a WAV asset becomes an
 * AUDIO_STREAM_TYPE_PCM stream) and dispatching to that type's own setup
 * (e.g. audioStreamPcmInit()). Does not begin playback; call
 * audioStreamPlay() once this returns.
 *
 * The stream takes its own lock on `asset` (see audiostream_t.asset's own
 * comment), released by audioStreamDispose() - the asset must already be
 * loaded (ASSET_ENTRY_STATE_LOADED) when this is called.
 *
 * @param stream The audio stream to initialize.
 * @param asset The loaded asset to play - its type must be one this
 *              function supports (ASSET_LOADER_TYPE_WAV or
 *              ASSET_LOADER_TYPE_MP3).
 * @return Error indicating success or failure.
 */
 errorret_t audioStreamInit(audiostream_t *stream, assetentry_t *asset);
 /**
 * Returns the total number of decoded PCM frames (one sample per channel)
 * available in the stream's underlying data, regardless of its type -
 * dispatches to audioStreamPcmGetTotalFrames() or
 * audioStreamMp3GetTotalFrames(). Platform backends should use this rather
 * than a type-specific function directly, so they don't need to know or
 * care which type they're driving.
 *
 * @param stream The audio stream to query.
 * @return The total number of frames available.
 */
 size_t audioStreamGetTotalFrames(const audiostream_t *stream);
 /**
 * Seeks the stream's decode position to the given frame offset, regardless
 * of its type - dispatches to audioStreamPcmSeek() or audioStreamMp3Seek().
 *
 * @param stream The audio stream to seek.
 * @param frame Frame offset to seek to, relative to the start of the
 *              stream's decoded data.
 * @return Error indicating success or failure.
 */
 errorret_t audioStreamSeek(audiostream_t *stream, const size_t frame);
 /**
 * Reads up to frameCount frames of decoded PCM sample data from the
 * stream's current position, regardless of its type - dispatches to
 * audioStreamPcmRead() or audioStreamMp3Read(). See either for the exact
 * short-read-at-end-of-stream contract, which is identical for both.
 *
 * @param stream The audio stream to read from.
 * @param buffer Destination buffer, sized for at least frameCount frames.
 * @param frameCount Maximum number of frames to read.
 * @param outFramesRead Set to the number of frames actually read.
 * @return Error indicating success or failure.
 */
 errorret_t audioStreamRead(
  audiostream_t *stream,
  int16_t *buffer,
  const size_t frameCount,
  size_t *outFramesRead
 );
 /**
 * Begins or resumes playback of the given audio stream.
 *
 * @param stream The audio stream to play.
 */
 void audioStreamPlay(audiostream_t *stream);
 /**
 * Pauses playback of the given audio stream. Playback position is retained,
 * so audioStreamPlay() resumes from the same point.
 *
 * @param stream The audio stream to pause.
 */
 void audioStreamPause(audiostream_t *stream);
 /**
 * Seeks the given audio stream to the given position, in seconds, wrapping
 * into range if the position is outside [0, duration). Takes effect on the
 * next audioStreamUpdate() call for platforms that re-buffer per frame
 * (e.g. Linux); on PSP, which manages an entire playback pass on its own
 * feeder thread once started, a seek only takes effect the next time the
 * stream begins playing from a stopped state, not instantaneously mid-pass.
 *
 * @param stream The audio stream to seek.
 * @param position The new playback position, in seconds.
 */
 void audioStreamSetPosition(audiostream_t *stream, const float_t position);
 /**
 * Sets the loop region for the given audio stream: once playback reaches
 * loopStart, it jumps back to loopTo instead of continuing (or stopping,
 * if not looping). Has no effect unless looping is also enabled via
 * audioStreamSetLooping().
 *
 * @param stream The audio stream to update.
 * @param loopStart Where the loop segment ends, in seconds, or -1 to loop
 *                   the whole stream (the default).
 * @param loopTo Where the loop segment starts, in seconds.
 */
 void audioStreamSetLoopPoints(
  audiostream_t *stream,
  const float_t loopStart,
  const float_t loopTo
 );
 /**
 * Computes normalized left/right pan factors (0..1) for the given audio
 * stream's directionality. Callers multiply these by their own
 * platform-specific base volume representation.
 *
 * @param stream The audio stream to read directionality from.
 * @param outLeft Set to the left channel's pan factor.
 * @param outRight Set to the right channel's pan factor.
 */
 void audioStreamGetPanFactors(
  const audiostream_t *stream,
  float_t *outLeft,
  float_t *outRight
 );
 /**
 * Computes the stop frame for a playback pass starting at startFrame: the
 * current loop segment's end (stream->loopStart, converted to frames and
 * clamped to totalFrames) if looping is enabled and a loop start is set,
 * or totalFrames itself otherwise - including when startFrame has already
 * reached or passed the computed loop end (e.g. a seek landing in an
 * outro past the loop point), in which case this pass plays out to the
 * true end of the stream once instead of only the loop segment.
 *
 * @param stream The audio stream to compute this for.
 * @param startFrame This pass's starting frame offset.
 * @param totalFrames The stream's total decoded frame count
 *                     (audioStreamGetTotalFrames()).
 * @return This pass's stop frame offset.
 */
 size_t audioStreamComputeEndFrame(
  const audiostream_t *stream,
  const size_t startFrame,
  const size_t totalFrames
 );
 /**
 * Sets the playback volume of the given audio stream.
 *
 * @param stream The audio stream to update.
 * @param volume The new volume, from 0.0 (silent) to 1.0 (loudest).
 */
 void audioStreamSetVolume(audiostream_t *stream, const float_t volume);
 /**
 * Sets the stereo directionality (panning) of the given audio stream.
 *
 * @param stream The audio stream to update.
 * @param directionality The new panning value, from AUDIO_STREAM_LEFT to
 *                        AUDIO_STREAM_RIGHT.
 */
 void audioStreamSetDirectionality(
  audiostream_t *stream,
  const float_t directionality
 );
 /**
 * Sets whether the given audio stream loops back to loopTo (or the start
 * of the buffer, by default - see audioStreamSetLoopPoints()) when it
 * reaches loopStart (or the end of the buffer), rather than stopping and
 * firing onEnd.
 *
 * @param stream The audio stream to update.
 * @param looping Whether the stream should loop.
 */
 void audioStreamSetLooping(audiostream_t *stream, const bool_t looping);
 /**
 * Sets the maximum number of times the given audio stream is allowed to
 * loop before stopping (firing onEnd) instead of restarting again. Has no
 * effect unless looping is also enabled via audioStreamSetLooping(). Resets
 * the stream's current loop-restart progress back to 0, so the stream gets
 * the full count from this call onward.
 *
 * @param stream The audio stream to update.
 * @param loopLimit Maximum number of loop restarts, or 0 (the default) to
 *                   loop forever.
 */
 void audioStreamSetLoopLimit(audiostream_t *stream, const uint32_t loopLimit);
 /**
 * Updates the given audio stream, decoding new data and advancing playback
 * as needed. Should be called every frame for every active stream.
 *
 * @param stream The audio stream to update.
 * @return Error indicating success or failure.
 */
 errorret_t audioStreamUpdate(audiostream_t *stream);
 /**
 * Disposes the audio stream, stopping playback and releasing any resources
 * associated with it.
 *
 * @param stream The audio stream to dispose.
 * @return Error indicating success or failure.
 */
 errorret_t audioStreamDispose(audiostream_t *stream);
@@ -0,0 +1,167 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "audiostreammp3.h"
 #include "audiostream.h"
 #include "assert/assert.h"
 #include "util/math.h"
 #include "util/memory.h"
 errorret_t audioStreamMp3Init(audiostream_t *stream) {
  assertNotNull(stream, "Stream cannot be NULL.");
  assertNotNull(stream->asset, "Stream must have an asset assigned.");
  assertTrue(
    stream->asset->type == ASSET_LOADER_TYPE_MP3,
    "Asset is not an MP3 file."
  );
  const assetmp3file_t *mp3 = &stream->asset->data.mp3;
  stream->type = AUDIO_STREAM_TYPE_MP3;
  stream->sampleRate = mp3->sampleRate;
  stream->channels = mp3->channels;
  stream->duration = (float_t) mp3->totalFrames / (float_t) mp3->sampleRate;
  stream->mp3.pendingFrames = 0;
  stream->mp3.pendingPosition = 0;
  stream->mp3.position = 0;
  stream->mp3.totalFrames = mp3->totalFrames;
  // Each stream opens its own independent handle to the same underlying
  // asset file - see audiostreampcm.c's audioStreamPcmInit() for why.
  errorChain(assetFileInit(
    &stream->mp3.file, stream->asset->name, NULL, NULL
  ));
  errorChain(assetFileOpen(&stream->mp3.file));
  errorChain(assetFileRead(&stream->mp3.file, NULL, mp3->dataOffset));
  errorChain(audioStreamMp3DecoderInit(stream));
  errorChain(audioStreamPlatformInit(stream));
  errorOk();
 }
 errorret_t audioStreamMp3Dispose(audiostream_t *stream) {
  assertNotNull(stream, "Stream cannot be NULL.");
  assertTrue(stream->type == AUDIO_STREAM_TYPE_MP3, "Stream is not MP3.");
  errorChain(audioStreamMp3DecoderDispose(stream));
  errorChain(assetFileClose(&stream->mp3.file));
  errorChain(assetFileDispose(&stream->mp3.file));
  errorOk();
 }
 size_t audioStreamMp3GetTotalFrames(const audiostream_t *stream) {
  assertNotNull(stream, "Stream cannot be NULL.");
  assertTrue(stream->type == AUDIO_STREAM_TYPE_MP3, "Stream is not MP3.");
  return stream->mp3.totalFrames;
 }
 errorret_t audioStreamMp3Seek(audiostream_t *stream, const size_t frame) {
  assertNotNull(stream, "Stream cannot be NULL.");
  assertTrue(stream->type == AUDIO_STREAM_TYPE_MP3, "Stream is not MP3.");
  if(frame == stream->mp3.position) {
    errorOk();
  }
  // Every seek - forward or backward - restarts decoding from the very
  // start of the compressed stream and discards frames until reaching the
  // target; see this file's own header comment for why MP3 has no cheaper
  // option, unlike audioStreamPcmSeek()'s direct byte-offset seek.
  errorChain(audioStreamMp3DecoderRewind(stream));
  stream->mp3.position = 0;
  stream->mp3.pendingFrames = 0;
  stream->mp3.pendingPosition = 0;
  const size_t channels = stream->channels;
  int16_t discard[AUDIO_MP3_MAX_SAMPLES_PER_FRAME];
  while(stream->mp3.position < frame) {
    size_t decodedFrames = 0;
    errorChain(
      audioStreamMp3DecoderDecodeFrame(stream, discard, &decodedFrames)
    );
    if(decodedFrames == 0) {
      // Ran out of stream before reaching the target - clamp rather than
      // erroring, same tolerance audioStreamPcmRead() has for a
      // shorter-than-declared asset.
      break;
    }
    const size_t framesNeeded = frame - stream->mp3.position;
    if(decodedFrames <= framesNeeded) {
      stream->mp3.position += decodedFrames;
      continue;
    }
    // This frame overshoots the target - keep the excess as pending so
    // the next Read() starts exactly at `frame` instead of skipping past
    // it.
    const size_t keepFrames = decodedFrames - framesNeeded;
    memoryMove(
      discard, discard + (framesNeeded * channels),
      keepFrames * channels * sizeof(int16_t)
    );
    memoryCopy(
      stream->mp3.pending, discard, keepFrames * channels * sizeof(int16_t)
    );
    stream->mp3.pendingFrames = keepFrames;
    stream->mp3.pendingPosition = 0;
    stream->mp3.position = frame;
  }
  errorOk();
 }
 errorret_t audioStreamMp3Read(
  audiostream_t *stream,
  int16_t *buffer,
  const size_t frameCount,
  size_t *outFramesRead
 ) {
  assertNotNull(stream, "Stream cannot be NULL.");
  assertNotNull(buffer, "Buffer cannot be NULL.");
  assertNotNull(outFramesRead, "outFramesRead cannot be NULL.");
  assertTrue(stream->type == AUDIO_STREAM_TYPE_MP3, "Stream is not MP3.");
  const size_t channels = stream->channels;
  size_t framesWritten = 0;
  while(framesWritten < frameCount) {
    if(stream->mp3.pendingPosition >= stream->mp3.pendingFrames) {
      size_t decodedFrames = 0;
      errorChain(audioStreamMp3DecoderDecodeFrame(
        stream, stream->mp3.pending, &decodedFrames
      ));
      stream->mp3.pendingFrames = decodedFrames;
      stream->mp3.pendingPosition = 0;
      if(decodedFrames == 0) break; // Genuine end of stream.
    }
    const size_t framesAvailable =
      stream->mp3.pendingFrames - stream->mp3.pendingPosition;
    const size_t framesToCopy =
      mathMin(frameCount - framesWritten, framesAvailable);
    memoryCopy(
      buffer + (framesWritten * channels),
      stream->mp3.pending + (stream->mp3.pendingPosition * channels),
      framesToCopy * channels * sizeof(int16_t)
    );
    stream->mp3.pendingPosition += framesToCopy;
    framesWritten += framesToCopy;
  }
  stream->mp3.position += framesWritten;
  *outFramesRead = framesWritten;
  errorOk();
 }
@@ -0,0 +1,140 @@
 /**
 * 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 "asset/assetfile.h"
 #include "audio/audiostreammp3decoder.h"
 typedef struct audiostream_s audiostream_t;
 // How many interleaved PCM samples (not frames - samples, i.e. frames *
 // channels) a single audioStreamMp3DecoderDecodeFrame() call is ever
 // allowed to produce. Sizes the pending-sample buffer below, which every
 // decoder backend writes directly into - this must be sized to the
 // largest of them, not just "one MPEG frame":
 //  - libmad (software, Linux/Dolphin): always exactly one frame, 1152
 //    samples/channel for MPEG-1 Layer III, doubled here for stereo.
 //  - sceMp3 (hardware, PSP): its own pcmBuf is provisioned at double that
 //    (see AUDIO_MP3_PSP_PCM_BUF_SIZE) - i.e. sceMp3Decode() can
 //    legitimately hand back more than one frame's worth in a single call.
 //    Sizing this for only one frame silently overflowed stream->mp3.pending
 //    on real hardware whenever that happened - confirmed as the cause of
 //    very intermittent audio corruption/clicking, since it only bit when
 //    sceMp3 actually returned the larger amount.
 // So this covers the larger (PSP) case; libmad's decode is safely well
 // within it.
 #define AUDIO_MP3_MAX_SAMPLES_PER_FRAME (1152 * 2 * 2)
 typedef struct {
  // This stream's own private handle into its asset's underlying file -
  // see audiostreampcm_t.file's own comment for why this isn't shared
  // across streams playing the same asset. Holds compressed MP3 bytes;
  // the decoder backend (audiostreammp3decoder.h) reads from it directly.
  assetfile_t file;
  // Opaque per-platform decoder state - a reserved sceMp3 handle plus its
  // buffers on PSP, or libmad's mad_stream/mad_frame/mad_synth state plus a
  // sliding compressed-byte window on the libmad-based software backend
  // (Linux/Dolphin). Defined by whichever audiostreammp3decoder.h is
  // actually visible when this file is compiled - see that header's own
  // comment.
  audiostreammp3decoder_t decoder;
  // One decoded MPEG frame's worth of PCM, held here across Read() calls
  // since a frame (576 or 1152 samples/channel) rarely lines up exactly
  // with whatever frameCount a caller asks for. pendingPosition marks how
  // many of the first pendingFrames frames have already been consumed.
  int16_t pending[AUDIO_MP3_MAX_SAMPLES_PER_FRAME];
  size_t pendingFrames;
  size_t pendingPosition;
  // Current logical PCM frame position, relative to the start of the
  // decoded stream - decoding is push-forward-only (see
  // audioStreamMp3Seek()'s own comment on why a backward seek re-decodes
  // from the start rather than truly random-accessing).
  size_t position;
  // Total decoded PCM frame count for the whole clip - copied from the
  // asset's parsed metadata at Init (see assetmp3file_t.totalFrames),
  // exact if a Xing/Info header was present, otherwise an estimate.
  size_t totalFrames;
 } audiostreammp3_t;
 /**
 * Configures the given MP3 audio stream from its already-assigned asset
 * (see audiostream_t.asset - set by audioStreamInit(), which is what
 * should be calling this, not application code directly): opens this
 * stream's own private file handle onto the asset's compressed MPEG data,
 * and initializes the platform decoder backend
 * (audioStreamMp3DecoderInit()).
 *
 * Must be called after stream->asset is set and before audioStreamPlay().
 *
 * @param stream The audio stream to configure.
 * @return Error indicating success or failure.
 */
 errorret_t audioStreamMp3Init(audiostream_t *stream);
 /**
 * Disposes the given MP3 audio stream's decoder backend and private file
 * handle.
 *
 * @param stream The audio stream to dispose.
 * @return Error indicating success or failure.
 */
 errorret_t audioStreamMp3Dispose(audiostream_t *stream);
 /**
 * Returns the total number of frames (one sample per channel) available in
 * the stream's underlying MP3 data - see assetmp3file_t.totalFrames's own
 * comment on why this is sometimes an estimate rather than an exact count,
 * unlike audioStreamPcmGetTotalFrames().
 *
 * @param stream The audio stream to query. Must be AUDIO_STREAM_TYPE_MP3.
 * @return The total number of frames available.
 */
 size_t audioStreamMp3GetTotalFrames(const audiostream_t *stream);
 /**
 * Seeks the stream's decode position to the given frame offset. Unlike
 * audioStreamPcmSeek(), this is never cheap: MPEG frames aren't
 * independently decodable (each one's bit reservoir can depend on data
 * carried over from prior frames), so there's no equivalent of PCM's
 * direct byte-offset seek - every call, forward or backward, rewinds the
 * decoder to the very start of the compressed stream and decodes (and
 * discards) frames until reaching the target. Acceptable for this engine's
 * actual use (looping background music, where loopTo is typically near
 * the start anyway), but a real, non-constant cost for a seek deep into a
 * long track.
 *
 * @param stream The audio stream to seek. Must be AUDIO_STREAM_TYPE_MP3.
 * @param frame Frame offset to seek to, relative to the start of the
 *              decoded stream.
 * @return Error indicating success or failure.
 */
 errorret_t audioStreamMp3Seek(audiostream_t *stream, const size_t frame);
 /**
 * Reads up to frameCount frames of PCM sample data from the stream's
 * current position, advancing it by however many frames were actually
 * read. Reads fewer than frameCount (down to zero) once the underlying
 * MP3 data is exhausted, rather than erroring - same contract as
 * audioStreamPcmRead().
 *
 * @param stream The audio stream to read from. Must be AUDIO_STREAM_TYPE_MP3.
 * @param buffer Destination buffer, sized for at least frameCount frames.
 * @param frameCount Maximum number of frames to read.
 * @param outFramesRead Set to the number of frames actually read.
 * @return Error indicating success or failure.
 */
 errorret_t audioStreamMp3Read(
  audiostream_t *stream,
  int16_t *buffer,
  const size_t frameCount,
  size_t *outFramesRead
 );
@@ -0,0 +1,179 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "audiostreampcm.h"
 #include "audiostream.h"
 #include "assert/assert.h"
 #include "util/math.h"
 #include "util/memory.h"
 #include "util/endian.h"
 errorret_t audioStreamPcmInit(audiostream_t *stream) {
  assertNotNull(stream, "Stream cannot be NULL.");
  assertNotNull(stream->asset, "Stream must have an asset assigned.");
  assertTrue(
    stream->asset->type == ASSET_LOADER_TYPE_WAV,
    "Asset is not a WAV file."
  );
  assetwavfile_t *wav = &stream->asset->data.wav;
  stream->type = AUDIO_STREAM_TYPE_PCM;
  stream->sampleRate = wav->sampleRate;
  stream->channels = wav->channels;
  stream->duration = (
    (float_t) audioStreamPcmGetTotalFrames(stream) /
    (float_t) wav->sampleRate
  );
  // Each stream opens its own independent handle to the same underlying
  // asset file, rather than sharing a single handle on the asset entry -
  // multiple streams playing the same asset concurrently (e.g. two
  // simultaneous plays of the same sound effect) would otherwise fight
  // over one shared read position. This isn't the final answer for that
  // (a shared decode/cache layer would scale better than N independent
  // decompression streams of the same data), but it's a correct one for
  // now - a problem to revisit once it actually matters.
  errorChain(assetFileInit(
    &stream->pcm.file, stream->asset->name, NULL, NULL
  ));
  errorChain(assetFileOpen(&stream->pcm.file));
  errorChain(assetFileRead(&stream->pcm.file, NULL, wav->dataOffset));
  errorChain(audioStreamPlatformInit(stream));
  errorOk();
 }
 errorret_t audioStreamPcmDispose(audiostream_t *stream) {
  assertNotNull(stream, "Stream cannot be NULL.");
  assertTrue(stream->type == AUDIO_STREAM_TYPE_PCM, "Stream is not PCM.");
  errorChain(assetFileClose(&stream->pcm.file));
  errorChain(assetFileDispose(&stream->pcm.file));
  errorOk();
 }
 size_t audioStreamPcmGetTotalFrames(const audiostream_t *stream) {
  assertNotNull(stream, "Stream cannot be NULL.");
  assertTrue(stream->type == AUDIO_STREAM_TYPE_PCM, "Stream is not PCM.");
  const assetwavfile_t *wav = &stream->asset->data.wav;
  const size_t sourceFrameSize = (
    stream->channels * (wav->bitsPerSample / 8)
  );
  return wav->dataSize / sourceFrameSize;
 }
 errorret_t audioStreamPcmSeek(audiostream_t *stream, const size_t frame) {
  assertNotNull(stream, "Stream cannot be NULL.");
  assertTrue(stream->type == AUDIO_STREAM_TYPE_PCM, "Stream is not PCM.");
  assetwavfile_t *wav = &stream->asset->data.wav;
  const size_t sourceFrameSize = (
    stream->channels * (wav->bitsPerSample / 8)
  );
  const size_t targetByte = wav->dataOffset + (frame * sourceFrameSize);
  assertTrue(
    frame * sourceFrameSize <= wav->dataSize,
    "Seek frame is beyond the end of the PCM data."
  );
  const size_t currentByte = (size_t) stream->pcm.file.position;
  if(targetByte < currentByte) {
    // A rewind is needed to move the read cursor earlier once it's
    // already advanced past a point - assetFileRewind() takes the cheap
    // in-place seek path since every dusk.dsk entry is stored
    // uncompressed.
    errorChain(assetFileRewind(&stream->pcm.file));
    errorChain(assetFileRead(&stream->pcm.file, NULL, targetByte));
  } else if(targetByte > currentByte) {
    errorChain(assetFileRead(
      &stream->pcm.file, NULL, targetByte - currentByte
    ));
  }
  errorOk();
 }
 errorret_t audioStreamPcmRead(
  audiostream_t *stream,
  int16_t *buffer,
  const size_t frameCount,
  size_t *outFramesRead
 ) {
  assertNotNull(stream, "Stream cannot be NULL.");
  assertNotNull(buffer, "Buffer cannot be NULL.");
  assertNotNull(outFramesRead, "outFramesRead cannot be NULL.");
  assertTrue(stream->type == AUDIO_STREAM_TYPE_PCM, "Stream is not PCM.");
  assetwavfile_t *wav = &stream->asset->data.wav;
  const size_t channels = stream->channels;
  const size_t sourceSampleBytes = wav->bitsPerSample / 8;
  const size_t sourceFrameSize = channels * sourceSampleBytes;
  const size_t dataEndByte = wav->dataOffset + wav->dataSize;
  const size_t currentByte = (size_t) stream->pcm.file.position;
  const size_t bytesAvailable = (
    currentByte < dataEndByte ? dataEndByte - currentByte : 0
  );
  const size_t framesAvailable = bytesAvailable / sourceFrameSize;
  const size_t framesToRead = mathMin(frameCount, framesAvailable);
  if(framesToRead == 0) {
    *outFramesRead = 0;
    errorOk();
  }
  if(sourceSampleBytes == sizeof(int16_t)) {
    // Output format already matches the source in width, but WAV samples
    // are always little-endian per the format spec regardless of host -
    // read straight through, then fix up byte order in place. A no-op on
    // every little-endian platform (endianLittleToHost16() compiles down
    // to returning its argument unchanged there) - only actually swaps
    // anything on a big-endian host (Dolphin/GameCube/Wii).
    errorChain(assetFileRead(
      &stream->pcm.file, buffer, framesToRead * sourceFrameSize
    ));
    const size_t sampleCount = framesToRead * channels;
    for(size_t i = 0; i < sampleCount; i++) {
      buffer[i] = (int16_t) endianLittleToHost16((uint16_t) buffer[i]);
    }
  } else {
    // 24-bit source (the only other width assetWavParseHeader() accepts) -
    // read the raw 3-byte samples into a scratch buffer, then truncate
    // each down to 16-bit, since none of PSP/Dolphin's audio hardware (or
    // SDL2 on Linux) accepts anything wider - see assetwavfile_t's own
    // comment on bitsPerSample.
    assertTrue(sourceSampleBytes == 3, "Unsupported PCM sample width.");
    const size_t rawBytes = framesToRead * sourceFrameSize;
    uint8_t *raw = memoryAllocate(rawBytes);
    errorret_t ret = assetFileRead(&stream->pcm.file, raw, rawBytes);
    if(errorIsNotOk(ret)) {
      memoryFree(raw);
      errorChain(ret);
    }
    // 24-bit PCM samples are little-endian two's complement - the top two
    // bytes of each (indices 1 and 2) already form that same value
    // truncated to 16-bit (equivalent to an arithmetic right-shift by 8
    // bits, which preserves the sign correctly since byte 2 carries it).
    const size_t sampleCount = framesToRead * channels;
    for(size_t i = 0; i < sampleCount; i++) {
      const uint8_t *sample = raw + (i * 3);
      buffer[i] = (int16_t) (sample[1] | (sample[2] << 8));
    }
    memoryFree(raw);
  }
  *outFramesRead = framesToRead;
  errorOk();
 }
@@ -0,0 +1,96 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "asset/assetfile.h"
 typedef struct audiostream_s audiostream_t;
 typedef struct {
  // This stream's own private handle into its asset's underlying file -
  // deliberately not shared with any other stream reading the same asset
  // (see audioStreamPcmInit's own comment for why). Its read cursor is
  // what audioStreamPcmRead()/audioStreamPcmSeek() operate on.
  assetfile_t file;
 } audiostreampcm_t;
 /**
 * Configures the given PCM audio stream from its already-assigned asset
 * (see audiostream_t.asset - set by audioStreamInit(), which is what
 * should be calling this, not application code directly) rather than
 * taking raw decoded data: sampleRate/channels/duration are read from the
 * asset's parsed WAV header, and a private file handle is opened for
 * reading sample data on demand as playback consumes it (see
 * audioStreamPcmRead()) - the PCM data itself is never read into memory
 * all at once, so this works the same regardless of how long the
 * underlying clip is.
 *
 * Must be called after stream->asset is set and before audioStreamPlay().
 *
 * @param stream The audio stream to configure.
 * @return Error indicating success or failure.
 */
 errorret_t audioStreamPcmInit(audiostream_t *stream);
 /**
 * Disposes the given PCM audio stream's own private file handle.
 *
 * @param stream The audio stream to dispose.
 * @return Error indicating success or failure.
 */
 errorret_t audioStreamPcmDispose(audiostream_t *stream);
 /**
 * Returns the total number of frames (one sample per channel) available
 * in the stream's underlying PCM data - NOT simply the asset's declared
 * byte size divided by a 16-bit frame size, since the source data isn't
 * always 16-bit even though audioStreamPcmRead() always produces 16-bit
 * output (see assetwavfile_t.bitsPerSample). Platform backends should use
 * this rather than computing frame counts from dataSize themselves.
 *
 * @param stream The audio stream to query. Must be AUDIO_STREAM_TYPE_PCM.
 * @return The total number of frames available.
 */
 size_t audioStreamPcmGetTotalFrames(const audiostream_t *stream);
 /**
 * Seeks the stream's private read cursor to the given frame offset
 * (relative to the start of the PCM data - the same units as
 * audiostream_t's startFrame/loopStart/loopTo, once converted from
 * seconds). Seeking backward re-reads from the start of the underlying
 * asset file (see assetFileRewind()), which is a cheap in-place seek
 * since every dusk.dsk entry is stored uncompressed.
 *
 * @param stream The audio stream to seek. Must be AUDIO_STREAM_TYPE_PCM.
 * @param frame Frame offset to seek to, relative to the start of the PCM
 *              data.
 * @return Error indicating success or failure.
 */
 errorret_t audioStreamPcmSeek(audiostream_t *stream, const size_t frame);
 /**
 * Reads up to frameCount frames of PCM sample data from the stream's
 * current read position, advancing it by however many frames were
 * actually read. Reads fewer than frameCount (down to zero) once the
 * underlying asset's PCM data is exhausted, rather than erroring - it's
 * up to the caller (platform code, which already knows about loop points)
 * to request no more than what it wants read from within the current
 * loop segment or the true end of the clip.
 *
 * @param stream The audio stream to read from. Must be AUDIO_STREAM_TYPE_PCM.
 * @param buffer Destination buffer, sized for at least frameCount frames.
 * @param frameCount Maximum number of frames to read.
 * @param outFramesRead Set to the number of frames actually read.
 * @return Error indicating success or failure.
 */
 errorret_t audioStreamPcmRead(
  audiostream_t *stream,
  int16_t *buffer,
  const size_t frameCount,
  size_t *outFramesRead
 );
@@ -0,0 +1,50 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "audiostreamtype.h"
 #include "util/string.h"
 const audiostreamassettypeinfo_t
 AUDIO_STREAM_TYPE_FOR_ASSET_TYPE[ASSET_LOADER_TYPE_COUNT] = {
  [ASSET_LOADER_TYPE_WAV] = {
    .type = AUDIO_STREAM_TYPE_PCM, .extension = ".wav"
  },
  [ASSET_LOADER_TYPE_MP3] = {
    .type = AUDIO_STREAM_TYPE_MP3, .extension = ".mp3"
  }
 };
 assetloadertype_t audioStreamAssetTypeForPath(const char_t *path) {
  for(assetloadertype_t i = 0; i < ASSET_LOADER_TYPE_COUNT; i++) {
    const char_t *extension = AUDIO_STREAM_TYPE_FOR_ASSET_TYPE[i].extension;
    if(extension != NULL && stringEndsWithCaseInsensitive(path, extension)) {
      return i;
    }
  }
  return ASSET_LOADER_TYPE_NULL;
 }
 audistreamtype_t audioStreamTypeForAssetType(
  const assetloadertype_t assetType
 ) {
  return AUDIO_STREAM_TYPE_FOR_ASSET_TYPE[assetType].type;
 }
 assetloadertype_t audioStreamAssetTypeForStreamType(
  const audistreamtype_t streamType
 ) {
  if(streamType == AUDIO_STREAM_TYPE_NULL) return ASSET_LOADER_TYPE_NULL;
  for(assetloadertype_t i = 0; i < ASSET_LOADER_TYPE_COUNT; i++) {
    if(AUDIO_STREAM_TYPE_FOR_ASSET_TYPE[i].type == streamType) {
      return i;
    }
  }
  return ASSET_LOADER_TYPE_NULL;
 }
@@ -0,0 +1,71 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "dusk.h"
 #include "asset/loader/assetloader.h"
 typedef enum {
  AUDIO_STREAM_TYPE_NULL,
  AUDIO_STREAM_TYPE_PCM,
  AUDIO_STREAM_TYPE_MP3,
  AUDIO_STREAM_TYPE_COUNT
 } audistreamtype_t;
 typedef struct {
  // The audistreamtype_t an audio stream backed by this asset type should
  // become - AUDIO_STREAM_TYPE_NULL (the zero-initialized default) for any
  // asset type that can't back an audio stream.
  audistreamtype_t type;
  // This asset type's file extension, including the leading '.' (e.g.
  // ".wav"). NULL for any asset type that can't back an audio stream.
  const char_t *extension;
 } audiostreamassettypeinfo_t;
 // Maps an assetloadertype_t to the info describing the audio stream it
 // backs. Indexed directly by assetentry_t.type; see audioStreamInit()'s own
 // use of this for the canonical "is this asset type supported" check. Use
 // the functions below rather than indexing this directly, except where
 // you already have an assetloadertype_t in hand.
 extern const audiostreamassettypeinfo_t
 AUDIO_STREAM_TYPE_FOR_ASSET_TYPE[ASSET_LOADER_TYPE_COUNT];
 /**
 * Determines which asset loader type a file path's extension corresponds
 * to, by matching it against AUDIO_STREAM_TYPE_FOR_ASSET_TYPE's own
 * extensions (case-insensitively).
 *
 * @param path The file path to inspect, e.g. "audio/boa.mp3".
 * @return The matching assetloadertype_t, or ASSET_LOADER_TYPE_NULL if the
 *         path's extension doesn't match any audio asset type.
 */
 assetloadertype_t audioStreamAssetTypeForPath(const char_t *path);
 /**
 * Looks up the audistreamtype_t an audio stream backed by the given asset
 * type should become.
 *
 * @param assetType The asset loader type to look up.
 * @return The matching audistreamtype_t, or AUDIO_STREAM_TYPE_NULL if
 *         assetType can't back an audio stream.
 */
 audistreamtype_t audioStreamTypeForAssetType(const assetloadertype_t assetType);
 /**
 * Looks up which asset loader type backs audio streams of the given type -
 * the reverse of audioStreamTypeForAssetType(). Scans
 * AUDIO_STREAM_TYPE_FOR_ASSET_TYPE for the first entry whose type matches,
 * since it isn't itself indexed by audistreamtype_t.
 *
 * @param streamType The audio stream type to look up.
 * @return The matching assetloadertype_t, or ASSET_LOADER_TYPE_NULL if
 *         streamType is AUDIO_STREAM_TYPE_NULL or otherwise unmapped.
 */
 assetloadertype_t audioStreamAssetTypeForStreamType(
  const audistreamtype_t streamType
 );
@@ -17,11 +17,9 @@ console_t CONSOLE;
 void consoleInit(void) {
  memoryZero(&CONSOLE, sizeof(console_t));
-  CONSOLE.visible = true;
+  CONSOLE.visible = false;
-
+  // CONSOLE.visible = true;
  #ifdef DUSK_CONSOLE_POSIX
  threadMutexInit(&CONSOLE.printMutex);
  #endif
 }
 void consolePrint(const char_t *message, ...) {
@@ -32,20 +30,14 @@ void consolePrint(const char_t *message, ...) {
  int32_t len = stringFormatVA(buffer, CONSOLE_LINE_MAX, message, args);
  va_end(args);
  #ifdef DUSK_CONSOLE_POSIX
  threadMutexLock(&CONSOLE.printMutex);
  #endif
  memoryMove(
    CONSOLE.line[0],
    CONSOLE.line[1],
    (CONSOLE_HISTORY_MAX - 1) * CONSOLE_LINE_MAX
  );
  memoryCopy(CONSOLE.line[CONSOLE_HISTORY_MAX - 1], buffer, len + 1);
  #ifdef DUSK_CONSOLE_POSIX
  threadMutexUnlock(&CONSOLE.printMutex);
  #endif
  logDebug("%s\n", buffer);
 }
@@ -61,7 +53,5 @@ void consoleUpdate(void) {
 }
 void consoleDispose(void) {
  #ifdef DUSK_CONSOLE_POSIX
  threadMutexDispose(&CONSOLE.printMutex);
  #endif
 }
@@ -6,24 +6,18 @@
 */
 #pragma once
 #include "consoledefs.h"
 #include "error/error.h"
 #include "dusk.h"
 #ifdef DUSK_CONSOLE_POSIX
 #include "thread/thread.h"
-  #include <poll.h>
+
-  #include <unistd.h>
+#define CONSOLE_LINE_MAX 128
-  #define CONSOLE_POSIX_POLL_RATE 75
+#define CONSOLE_HISTORY_MAX 16
-#endif
+#define CONSOLE_EXEC_BUFFER_MAX 32
 typedef struct {
  char_t line[CONSOLE_HISTORY_MAX][CONSOLE_LINE_MAX];
  bool_t visible;
  #ifdef DUSK_CONSOLE_POSIX
  threadmutex_t printMutex;
  #endif
 } console_t;
 extern console_t CONSOLE;
@@ -21,7 +21,7 @@ add_subdirectory(texture)
 # Color definitions
 dusk_run_python(
  dusk_color_defs
-  tools.color.csv
+  tools.color
    --csv ${CMAKE_CURRENT_SOURCE_DIR}/color.csv
    --output ${DUSK_GENERATED_HEADERS_DIR}/display/color.h
 )
@@ -7,7 +7,8 @@
 #include "display/display.h"
 #include "display/framebuffer/framebuffer.h"
-#include "scene/scene.h"
+#include "entity/entity.h"
 #include "entity/entityrender.h"
 #include "display/spritebatch/spritebatch.h"
 #include "display/mesh/quad.h"
 #include "display/mesh/cube.h"
@@ -16,7 +17,6 @@
 #include "display/mesh/capsule.h"
 #include "display/mesh/triprism.h"
 #include "display/screen/screen.h"
 #include "ui/ui.h"
 #include "display/text/text.h"
 #include "assert/assert.h"
 #include "util/memory.h"
@@ -33,13 +33,17 @@ errorret_t displayInit(void) {
  #ifdef displayPlatformInit
    errorChain(displayPlatformInit());
  #endif
  // Set initial state
  errorChain(displaySetState((displaystate_t){ .flags = 0 }));
  // Init the fixed textures
  errorChain(textureInit(
-    &TEXTURE_WHITE, 4, 4,
+    &TEXTURE_WHITE, TEXTURE_FIXED_WIDTH, TEXTURE_FIXED_HEIGHT,
    TEXTURE_FORMAT_RGBA, (texturedata_t){ .rgbaColors = TEXTURE_WHITE_PIXELS }
  ));
  errorChain(textureInit(
-    &TEXTURE_TEST, 4, 4,
+    &TEXTURE_TEST, TEXTURE_FIXED_WIDTH, TEXTURE_FIXED_HEIGHT,
    TEXTURE_FORMAT_RGBA, (texturedata_t){ .rgbaColors = TEXTURE_TEST_PIXELS }
  ));
@@ -51,13 +55,13 @@ errorret_t displayInit(void) {
  errorChain(capsuleInit());
  errorChain(triPrismInit());
  // Init the subsystems
  errorChain(frameBufferInitBackBuffer());
  errorChain(spriteBatchInit());
  errorChain(textInit());
  errorChain(screenInit());
  // Setup initial shader with default values
  errorChain(shaderListInit());
  errorOk();
@@ -72,14 +76,14 @@ errorret_t displayUpdate(void) {
  spriteBatchClear();
  errorChain(frameBufferBind(NULL));
-  // Bind screen and render scene
+  // Bind screen and render the entity world
  errorChain(screenBind());
  frameBufferClear(
    FRAMEBUFFER_CLEAR_COLOR | FRAMEBUFFER_CLEAR_DEPTH,
    SCREEN.background
  );
-  errorChain(sceneRender());
+  errorChain(entityRenderAll());
  // Finish up
  screenUnbind();
@@ -33,6 +33,14 @@
  #endif
 #endif
 #ifndef DUSK_DISPLAY_SCALE_UI
  #define DUSK_DISPLAY_SCALE_UI 1
 #endif
 #ifndef DUSK_DISPLAY_SCALE_3D
  #define DUSK_DISPLAY_SCALE_3D 1
 #endif
 // Main Display Struct, platform-speicifc
 typedef displayplatform_t display_t;
@@ -20,9 +20,6 @@ errorret_t capsuleInit() {
    0.5f,
    CAPSULE_CAP_RINGS,
    CAPSULE_SECTORS
    #if MESH_ENABLE_COLOR
      , COLOR_WHITE_4B
    #endif
  );
  errorChain(meshInit(
    &CAPSULE_MESH_SIMPLE,
@@ -40,9 +37,6 @@ void capsuleBuffer(
  const float_t halfHeight,
  const int32_t capRings,
  const int32_t sectors
  #if MESH_ENABLE_COLOR
    , const color_t color
  #endif
 ) {
  assertNotNull(vertices, "Vertices cannot be NULL");
  assertNotNull(center, "Center vector cannot be NULL");
@@ -53,17 +47,6 @@ void capsuleBuffer(
  const float_t sectorStep = 2.0f * (float_t)GLM_PI / (float_t)sectors;
  int32_t vi = 0;
  /* Helper macro: write one vertex. */
  #if MESH_ENABLE_COLOR
    #define CAP_VERT(px, py, pz, u, v) \
      vertices[vi].color    = color; \
      vertices[vi].pos[0]   = (px); \
      vertices[vi].pos[1]   = (py); \
      vertices[vi].pos[2]   = (pz); \
      vertices[vi].uv[0]    = (u);  \
      vertices[vi].uv[1]    = (v);  \
      vi++;
  #else
  #define CAP_VERT(px, py, pz, u, v) \
    vertices[vi].pos[0]   = (px); \
    vertices[vi].pos[1]   = (py); \
@@ -71,7 +54,6 @@ void capsuleBuffer(
    vertices[vi].uv[0]    = (u);  \
    vertices[vi].uv[1]    = (v);  \
    vi++;
  #endif
  /* ---- Top hemisphere ---- */
  /* phi ranges from PI/2 (top pole) down to 0 (equator). */
@@ -7,7 +7,6 @@
 #pragma once
 #include "display/mesh/mesh.h"
 #include "display/color.h"
 #define CAPSULE_CAP_RINGS 4
 #define CAPSULE_SECTORS   16
@@ -46,7 +45,4 @@ void capsuleBuffer(
  const float_t halfHeight,
  const int32_t capRings,
  const int32_t sectors
  #if MESH_ENABLE_COLOR
    , const color_t color
  #endif
 );
@@ -14,12 +14,7 @@ meshvertex_t CUBE_MESH_SIMPLE_VERTICES[CUBE_VERTEX_COUNT];
 errorret_t cubeInit() {
  vec3 min = { 0.0f, 0.0f, 0.0f };
  vec3 max = { 1.0f, 1.0f, 1.0f };
-  cubeBuffer(
+  cubeBuffer(CUBE_MESH_SIMPLE_VERTICES, min, max);
    CUBE_MESH_SIMPLE_VERTICES, min, max
    #if MESH_ENABLE_COLOR
      , COLOR_WHITE_4B
    #endif
  );
  errorChain(meshInit(
    &CUBE_MESH_SIMPLE,
    CUBE_PRIMITIVE_TYPE,
@@ -29,31 +24,17 @@ errorret_t cubeInit() {
  errorOk();
 }
 // Helper macro: set one vertex position, UV and color.
 #if MESH_ENABLE_COLOR
  #define CUBE_VERT(i, px, py, pz, u, v) \
    vertices[i].color  = color; \
    vertices[i].pos[0] = (px); \
    vertices[i].pos[1] = (py); \
    vertices[i].pos[2] = (pz); \
    vertices[i].uv[0]  = (u);  \
    vertices[i].uv[1]  = (v);
 #else
 #define CUBE_VERT(i, px, py, pz, u, v) \
  vertices[i].pos[0] = (px); \
  vertices[i].pos[1] = (py); \
  vertices[i].pos[2] = (pz); \
  vertices[i].uv[0]  = (u);  \
  vertices[i].uv[1]  = (v);
 #endif
 void cubeBuffer(
  meshvertex_t *vertices,
  const vec3 min,
  const vec3 max
  #if MESH_ENABLE_COLOR
    , const color_t color
  #endif
 ) {
  assertNotNull(vertices, "Vertices cannot be NULL");
  assertNotNull(min, "Min vector cannot be NULL");
@@ -7,7 +7,6 @@
 #pragma once
 #include "display/mesh/mesh.h"
 #include "display/color.h"
 #define CUBE_FACE_COUNT 6
 #define CUBE_VERTICES_PER_FACE 6
@@ -37,7 +36,4 @@ void cubeBuffer(
  meshvertex_t *vertices,
  const vec3 min,
  const vec3 max
  #if MESH_ENABLE_COLOR
    , const color_t color
  #endif
 );
@@ -7,20 +7,11 @@
 #pragma once
 #include "dusk.h"
 #include "display/color.h"
 #ifndef MESH_ENABLE_COLOR
  #define MESH_ENABLE_COLOR 0
 #endif
 #define MESH_VERTEX_UV_SIZE 2
 #define MESH_VERTEX_POS_SIZE 3
 typedef struct {
  #if MESH_ENABLE_COLOR
    color_t color;
  #endif
  float_t uv[MESH_VERTEX_UV_SIZE];
  float_t pos[MESH_VERTEX_POS_SIZE];
 } meshvertex_t;