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

The old widget system (archive/dusk/ui/) depended on infrastructure this rewrite deleted -- a static X-macro element list, a 9-slice UI_FRAME, and a global gamepad/keyboard focus stack -- so everything below is rebuilt on top of the new native uielement_t pool + parent/child tree instead, gamepad/keyboard-only (no mouse support exists in the input system). New JS widgets (assets/scripts/), all pure composites of Label/Rectangle following the Button.js pattern: Checkbox, Tab, Slider, Dropdown. Slider/ Dropdown expose a directionInput(dx, dy) hook so a menu can hand them LEFT/RIGHT before falling back to cursor movement. New Menu.js replaces the old global uifocus_t stack: a small push/pop stack of Menu instances where only the topmost consumes CANCEL/ACCEPT/ direction input each tick (needed for nested modals -- a Settings sub-page menu plus a "discard changes?" Confirm can be open at once). Held-direction repeat timing matches the old 0.5s delay / 0.1s repeat. New overlay composites (added via a new UI.addOverlay()/UI.removeOverlay(), always drawn/updated after normal roots): FpsCounter, ConsoleOverlay (one Label per console history line, driven directly rather than via add() since History (16) exceeds the 8-children-per-element cap), Crop (letterbox/pillarbox bars), and Fullbox (a reusable tweened full-screen fade covering both the old fullbox and transition effects -- reuses shared instances rather than allocate-and-dispose, since disposing an element from inside its own render() callback risks the same JerryScript refcount corruption hit earlier in this rewrite). New Confirm.js (Yes/No dialog) and Settings.js (+ SettingsGeneral/ SettingsInput sub-pages) built on Menu. Display/Audio settings pages are intentionally not ported -- neither had a real backing engine system even in the old code. Frame is a flat Rectangle for now, not real 9-slice (a genuinely bigger native lift, deliberately deferred). Small native binding additions needed by the above, each with its own unit test: Time.renderDelta, Console.lineCount/getLine/visible/ consumeDirty, a new Screen module, a new Locale module, Input.deadzone, a new Save module, and Label.color (was missing entirely). Also fixes a real gap from the UI.addOverlay() work: uiElementDispose() wasn't removing disposed elements from the new overlay root array, which would have left dangling ids behind. Co-Authored-By: Claude Sonnet 5 <[email protected]>
Rebuild UI as a scriptable element tree, archive the old system
2026-08-14 09:05:11 -05:00 · 2026-08-13 11:13:23 -05:00 · 2026-08-11 23:33:29 -05:00 · 2026-08-11 16:03:32 -05:00 · 2026-08-11 14:34:51 -05:00 · 2026-08-11 13:11:22 -05:00
1193 changed files with 66619 additions and 17708 deletions
@@ -1,5 +0,0 @@
 FROM devkitpro/devkitppc
 RUN apt update && \
    apt install -y python3 python3-pip python3-polib python3-pil python3-dotenv python3-pyqt5 python3-opengl && \
    dkp-pacman -S --needed --noconfirm gamecube-sdl2 ppc-liblzma ppc-libzip
@@ -1,12 +0,0 @@
 #!/bin/bash
 docker build -t myapp:latest -f .ci/dolphin/Dockerfile .
 docker run -it -v ./:/workdir myapp:latest /bin/bash -c ' \
  export PATH="$DEVKITPPC/bin:$PATH" && \
  cd /workdir && \
  rm -rf build-gamecube && \
  mkdir -p build-gamecube && \
  cmake -S. -Bbuild-gamecube -DDUSK_TARGET_SYSTEM=gamecube -DCMAKE_TOOLCHAIN_FILE="$DEVKITPRO/cmake/GameCube.cmake" && \
  cd build-gamecube && \
  make VERBOSE=1
 '
 # docker run -it -v ./:/workdir myapp:latest /bin/bash
@@ -1,13 +0,0 @@
 #!/bin/bash
 docker build -t myapp:latest -f .ci/dolphin/Dockerfile .
 docker run -it -v ./:/workdir myapp:latest /bin/bash -c ' \
  export PATH="$DEVKITPPC/bin:$PATH" && \
  cd /workdir && \
  rm -rf build-wii && \
  mkdir -p build-wii && \
  cmake -S. -Bbuild-wii -DDUSK_TARGET_SYSTEM=wii -DCMAKE_TOOLCHAIN_FILE="$DEVKITPRO/cmake/Wii.cmake" && \
  cd build-wii && \
  make VERBOSE=1 && \
  mv ./Dusk.dol ./boot.dol
 '
 # docker run -it -v ./:/workdir myapp:latest /bin/bash
@@ -1,87 +0,0 @@
 name: Build Dusk
 on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
 jobs:
  run-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5
      - name: Install dependencies
        run: |
          apt-get update
          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 liblua5.3-dev
      - name: Configure CMake for tests
        run: cmake -S . -B build -DDUSK_BUILD_TESTS=ON -DDUSK_TARGET_SYSTEM=linux
      - name: Build tests
        run: cmake --build build -- -j$(nproc)
      - name: Run tests
        run: ctest --output-on-failure --test-dir build
  build-linux:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5
      - name: Install dependencies
        run: |
          apt-get update
          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 liblua5.3-dev
      - name: Configure CMake
        run: cmake -S . -B build -DDUSK_TARGET_SYSTEM=linux
      - name: Build
        run: cmake --build build -- -j$(nproc)
      - name: List build output
        run: ls -lh build
      - name: Upload Linux binary
        uses: actions/upload-artifact@v3
        with:
          name: dusk-linux
          path: build/Dusk
          if-no-files-found: error
  build-psp:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5
      - name: Install dependencies
        run: |
          apt-get update
          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 liblua5.3-dev
      - name: Configure CMake
        run: cmake -S . -B build -DDUSK_TARGET_SYSTEM=psp -DENABLE_TESTS=OFF
      - name: Build
        run: cmake --build build -- -j$(nproc)
      - name: Move EBOOT.PBP to Dusk subfolder
        run: |
          mkdir -p build/gitea/Dusk
          mv build/EBOOT.PBP build/gitea/Dusk/EBOOT.PBP
      - name: List build output
        run: ls -lh build/gitea/Dusk
      - name: Upload PSP binary
        uses: actions/upload-artifact@v3
        with:
          name: dusk-psp
          path: build/gitea/
          if-no-files-found: error
  build-dolphin:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5
      - name: Install dependencies
        run: |
          apt-get update
          apt-get install -y docker.io
      - name: Docker test
        run: |
          ./.ci/dolphin/build-gamecube.sh
@@ -0,0 +1,49 @@
 name: Setup devkitPro
 description: Install devkitPro with GameCube/Wii packages on an Ubuntu runner
 runs:
  using: composite
  steps:
    - name: Install apt dependencies
      shell: bash
      run: |
        sudo apt-get update
        sudo apt-get install -y \
          cmake \
          python3 \
          python3-pip \
          python3-polib \
          python3-pil \
          python3-dotenv \
          python3-pyqt5 \
          python3-opengl \
          xorriso
    - name: Install devkitPro pacman
      shell: bash
      run: |
        sudo ln -sf /proc/self/mounts /etc/mtab
        wget https://apt.devkitpro.org/install-devkitpro-pacman \
          -O /tmp/install-devkitpro-pacman
        echo "=== installer script contents ==="
        cat /tmp/install-devkitpro-pacman
        echo "================================="
        chmod +x /tmp/install-devkitpro-pacman
        sudo /tmp/install-devkitpro-pacman
        echo "DEVKITPRO=/opt/devkitpro" >> $GITHUB_ENV
        echo "DEVKITPPC=/opt/devkitpro/devkitPPC" >> $GITHUB_ENV
        echo "/opt/devkitpro/tools/bin" >> $GITHUB_PATH
        echo "/opt/devkitpro/devkitPPC/bin" >> $GITHUB_PATH
    - name: Install devkitPro GameCube/Wii packages
      shell: bash
      run: |
        sudo dkp-pacman -S --needed --noconfirm \
          gamecube-dev \
          gamecube-sdl2 \
          ppc-liblzma \
          ppc-libzip \
          libogc2 \
          gamecube-tools \
          ppc-libmad \
          ppc-zlib-ng \
          ppc-bzip2 \
          ppc-zstd
@@ -0,0 +1,20 @@
 name: Setup pspdev
 description: Install the pspdev PSP toolchain on an Ubuntu runner
 runs:
  using: composite
  steps:
    - name: Install dependencies
      shell: bash
      run: |
        sudo apt-get update
        sudo apt-get install -y cmake python3 python3-pip python3-dotenv
    - name: Install pspdev toolchain
      shell: bash
      run: |
        wget -q \
          https://github.com/pspdev/pspdev/releases/latest/download/pspdev-ubuntu-latest-x86_64.tar.gz \
          -O /tmp/pspdev.tar.gz
        sudo tar -xzf /tmp/pspdev.tar.gz -C /usr/local
        echo "PSPDEV=/usr/local/pspdev" >> $GITHUB_ENV
        echo "/usr/local/pspdev/bin" >> $GITHUB_PATH
@@ -0,0 +1,247 @@
 name: Build Dusk
 on:
  push:
    tags:
      - '*'
 jobs:
  build-linux:
    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: Build Linux
        run: ./scripts/build-linux.sh
      - name: Upload Linux binary
        uses: actions/upload-artifact@v3
        with:
          name: dusk-linux
          path: build-linux/Dusk
          if-no-files-found: error
  build-psp:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Setup pspdev
        uses: ./.github/actions/setup-pspdev
      - name: Build PSP
        run: ./scripts/build-psp.sh
      - name: Move EBOOT.PBP to Dusk subfolder
        run: |
          mkdir -p ./git-artifcats/Dusk/PSP/GAME/Dusk
          cp build-psp/EBOOT.PBP ./git-artifcats/Dusk/PSP/GAME/Dusk/EBOOT.PBP
      - name: Upload PSP binary
        uses: actions/upload-artifact@v3
        with:
          name: dusk-psp
          path: ./git-artifcats/Dusk
          if-no-files-found: error
  build-knulli:
    runs-on: ubuntu-latest
    container:
      image: debian:trixie
    steps:
      - name: Install Node.js
        run: apt-get update && apt-get install -y nodejs
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install dependencies
        run: |
          dpkg --add-architecture arm64
          apt-get update
          apt-get install -y --no-install-recommends \
            crossbuild-essential-arm64 \
            ca-certificates \
            pkg-config \
            cmake \
            make \
            ninja-build \
            git \
            file \
            python3 \
            python3-pip \
            python3-polib \
            python3-pil \
            python3-dotenv \
            python3-pyqt5 \
            python3-opengl \
            liblua5.4-dev:arm64 \
            xz-utils:arm64 \
            libbz2-dev:arm64 \
            zlib1g-dev:arm64 \
            libzip-dev:arm64 \
            libssl-dev:arm64 \
            libsdl2-dev:arm64 \
            liblzma-dev:arm64 \
            libopengl0:arm64 \
            libgl1:arm64 \
            libegl1:arm64 \
            libgles2:arm64 \
            libgl1-mesa-dev:arm64
      - name: Build Knulli
        run: ./scripts/build-knulli.sh
      - name: Move output to Dusk subfolder
        run: |
          mkdir -p ./git-artifcats/Dusk
          cp -r build-knulli/dusk ./git-artifcats/Dusk
      - name: Upload Knulli binary
        uses: actions/upload-artifact@v3
        with:
          name: dusk-knulli
          path: ./git-artifcats/Dusk
          if-no-files-found: error
  build-gamecube:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/extremscorner/libogc2:latest
    steps:
      - name: Install Node.js
        run: apt-get update && apt-get install -y nodejs
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install additional dependencies
        run: |
          apt-get install -y \
            python3-pip python3-polib python3-pil \
            python3-dotenv python3-pyqt5 python3-opengl
          dkp-pacman -Syu --noconfirm
          dkp-pacman -S --needed --noconfirm \
            gamecube-sdl2 ppc-liblzma ppc-libzip \
            gamecube-tools ppc-libmad ppc-zlib-ng ppc-bzip2 ppc-zstd
      - name: Build GameCube
        run: ./scripts/build-gamecube.sh
      - name: Copy output files
        run: |
          mkdir -p ./git-artifcats/Dusk
          cp build-gamecube/Dusk.dol ./git-artifcats/Dusk/Dusk.dol
          cp build-gamecube/dusk.dsk ./git-artifcats/Dusk/dusk.dsk
      - name: Upload GameCube binary
        uses: actions/upload-artifact@v3
        with:
          name: dusk-gamecube
          path: ./git-artifcats/Dusk
          if-no-files-found: error
  build-gamecube-iso:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/extremscorner/libogc2:latest
    steps:
      - name: Install Node.js
        run: apt-get update && apt-get install -y nodejs
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install additional dependencies
        run: |
          apt-get install -y \
            python3-pip python3-polib python3-pil \
            python3-dotenv python3-pyqt5 python3-opengl xorriso
          dkp-pacman -Syu --noconfirm
          dkp-pacman -S --needed --noconfirm \
            gamecube-sdl2 ppc-liblzma ppc-libzip \
            gamecube-tools ppc-libmad ppc-zlib-ng ppc-bzip2 ppc-zstd
      - name: Build GameCube ISO
        run: ./scripts/build-gamecube-iso.sh
      - name: Copy output files
        run: |
          mkdir -p ./git-artifcats/Dusk
          cp build-gamecube-iso/Dusk-NTSC-J.iso ./git-artifcats/Dusk/Dusk-NTSC-J.iso
          cp build-gamecube-iso/Dusk-NTSC-U.iso ./git-artifcats/Dusk/Dusk-NTSC-U.iso
          cp build-gamecube-iso/Dusk-PAL.iso    ./git-artifcats/Dusk/Dusk-PAL.iso
      - name: Upload GameCube ISO
        uses: actions/upload-artifact@v3
        with:
          name: dusk-gamecube-iso
          path: ./git-artifcats/Dusk
          if-no-files-found: error
  build-wii:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/extremscorner/libogc2:latest
    steps:
      - name: Install Node.js
        run: apt-get update && apt-get install -y nodejs
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install additional dependencies
        run: |
          apt-get install -y \
            python3-pip python3-polib python3-pil \
            python3-dotenv python3-pyqt5 python3-opengl
          dkp-pacman -Syu --noconfirm
          dkp-pacman -S --needed --noconfirm \
            gamecube-sdl2 ppc-liblzma ppc-libzip \
            gamecube-tools ppc-libmad ppc-zlib-ng ppc-bzip2 ppc-zstd
      - name: Build Wii
        run: ./scripts/build-wii.sh
      - name: Copy output files
        run: |
          mkdir -p ./git-artifcats/Dusk/apps/Dusk
          cp build-wii/boot.dol ./git-artifcats/Dusk/apps/Dusk/boot.dol
          cp build-wii/dusk.dsk ./git-artifcats/Dusk/apps/Dusk/dusk.dsk
          cp build-wii/meta.xml ./git-artifcats/Dusk/apps/Dusk/meta.xml
      - name: Upload Wii binary
        uses: actions/upload-artifact@v3
        with:
          name: dusk-wii
          path: ./git-artifcats/Dusk
          if-no-files-found: error
  build-wii-iso:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/extremscorner/libogc2:latest
    steps:
      - name: Install Node.js
        run: apt-get update && apt-get install -y nodejs
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install additional dependencies
        run: |
          apt-get install -y \
            python3-pip python3-polib python3-pil \
            python3-dotenv python3-pyqt5 python3-opengl xorriso
          dkp-pacman -Syu --noconfirm
          dkp-pacman -S --needed --noconfirm \
            gamecube-sdl2 ppc-liblzma ppc-libzip \
            gamecube-tools ppc-libmad ppc-zlib-ng ppc-bzip2 ppc-zstd
      - name: Build Wii ISO
        run: ./scripts/build-wii-iso.sh
      - name: Copy output files
        run: |
          mkdir -p ./git-artifcats/Dusk
          cp build-wii-iso/Dusk-NTSC-J.iso ./git-artifcats/Dusk/Dusk-NTSC-J.iso
          cp build-wii-iso/Dusk-NTSC-U.iso ./git-artifcats/Dusk/Dusk-NTSC-U.iso
          cp build-wii-iso/Dusk-PAL.iso    ./git-artifcats/Dusk/Dusk-PAL.iso
      - name: Upload Wii ISO
        uses: actions/upload-artifact@v3
        with:
          name: dusk-wii-iso
          path: ./git-artifcats/Dusk
          if-no-files-found: error
@@ -0,0 +1,106 @@
 name: Test Dusk
 on:
  pull_request:
    branches:
      - main
 jobs:
  run-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            build-essential \
            cmake \
            python3 \
            python3-pip \
            python3-polib \
            python3-pil \
            libsdl2-dev \
            libgl1-mesa-dev \
            libzip-dev \
            python3-dotenv \
            python3-pyqt5 \
            python3-opengl \
            xz-utils \
            liblzma-dev \
            libbz2-dev \
            zlib1g-dev \
            git \
            libssl-dev
      - name: Run tests
        run: ./scripts/test-linux.sh
  # Emulator smoke tests: boot the built disc/EBOOT for a fixed window and
  # confirm the emulator doesn't crash. Not yet verified against a real
  # runner (no CI run has exercised these) -- continue-on-error so a
  # flaky/broken emulator step doesn't block the required Linux test job.
  run-tests-gamecube-dolphin:
    runs-on: ubuntu-latest
    continue-on-error: true
    container:
      image: ghcr.io/extremscorner/libogc2:latest
    steps:
      - name: Install Node.js
        run: apt-get update && apt-get install -y nodejs
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install additional dependencies
        run: |
          apt-get install -y \
            python3-pip python3-polib python3-pil \
            python3-dotenv python3-pyqt5 python3-opengl xorriso \
            dolphin-emu xvfb
          dkp-pacman -Syu --noconfirm
          dkp-pacman -S --needed --noconfirm \
            gamecube-sdl2 ppc-liblzma ppc-libzip \
            gamecube-tools ppc-libmad ppc-zlib-ng ppc-bzip2 ppc-zstd
      - name: Build GameCube ISO and boot it in Dolphin
        run: ./scripts/test-gamecube-dolphin.sh
  run-tests-wii-dolphin:
    runs-on: ubuntu-latest
    continue-on-error: true
    container:
      image: ghcr.io/extremscorner/libogc2:latest
    steps:
      - name: Install Node.js
        run: apt-get update && apt-get install -y nodejs
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install additional dependencies
        run: |
          apt-get install -y \
            python3-pip python3-polib python3-pil \
            python3-dotenv python3-pyqt5 python3-opengl xorriso \
            dolphin-emu xvfb
          dkp-pacman -Syu --noconfirm
          dkp-pacman -S --needed --noconfirm \
            gamecube-sdl2 ppc-liblzma ppc-libzip \
            gamecube-tools ppc-libmad ppc-zlib-ng ppc-bzip2 ppc-zstd
      - name: Build Wii ISO and boot it in Dolphin
        run: ./scripts/test-wii-dolphin.sh
  run-tests-psp-ppsspp:
    runs-on: ubuntu-latest
    continue-on-error: true
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Setup pspdev
        uses: ./.github/actions/setup-pspdev
      - name: Install PPSSPPHeadless build dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y git cmake ninja-build libsdl2-dev zlib1g-dev
      - name: Build PPSSPPHeadless
        run: |
          git clone --recursive --depth 1 https://github.com/hrydgard/ppsspp.git /tmp/ppsspp
          cmake -S /tmp/ppsspp -B /tmp/ppsspp/build -DCMAKE_BUILD_TYPE=Release
          cmake --build /tmp/ppsspp/build --target PPSSPPHeadless -- -j$(nproc)
          echo "PPSSPP_HEADLESS_BIN=/tmp/ppsspp/build/PPSSPPHeadless" >> "$GITHUB_ENV"
      - name: Build PSP EBOOT and boot it in PPSSPPHeadless
        run: ./scripts/test-psp-ppsspp.sh
@@ -83,7 +83,6 @@ assets/borrowed
 .VSCode*
 /vita
 ._*
 *~
@@ -104,4 +103,7 @@ yarn.lock
 .venv
 /build2
-/build*
+/build*
 /assets/test
 /tools_old
 /assets/test.png
@@ -4,13 +4,21 @@
 # https://opensource.org/licenses/MIT
 # Setup
-cmake_minimum_required(VERSION 3.18)
+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)
 cmake_policy(SET CMP0079 NEW)
 # set(FETCHCONTENT_UPDATES_DISCONNECTED ON)
-option(ENABLE_TESTS "Enable tests" OFF)
+option(DUSK_BUILD_TESTS "Enable tests" OFF)
 option(DUSK_NETWORKING "Enable networking support" OFF)
 set(DUSK_GAME_NAME "Dusk" CACHE STRING "Game display name")
 set(DUSK_GAME_AUTHOR "YourWishes" CACHE STRING "Game author / coder")
 set(DUSK_GAME_SHORT_DESCRIPTION "Dusk game" CACHE STRING "One-line description")
 set(DUSK_GAME_LONG_DESCRIPTION  "No description yet." CACHE STRING "Full description")
 # Prep cache
 set(DUSK_CACHE_TARGET "dusk-target")
@@ -30,184 +38,104 @@ 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})
 # Create directories
 file(MAKE_DIRECTORY ${DUSK_GENERATED_HEADERS_DIR})
 # Find packages
 find_package(Python3 COMPONENTS Interpreter REQUIRED)
 # Set target system
 # message(FATAL_ERROR "DISABLED FOR NOW2 ${DUSK_TARGET_SYSTEM}") 
 if(NOT DEFINED DUSK_TARGET_SYSTEM)
  set(DUSK_TARGET_SYSTEM "linux")
  # set(DUSK_TARGET_SYSTEM "psp")
 endif()
-# Toolchains
+# Create directories
-if(DUSK_TARGET_SYSTEM STREQUAL "psp")
+file(MAKE_DIRECTORY ${DUSK_GENERATED_HEADERS_DIR})
-  find_package(pspsdk REQUIRED)
+file(MAKE_DIRECTORY ${DUSK_TEMP_DIR})
-endif()
+file(MAKE_DIRECTORY ${DUSK_BUILT_ASSETS_DIR})
-if(DUSK_TARGET_SYSTEM STREQUAL "gamecube" OR DUSK_TARGET_SYSTEM STREQUAL "wii")
+# Required build packages
-  # Override to make library and binary be the same.
+find_package(Python3 COMPONENTS Interpreter REQUIRED)
  set(DUSK_LIBRARY_TARGET_NAME "${DUSK_LIBRARY_TARGET_NAME}.elf" CACHE INTERNAL ${DUSK_CACHE_TARGET})
 endif()
 # Init Project.
 project(${DUSK_LIBRARY_TARGET_NAME}
  VERSION 1.0.0
-  LANGUAGES C CXX
+  LANGUAGES C
 )
 # Either, create library and binary separately (used for tests), or make them
-# one in the same so all code is in the binary.
+# one in the same so all code is in the binary only.
-if(ENABLE_TESTS)
+# Binary Executable
 add_executable(${DUSK_BINARY_TARGET_NAME} ${DUSK_SOURCES_DIR}/dusk/null.c)
 if(DUSK_BUILD_TESTS)
  # MainLibrary
  add_library(${DUSK_LIBRARY_TARGET_NAME} STATIC)
  # Binary Executable
  add_executable(${DUSK_BINARY_TARGET_NAME} ${DUSK_SOURCES_DIR}/null.c)
  # Link library to binary
  target_link_libraries(${DUSK_BINARY_TARGET_NAME}
    PUBLIC
      ${DUSK_LIBRARY_TARGET_NAME}
  )
 else()
-  set(DUSK_BINARY_TARGET_NAME "${DUSK_LIBRARY_TARGET_NAME}" CACHE INTERNAL ${DUSK_CACHE_TARGET})
+  set(DUSK_LIBRARY_TARGET_NAME "${DUSK_BINARY_TARGET_NAME}" CACHE INTERNAL ${DUSK_CACHE_TARGET})
  add_executable(${DUSK_BINARY_TARGET_NAME} ${DUSK_SOURCES_DIR}/null.c)
 endif()
 if(NOT DEFINED DUSK_VERSION)
  string(TIMESTAMP DUSK_VERSION "debug-%y%m%d%H%M%S")
 endif()
 # Definitions
 target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    DUSK_TARGET_SYSTEM="${DUSK_TARGET_SYSTEM}"
    DUSK_GAME_NAME="${DUSK_GAME_NAME}"
    DUSK_GAME_AUTHOR="${DUSK_GAME_AUTHOR}"
    DUSK_GAME_SHORT_DESCRIPTION="${DUSK_GAME_SHORT_DESCRIPTION}"
    DUSK_GAME_LONG_DESCRIPTION="${DUSK_GAME_LONG_DESCRIPTION}"
    DUSK_VERSION="${DUSK_VERSION}"
 )
 if(DUSK_NETWORKING)
  target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
    DUSK_NETWORKING
  )
 endif()
 # Toolchains
 include(cmake/targets/${DUSK_TARGET_SYSTEM}.cmake)
 # Add tools
 add_subdirectory(tools)
-# Assets
+# Include generated headers from tools.
-add_subdirectory(assets)
+target_include_directories(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
-
+  ${DUSK_GENERATED_HEADERS_DIR}
 # Add libraries
 if(DUSK_TARGET_SYSTEM STREQUAL "linux")
  find_package(SDL2 REQUIRED)
  find_package(OpenGL REQUIRED)
  target_link_libraries(${DUSK_LIBRARY_TARGET_NAME} PUBLIC 
    SDL2
    pthread
    OpenGL::GL
    GL
    m
  )
 elseif(DUSK_TARGET_SYSTEM STREQUAL "psp")
  find_package(SDL2 REQUIRED)
  find_package(OpenGL REQUIRED)
  target_link_libraries(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
    ${SDL2_LIBRARIES}
    SDL2
    pthread
    OpenGL::GL
    zip
    bz2
    z
    mbedtls
    mbedcrypto
    lzma
    m
  )
  target_include_directories(${DUSK_LIBRARY_TARGET_NAME} PRIVATE
    ${SDL2_INCLUDE_DIRS}
  )
 elseif(DUSK_TARGET_SYSTEM STREQUAL "gamecube" OR DUSK_TARGET_SYSTEM STREQUAL "wii")
  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fno-rtti -fno-exceptions")
  configure_file(opengl.pc.in opengl.pc @ONLY)
  find_package(PkgConfig REQUIRED)
  pkg_check_modules(zip IMPORTED_TARGET libzip)
  target_compile_definitions(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
    DOLPHIN
  )
  # Custom flags for cglm
  set(CGLM_SHARED OFF CACHE BOOL "Build cglm shared" FORCE)
  set(CGLM_STATIC ON  CACHE BOOL "Build cglm static" FORCE)
  find_package(cglm REQUIRED)
  # Compile lua
  include(FetchContent)
  FetchContent_Declare(
    liblua
    URL https://www.lua.org/ftp/lua-5.5.0.tar.gz
  )
  FetchContent_MakeAvailable(liblua)
  set(LUA_SRC_DIR "${liblua_SOURCE_DIR}/src")
  set(LUA_C_FILES 
    lapi.c lauxlib.c lbaselib.c lcode.c lcorolib.c lctype.c ldblib.c ldebug.c
    ldo.c ldump.c lfunc.c lgc.c linit.c liolib.c llex.c lmathlib.c lmem.c
    loadlib.c lobject.c lopcodes.c loslib.c lparser.c lstate.c lstring.c
    lstrlib.c ltable.c ltablib.c ltm.c lundump.c lutf8lib.c lvm.c lzio.c
  )
  list(TRANSFORM LUA_C_FILES PREPEND "${LUA_SRC_DIR}/")
  add_library(liblua STATIC ${LUA_C_FILES})
  target_include_directories(liblua PUBLIC "${LUA_SRC_DIR}")
  target_compile_definitions(liblua PRIVATE LUA_USE_C89)
  add_library(lua::lua ALIAS liblua)
  set(Lua_FOUND TRUE CACHE BOOL "Lua found" FORCE)
  target_link_libraries(${DUSK_LIBRARY_TARGET_NAME} PRIVATE
    cglm
    liblua
    m
    fat
    PkgConfig::zip
  )
 endif()
 # Force turn tests off for now
 set(ENABLE_TESTS OFF CACHE BOOL "Enable tests" FORCE)
 # Add code
 add_subdirectory(${DUSK_SOURCES_DIR})
 # Handle tests
 if(ENABLE_TESTS)
  enable_testing()
  add_subdirectory(test)
 endif()
 # Build assets
 dusk_run_python(
  DUSK_ASSETS_BUILT
  tools.asset.bundle
    --assets ${DUSK_ASSETS_DIR}
    --output-assets ${DUSK_BUILT_ASSETS_DIR}
    --output-file ${DUSK_BUILD_DIR}/dusk.dsk
    --headers-dir ${DUSK_GENERATED_HEADERS_DIR}
    --input ${DUSK_ASSETS}
 )
-add_dependencies(${DUSK_LIBRARY_TARGET_NAME} DUSK_ASSETS_BUILT)
+
 # Add main code
 add_subdirectory(${DUSK_SOURCES_DIR})
 # Include generated headers
 target_include_directories(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
  ${DUSK_GENERATED_HEADERS_DIR}
 )
-# Postbuild
+# Handle tests
-if(DUSK_TARGET_SYSTEM STREQUAL "psp")
+if(DUSK_BUILD_TESTS)
-  create_pbp_file(
+  enable_testing()
-    TARGET "${DUSK_BINARY_TARGET_NAME}"
+  add_subdirectory(test)
    ICON_PATH NULL
    BACKGROUND_PATH NULL
    PREVIEW_PATH NULL
    TITLE "${DUSK_BINARY_TARGET_NAME}"
    PSAR_PATH ${DUSK_BUILD_DIR}/dusk.dsk
    VERSION 01.00
  )
 elseif(DUSK_TARGET_SYSTEM STREQUAL "gamecube" OR DUSK_TARGET_SYSTEM STREQUAL "wii")
  set(DUSK_BINARY_TARGET_NAME_DOL "${DUSK_BUILD_DIR}/Dusk.dol")
  add_custom_command(TARGET ${DUSK_BINARY_TARGET_NAME} POST_BUILD
    COMMAND elf2dol
            "$<TARGET_FILE:${DUSK_BINARY_TARGET_NAME}>"
            "${DUSK_BINARY_TARGET_NAME_DOL}"
    COMMENT "Generating ${DUSK_BINARY_TARGET_NAME_DOL} from ${DUSK_BINARY_TARGET_NAME}"
  )
 endif()
 # Build assets
 # Deliberately not CONFIGURE_DEPENDS: that reruns the full CMake configure
 # step (which invalidates generated headers and forces a huge rebuild) on
 # every single asset edit. Re-run cmake manually when assets are added or
 # removed.
 file(GLOB_RECURSE DUSK_ASSET_FILES "${DUSK_ASSETS_DIR}/*")
 add_custom_command(
  OUTPUT "${DUSK_ASSETS_ZIP}"
  COMMAND ${CMAKE_COMMAND} -E make_directory "${DUSK_ASSETS_DIR}"
  COMMAND ${CMAKE_COMMAND} -E rm -f "${DUSK_ASSETS_ZIP}"
  COMMAND ${CMAKE_COMMAND} -E tar "cf" "${DUSK_ASSETS_ZIP}" --format=zip -- .
  WORKING_DIRECTORY "${DUSK_ASSETS_DIR}"
  DEPENDS ${DUSK_ASSET_FILES}
  VERBATIM
 )
 add_custom_target(DUSK_ASSETS_BUILT DEPENDS "${DUSK_ASSETS_ZIP}")
 add_dependencies(${DUSK_LIBRARY_TARGET_NAME} DUSK_ASSETS_BUILT)
@@ -0,0 +1,18 @@
 # Copyright (c) 2026 Dominic Masters
 # 
 # This software is released under the MIT License.
 # https://opensource.org/licenses/MIT
 add_subdirectory(debug)
 add_subdirectory(frame)
 add_subdirectory(focus)
 add_subdirectory(overlay)
 add_subdirectory(transition)
 add_subdirectory(widget)
 # Sources
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    ui.c
    uielement.c
 )
@@ -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
    uiconsole.c
    uifps.c
 )
@@ -0,0 +1,138 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uiconsole.h"
 #include "assert/assert.h"
 #include "console/console.h"
 #include "display/screen/screen.h"
 #include "display/text/text.h"
 #include "display/spritebatch/spritebatch.h"
 #include "display/shader/shaderunlit.h"
 #include "display/mesh/mesh.h"
 #include "util/memory.h"
 typedef struct {
  mesh_t mesh;
  bool_t built;
  meshvertex_t vertices[UI_CONSOLE_CACHE_VERTEX_MAX];
  int32_t vertexCount;
  int32_t cachedScanX;
  int32_t cachedScanY;
 } uiconsolecache_t;
 uiconsolecache_t UI_CONSOLE_CACHE;
 errorret_t uiConsoleDraw(void) {
  if(!CONSOLE.visible) errorOk();
  if(
    CONSOLE.dirty ||
    UI_CONSOLE_CACHE.cachedScanX != SCREEN.scanX ||
    UI_CONSOLE_CACHE.cachedScanY != SCREEN.scanY
  ) {
    errorChain(uiConsoleRebuild());
  }
  if(UI_CONSOLE_CACHE.vertexCount == 0) errorOk();
  shadermaterial_t material = {
    .unlit = {
      .color = COLOR_RED,
      .texture = FONT_DEFAULT.texture
    }
  };
  errorChain(shaderBind(&SHADER_UNLIT));
  errorChain(shaderSetMaterial(&SHADER_UNLIT, &material));
  return meshDraw(&UI_CONSOLE_CACHE.mesh, 0, UI_CONSOLE_CACHE.vertexCount);
 }
 errorret_t uiConsoleRebuild(void) {
  int32_t spriteCount = 0;
  for(uint32_t i = 0; i < CONSOLE_HISTORY_MAX; i++) {
    char_t c;
    int32_t j = 0;
    while((c = CONSOLE.line[i][j++]) != '\0') {
      if(c != ' ' && c != '\n') spriteCount++;
    }
  }
  assertTrue(
    spriteCount <= UI_CONSOLE_CACHE_GLYPH_MAX,
    "Console history exceeds fixed cache capacity"
  );
  const int32_t vertexCount = spriteCount * QUAD_VERTEX_COUNT;
  UI_CONSOLE_CACHE.vertexCount = vertexCount;
  if(vertexCount > 0) {
    const float_t lineH = (float_t)FONT_DEFAULT.tileset->tileHeight;
    const float_t charW = (float_t)FONT_DEFAULT.tileset->tileWidth;
    int32_t index = 0;
    int32_t row = 0;
    for(uint32_t i = 0; i < CONSOLE_HISTORY_MAX; i++) {
      float_t posX = (float_t)SCREEN.scanX;
      float_t posY = (float_t)SCREEN.scanY + lineH * (float_t)row;
      char_t c;
      int32_t j = 0;
      while((c = CONSOLE.line[i][j++]) != '\0') {
        if(c == '\n') {
          posX = (float_t)SCREEN.scanX;
          posY += lineH;
          row++;
          continue;
        }
        if(c == ' ') {
          posX += charW;
          continue;
        }
        const spritebatchsprite_t sprite = textGetSprite(
          (vec2){ posX, posY }, c, &FONT_DEFAULT
        );
        spriteBatchBufferToMesh(
          &sprite, 1,
          &UI_CONSOLE_CACHE.vertices[index], QUAD_VERTEX_COUNT
        );
        index += QUAD_VERTEX_COUNT;
        posX += charW;
      }
      row++;
    }
    if(!UI_CONSOLE_CACHE.built) {
      errorChain(meshInit(
        &UI_CONSOLE_CACHE.mesh,
        QUAD_PRIMITIVE_TYPE,
        UI_CONSOLE_CACHE_VERTEX_MAX,
        UI_CONSOLE_CACHE.vertices
      ));
      UI_CONSOLE_CACHE.built = true;
    } else {
      errorChain(meshFlush(&UI_CONSOLE_CACHE.mesh, 0, vertexCount));
    }
  }
  UI_CONSOLE_CACHE.cachedScanX = SCREEN.scanX;
  UI_CONSOLE_CACHE.cachedScanY = SCREEN.scanY;
  CONSOLE.dirty = false;
  errorOk();
 }
 errorret_t uiConsoleDispose(void) {
  if(UI_CONSOLE_CACHE.built) {
    errorChain(meshDispose(&UI_CONSOLE_CACHE.mesh));
  }
  memoryZero(&UI_CONSOLE_CACHE, sizeof(uiconsolecache_t));
  errorOk();
 }
@@ -0,0 +1,48 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "display/mesh/quad.h"
 // Fixed capacity for the console's cached glyph mesh, in glyphs -- the
 // mesh/vertex buffer is sized to this once and never grown/shrunk, so
 // history producing more non-space characters than this asserts (see
 // uiConsoleRebuild) instead of reallocating.
 #define UI_CONSOLE_CACHE_GLYPH_MAX 512
 #define UI_CONSOLE_CACHE_VERTEX_MAX (\
  UI_CONSOLE_CACHE_GLYPH_MAX * QUAD_VERTEX_COUNT \
 )
 /**
 * Renders the console history into the scan-safe area, drawing a mesh
 * that is only rebuilt when the history changes or the scan-safe origin
 * moves, rather than rebuffering vertices every frame. No-ops when the
 * console is not visible.
 *
 * @return Any error that occurs.
 */
 errorret_t uiConsoleDraw(void);
 /**
 * Rebuilds the cached mesh for the console's current history and
 * scan-safe origin. Called automatically by uiConsoleDraw() whenever
 * needed; only needs calling directly to force an immediate rebuild.
 * The underlying vertex buffer is a fixed-size array (see
 * UI_CONSOLE_CACHE_VERTEX_MAX) -- asserts if the history produces more
 * glyphs than that capacity, rather than growing it.
 *
 * @return Any error that occurs.
 */
 errorret_t uiConsoleRebuild(void);
 /**
 * Frees the mesh and vertex buffer built up by uiConsoleDraw().
 *
 * @return Any error that occurs.
 */
 errorret_t uiConsoleDispose(void);
@@ -0,0 +1,78 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uifps.h"
 #include "time/time.h"
 #include "util/string.h"
 #include "display/text/text.h"
 #include "display/screen/screen.h"
 #include "engine/engine.h"
 uifps_t UIFPS;
 errorret_t uiFPSInit() {
  uiLabelInit(&UIFPS.fpsLabel, &FONT_DEFAULT);
  uiLabelInit(&UIFPS.versionLabel, &FONT_DEFAULT);
  uiLabelSetText(&UIFPS.versionLabel, ENGINE.version);
  uiLabelSetColor(&UIFPS.versionLabel, color(255, 255, 255, 128));
  errorOk();
 }
 errorret_t uiFPSDraw() {
  char_t fpsText[32];
  // Get now.
  dusktimeepoch_t now = timeGetEpoch();
  double_t delta = now.time - UIFPS.lastTick.time;
  UIFPS.lastTick = now;
  // Raw current FPS
  float_t fps = delta > 0 ? 1.0 / delta : 0.0;
  // Average FPS using exponential moving average
  const float_t alpha = 0.1f; // Smoothing factor
  if(UIFPS.fpsAverage == 0.0f) {
    UIFPS.fpsAverage = fps; // Initialize average on first run
  } else {
    UIFPS.fpsAverage = alpha * fps + (1.0f - alpha) * UIFPS.fpsAverage;
  }
  snprintf(
    fpsText,
    sizeof(fpsText),
    "%.1f/%.1fms",
    UIFPS.fpsAverage,
    delta * 1000.0f
  );
  color_t textColor;
  if(fps >= 55.0f) {
    textColor = COLOR_GREEN;
  } else if(fps >= 45.0f) {
    textColor = COLOR_YELLOW;
  } else {
    textColor = COLOR_RED;
  }
  uiLabelSetColor(&UIFPS.fpsLabel, textColor);
  if(stringCompare(fpsText, UIFPS.fpsLabel.text) != 0) {
    uiLabelSetText(&UIFPS.fpsLabel, fpsText);
  }
  errorChain(uiLabelDraw(
    &UIFPS.fpsLabel, (float_t)SCREEN.scanX, (float_t)SCREEN.scanY
  ));
  int32_t versionWidth, versionHeight;
  uiLabelGetSize(&UIFPS.versionLabel, &versionWidth, &versionHeight);
  errorChain(uiLabelDraw(
    &UIFPS.versionLabel,
    (float_t)(SCREEN.scanX + SCREEN.scanWidth - versionWidth),
    (float_t)(SCREEN.scanY + SCREEN.scanHeight - versionHeight)
  ));
  errorOk();
 }
@@ -0,0 +1,34 @@
 /**
 * 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 "time/timeepoch.h"
 #include "ui/widget/uilabel.h"
 typedef struct {
  dusktimeepoch_t lastTick;
  float_t fpsAverage;
  uilabel_t fpsLabel;
  uilabel_t versionLabel;
 } uifps_t;
 extern uifps_t UIFPS;
 /**
 * Initializes the FPS counter, caching the (static) version label.
 *
 * @return Any error that occurs.
 */
 errorret_t uiFPSInit();
 /**
 * Draws the FPS counter on the screen, and also does the update (for now).
 *
 * @return Any error that occurs.
 */
 errorret_t uiFPSDraw();
@@ -0,0 +1,9 @@
 # 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
    uifocus.c
 )
@@ -0,0 +1,190 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uifocus.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "input/input.h"
 #include "time/time.h"
 const uifocusdirmap_t UI_FOCUS_DIR_MAP[] = {
  { INPUT_BIND_UP,    UI_FOCUS_DIRECTION_UP,     0, -1 },
  { INPUT_BIND_DOWN,  UI_FOCUS_DIRECTION_DOWN,   0,  1 },
  { INPUT_BIND_LEFT,  UI_FOCUS_DIRECTION_LEFT,  -1,  0 },
  { INPUT_BIND_RIGHT, UI_FOCUS_DIRECTION_RIGHT,  1,  0 },
  { INPUT_BIND_NULL,  UI_FOCUS_DIRECTION_NONE,   0,  0 },
 };
 uifocus_t UI_FOCUS;
 void uiFocusInit(void) {
  memoryZero(&UI_FOCUS, sizeof(uifocus_t));
 }
 uifocusitem_t * uiFocusPush(
  const uint8_t cols,
  const uint8_t rows,
  uifocusitemcallback_t selected,
  uifocusitemcallback_t changed,
  uifocusitemcallback_t closed,
  uifocusitemdirectioncallback_t direction,
  void *user
 ) {
  assertTrue(
    UI_FOCUS.count < UI_FOCUS_STACK_MAX,
    "UI focus stack overflow"
  );
  assertTrue(cols > 0, "Focus item cols must be > 0");
  assertTrue(rows > 0, "Focus item rows must be > 0");
  uifocusitem_t *item = &UI_FOCUS.items[UI_FOCUS.count];
  memoryZero(item, sizeof(uifocusitem_t));
  item->cols = cols;
  item->rows = rows;
  item->selected = selected;
  item->changed = changed;
  item->closed = closed;
  item->direction = direction;
  item->user = user;
  UI_FOCUS.count++;
  UI_FOCUS.pushedThisTick = true;
  if(item->changed != NULL) item->changed(item);
  return item;
 }
 void uiFocusPop(void) {
  assertTrue(UI_FOCUS.count > 0, "UI focus stack underflow");
  uifocusitem_t *item = &UI_FOCUS.items[UI_FOCUS.count - 1];
  if(item->closed != NULL) item->closed(item);
  UI_FOCUS.count--;
 }
 void uiFocusPopItem(uifocusitem_t *item) {
  assertTrue(UI_FOCUS.count > 0, "UI focus stack underflow");
  assertTrue(item >= UI_FOCUS.items, "Item is not on the focus stack");
  assertTrue(
    item < UI_FOCUS.items + UI_FOCUS.count,
    "Item is not on the focus stack"
  );
  while(&UI_FOCUS.items[UI_FOCUS.count - 1] != item) {
    uiFocusPop();
  }
  uiFocusPop();
 }
 void uiFocusSetPosition(uifocusitem_t *item, const uint8_t x, const uint8_t y) {
  assertTrue(UI_FOCUS.count > 0, "No active focus item");
  assertTrue(item->cols > 0, "Focus item cols must be > 0");
  assertTrue(item->rows > 0, "Focus item rows must be > 0");
  uint8_t newX = x % item->cols;
  uint8_t newY = y % item->rows;
  if(item->changed != NULL) {
    uint8_t oldX = item->x;
    uint8_t oldY = item->y;
    item->x = newX;
    item->y = newY;
    if(!item->changed(item)) {
      item->x = oldX;
      item->y = oldY;
    }
    return;
  }
  item->x = newX;
  item->y = newY;
 }
 void uiFocusMoveDirection(
  uifocusitem_t *item,
  const uifocusdirection_t dir
 ) {
  for(
    const uifocusdirmap_t *m = UI_FOCUS_DIR_MAP;
    m->action != INPUT_BIND_NULL;
    m++
  ) {
    if(m->direction != dir) continue;
    uint8_t x = (uint8_t)(item->x + m->dx);
    uint8_t y = (uint8_t)(item->y + m->dy);
    uiFocusSetPosition(item, x, y);
    break;
  }
 }
 void uiFocusHandleDirection(
  uifocusitem_t *item,
  const uifocusdirection_t dir
 ) {
  if(item->direction != NULL && item->direction(item, dir)) return;
  uiFocusMoveDirection(item, dir);
 }
 void uiFocusUpdate(void) {
  if(UI_FOCUS.count == 0) return;
  #ifdef DUSK_TIME_DYNAMIC
    if(TIME.dynamicUpdate) return;
  #endif
  if(UI_FOCUS.pushedThisTick) {
    UI_FOCUS.pushedThisTick = false;
    return;
  }
  uifocusitem_t *item = &UI_FOCUS.items[UI_FOCUS.count - 1];
  if(inputPressed(INPUT_BIND_ACCEPT)) {
    if(item->selected != NULL) item->selected(item);
    return;
  }
  if(inputPressed(INPUT_BIND_CANCEL)) {
    uiFocusPop();
    return;
  }
  for(
    const uifocusdirmap_t *m = UI_FOCUS_DIR_MAP;
    m->action != INPUT_BIND_NULL;
    m++
  ) {
    if(!inputPressed(m->action)) continue;
    UI_FOCUS.direction = m->direction;
    UI_FOCUS.timeHeld = 0.0f;
    uiFocusHandleDirection(item, m->direction);
    return;
  }
  bool_t held = false;
  for(
    const uifocusdirmap_t *m = UI_FOCUS_DIR_MAP;
    m->action != INPUT_BIND_NULL;
    m++
  ) {
    if(m->direction != UI_FOCUS.direction) continue;
    held = inputIsDown(m->action);
    break;
  }
  if(!held) {
    UI_FOCUS.direction = UI_FOCUS_DIRECTION_NONE;
    UI_FOCUS.timeHeld = 0.0f;
    return;
  }
  UI_FOCUS.timeHeld += TIME.delta;
  if(UI_FOCUS.timeHeld < UI_FOCUS_HOLD_DELAY) return;
  if(UI_FOCUS.timeHeld < UI_FOCUS_HOLD_DELAY + UI_FOCUS_HOLD_REPEAT) return;
  UI_FOCUS.timeHeld = UI_FOCUS_HOLD_DELAY;
  uiFocusHandleDirection(item, UI_FOCUS.direction);
 }
@@ -0,0 +1,133 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "uifocusitem.h"
 #include "input/inputaction.h"
 /** Maximum depth of the focus stack. */
 #define UI_FOCUS_STACK_MAX 8
 /**
 * How long a direction must be held before repeating begins, in seconds.
 */
 #define UI_FOCUS_HOLD_DELAY 0.5f
 /**
 * Interval between repeated moves while a direction is held, in seconds.
 */
 #define UI_FOCUS_HOLD_REPEAT 0.1f
 typedef struct {
  inputbind_t action;
  uifocusdirection_t direction;
  int8_t dx;
  int8_t dy;
 } uifocusdirmap_t;
 /**
 * Mapping of input actions to focus directions, terminated by an
 * entry with action == INPUT_BIND_NULL.
 */
 extern const uifocusdirmap_t UI_FOCUS_DIR_MAP[];
 /**
 * A stack of focused UI items. Push an item when a widget captures
 * focus; pop it when focus is released. The topmost item is always
 * the active focus context.
 */
 typedef struct {
  uifocusitem_t items[UI_FOCUS_STACK_MAX];
  uint8_t count;
  uifocusdirection_t direction;
  float_t timeHeld;
  bool_t pushedThisTick;
 } uifocus_t;
 extern uifocus_t UI_FOCUS;
 /**
 * Initializes the focus system, zeroing all state.
 */
 void uiFocusInit(void);
 /**
 * Pushes a new focus item onto the stack with the given grid dimensions
 * and callbacks. x and y are initialized to 0.
 *
 * @param cols      Number of columns in the focus grid.
 * @param rows      Number of rows in the focus grid.
 * @param selected  Called when the user selects the focused cell.
 * @param changed   Called when the focused cell position changes.
 * @param closed    Called when this focus item is popped.
 * @param direction Called on a direction press/hold before the default
 *                  cell-to-cell movement is applied; may be NULL.
 * @param user      Arbitrary pointer stored on the item before changed fires.
 * @returns Pointer to the newly pushed focus item.
 */
 uifocusitem_t * uiFocusPush(
  const uint8_t cols,
  const uint8_t rows,
  uifocusitemcallback_t selected,
  uifocusitemcallback_t changed,
  uifocusitemcallback_t closed,
  uifocusitemdirectioncallback_t direction,
  void *user
 );
 /**
 * Pops the topmost focus item from the stack, invoking its closed
 * callback if one is set.
 */
 void uiFocusPop(void);
 /**
 * Pops an item and anything that was pushed after it from the focus stack.
 * 
 * @param item The focus item to pop to. Must be on the stack.
 */
 void uiFocusPopItem(uifocusitem_t *item);
 /**
 * Manually sets the cursor position of the topmost focus item and
 * fires its changed callback.
 *
 * @param x Column to move to.
 * @param y Row to move to.
 */
 void uiFocusSetPosition(uifocusitem_t *item, const uint8_t x, const uint8_t y);
 /**
 * Moves the topmost focus item one step in the given direction,
 * wrapping at the grid edges, and fires its changed callback.
 *
 * @param item The focus item to move.
 * @param dir Direction to move.
 */
 void uiFocusMoveDirection(
  uifocusitem_t *item,
  const uifocusdirection_t dir
 );
 /**
 * Handles a direction press/hold for the given item: gives the item's
 * direction callback (if any) first refusal, falling back to the
 * default cell-to-cell movement if it's unset or returns false.
 *
 * @param item The focus item to move.
 * @param dir Direction that was pressed or held.
 */
 void uiFocusHandleDirection(
  uifocusitem_t *item,
  const uifocusdirection_t dir
 );
 /**
 * Updates the focus system. Handles first-press movement and
 * held-direction repeating. Called once per game tick.
 */
 void uiFocusUpdate(void);
@@ -0,0 +1,57 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "dusk.h"
 typedef struct uifocusitem_s uifocusitem_t;
 typedef enum {
  UI_FOCUS_DIRECTION_NONE,
  UI_FOCUS_DIRECTION_UP,
  UI_FOCUS_DIRECTION_DOWN,
  UI_FOCUS_DIRECTION_LEFT,
  UI_FOCUS_DIRECTION_RIGHT
 } uifocusdirection_t;
 /**
 * Callback invoked when a focus item's selected cell changes.
 *
 * @param item The focus item that changed.
 */
 typedef bool_t (*uifocusitemcallback_t)(const uifocusitem_t *item);
 /**
 * Callback invoked when a direction is pressed or held-repeated while
 * this item is focused, before the default cell-to-cell movement is
 * applied.
 *
 * @param item The focus item that is currently focused.
 * @param direction The direction that was pressed.
 * @returns True if the direction was fully handled and the default
 * grid movement should be skipped; false to fall through to it.
 */
 typedef bool_t (*uifocusitemdirectioncallback_t)(
  const uifocusitem_t *item,
  const uifocusdirection_t direction
 );
 /**
 * A single entry on the UI focus stack. Tracks the focused cell
 * within a grid of cols x rows, and the current x/y position.
 */
 struct uifocusitem_s {
  uint8_t cols;
  uint8_t rows;
  uint8_t x;
  uint8_t y;
  uifocusitemcallback_t selected;
  uifocusitemcallback_t changed;
  uifocusitemcallback_t closed;
  uifocusitemdirectioncallback_t direction;
  void *user;
 };
@@ -0,0 +1,12 @@
 # Copyright (c) 2026 Dominic Masters
 #
 # This software is released under the MIT License.
 # https://opensource.org/licenses/MIT
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    uiframe.c
    uiconfirm.c
 )
 add_subdirectory(settings)
@@ -0,0 +1,13 @@
 # Copyright (c) 2026 Dominic Masters
 #
 # This software is released under the MIT License.
 # https://opensource.org/licenses/MIT
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    uisettings.c
    uisettingsgeneral.c
    uisettingsinput.c
    uisettingsdisplay.c
    uisettingsaudio.c
 )
@@ -0,0 +1,248 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uisettings.h"
 #include "uisettingsgeneral.h"
 #include "uisettingsinput.h"
 #include "uisettingsdisplay.h"
 #include "uisettingsaudio.h"
 #include "ui/frame/uiframe.h"
 #include "ui/frame/uiconfirm.h"
 #include "util/memory.h"
 #include "display/text/text.h"
 #include "display/screen/screen.h"
 #include "assert/assert.h"
 #include "locale/localemanager.h"
 #include "asset/loader/locale/assetlocaleloader.h"
 uisettings_t UI_SETTINGS;
 uisettingstabdef_t UI_SETTINGS_TAB_DEFS[UI_SETTINGS_TAB_COUNT] = {
  {
    .localeId = "ui.settings.tabs.general",
    .init = uiSettingsGeneralInit,
    .menu = (uimenu_t *)&UI_SETTINGS.data,
    .load = uiSettingsGeneralLoad,
    .apply = uiSettingsGeneralApply,
    .hasChanges = uiSettingsGeneralHasChanges
  },
  {
    .localeId = "ui.settings.tabs.input",
    .init = uiSettingsInputInit,
    .menu = (uimenu_t *)&UI_SETTINGS.data,
    .load = uiSettingsInputLoad,
    .apply = uiSettingsInputApply,
    .hasChanges = uiSettingsInputHasChanges
  },
  {
    .localeId = "ui.settings.tabs.display",
    .init = uiSettingsDisplayInit,
    .menu = (uimenu_t *)&UI_SETTINGS.data,
    .load = uiSettingsDisplayLoad,
    .apply = uiSettingsDisplayApply,
    .hasChanges = uiSettingsDisplayHasChanges
  },
  {
    .localeId = "ui.settings.tabs.audio",
    .init = uiSettingsAudioInit,
    .menu = (uimenu_t *)&UI_SETTINGS.data,
    .load = uiSettingsAudioLoad,
    .apply = uiSettingsAudioApply,
    .hasChanges = uiSettingsAudioHasChanges
  }
 };
 static uisettingstabdef_t UI_SETTINGS_TOP_DEF = {
  .menu = &UI_SETTINGS.tabsMenu,
  .load = uiSettingsLoad,
  .hasChanges = uiSettingsHasChanges
 };
 static uisettingstabdef_t *UI_SETTINGS_PENDING_DISCARD = NULL;
 static uisettingstabdef_t *UI_SETTINGS_ACTIVE_TAB = NULL;
 errorret_t uiSettingsActivateTab(uisettingstabdef_t *def) {
  if(def == UI_SETTINGS_ACTIVE_TAB) errorOk();
  errorChain(def->init(&UI_SETTINGS.data));
  def->menu->user = def;
  def->load();
  UI_SETTINGS_ACTIVE_TAB = def;
  errorOk();
 }
 void uiSettingsTabChanged(
  const uimenu_t *menu,
  const uint8_t index,
  const uimenuitem_t *item
 ) {
  if(index >= UI_SETTINGS_TAB_COUNT) return;
  errorCatch(uiSettingsActivateTab(&UI_SETTINGS_TAB_DEFS[index]));
 }
 void uiSettingsTabSelected(
  const uimenu_t *menu,
  const uint8_t index,
  const uimenuitem_t *item
 ) {
  if(index >= UI_SETTINGS_TAB_COUNT) return;
  uisettingstabdef_t *def = &UI_SETTINGS_TAB_DEFS[index];
  errorCatch(uiSettingsActivateTab(def));
  uiMenuOpen(def->menu);
 }
 errorret_t uiSettingsInit(void) {
  memoryZero(&UI_SETTINGS, sizeof(uisettings_t));
  UI_SETTINGS_ACTIVE_TAB = NULL;
  for(uint8_t i = 0; i < UI_SETTINGS_TAB_COUNT; i++) {
    errorChain(assetLocaleGetString(
      &LOCALE.entry->data.locale,
      UI_SETTINGS_TAB_DEFS[i].localeId,
      0,
      UI_SETTINGS.tabLabels[i],
      UI_SETTINGS_TAB_LABEL_MAX
    ));
  }
  MENU_BEGIN(
    &UI_SETTINGS.tabsMenu, UI_SETTINGS.tabs, uiSettingsTabSelected,
    uiSettingsDiscardMenuClosed, uiSettingsTabChanged
  );
  for(uint8_t i = 0; i < UI_SETTINGS_TAB_COUNT; i++) {
    MENU_TAB(UI_SETTINGS.tabLabels[i]);
  }
  MENU_END(UI_SETTINGS.tabs, menuIndex);
  UI_SETTINGS.tabsMenu.user = &UI_SETTINGS_TOP_DEF;
  errorChain(assetLocaleGetString(
    &LOCALE.entry->data.locale,
    "ui.settings.apply",
    0,
    UI_SETTINGS.applyLabel,
    UI_SETTINGS_APPLY_LABEL_MAX
  ));
  errorChain(uiSettingsActivateTab(&UI_SETTINGS_TAB_DEFS[0]));
  errorOk();
 }
 errorret_t uiSettingsDraw(void) {
  if(!uiMenuIsActive(&UI_SETTINGS.tabsMenu)) errorOk();
  const float_t width = SCREEN.width;
  const float_t height = SCREEN.height;
  const float_t x = (float_t)SCREEN.scanX +
    ((float_t)SCREEN.scanWidth - width) * 0.5f;
  const float_t y = (float_t)SCREEN.scanY +
    ((float_t)SCREEN.scanHeight - height) * 0.5f;
  errorChain(uiFrameDrawCached(&UI_SETTINGS.frameCache, x, y, width, height));
  const float_t contentX = x + UI_FRAME_START_X;
  const float_t contentY = y + UI_FRAME_START_Y;
  const float_t contentWidth = width - (UI_FRAME_START_X * 2);
  const float_t contentHeight = height - (UI_FRAME_START_Y * 2);
  errorChain(uiMenuDraw(
    &UI_SETTINGS.tabsMenu,
    contentX,
    contentY,
    contentWidth,
    contentHeight
  ));
  const float_t tabsRowHeight = (float_t)FONT_DEFAULT.tileset->tileHeight;
  const float_t pageY = contentY + tabsRowHeight + UI_FRAME_PADDING_Y;
  const float_t pageHeight = contentHeight - tabsRowHeight - UI_FRAME_PADDING_Y;
  if(UI_SETTINGS_ACTIVE_TAB != NULL) {
    errorChain(uiMenuDraw(
      UI_SETTINGS_ACTIVE_TAB->menu, contentX, pageY, contentWidth, pageHeight
    ));
  }
  errorOk();
 }
 errorret_t uiSettingsUpdate(void) {
  if(!UI_SETTINGS_PENDING_DISCARD) errorOk();
  uisettingstabdef_t *def = UI_SETTINGS_PENDING_DISCARD;
  UI_SETTINGS_PENDING_DISCARD = NULL;
  return uiSettingsDiscardUpdate(def);
 }
 bool_t uiSettingsIsOpen(void) {
  return uiMenuIsActive(&UI_SETTINGS.tabsMenu);
 }
 void uiSettingsOpen() {
  uiSettingsLoad();
  uiMenuOpen(&UI_SETTINGS.tabsMenu);
 }
 void uiSettingsClose() {
  uiMenuClose(&UI_SETTINGS.tabsMenu);
 }
 errorret_t uiSettingsDispose(void) {
  errorOk();
 }
 void uiSettingsLoad(void) {
  if(UI_SETTINGS_ACTIVE_TAB != NULL) UI_SETTINGS_ACTIVE_TAB->load();
 }
 void uiSettingsApply(void) {
  if(UI_SETTINGS_ACTIVE_TAB != NULL) UI_SETTINGS_ACTIVE_TAB->apply();
 }
 bool_t uiSettingsHasChanges(void) {
  return UI_SETTINGS_ACTIVE_TAB != NULL && UI_SETTINGS_ACTIVE_TAB->hasChanges();
 }
 void uiSettingsDiscardMenuClosed(const uimenu_t *menu) {
  uisettingstabdef_t *def = (uisettingstabdef_t *)menu->user;
  if(def->hasChanges()) UI_SETTINGS_PENDING_DISCARD = def;
 }
 errorret_t uiSettingsDiscardUpdate(uisettingstabdef_t *def) {
  #define UI_SETTINGS_DISCARD_TEXT_MAX 128
  char_t text[UI_SETTINGS_DISCARD_TEXT_MAX];
  errorChain(assetLocaleGetString(
    &LOCALE.entry->data.locale,
    "ui.confirm.discard_changes",
    0,
    text,
    UI_SETTINGS_DISCARD_TEXT_MAX
  ));
  #undef UI_SETTINGS_DISCARD_TEXT_MAX
  uiConfirmOpen(text, uiSettingsDiscardConfirmResult, def);
  errorOk();
 }
 void uiSettingsDiscardConfirmResult(const bool_t result, void *user) {
  uisettingstabdef_t *def = (uisettingstabdef_t *)user;
  if(!result) {
    uiMenuOpen(def->menu);
    return;
  }
  def->load();
 }
@@ -0,0 +1,135 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "ui/widget/uimenu.h"
 #include "ui/frame/uiframe.h"
 #include "uisettingsdata.h"
 #define UI_SETTINGS_TAB_COUNT 4
 #define UI_SETTINGS_TAB_LABEL_MAX 32
 #define UI_SETTINGS_APPLY_LABEL_MAX 32
 typedef struct {
  const char_t *localeId;
  errorret_t (*init)(uisettingsdata_t *data);
  uimenu_t *menu;
  void (*load)(void);
  void (*apply)(void);
  bool_t (*hasChanges)(void);
 } uisettingstabdef_t;
 typedef struct {
  uimenu_t tabsMenu;
  uimenuitem_t tabs[UI_SETTINGS_TAB_COUNT];
  char_t tabLabels[UI_SETTINGS_TAB_COUNT][UI_SETTINGS_TAB_LABEL_MAX];
  char_t applyLabel[UI_SETTINGS_APPLY_LABEL_MAX];
  uisettingsdata_t data;
  uiframecache_t frameCache;
 } uisettings_t;
 extern uisettings_t UI_SETTINGS;
 extern uisettingstabdef_t UI_SETTINGS_TAB_DEFS[UI_SETTINGS_TAB_COUNT];
 /**
 * Menu closed callback that flags a pending discard-changes
 * confirmation if the menu's settings page/panel reports unsaved
 * changes. Pass this directly as a settings page menu's closed
 * callback. The pending def is picked up by uiSettingsUpdate on the
 * next tick.
 *
 * @param menu The menu that was just closed.
 */
 void uiSettingsDiscardMenuClosed(const uimenu_t *menu);
 /**
 * Shows the discard-changes confirmation dialog for def. Called once
 * by uiSettingsUpdate when uiSettingsDiscardMenuClosed has flagged a
 * pending def.
 *
 * @param def The tab/panel def to show the confirmation for.
 * @return Any error that occurs.
 */
 errorret_t uiSettingsDiscardUpdate(uisettingstabdef_t *def);
 /**
 * Callback passed to uiConfirmOpen by uiSettingsDiscardUpdate. Reopens
 * the menu if the user chose to keep editing, otherwise reloads the
 * widgets back to the actual engine values.
 *
 * @param result True if the user confirmed discarding changes, false
 * to keep editing.
 * @param user The uisettingstabdef_t* this confirmation belongs to.
 */
 void uiSettingsDiscardConfirmResult(const bool_t result, void *user);
 /**
 * Initializes the settings panel and all of its category pages.
 *
 * @return Any error that occurs.
 */
 errorret_t uiSettingsInit(void);
 /**
 * Draws the settings panel. No-op when not visible.
 *
 * @return Any error that occurs.
 */
 errorret_t uiSettingsDraw(void);
 /**
 * Updates the settings panel. Shows a discard-changes confirmation if
 * the panel was just closed with unsaved changes.
 *
 * @return Any error that occurs.
 */
 errorret_t uiSettingsUpdate(void);
 /**
 * Returns true when the settings panel is currently open.
 *
 * @returns True if open.
 */
 bool_t uiSettingsIsOpen(void);
 /**
 * Opens the settings panel. No-op when already open.
 */
 void uiSettingsOpen();
 /**
 * Closes the settings panel. No-op when already closed.
 */
 void uiSettingsClose();
 /**
 * Disposes of the settings panel.
 *
 * @return Any error that occurs.
 */
 errorret_t uiSettingsDispose(void);
 /**
 * Loads every category page's widgets from the current engine settings.
 * Called automatically by uiSettingsOpen.
 */
 void uiSettingsLoad(void);
 /**
 * Applies every category page's widget values to the engine settings.
 * Called automatically when a page's own Apply button is pressed.
 */
 void uiSettingsApply(void);
 /**
 * Returns whether any category page has a widget value that differs
 * from what was loaded.
 *
 * @returns True if there are unsaved changes.
 */
 bool_t uiSettingsHasChanges(void);
@@ -0,0 +1,47 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uisettingsaudio.h"
 #include "uisettings.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 void uiSettingsAudioSelected(
  const uimenu_t *menu,
  const uint8_t index,
  const uimenuitem_t *item
 ) {
  if(index != UI_SETTINGS_AUDIO_INDEX_APPLY) return;
  uiSettingsAudioApply();
 }
 errorret_t uiSettingsAudioInit(uisettingsdata_t *data) {
  uisettingsaudio_t *audio = &data->audio;
  memoryZero(audio, sizeof(uisettingsaudio_t));
  MENU_BEGIN(
    &audio->menu, audio->items,
    uiSettingsAudioSelected, uiSettingsDiscardMenuClosed, NULL
  );
  MENU_LABEL("No audio settings yet");
  MENU_BUTTON(UI_SETTINGS.applyLabel);
  MENU_END(audio->items, 1);
  errorOk();
 }
 void uiSettingsAudioLoad(void) {
 }
 void uiSettingsAudioApply(void) {
  uiMenuClose(&UI_SETTINGS.data.audio.menu);
 }
 bool_t uiSettingsAudioHasChanges(void) {
  return false;
 }
@@ -0,0 +1,36 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "uisettingsdata.h"
 /**
 * Initializes the audio settings page into the shared settings data
 * union.
 *
 * @param data The shared settings data union to initialize into.
 * @return Any error that occurs.
 */
 errorret_t uiSettingsAudioInit(uisettingsdata_t *data);
 /**
 * Loads the page's widgets from the current engine audio settings.
 */
 void uiSettingsAudioLoad(void);
 /**
 * Applies the page's widget values to the engine audio settings.
 */
 void uiSettingsAudioApply(void);
 /**
 * Returns whether any widget's value differs from what was loaded.
 *
 * @returns True if there are unsaved changes.
 */
 bool_t uiSettingsAudioHasChanges(void);
@@ -0,0 +1,67 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "ui/widget/uimenu.h"
 #define UI_SETTINGS_GENERAL_ITEM_COUNT 3
 #define UI_SETTINGS_GENERAL_INDEX_LANGUAGE 0
 #define UI_SETTINGS_GENERAL_INDEX_LANGUAGE_DETAIL 1
 #define UI_SETTINGS_GENERAL_INDEX_APPLY 2
 #define UI_SETTINGS_GENERAL_LOCALE_COUNT 3
 #define UI_SETTINGS_GENERAL_LABEL_MAX 32
 #define UI_SETTINGS_GENERAL_INFO_MAX 64
 typedef struct {
  uimenu_t menu;
  uimenuitem_t items[UI_SETTINGS_GENERAL_ITEM_COUNT];
  const char_t *localeNames[UI_SETTINGS_GENERAL_LOCALE_COUNT];
  char_t languageLabel[UI_SETTINGS_GENERAL_LABEL_MAX];
  char_t labelInfo[UI_SETTINGS_GENERAL_INFO_MAX];
 } uisettingsgeneral_t;
 #define UI_SETTINGS_INPUT_ITEM_COUNT 2
 #define UI_SETTINGS_INPUT_LABEL_MAX 32
 #define UI_SETTINGS_INPUT_INDEX_DEADZONE 0
 #define UI_SETTINGS_INPUT_INDEX_APPLY 1
 typedef struct {
  uimenu_t menu;
  uimenuitem_t items[UI_SETTINGS_INPUT_ITEM_COUNT];
  char_t deadzoneLabel[UI_SETTINGS_INPUT_LABEL_MAX];
 } uisettingsinput_t;
 #define UI_SETTINGS_DISPLAY_ITEM_COUNT 2
 #define UI_SETTINGS_DISPLAY_INDEX_APPLY 1
 typedef struct {
  uimenu_t menu;
  uimenuitem_t items[UI_SETTINGS_DISPLAY_ITEM_COUNT];
 } uisettingsdisplay_t;
 #define UI_SETTINGS_AUDIO_ITEM_COUNT 2
 #define UI_SETTINGS_AUDIO_INDEX_APPLY 1
 typedef struct {
  uimenu_t menu;
  uimenuitem_t items[UI_SETTINGS_AUDIO_ITEM_COUNT];
 } uisettingsaudio_t;
 /**
 * Shared, overlapping storage for every settings tab's page data. Only
 * one member is ever live at a time -- the active tab's Init writes
 * into it, overwriting whatever the previously active tab left there.
 * This trades simultaneous access to every tab for a memory footprint
 * of only the single largest page.
 */
 typedef union {
  uisettingsgeneral_t general;
  uisettingsinput_t input;
  uisettingsdisplay_t display;
  uisettingsaudio_t audio;
 } uisettingsdata_t;
@@ -0,0 +1,47 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uisettingsdisplay.h"
 #include "uisettings.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 void uiSettingsDisplaySelected(
  const uimenu_t *menu,
  const uint8_t index,
  const uimenuitem_t *item
 ) {
  if(index != UI_SETTINGS_DISPLAY_INDEX_APPLY) return;
  uiSettingsDisplayApply();
 }
 errorret_t uiSettingsDisplayInit(uisettingsdata_t *data) {
  uisettingsdisplay_t *display = &data->display;
  memoryZero(display, sizeof(uisettingsdisplay_t));
  MENU_BEGIN(
    &display->menu, display->items,
    uiSettingsDisplaySelected, uiSettingsDiscardMenuClosed, NULL
  );
  MENU_LABEL("No display settings yet");
  MENU_BUTTON(UI_SETTINGS.applyLabel);
  MENU_END(display->items, 1);
  errorOk();
 }
 void uiSettingsDisplayLoad(void) {
 }
 void uiSettingsDisplayApply(void) {
  uiMenuClose(&UI_SETTINGS.data.display.menu);
 }
 bool_t uiSettingsDisplayHasChanges(void) {
  return false;
 }
@@ -0,0 +1,36 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "uisettingsdata.h"
 /**
 * Initializes the display settings page into the shared settings data
 * union.
 *
 * @param data The shared settings data union to initialize into.
 * @return Any error that occurs.
 */
 errorret_t uiSettingsDisplayInit(uisettingsdata_t *data);
 /**
 * Loads the page's widgets from the current engine display settings.
 */
 void uiSettingsDisplayLoad(void);
 /**
 * Applies the page's widget values to the engine display settings.
 */
 void uiSettingsDisplayApply(void);
 /**
 * Returns whether any widget's value differs from what was loaded.
 *
 * @returns True if there are unsaved changes.
 */
 bool_t uiSettingsDisplayHasChanges(void);
@@ -0,0 +1,117 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uisettingsgeneral.h"
 #include "uisettings.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "util/string.h"
 #include "locale/localemanager.h"
 #include "locale/localeinfo.h"
 #include "asset/loader/locale/assetlocaleloader.h"
 static const localeinfo_t *const UI_SETTINGS_GENERAL_LOCALES[
  UI_SETTINGS_GENERAL_LOCALE_COUNT
 ] = {
  &LOCALE_EN_US,
  &LOCALE_JP_JP,
  &LOCALE_ES_MX
 };
 void uiSettingsGeneralSelected(
  const uimenu_t *menu,
  const uint8_t index,
  const uimenuitem_t *item
 ) {
  switch(index) {
    case UI_SETTINGS_GENERAL_INDEX_APPLY:
      uiSettingsGeneralApply();
      break;
    default:
      break;
  }
 }
 errorret_t uiSettingsGeneralInit(uisettingsdata_t *data) {
  uisettingsgeneral_t *general = &data->general;
  memoryZero(general, sizeof(uisettingsgeneral_t));
  for(uint8_t i = 0; i < UI_SETTINGS_GENERAL_LOCALE_COUNT; i++) {
    general->localeNames[i] = UI_SETTINGS_GENERAL_LOCALES[i]->name;
  }
  errorChain(assetLocaleGetString(
    &LOCALE.entry->data.locale,
    "ui.settings.general.language",
    0,
    general->languageLabel,
    UI_SETTINGS_GENERAL_LABEL_MAX
  ));
  errorChain(assetLocaleGetString(
    &LOCALE.entry->data.locale,
    "ui.settings.general.language_detail",
    0,
    general->labelInfo,
    UI_SETTINGS_GENERAL_INFO_MAX
  ));
  MENU_BEGIN(
    &general->menu, general->items,
    uiSettingsGeneralSelected, uiSettingsDiscardMenuClosed, NULL
  );
  MENU_DROPDOWN(
    general->languageLabel, general->localeNames,
    UI_SETTINGS_GENERAL_LOCALE_COUNT, 0
  );
  MENU_LABEL(general->labelInfo);
  MENU_BUTTON(UI_SETTINGS.applyLabel);
  MENU_END(general->items, 1);
  errorOk();
 }
 void uiSettingsGeneralLoad(void) {
  uisettingsgeneral_t *general = &UI_SETTINGS.data.general;
  uint8_t index = 0;
  for(uint8_t i = 0; i < UI_SETTINGS_GENERAL_LOCALE_COUNT; i++) {
    if(stringCompare(LOCALE.locale->file, UI_SETTINGS_GENERAL_LOCALES[i]->file) != 0) {
      continue;
    }
    index = i;
    break;
  }
  uiDropdownSetSelectedIndex(
    &general->items[UI_SETTINGS_GENERAL_INDEX_LANGUAGE].dropdown, index
  );
 }
 void uiSettingsGeneralApply(void) {
  uisettingsgeneral_t *general = &UI_SETTINGS.data.general;
  uint8_t index = uiDropdownGetSelectedIndex(
    &general->items[UI_SETTINGS_GENERAL_INDEX_LANGUAGE].dropdown
  );
  errorCatch(localeManagerSetLocale(UI_SETTINGS_GENERAL_LOCALES[index]));
  uiMenuClose(&general->menu);
 }
 bool_t uiSettingsGeneralHasChanges(void) {
  uisettingsgeneral_t *general = &UI_SETTINGS.data.general;
  uint8_t index = uiDropdownGetSelectedIndex(
    &general->items[UI_SETTINGS_GENERAL_INDEX_LANGUAGE].dropdown
  );
  return stringCompare(
    LOCALE.locale->file, UI_SETTINGS_GENERAL_LOCALES[index]->file
  ) != 0;
 }
@@ -0,0 +1,36 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "uisettingsdata.h"
 /**
 * Initializes the general settings page into the shared settings data
 * union.
 *
 * @param data The shared settings data union to initialize into.
 * @return Any error that occurs.
 */
 errorret_t uiSettingsGeneralInit(uisettingsdata_t *data);
 /**
 * Loads the page's widgets from the current engine general settings.
 */
 void uiSettingsGeneralLoad(void);
 /**
 * Applies the page's widget values to the engine general settings.
 */
 void uiSettingsGeneralApply(void);
 /**
 * Returns whether any widget's value differs from what was loaded.
 *
 * @returns True if there are unsaved changes.
 */
 bool_t uiSettingsGeneralHasChanges(void);
@@ -0,0 +1,82 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uisettingsinput.h"
 #include "uisettings.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "locale/localemanager.h"
 #include "asset/loader/locale/assetlocaleloader.h"
 #include "input/input.h"
 #include "save/savesettings.h"
 void uiSettingsInputSelected(
  const uimenu_t *menu,
  const uint8_t index,
  const uimenuitem_t *item
 ) {
  if(index != UI_SETTINGS_INPUT_INDEX_APPLY) return;
  uiSettingsInputApply();
 }
 errorret_t uiSettingsInputInit(uisettingsdata_t *data) {
  uisettingsinput_t *input = &data->input;
  memoryZero(input, sizeof(uisettingsinput_t));
  MENU_BEGIN(
    &input->menu, input->items,
    uiSettingsInputSelected, uiSettingsDiscardMenuClosed, NULL
  );
  #ifdef DUSK_INPUT_GAMEPAD
    errorChain(assetLocaleGetString(
      &LOCALE.entry->data.locale,
      "ui.settings.input.deadzone",
      0,
      input->deadzoneLabel,
      UI_SETTINGS_INPUT_LABEL_MAX
    ));
    MENU_SLIDER_FLOAT(
      input->deadzoneLabel, INPUT_DEADZONE_DEFAULT, 0.0f, 1.0f, 0.05f
    );
  #else
    MENU_LABEL("No input settings yet");
  #endif
  MENU_BUTTON(UI_SETTINGS.applyLabel);
  MENU_END(input->items, 1);
  errorOk();
 }
 void uiSettingsInputLoad(void) {
  #ifdef DUSK_INPUT_GAMEPAD
    uiSliderSetFloat(
      &UI_SETTINGS.data.input.items[UI_SETTINGS_INPUT_INDEX_DEADZONE].slider,
      INPUT.deadzone
    );
  #endif
 }
 void uiSettingsInputApply(void) {
  #ifdef DUSK_INPUT_GAMEPAD
    INPUT.deadzone = uiSliderGetFloat(
      &UI_SETTINGS.data.input.items[UI_SETTINGS_INPUT_INDEX_DEADZONE].slider
    );
  #endif
  errorCatch(errorPrint(saveSettingsWrite()));
  uiMenuClose(&UI_SETTINGS.data.input.menu);
 }
 bool_t uiSettingsInputHasChanges(void) {
  #ifdef DUSK_INPUT_GAMEPAD
    if(uiSliderGetFloat(
      &UI_SETTINGS.data.input.items[UI_SETTINGS_INPUT_INDEX_DEADZONE].slider
    ) != INPUT.deadzone) return true;
  #endif
  return false;
 }
@@ -0,0 +1,36 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "uisettingsdata.h"
 /**
 * Initializes the input settings page into the shared settings data
 * union.
 *
 * @param data The shared settings data union to initialize into.
 * @return Any error that occurs.
 */
 errorret_t uiSettingsInputInit(uisettingsdata_t *data);
 /**
 * Loads the page's widgets from the current engine input settings.
 */
 void uiSettingsInputLoad(void);
 /**
 * Applies the page's widget values to the engine input settings.
 */
 void uiSettingsInputApply(void);
 /**
 * Returns whether any widget's value differs from what was loaded.
 *
 * @returns True if there are unsaved changes.
 */
 bool_t uiSettingsInputHasChanges(void);
@@ -0,0 +1,126 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uiconfirm.h"
 #include "uiframe.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "util/math.h"
 #include "display/screen/screen.h"
 #include "display/text/text.h"
 #include "display/color.h"
 #include "display/spritebatch/spritebatch.h"
 #include "display/texture/texture.h"
 #include "display/shader/shaderunlit.h"
 #define UI_CONFIRM_BACKDROP_COLOR color4b(0, 0, 0, 160)
 uiconfirm_t UI_CONFIRM;
 void uiConfirmSelected(
  const uimenu_t *menu,
  const uint8_t index,
  const uimenuitem_t *item
 ) {
  UI_CONFIRM.result = index == UI_CONFIRM_INDEX_CONFIRM;
  uiConfirmClose();
 }
 void uiConfirmClosed(const uimenu_t *menu) {
  if(UI_CONFIRM.callback != NULL) {
    UI_CONFIRM.callback(UI_CONFIRM.result, UI_CONFIRM.user);
  }
 }
 errorret_t uiConfirmInit(void) {
  memoryZero(&UI_CONFIRM, sizeof(uiconfirm_t));
  uiLabelInit(&UI_CONFIRM.textLabel, &FONT_DEFAULT);
  MENU_BEGIN(
    &UI_CONFIRM.menu, UI_CONFIRM.items, uiConfirmSelected, uiConfirmClosed, NULL
  );
  MENU_BUTTON("Confirm");
  MENU_BUTTON("Cancel");
  MENU_END(UI_CONFIRM.items, menuIndex);
  errorOk();
 }
 errorret_t uiConfirmDraw(void) {
  if(!uiMenuIsActive(&UI_CONFIRM.menu)) errorOk();
  spritebatchsprite_t backdropSprite = {
    .min = { 0.0f, 0.0f, 0.0f },
    .max = { (float_t)SCREEN.width, (float_t)SCREEN.height, 0.0f },
    .uvMin = { 0.0f, 0.0f },
    .uvMax = { 1.0f, 1.0f }
  };
  shadermaterial_t backdropMaterial = {
    .unlit = {
      .color = UI_CONFIRM_BACKDROP_COLOR,
      .texture = &TEXTURE_WHITE
    }
  };
  errorChain(
    spriteBatchBuffer(&backdropSprite, 1, &SHADER_UNLIT, backdropMaterial)
  );
  int32_t textW, textH;
  uiLabelGetSize(&UI_CONFIRM.textLabel, &textW, &textH);
  float_t rowHeight = (float_t)FONT_DEFAULT.tileset->tileHeight;
  float_t width = mathMax(
    (float_t)textW + (UI_FRAME_START_X * 2), UI_CONFIRM_MIN_WIDTH
  );
  float_t height = (UI_FRAME_START_Y * 2) + rowHeight + UI_FRAME_PADDING_Y +
    rowHeight;
  float_t x = (float_t)SCREEN.scanX + ((float_t)SCREEN.scanWidth - width) * 0.5f;
  float_t y = (float_t)SCREEN.scanY + ((float_t)SCREEN.scanHeight - height) * 0.5f;
  errorChain(uiFrameDrawCached(&UI_CONFIRM.frameCache, x, y, width, height));
  float_t contentX = x + UI_FRAME_START_X;
  float_t contentY = y + UI_FRAME_START_Y;
  float_t contentWidth = width - (UI_FRAME_START_X * 2);
  errorChain(uiLabelDraw(&UI_CONFIRM.textLabel, contentX, contentY));
  float_t buttonsY = contentY + rowHeight + UI_FRAME_PADDING_Y;
  errorChain(uiMenuDraw(&UI_CONFIRM.menu, contentX, buttonsY, contentWidth, rowHeight));
  errorOk();
 }
 bool_t uiConfirmIsOpen(void) {
  return uiMenuIsActive(&UI_CONFIRM.menu);
 }
 bool_t uiConfirmGetResult(void) {
  return UI_CONFIRM.result;
 }
 void uiConfirmOpen(
  const char_t *question,
  uiconfirmcallback_t callback,
  void *user
 ) {
  assertNotNull(question, "Question cannot be NULL");
  uiLabelSetText(&UI_CONFIRM.textLabel, question);
  UI_CONFIRM.callback = callback;
  UI_CONFIRM.user = user;
  UI_CONFIRM.result = false;
  uiMenuOpen(&UI_CONFIRM.menu);
 }
 void uiConfirmClose(void) {
  uiMenuClose(&UI_CONFIRM.menu);
 }
 errorret_t uiConfirmDispose(void) {
  errorOk();
 }
@@ -0,0 +1,96 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "ui/widget/uimenu.h"
 #include "ui/widget/uilabel.h"
 #include "ui/frame/uiframe.h"
 #define UI_CONFIRM_MIN_WIDTH 160.0f
 #define UI_CONFIRM_INDEX_CONFIRM 0
 #define UI_CONFIRM_INDEX_CANCEL 1
 #define UI_CONFIRM_ITEM_COUNT 2
 /**
 * Callback invoked once a confirm dialog is dismissed.
 *
 * @param result True if Confirm was selected, false if Cancel was
 * selected or the dialog was backed out of.
 * @param user Arbitrary pointer passed to uiConfirmOpen.
 */
 typedef void (*uiconfirmcallback_t)(const bool_t result, void *user);
 typedef struct {
  uilabel_t textLabel;
  uimenu_t menu;
  uimenuitem_t items[UI_CONFIRM_ITEM_COUNT];
  uiconfirmcallback_t callback;
  void *user;
  bool_t result;
  uiframecache_t frameCache;
 } uiconfirm_t;
 extern uiconfirm_t UI_CONFIRM;
 /**
 * Initializes the confirm dialog.
 *
 * @return Any error that occurs.
 */
 errorret_t uiConfirmInit(void);
 /**
 * Draws the confirm dialog: a semi-transparent black backdrop covering
 * the whole screen, then its own centered frame with the question text
 * and Confirm/Cancel buttons. No-op when not open.
 *
 * @return Any error that occurs.
 */
 errorret_t uiConfirmDraw(void);
 /**
 * Returns true when the confirm dialog is currently open.
 *
 * @returns True if open.
 */
 bool_t uiConfirmIsOpen(void);
 /**
 * Returns the result of the most recently dismissed confirm dialog.
 *
 * @returns True if Confirm was selected, false otherwise.
 */
 bool_t uiConfirmGetResult(void);
 /**
 * Opens the confirm dialog with the given question text. callback is
 * invoked exactly once with the result, whether the dialog was
 * dismissed by selecting a button or by pressing cancel/back.
 *
 * @param question Display text; copied internally, safe to be transient.
 * @param callback Called with the result once the dialog closes. May be
 * NULL.
 * @param user Arbitrary pointer passed through to callback.
 */
 void uiConfirmOpen(
  const char_t *question,
  uiconfirmcallback_t callback,
  void *user
 );
 /**
 * Closes the confirm dialog. No-op when already closed.
 */
 void uiConfirmClose(void);
 /**
 * Disposes of the confirm dialog.
 *
 * @return Any error that occurs.
 */
 errorret_t uiConfirmDispose(void);
@@ -0,0 +1,161 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uiframe.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "display/texture/texture.h"
 #include "display/spritebatch/spritebatch.h"
 #include "display/shader/shaderunlit.h"
 #include "display/color.h"
 uiframe_t UI_FRAME;
 errorret_t uiFrameInit(void) {
  memoryZero(&UI_FRAME, sizeof(uiframe_t));
  // Init texture.
  color_t border = color4b(0, 50, 255, 255);
  color_t center = color4b(0, 100, 220, 240);
  for(uint8_t y = 0; y < UI_FRAME_TEXTURE_HEIGHT_POW2; y++) {
    for(uint8_t x = 0; x < UI_FRAME_TEXTURE_WIDTH_POW2; x++) {
      color_t c;
      if(x >= UI_FRAME_TEXTURE_WIDTH || y >= UI_FRAME_TEXTURE_HEIGHT) {
        c = COLOR_TRANSPARENT;
      } else if(
        y < UI_FRAME_TILE_HEIGHT || y >= UI_FRAME_TILE_HEIGHT * 2 ||
        x < UI_FRAME_TILE_WIDTH  || x >= UI_FRAME_TILE_WIDTH * 2
      ) {
        c = border;
      } else {
        c = center;
      }
      UI_FRAME.pixels[y * UI_FRAME_TEXTURE_WIDTH_POW2 + x] = c;
    }
  }
  errorChain(textureInit(
    &UI_FRAME.texture,
    UI_FRAME_TEXTURE_WIDTH_POW2, UI_FRAME_TEXTURE_HEIGHT_POW2,
    TEXTURE_FORMAT_RGBA,
    (texturedata_t){ .rgbaColors = UI_FRAME.pixels }
  ));
  UI_FRAME.tileset.tileWidth = UI_FRAME_TILE_WIDTH;
  UI_FRAME.tileset.tileHeight = UI_FRAME_TILE_HEIGHT;
  UI_FRAME.tileset.columns = 3;
  UI_FRAME.tileset.rows = 3;
  UI_FRAME.tileset.tileCount = 9;
  UI_FRAME.tileset.uv[0] =
    (float_t)UI_FRAME_TILE_WIDTH / UI_FRAME_TEXTURE_WIDTH_POW2;
  UI_FRAME.tileset.uv[1] =
    (float_t)UI_FRAME_TILE_HEIGHT / UI_FRAME_TEXTURE_HEIGHT_POW2;
  errorOk();
 }
 errorret_t uiFrameDraw(
  const float_t x,
  const float_t y,
  const float_t width,
  const float_t height
 ) {
  shadermaterial_t material = {
    .unlit = {
      .color = COLOR_WHITE,
      .texture = &UI_FRAME.texture
    }
  };
  spritebatchsprite_t sprites[9];
  uiFrameBuildSprites(sprites, x, y, width, height);
  return spriteBatchBuffer(sprites, 9, &SHADER_UNLIT, material);
 }
 void uiFrameBuildSprites(
  spritebatchsprite_t sprites[9],
  const float_t x,
  const float_t y,
  const float_t width,
  const float_t height
 ) {
  float_t tileW = (float_t)UI_FRAME_BORDER_WIDTH;
  float_t tileH = (float_t)UI_FRAME_BORDER_HEIGHT;
  sprites[0] = spriteBatchSpriteTilesetPosition(
    &UI_FRAME.tileset, 0, 0,
    x, y, tileW, tileH
  );
  sprites[1] = spriteBatchSpriteTilesetPosition(
    &UI_FRAME.tileset, 1, 0,
    x + tileW, y, width - (tileW * 2.0f), tileH
  );
  sprites[2] = spriteBatchSpriteTilesetPosition(
    &UI_FRAME.tileset, 2, 0,
    x + width - tileW, y, tileW, tileH
  );
  sprites[3] = spriteBatchSpriteTilesetPosition(
    &UI_FRAME.tileset, 0, 1,
    x, y + tileH, tileW, height - (tileH * 2.0f)
  );
  sprites[4] = spriteBatchSpriteTilesetPosition(
    &UI_FRAME.tileset, 1, 1,
    x + tileW, y + tileH,
    width - (tileW * 2.0f), height - (tileH * 2.0f)
  );
  sprites[5] = spriteBatchSpriteTilesetPosition(
    &UI_FRAME.tileset, 2, 1,
    x + width - tileW, y + tileH, tileW, height - (tileH * 2.0f)
  );
  sprites[6] = spriteBatchSpriteTilesetPosition(
    &UI_FRAME.tileset, 0, 2,
    x, y + height - tileH, tileW, tileH
  );
  sprites[7] = spriteBatchSpriteTilesetPosition(
    &UI_FRAME.tileset, 1, 2,
    x + tileW, y + height - tileH, width - (tileW * 2.0f), tileH
  );
  sprites[8] = spriteBatchSpriteTilesetPosition(
    &UI_FRAME.tileset, 2, 2,
    x + width - tileW, y + height - tileH, tileW, tileH
  );
 }
 errorret_t uiFrameDrawCached(
  uiframecache_t *cache,
  const float_t x,
  const float_t y,
  const float_t width,
  const float_t height
 ) {
  assertNotNull(cache, "Frame cache cannot be NULL");
  if(
    !cache->built ||
    cache->lastX != x || cache->lastY != y ||
    cache->lastWidth != width || cache->lastHeight != height
  ) {
    uiFrameBuildSprites(cache->sprites, x, y, width, height);
    cache->lastX = x;
    cache->lastY = y;
    cache->lastWidth = width;
    cache->lastHeight = height;
    cache->built = true;
  }
  shadermaterial_t material = {
    .unlit = {
      .color = COLOR_WHITE,
      .texture = &UI_FRAME.texture
    }
  };
  return spriteBatchBuffer(cache->sprites, 9, &SHADER_UNLIT, material);
 }
 errorret_t uiFrameDispose(void) {
  return textureDispose(&UI_FRAME.texture);
 }
@@ -0,0 +1,122 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "display/texture/texture.h"
 #include "display/texture/tileset.h"
 #include "display/spritebatch/spritebatchsprite.h"
 #define UI_FRAME_BORDER_WIDTH 6
 #define UI_FRAME_BORDER_HEIGHT 6
 #define UI_FRAME_PADDING_X 2
 #define UI_FRAME_PADDING_Y 2
 #define UI_FRAME_START_X (UI_FRAME_BORDER_WIDTH + UI_FRAME_PADDING_X)
 #define UI_FRAME_START_Y (UI_FRAME_BORDER_HEIGHT + UI_FRAME_PADDING_Y)
 #define UI_FRAME_TILE_WIDTH 1
 #define UI_FRAME_TILE_HEIGHT 1
 #define UI_FRAME_TEXTURE_WIDTH (UI_FRAME_TILE_WIDTH * 3)
 #define UI_FRAME_TEXTURE_HEIGHT (UI_FRAME_TILE_HEIGHT * 3)
 #define UI_FRAME_TEXTURE_WIDTH_POW2 4
 #define UI_FRAME_TEXTURE_HEIGHT_POW2 4 
 typedef struct {
  tileset_t tileset;
  texture_t texture;
  color_t pixels[UI_FRAME_BORDER_WIDTH * UI_FRAME_BORDER_HEIGHT];
 } uiframe_t;
 extern uiframe_t UI_FRAME;
 /**
 * Initializes the global UI_FRAME: builds the dummy texture and
 * configures the tileset. Call once after displayInit().
 *
 * @return Any error that occurs.
 */
 errorret_t uiFrameInit(void);
 /**
 * Draws UI_FRAME using 9-slice rendering from its 3x3 tileset.
 * Pushes quads to the sprite batch without flushing.
 *
 * @param x Screen x position.
 * @param y Screen y position.
 * @param width Total width of the frame.
 * @param height Total height of the frame.
 * @return Any error that occurs.
 */
 errorret_t uiFrameDraw(
  const float_t x,
  const float_t y,
  const float_t width,
  const float_t height
 );
 /**
 * Builds the 9 sprites for a 9-slice frame at the given rect. Used
 * internally by uiFrameDraw and uiFrameDrawCached -- call directly only
 * if you need the raw sprites instead of buffering them.
 *
 * @param sprites Destination array of exactly 9 sprites.
 * @param x Screen x position.
 * @param y Screen y position.
 * @param width Total width of the frame.
 * @param height Total height of the frame.
 */
 void uiFrameBuildSprites(
  spritebatchsprite_t sprites[9],
  const float_t x,
  const float_t y,
  const float_t width,
  const float_t height
 );
 /**
 * A frame's cached 9-slice sprites, plus the rect they were built for.
 * Owned by whichever widget/screen draws a frame repeatedly (dialogs,
 * textboxes, settings panels) so uiFrameDrawCached can skip rebuilding
 * the sprites when the rect hasn't moved since the last draw.
 */
 typedef struct {
  spritebatchsprite_t sprites[9];
  bool_t built;
  float_t lastX;
  float_t lastY;
  float_t lastWidth;
  float_t lastHeight;
 } uiframecache_t;
 /**
 * Draws a 9-slice frame using a caller-owned cache, only rebuilding the
 * sprites (via uiFrameBuildSprites) when x/y/width/height differ from
 * the last call -- unlike uiFrameDraw, which rebuilds unconditionally
 * every time. Prefer this for frames redrawn every frame at a fixed or
 * rarely-changing rect (dialogs, panels); use plain uiFrameDraw for
 * genuinely one-off or per-frame-varying rects.
 *
 * @param cache Caller-owned cache, zero-initialized before first use.
 * @param x Screen x position.
 * @param y Screen y position.
 * @param width Total width of the frame.
 * @param height Total height of the frame.
 * @return Any error that occurs.
 */
 errorret_t uiFrameDrawCached(
  uiframecache_t *cache,
  const float_t x,
  const float_t y,
  const float_t width,
  const float_t height
 );
 /**
 * Disposes of the global UI_FRAME, releasing its GPU texture.
 *
 * @return Any error that occurs.
 */
 errorret_t uiFrameDispose(void);
@@ -0,0 +1,11 @@
 # Copyright (c) 2026 Dominic Masters
 #
 # This software is released under the MIT License.
 # https://opensource.org/licenses/MIT
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    uicrop.c
    uifullbox.c
    uiloading.c
 )
@@ -0,0 +1,89 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uicrop.h"
 #include "display/screen/screen.h"
 #include "display/spritebatch/spritebatch.h"
 #include "display/shader/shaderunlit.h"
 #include "display/texture/texture.h"
 uicrop_t UI_CROP;
 errorret_t uiCropInit(void) {
  UI_CROP.color = COLOR_BLACK;
  errorOk();
 }
 errorret_t uiCropDraw(void) {
  #ifndef DUSK_DISPLAY_SIZE_DYNAMIC
    errorOk();
  #endif
  if(
    SCREEN.scanX == 0 &&
    SCREEN.scanY == 0 &&
    SCREEN.scanWidth == SCREEN.width &&
    SCREEN.scanHeight == SCREEN.height
  ) errorOk();
  float_t x0 = (float_t)SCREEN.scanX;
  float_t y0 = (float_t)SCREEN.scanY;
  float_t x1 = (float_t)(SCREEN.scanX + SCREEN.scanWidth);
  float_t y1 = (float_t)(SCREEN.scanY + SCREEN.scanHeight);
  float_t w = (float_t)SCREEN.width;
  float_t h = (float_t)SCREEN.height;
  spritebatchsprite_t sprites[4];
  int32_t count = 0;
  if(SCREEN.scanX > 0) {
    sprites[count++] = (spritebatchsprite_t){
      .min = { 0.0f, 0.0f, 0.0f },
      .max = { x0, h, 0.0f },
      .uvMin = { 0.0f, 0.0f },
      .uvMax = { 1.0f, 1.0f }
    };
  }
  if(SCREEN.scanX + SCREEN.scanWidth < SCREEN.width) {
    sprites[count++] = (spritebatchsprite_t){
      .min = { x1, 0.0f, 0.0f },
      .max = { w, h, 0.0f },
      .uvMin = { 0.0f, 0.0f },
      .uvMax = { 1.0f, 1.0f }
    };
  }
  if(SCREEN.scanY > 0) {
    sprites[count++] = (spritebatchsprite_t){
      .min = { x0, 0.0f, 0.0f },
      .max = { x1, y0, 0.0f },
      .uvMin = { 0.0f, 0.0f },
      .uvMax = { 1.0f, 1.0f }
    };
  }
  if(SCREEN.scanY + SCREEN.scanHeight < SCREEN.height) {
    sprites[count++] = (spritebatchsprite_t){
      .min = { x0, y1, 0.0f },
      .max = { x1, h, 0.0f },
      .uvMin = { 0.0f, 0.0f },
      .uvMax = { 1.0f, 1.0f }
    };
  }
  if(count == 0) errorOk();
  shadermaterial_t material = {
    .unlit = {
      .color = UI_CROP.color,
      .texture = &TEXTURE_WHITE
    }
  };
  errorChain(spriteBatchBuffer(sprites, count, &SHADER_UNLIT, material));
  errorOk();
 }
@@ -0,0 +1,32 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "display/color.h"
 typedef struct {
  color_t color;
 } uicrop_t;
 extern uicrop_t UI_CROP;
 /**
 * Initializes the crop bars to opaque black.
 *
 * @return Any error that occurs.
 */
 errorret_t uiCropInit(void);
 /**
 * Renders solid-color bars covering every area outside the
 * current scan-safe region. No-ops when the scan area equals
 * the full viewport.
 *
 * @return Any error that occurs.
 */
 errorret_t uiCropDraw(void);
@@ -0,0 +1,122 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uifullbox.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "time/time.h"
 #include "display/screen/screen.h"
 #include "display/texture/texture.h"
 #include "display/spritebatch/spritebatch.h"
 #include "display/shader/shaderunlit.h"
 uifullbox_t UI_FULLBOX_UNDER;
 uifullbox_t UI_FULLBOX_OVER;
 void uiFullboxInit(uifullbox_t *fullbox) {
  assertNotNull(fullbox, "fullbox must not be NULL");
  memoryZero(fullbox, sizeof(uifullbox_t));
  eventInit(
    &fullbox->onTransitionEnd,
    fullbox->onTransitionEndCallbacks,
    fullbox->onTransitionEndUsers,
    4
  );
 }
 void uiFullboxUpdate(uifullbox_t *fullbox, float_t delta) {
  assertNotNull(fullbox, "fullbox must not be NULL");
  if(fullbox->duration <= 0.0f || fullbox->time >= fullbox->duration) return;
  fullbox->time += delta;
  if(fullbox->time >= fullbox->duration) {
    fullbox->time = fullbox->duration;
    eventInvoke(&fullbox->onTransitionEnd, fullbox);
  }
 }
 static color_t uiFullboxGetColor(const uifullbox_t *fullbox) {
  if(fullbox->duration <= 0.0f || fullbox->time >= fullbox->duration) {
    return fullbox->toColor;
  }
  float_t t = easingApply(fullbox->easing, fullbox->time / fullbox->duration);
  return color4b(
    (uint8_t)((float_t)fullbox->fromColor.r +
      ((float_t)fullbox->toColor.r - (float_t)fullbox->fromColor.r) * t),
    (uint8_t)((float_t)fullbox->fromColor.g +
      ((float_t)fullbox->toColor.g - (float_t)fullbox->fromColor.g) * t),
    (uint8_t)((float_t)fullbox->fromColor.b +
      ((float_t)fullbox->toColor.b - (float_t)fullbox->fromColor.b) * t),
    (uint8_t)((float_t)fullbox->fromColor.a +
      ((float_t)fullbox->toColor.a - (float_t)fullbox->fromColor.a) * t)
  );
 }
 errorret_t uiFullboxDraw(uifullbox_t *fullbox) {
  assertNotNull(fullbox, "fullbox must not be NULL");
  color_t color = uiFullboxGetColor(fullbox);
  if(color.a == 0) errorOk();
  spritebatchsprite_t sprite = {
    .min = { 0.0f, 0.0f, 0.0f },
    .max = { (float_t)SCREEN.width, (float_t)SCREEN.height, 0.0f },
    .uvMin = { 0.0f, 0.0f },
    .uvMax = { 1.0f, 1.0f }
  };
  shadermaterial_t material = {
    .unlit = {
      .color = color,
      .texture = &TEXTURE_WHITE
    }
  };
  errorChain(spriteBatchBuffer(&sprite, 1, &SHADER_UNLIT, material));
  errorOk();
 }
 void uiFullboxTransition(
  uifullbox_t *fullbox,
  color_t from,
  color_t to,
  float_t duration,
  easingtype_t easing
 ) {
  assertNotNull(fullbox, "fullbox must not be NULL");
  fullbox->fromColor = from;
  fullbox->toColor = to;
  fullbox->duration = duration;
  fullbox->time = 0.0f;
  fullbox->easing = easing;
 }
 errorret_t uiFullboxUnderInit(void) {
  uiFullboxInit(&UI_FULLBOX_UNDER);
  errorOk();
 }
 errorret_t uiFullboxUnderUpdate(void) {
  uiFullboxUpdate(&UI_FULLBOX_UNDER, TIME.delta);
  errorOk();
 }
 errorret_t uiFullboxUnderDraw(void) {
  return uiFullboxDraw(&UI_FULLBOX_UNDER);
 }
 errorret_t uiFullboxOverInit(void) {
  uiFullboxInit(&UI_FULLBOX_OVER);
  errorOk();
 }
 errorret_t uiFullboxOverUpdate(void) {
  uiFullboxUpdate(&UI_FULLBOX_OVER, TIME.delta);
  errorOk();
 }
 errorret_t uiFullboxOverDraw(void) {
  return uiFullboxDraw(&UI_FULLBOX_OVER);
 }
@@ -0,0 +1,109 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "display/color.h"
 #include "animation/easing.h"
 #include "event/event.h"
 typedef struct {
  color_t fromColor;
  color_t toColor;
  float_t duration;
  float_t time;
  easingtype_t easing;
  eventcallback_t onTransitionEndCallbacks[4];
  void *onTransitionEndUsers[4];
  event_t onTransitionEnd;
 } uifullbox_t;
 extern uifullbox_t UI_FULLBOX_UNDER;
 extern uifullbox_t UI_FULLBOX_OVER;
 /**
 * Initializes a fullbox, zeroing all fields.
 *
 * @param fullbox The fullbox to initialize.
 */
 void uiFullboxInit(uifullbox_t *fullbox);
 /**
 * Advances the fullbox transition. Fires onTransitionEnd once when the
 * transition completes. Safe to call when no transition is running.
 *
 * @param fullbox The fullbox to update.
 * @param delta   Seconds elapsed since last update.
 */
 void uiFullboxUpdate(uifullbox_t *fullbox, float_t delta);
 /**
 * Renders the fullbox. Skipped entirely when the current alpha is zero.
 *
 * @param fullbox The fullbox to draw.
 * @return Any error that occurs.
 */
 errorret_t uiFullboxDraw(uifullbox_t *fullbox);
 /**
 * Begins a color transition.
 *
 * @param fullbox  The fullbox to transition.
 * @param from     Start color.
 * @param to       End color.
 * @param duration Transition duration in seconds.
 * @param easing   Easing function to apply.
 */
 void uiFullboxTransition(
  uifullbox_t *fullbox,
  color_t from,
  color_t to,
  float_t duration,
  easingtype_t easing
 );
 /**
 * Init function for UI_FULLBOX_UNDER (registered in UI_ELEMENTS).
 *
 * @return Any error that occurs.
 */
 errorret_t uiFullboxUnderInit(void);
 /**
 * Update function for UI_FULLBOX_UNDER (registered in UI_ELEMENTS).
 *
 * @return Any error that occurs.
 */
 errorret_t uiFullboxUnderUpdate(void);
 /**
 * Draw function for UI_FULLBOX_UNDER (registered in UI_ELEMENTS).
 *
 * @return Any error that occurs.
 */
 errorret_t uiFullboxUnderDraw(void);
 /**
 * Init function for UI_FULLBOX_OVER (registered in UI_ELEMENTS).
 *
 * @return Any error that occurs.
 */
 errorret_t uiFullboxOverInit(void);
 /**
 * Update function for UI_FULLBOX_OVER (registered in UI_ELEMENTS).
 *
 * @return Any error that occurs.
 */
 errorret_t uiFullboxOverUpdate(void);
 /**
 * Draw function for UI_FULLBOX_OVER (registered in UI_ELEMENTS).
 *
 * @return Any error that occurs.
 */
 errorret_t uiFullboxOverDraw(void);
@@ -0,0 +1,111 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uiloading.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "time/time.h"
 #include "display/text/text.h"
 #include "display/screen/screen.h"
 #include "uifullbox.h"
 #define UI_LOADING_TEXT "loading"
 uiloading_t UI_LOADING;
 errorret_t uiLoadingInit(void) {
  memoryZero(&UI_LOADING, sizeof(uiloading_t));
  uiLabelInit(&UI_LOADING.textLabel, &FONT_DEFAULT);
  uiLabelSetText(&UI_LOADING.textLabel, UI_LOADING_TEXT);
  eventInit(
    &UI_LOADING.onTransitionEnd,
    UI_LOADING.onTransitionEndCallbacks,
    UI_LOADING.onTransitionEndUsers,
    4
  );
  errorOk();
 }
 errorret_t uiLoadingUpdate(void) {
  if(UI_LOADING.duration > 0.0f && UI_LOADING.time < UI_LOADING.duration) {
    UI_LOADING.time += TIME.delta;
    if(UI_LOADING.time >= UI_LOADING.duration) {
      UI_LOADING.time = UI_LOADING.duration;
      eventInvoke(&UI_LOADING.onTransitionEnd, &UI_LOADING);
    }
  }
  errorOk();
 }
 errorret_t uiLoadingDraw(void) {
  float_t alpha;
  if(UI_LOADING.duration <= 0.0f || UI_LOADING.time >= UI_LOADING.duration) {
    alpha = UI_LOADING.toAlpha;
  } else {
    float_t t = UI_LOADING.time / UI_LOADING.duration;
    alpha = UI_LOADING.fromAlpha +
      (UI_LOADING.toAlpha - UI_LOADING.fromAlpha) * t;
  }
  if(alpha <= 0.0f) errorOk();
  int32_t textW, textH;
  uiLabelGetSize(&UI_LOADING.textLabel, &textW, &textH);
  float_t x = (float_t)(SCREEN.scanX + SCREEN.scanWidth) -
    (float_t)textW - UI_LOADING_MARGIN;
  float_t y = (float_t)(SCREEN.scanY + SCREEN.scanHeight) -
    (float_t)textH - UI_LOADING_MARGIN;
  color_t color = COLOR_WHITE;
  color.a = (uint8_t)(alpha * 255.0f);
  uiLabelSetColor(&UI_LOADING.textLabel, color);
  errorChain(uiLabelDraw(&UI_LOADING.textLabel, x, y));
  errorOk();
 }
 static void uiLoadingTransition(
  const float_t from,
  const float_t to,
  const eventcallback_t callback,
  void *user
 ) {
  UI_LOADING.fromAlpha = from;
  UI_LOADING.toAlpha = to;
  UI_LOADING.duration = UI_LOADING_FADE_DURATION;
  UI_LOADING.time = 0.0f;
  eventInit(
    &UI_LOADING.onTransitionEnd,
    UI_LOADING.onTransitionEndCallbacks,
    UI_LOADING.onTransitionEndUsers,
    4
  );
  if(callback) eventSubscribe(&UI_LOADING.onTransitionEnd, callback, user);
 }
 void uiLoadingShow(eventcallback_t callback, void *user) {
  uiLoadingTransition(0.0f, 1.0f, callback, user);
  uiFullboxTransition(
    &UI_FULLBOX_OVER,
    COLOR_TRANSPARENT_BLACK,
    COLOR_BLACK,
    UI_LOADING_FADE_DURATION,
    EASING_LINEAR
  );
 }
 void uiLoadingHide(eventcallback_t callback, void *user) {
  uiLoadingTransition(1.0f, 0.0f, callback, user);
  uiFullboxTransition(
    &UI_FULLBOX_OVER,
    COLOR_BLACK,
    COLOR_TRANSPARENT_BLACK,
    UI_LOADING_FADE_DURATION,
    EASING_LINEAR
  );
 }
@@ -0,0 +1,65 @@
 /**
 * 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 "event/event.h"
 #include "ui/widget/uilabel.h"
 #define UI_LOADING_FADE_DURATION 0.5f
 #define UI_LOADING_MARGIN 8.0f
 typedef struct {
  float_t fromAlpha;
  float_t toAlpha;
  float_t duration;
  float_t time;
  eventcallback_t onTransitionEndCallbacks[4];
  void *onTransitionEndUsers[4];
  event_t onTransitionEnd;
  uilabel_t textLabel;
 } uiloading_t;
 extern uiloading_t UI_LOADING;
 /**
 * Initializes the loading indicator.
 *
 * @return Any error that occurs.
 */
 errorret_t uiLoadingInit(void);
 /**
 * Advances the loading indicator fade transition. Fires onTransitionEnd once
 * when the transition completes.
 *
 * @return Any error that occurs.
 */
 errorret_t uiLoadingUpdate(void);
 /**
 * Draws the loading indicator. No-op when fully transparent.
 *
 * @return Error state.
 */
 errorret_t uiLoadingDraw(void);
 /**
 * Fades the loading indicator in. Invokes callback when fully visible.
 *
 * @param callback Called when the fade-in completes. May be NULL.
 * @param user     Forwarded to the callback unchanged.
 */
 void uiLoadingShow(eventcallback_t callback, void *user);
 /**
 * Fades the loading indicator out. Invokes callback when fully hidden.
 *
 * @param callback Called when the fade-out completes. May be NULL.
 * @param user     Forwarded to the callback unchanged.
 */
 void uiLoadingHide(eventcallback_t callback, void *user);
@@ -0,0 +1,10 @@
 # Copyright (c) 2026 Dominic Masters
 #
 # This software is released under the MIT License.
 # https://opensource.org/licenses/MIT
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    uitransition.c
    uitransitionfade.c
 )
@@ -0,0 +1,81 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uitransition.h"
 #include "uitransitionfade.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "time/time.h"
 #include "util/math.h"
 uitransition_t UI_TRANSITION;
 uitransitiondrawfunc_t UI_TRANSITION_TYPE_DRAW[UI_TRANSITION_TYPE_COUNT] = {
  [UI_TRANSITION_TYPE_FADE] = uiTransitionFadeDraw
 };
 errorret_t uiTransitionInit(void) {
  memoryZero(&UI_TRANSITION, sizeof(uitransition_t));
  // uiTransitionStart((uitransitionstartparams_t){
  //   .duration = 5.0f,
  //   .type = UI_TRANSITION_TYPE_FADE,
  //   .params = {
  //     .fade = {
  //       .easing = EASING_OUT_QUART,
  //       .fromColor = COLOR_TRANSPARENT_BLACK,
  //       .toColor = COLOR_BLACK
  //     }
  //   },
  //   .finished = NULL,
  //   .user = NULL
  // });
  errorOk();
 }
 errorret_t uiTransitionUpdate(void) {
  // Update time.
  float_t newTime = UI_TRANSITION.data.time + TIME.delta;
  UI_TRANSITION.data.time = mathClamp(
    newTime,
    0.0f,
    UI_TRANSITION.data.duration
  );
  UI_TRANSITION.data.t = (
    (UI_TRANSITION.data.duration <= 0.0f) ?
    1.0f :
    (UI_TRANSITION.data.time / UI_TRANSITION.data.duration)
  );
  if(UI_TRANSITION.data.t >= 1.0f && UI_TRANSITION.finished) {
    UI_TRANSITION.finished(UI_TRANSITION.user);
  }
  errorOk();
 }
 errorret_t uiTransitionDraw(void) {
  uitransitiondrawfunc_t draw = UI_TRANSITION_TYPE_DRAW[UI_TRANSITION.type];
  if(!draw) errorOk();
  return draw(&UI_TRANSITION.data);
 }
 void uiTransitionStart(const uitransitionstartparams_t info) {
  assertTrue(info.type > UI_TRANSITION_TYPE_NULL, "Invalid type");
  assertTrue(info.type < UI_TRANSITION_TYPE_COUNT, "Invalid type");
  assertTrue(info.duration >= 0.0f, "Duration must be non-negative");
  memoryZero(&UI_TRANSITION, sizeof(uitransition_t));
  UI_TRANSITION.data.duration = info.duration;
  UI_TRANSITION.type = info.type;
  UI_TRANSITION.data.params = info.params;
  UI_TRANSITION.finished = info.finished;
  UI_TRANSITION.user = info.user;
 }
@@ -0,0 +1,74 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "display/color.h"
 #include "animation/easing.h"
 #include "uitransitiondata.h"
 typedef void (*uitransitioncallback_t)(void *user);
 typedef enum {
  UI_TRANSITION_TYPE_NULL,
  UI_TRANSITION_TYPE_FADE,
  UI_TRANSITION_TYPE_COUNT
 } uitransitiontype_t;
 extern uitransitiondrawfunc_t UI_TRANSITION_TYPE_DRAW[UI_TRANSITION_TYPE_COUNT];
 typedef struct {
  uitransitiondata_t data;
  uitransitiontype_t type;
  uitransitioncallback_t finished;
  void *user;
 } uitransition_t;
 extern uitransition_t UI_TRANSITION;
 /**
 * Initializes the transition overlay, zeroing all fields and wiring the
 * onTransitionEnd event.
 *
 * @return Any error that occurs.
 */
 errorret_t uiTransitionInit(void);
 /**
 * Advances the transition. Fires onTransitionEnd once when it completes.
 * Safe to call when no transition is running.
 *
 * @return Any error that occurs.
 */
 errorret_t uiTransitionUpdate(void);
 /**
 * Renders the transition overlay. Skipped entirely when the current alpha
 * is zero.
 *
 * @return Any error that occurs.
 */
 errorret_t uiTransitionDraw(void);
 typedef struct {
  float_t duration;
  uitransitiontype_t type;
  uitransitionparams_t params;
  uitransitioncallback_t finished;
  void *user;
 } uitransitionstartparams_t;
 /**
 * Starts a transition described by an info struct.
 *
 * @param info Transition parameters.
 */
 void uiTransitionStart(const uitransitionstartparams_t info);
@@ -0,0 +1,23 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "uitransitionfade.h"
 typedef union uitransitionparams_u {
  uitransitionfade_t fade;
 } uitransitionparams_t;
 typedef struct uitransitiondata_s {
  float_t time;
  float_t duration;
  float_t t;
  uitransitionparams_t params;
 } uitransitiondata_t;
 typedef errorret_t (*uitransitiondrawfunc_t)(const uitransitiondata_t *data);
@@ -0,0 +1,56 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uitransition.h"
 #include "assert/assert.h"
 #include "display/screen/screen.h"
 #include "display/texture/texture.h"
 #include "display/spritebatch/spritebatch.h"
 #include "display/shader/shaderunlit.h"
 errorret_t uiTransitionFadeDraw(const uitransitiondata_t *data) {
  assertNotNull(data, "data must not be NULL");
  float_t e = easingApply(data->params.fade.easing, data->t);
  float_t r = (float_t)(
    data->params.fade.toColor.r - data->params.fade.fromColor.r
  ) * e;
  float_t g = (float_t)(
    data->params.fade.toColor.g - data->params.fade.fromColor.g
  ) * e;
  float_t b = (float_t)(
    data->params.fade.toColor.b - data->params.fade.fromColor.b
  ) * e;
  float_t a = (float_t)(
    data->params.fade.toColor.a - data->params.fade.fromColor.a
  ) * e;
  color_t color = color4b(
    data->params.fade.fromColor.r + (uint8_t)r,
    data->params.fade.fromColor.g + (uint8_t)g,
    data->params.fade.fromColor.b + (uint8_t)b,
    data->params.fade.fromColor.a + (uint8_t)a
  );
  if(color.a == 0) errorOk();
  spritebatchsprite_t sprite = {
    .min = { 0.0f, 0.0f, 0.0f },
    .max = { (float_t)SCREEN.width, (float_t)SCREEN.height, 0.0f },
    .uvMin = { 0.0f, 0.0f },
    .uvMax = { 1.0f, 1.0f }
  };
  shadermaterial_t material = {
    .unlit = {
      .color = color,
      .texture = NULL
    }
  };
  errorChain(spriteBatchBuffer(&sprite, 1, &SHADER_UNLIT, material));
  errorOk();
 }
@@ -0,0 +1,29 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "display/color.h"
 #include "animation/easing.h"
 typedef struct uitransitiondata_s uitransitiondata_t;
 typedef struct {
  color_t fromColor;
  color_t toColor;
  easingtype_t easing;
 } uitransitionfade_t;
 /**
 * Renders a full-screen color overlay interpolated between fade->fromColor
 * and fade->toColor using fade->easing. t is the raw normalized progress
 * in [0, 1] before easing is applied. No-op when the resulting alpha is zero.
 *
 * @param fade The fade parameters.
 * @return Any error that occurs.
 */
 errorret_t uiTransitionFadeDraw(const uitransitiondata_t *fade);
@@ -0,0 +1,62 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "ui.h"
 #include "util/memory.h"
 #include "assert/assert.h"
 #include "display/spritebatch/spritebatch.h"
 #include "display/screen/screen.h"
 #include "ui/uielement.h"
 #include "ui/focus/uifocus.h"
 ui_t UI;
 errorret_t uiInit(void) {
  memoryZero(&UI, sizeof(ui_t));
  uiFocusInit();
  uiElementsSort();
  uielement_t *element = &UI_ELEMENTS[0];
  while(!uiElementIsNull(element)) {
    errorChain(uiElementInit(element));
    element++;
  }
  errorOk();
 }
 errorret_t uiUpdate(void) {
  uiFocusUpdate();
  uielement_t *element = &UI_ELEMENTS[0];
  while(!uiElementIsNull(element)) {
    errorChain(uiElementUpdate(element));
    element++;
  }
  errorOk();
 }
 errorret_t uiRender(void) {
  const uielement_t *element = &UI_ELEMENTS[0];
  while(!uiElementIsNull(element)) {
    errorChain(uiElementDraw(element));
    element++;
  }
  errorChain(spriteBatchFlush());
  errorOk();
 }
 errorret_t uiDispose(void) {
  uielement_t *element = &UI_ELEMENTS[0];
  while(!uiElementIsNull(element)) {
    errorChain(uiElementDispose(element));
    element++;
  }
  errorOk();
 }
@@ -6,11 +6,10 @@
 */
 #pragma once
 #include "display/camera/camera.h"
 #include "error/error.h"
 typedef struct {
-  camera_t camera;
+  void *nothing;
 } ui_t;
 extern ui_t UI;
@@ -22,15 +21,21 @@ errorret_t uiInit(void);
 /**
 * Updates the UI system.
 *
 * @return Any error that occurs.
 */
-void uiUpdate(void);
+errorret_t uiUpdate(void);
 /**
 * Renders the UI system.
 * 
 * @return Any error that occurs.
 */
-void uiRender(void);
+errorret_t uiRender(void);
 /**
 * Disposes of the UI system.
 *
 * @return Any error that occurs.
 */
-void uiDispose(void);
+errorret_t uiDispose(void);
@@ -0,0 +1,86 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uielement.h"
 #include "assert/assert.h"
 #include "util/sort.h"
 #include "ui/frame/uiframe.h"
 #include "ui/debug/uifps.h"
 #include "engine/engine.h"
 #include "ui/overlay/uifullbox.h"
 #include "ui/overlay/uiloading.h"
 #include "ui/overlay/uicrop.h"
 #include "ui/transition/uitransition.h"
 #include "ui/debug/uiconsole.h"
 #include "ui/frame/uiconfirm.h"
 // Priming pass: X does nothing here, so this only exists to process any
 // #include directives nested in uielementlist.h/ui/uielementgame.h at
 // file scope (each such header's own #pragma once makes it a no-op on
 // the real pass below, which happens inside UI_ELEMENTS[]'s braces,
 // where a raw #include of a declaration would be invalid).
 #define X(initFn, updateFn, drawFn, disposeFn, order) // do nothing
 #include "uielementlist.h"
 #undef X
 uielement_t UI_ELEMENTS[] = {
  #define X(initFn, updateFn, drawFn, disposeFn, elementOrder) \
    { \
      .init = initFn, .update = updateFn, .draw = drawFn, \
      .dispose = disposeFn, .order = elementOrder \
    },
  #include "uielementlist.h"
  #undef X
  { 0 } // Null terminator
 };
 bool_t uiElementIsNull(const uielement_t *element) {
  return element->init == NULL &&
    element->update == NULL &&
    element->draw == NULL &&
    element->dispose == NULL;
 }
 int_t uiElementCompareOrder(const void *a, const void *b) {
  const uielement_t *elementA = (const uielement_t *)a;
  const uielement_t *elementB = (const uielement_t *)b;
  if(elementA->order < elementB->order) return -1;
  if(elementA->order > elementB->order) return 1;
  return 0;
 }
 void uiElementsSort(void) {
  // The trailing null terminator is always the last static entry -- sort
  // everything before it, and leave it in place.
  const size_t count = (sizeof(UI_ELEMENTS) / sizeof(UI_ELEMENTS[0])) - 1;
  sortBubble(UI_ELEMENTS, count, sizeof(uielement_t), uiElementCompareOrder);
 }
 errorret_t uiElementInit(uielement_t *element) {
  assertNotNull(element, "element must not be NULL");
  if(element->init != NULL) errorChain(element->init());
  errorOk();
 }
 errorret_t uiElementUpdate(uielement_t *element) {
  assertNotNull(element, "element must not be NULL");
  if(element->update != NULL) errorChain(element->update());
  errorOk();
 }
 errorret_t uiElementDraw(const uielement_t *element) {
  assertNotNull(element, "element must not be NULL");
  if(element->draw != NULL) errorChain(element->draw());
  errorOk();
 }
 errorret_t uiElementDispose(uielement_t *element) {
  assertNotNull(element, "element must not be NULL");
  if(element->dispose != NULL) errorChain(element->dispose());
  errorOk();
 }
@@ -0,0 +1,84 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 // Built-in order tiers. Lower values update/render first; ties preserve
 // their relative UI_ELEMENTS declaration order (uiElementsSort uses a
 // stable sort). Game-specific elements can use any int32_t value -- these
 // are just the ones the engine itself relies on.
 #define UI_ELEMENT_ORDER_DEFAULT 0
 #define UI_ELEMENT_ORDER_DEBUG   1000
 typedef struct {
  errorret_t (*init)();
  errorret_t (*update)();
  errorret_t (*draw)();
  errorret_t (*dispose)();
  int32_t order;
 } uielement_t;
 extern uielement_t UI_ELEMENTS[];
 /**
 * Returns true when all four callbacks on the element are NULL,
 * which marks the end of the UI_ELEMENTS array.
 *
 * @param element The element to test.
 * @returns True if the element is the null terminator.
 */
 bool_t uiElementIsNull(const uielement_t *element);
 /**
 * Compares two elements by their .order field, ascending. Matches
 * sortcompare_t, for use with the project's sort utilities.
 *
 * @param a First uielement_t to compare.
 * @param b Second uielement_t to compare.
 * @return Negative if a < b, zero if a == b, positive if a > b.
 */
 int_t uiElementCompareOrder(const void *a, const void *b);
 /**
 * Stably sorts UI_ELEMENTS in place by .order, ascending. The trailing
 * null terminator is never moved. Called once by uiInit -- element order
 * is static after that, so there's no need to re-sort every frame.
 */
 void uiElementsSort(void);
 /**
 * Initializes a UI element, invoking its init callback if set.
 *
 * @param element The element to initialize.
 * @return Any error that occurs.
 */
 errorret_t uiElementInit(uielement_t *element);
 /**
 * Updates a UI element, calling its update callback if set.
 *
 * @param element The element to update.
 * @return Any error that occurs.
 */
 errorret_t uiElementUpdate(uielement_t *element);
 /**
 * Draws a UI element, calling its draw callback if set.
 *
 * @param element The element to render.
 * @return Any error that occurs.
 */
 errorret_t uiElementDraw(const uielement_t *element);
 /**
 * Disposes of a UI element, invoking its dispose callback if set.
 *
 * @param element The element to dispose.
 * @return Any error that occurs.
 */
 errorret_t uiElementDispose(uielement_t *element);
@@ -0,0 +1,47 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 // X(init, update, draw, dispose, order) -- pass NULL for any callback the
 // element doesn't need. order controls update/draw sequence (lower first,
 // see UI_ELEMENT_ORDER_* in uielement.h); ties preserve declaration order.
 // See uielement.c for how this expands.
 X(uiFrameInit, NULL, NULL, uiFrameDispose, UI_ELEMENT_ORDER_DEFAULT)
 // Fullbox under: above scene, below system UI.
 X(
  uiFullboxUnderInit, uiFullboxUnderUpdate, uiFullboxUnderDraw, NULL,
  UI_ELEMENT_ORDER_DEFAULT
 )
 // Text stuffs
 X(uiConfirmInit, NULL, uiConfirmDraw, uiConfirmDispose, UI_ELEMENT_ORDER_DEFAULT)
 X(
  uiTransitionInit, uiTransitionUpdate, uiTransitionDraw, NULL,
  UI_ELEMENT_ORDER_DEFAULT
 )
 // Fullbox over: above absolutely everything (except debug).
 X(
  uiFullboxOverInit, uiFullboxOverUpdate, uiFullboxOverDraw, NULL,
  UI_ELEMENT_ORDER_DEFAULT
 )
 X(
  uiLoadingInit, uiLoadingUpdate, uiLoadingDraw, NULL,
  UI_ELEMENT_ORDER_DEFAULT
 )
 X(uiCropInit, NULL, uiCropDraw, NULL, UI_ELEMENT_ORDER_DEFAULT)
 // Debug items -- always last.
 X(NULL, NULL, uiConsoleDraw, uiConsoleDispose, UI_ELEMENT_ORDER_DEBUG)
 X(uiFPSInit, NULL, uiFPSDraw, NULL, UI_ELEMENT_ORDER_DEBUG)
 // Game-specific UI elements (duskrpg)
 #include "ui/uielementgame.h"
@@ -0,0 +1,17 @@
 # Copyright (c) 2026 Dominic Masters
 #
 # This software is released under the MIT License.
 # https://opensource.org/licenses/MIT
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    uibutton.c
    uicheckbox.c
    uitab.c
    uislider.c
    uidropdown.c
    uiscrolling.c
    uimenu.c
    uilabel.c
    uiwidgetlabel.c
 )
@@ -0,0 +1,42 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uibutton.h"
 #include "assert/assert.h"
 #include "display/text/text.h"
 #include "display/color.h"
 void uiButtonInit(uibutton_t *button, const char_t *label) {
  assertNotNull(button, "Button cannot be NULL");
  assertNotNull(label, "Label cannot be NULL");
  uiWidgetLabelInit(&button->label, &FONT_DEFAULT);
  uiWidgetLabelSetText(&button->label, label);
  button->highlighted = false;
 }
 bool_t uiButtonIsHighlighted(const uibutton_t *button) {
  assertNotNull(button, "Button cannot be NULL");
  return button->highlighted;
 }
 void uiButtonSetHighlighted(uibutton_t *button, const bool_t highlighted) {
  assertNotNull(button, "Button cannot be NULL");
  button->highlighted = highlighted;
  uiWidgetLabelSetColor(
    &button->label, highlighted ? COLOR_RED : COLOR_WHITE
  );
 }
 errorret_t uiButtonDraw(
  const uibutton_t *button,
  const float_t x,
  const float_t y
 ) {
  assertNotNull(button, "Button cannot be NULL");
  errorChain(uiWidgetLabelDraw(&button->label, x, y));
  errorOk();
 }
@@ -0,0 +1,53 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "ui/widget/uiwidgetlabel.h"
 typedef struct {
  uiwidgetlabel_t label;
  bool_t highlighted;
 } uibutton_t;
 /**
 * Initializes a button.
 *
 * @param button The button to initialize.
 * @param label Display label.
 */
 void uiButtonInit(uibutton_t *button, const char_t *label);
 /**
 * Returns whether the button is highlighted.
 *
 * @param button The button to query.
 * @returns True if highlighted.
 */
 bool_t uiButtonIsHighlighted(const uibutton_t *button);
 /**
 * Sets the highlighted state of the button.
 *
 * @param button The button to update.
 * @param highlighted The new highlighted state.
 */
 void uiButtonSetHighlighted(uibutton_t *button, const bool_t highlighted);
 /**
 * Draws the button at the given screen position.
 *
 * @param button The button to draw.
 * @param x Screen x position.
 * @param y Screen y position.
 * @return Any error that occurs.
 */
 errorret_t uiButtonDraw(
  const uibutton_t *button,
  const float_t x,
  const float_t y
 );
@@ -0,0 +1,64 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uicheckbox.h"
 #include "util/memory.h"
 #include "util/string.h"
 #include "display/text/text.h"
 #include "display/color.h"
 void uiCheckboxInit(
  uicheckbox_t *checkbox,
  const char_t *label
 ) {
  memoryZero(checkbox, sizeof(uicheckbox_t));
  checkbox->rawLabel = label;
  uiWidgetLabelInit(&checkbox->label, &FONT_DEFAULT);
  uiCheckboxRebuildLabel(checkbox);
 }
 bool_t uiCheckboxIsChecked(const uicheckbox_t *checkbox) {
  return checkbox->checked;
 }
 void uiCheckboxSetChecked(uicheckbox_t *checkbox, const bool_t checked) {
  checkbox->checked = checked;
  uiCheckboxRebuildLabel(checkbox);
 }
 void uiCheckboxToggle(uicheckbox_t *checkbox) {
  uiCheckboxSetChecked(checkbox, !uiCheckboxIsChecked(checkbox));
 }
 bool_t uiCheckboxIsHighlighted(const uicheckbox_t *checkbox) {
  return checkbox->highlighted;
 }
 void uiCheckboxSetHighlighted(uicheckbox_t *checkbox, const bool_t highlighted) {
  checkbox->highlighted = highlighted;
  uiWidgetLabelSetColor(
    &checkbox->label, highlighted ? COLOR_RED : COLOR_WHITE
  );
 }
 errorret_t uiCheckboxDraw(
  const uicheckbox_t *checkbox,
  const float_t x,
  const float_t y
 ) {
  errorChain(uiWidgetLabelDraw(&checkbox->label, x, y));
  errorOk();
 }
 void uiCheckboxRebuildLabel(uicheckbox_t *checkbox) {
  char_t combined[UI_WIDGET_LABEL_TEXT_MAX];
  stringFormat(
    combined, UI_WIDGET_LABEL_TEXT_MAX - 1, "%s %s",
    checkbox->checked ? "Y" : "N", checkbox->rawLabel
  );
  uiWidgetLabelSetText(&checkbox->label, combined);
 }
@@ -0,0 +1,90 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "ui/widget/uiwidgetlabel.h"
 typedef struct uicheckbox_s {
  const char_t *rawLabel;
  uiwidgetlabel_t label;
  bool_t checked;
  bool_t highlighted;
 } uicheckbox_t;
 /**
 * Initializes a checkbox.
 *
 * @param checkbox The checkbox to initialize.
 * @param label Display label.
 */
 void uiCheckboxInit(
  uicheckbox_t *checkbox,
  const char_t *label
 );
 /**
 * Returns whether the checkbox is checked.
 *
 * @param checkbox The checkbox to query.
 * @returns True if checked.
 */
 bool_t uiCheckboxIsChecked(const uicheckbox_t *checkbox);
 /**
 * Sets the checked state of the checkbox.
 *
 * @param checkbox The checkbox to update.
 * @param checked The new checked state.
 */
 void uiCheckboxSetChecked(uicheckbox_t *checkbox, const bool_t checked);
 /**
 * Toggles the checked state of the checkbox.
 *
 * @param checkbox The checkbox to toggle.
 */
 void uiCheckboxToggle(uicheckbox_t *checkbox);
 /**
 * Returns whether the checkbox is highlighted.
 *
 * @param checkbox The checkbox to query.
 * @returns True if highlighted.
 */
 bool_t uiCheckboxIsHighlighted(const uicheckbox_t *checkbox);
 /**
 * Sets the highlighted state of the checkbox.
 *
 * @param checkbox The checkbox to update.
 * @param highlighted The new highlighted state.
 */
 void uiCheckboxSetHighlighted(uicheckbox_t *checkbox, const bool_t highlighted);
 /**
 * Draws the checkbox at the given screen position.
 *
 * @param checkbox The checkbox to draw.
 * @param x Screen x position.
 * @param y Screen y position.
 * @return Any error that occurs.
 */
 errorret_t uiCheckboxDraw(
  const uicheckbox_t *checkbox,
  const float_t x,
  const float_t y
 );
 /**
 * Rebuilds the checkbox's cached label ("Y "/"N " mark plus rawLabel)
 * from its current checked state. Called internally whenever checked
 * changes.
 *
 * @param checkbox The checkbox to update.
 */
 void uiCheckboxRebuildLabel(uicheckbox_t *checkbox);
@@ -0,0 +1,110 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uidropdown.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "util/string.h"
 #include "display/text/text.h"
 #include "display/color.h"
 void uiDropdownInit(
  uidropdown_t *dropdown,
  const char_t *label,
  const char_t *const *options,
  const uint8_t optionCount,
  const uint8_t selectedIndex
 ) {
  assertNotNull(dropdown, "Dropdown cannot be NULL");
  assertNotNull(label, "Label cannot be NULL");
  assertNotNull(options, "Options cannot be NULL");
  assertTrue(optionCount > 0, "Dropdown must have at least one option");
  memoryZero(dropdown, sizeof(uidropdown_t));
  uiWidgetLabelInit(&dropdown->label, &FONT_DEFAULT);
  uiWidgetLabelSetText(&dropdown->label, label);
  uiWidgetLabelInit(&dropdown->value, &FONT_DEFAULT);
  dropdown->options = options;
  dropdown->optionCount = optionCount;
  dropdown->selectedIndex = selectedIndex < optionCount ? selectedIndex : 0;
  uiDropdownRebuildValue(dropdown);
 }
 uint8_t uiDropdownGetSelectedIndex(const uidropdown_t *dropdown) {
  assertNotNull(dropdown, "Dropdown cannot be NULL");
  return dropdown->selectedIndex;
 }
 const char_t *uiDropdownGetSelectedOption(const uidropdown_t *dropdown) {
  assertNotNull(dropdown, "Dropdown cannot be NULL");
  return dropdown->options[dropdown->selectedIndex];
 }
 void uiDropdownSetSelectedIndex(uidropdown_t *dropdown, const uint8_t index) {
  assertNotNull(dropdown, "Dropdown cannot be NULL");
  assertTrue(index < dropdown->optionCount, "Dropdown index out of range");
  dropdown->selectedIndex = index;
  uiDropdownRebuildValue(dropdown);
 }
 void uiDropdownStepNext(uidropdown_t *dropdown) {
  assertNotNull(dropdown, "Dropdown cannot be NULL");
  dropdown->selectedIndex =
    (dropdown->selectedIndex + 1) % dropdown->optionCount;
  uiDropdownRebuildValue(dropdown);
 }
 void uiDropdownStepPrev(uidropdown_t *dropdown) {
  assertNotNull(dropdown, "Dropdown cannot be NULL");
  dropdown->selectedIndex = dropdown->selectedIndex == 0 ?
    dropdown->optionCount - 1 : dropdown->selectedIndex - 1;
  uiDropdownRebuildValue(dropdown);
 }
 bool_t uiDropdownIsHighlighted(const uidropdown_t *dropdown) {
  assertNotNull(dropdown, "Dropdown cannot be NULL");
  return dropdown->highlighted;
 }
 void uiDropdownSetHighlighted(
  uidropdown_t *dropdown,
  const bool_t highlighted
 ) {
  assertNotNull(dropdown, "Dropdown cannot be NULL");
  dropdown->highlighted = highlighted;
  color_t color = highlighted ? COLOR_RED : COLOR_WHITE;
  uiWidgetLabelSetColor(&dropdown->label, color);
  uiWidgetLabelSetColor(&dropdown->value, color);
 }
 errorret_t uiDropdownDraw(
  const uidropdown_t *dropdown,
  const float_t x,
  const float_t y
 ) {
  assertNotNull(dropdown, "Dropdown cannot be NULL");
  errorChain(uiWidgetLabelDraw(&dropdown->label, x, y));
  int32_t labelW, labelH;
  uiWidgetLabelGetSize(&dropdown->label, &labelW, &labelH);
  errorChain(uiWidgetLabelDraw(
    &dropdown->value, x + (float_t)labelW + UI_DROPDOWN_GAP, y
  ));
  errorOk();
 }
 void uiDropdownRebuildValue(uidropdown_t *dropdown) {
  char_t valueText[UI_WIDGET_LABEL_TEXT_MAX];
  stringFormat(
    valueText, UI_WIDGET_LABEL_TEXT_MAX - 1, "< %s >",
    uiDropdownGetSelectedOption(dropdown)
  );
  uiWidgetLabelSetText(&dropdown->value, valueText);
 }
@@ -0,0 +1,123 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "ui/widget/uiwidgetlabel.h"
 #define UI_DROPDOWN_GAP 4.0f
 typedef struct {
  uiwidgetlabel_t label;
  uiwidgetlabel_t value;
  const char_t *const *options;
  uint8_t optionCount;
  uint8_t selectedIndex;
  bool_t highlighted;
 } uidropdown_t;
 /**
 * Initializes a dropdown.
 *
 * @param dropdown The dropdown to initialize.
 * @param label Display label.
 * @param options Array of option display strings; caller-owned, must
 * outlive the dropdown.
 * @param optionCount Number of entries in options. Must be > 0.
 * @param selectedIndex Initial selected option index, clamped to
 * [0, optionCount - 1].
 */
 void uiDropdownInit(
  uidropdown_t *dropdown,
  const char_t *label,
  const char_t *const *options,
  const uint8_t optionCount,
  const uint8_t selectedIndex
 );
 /**
 * Returns the index of the currently selected option.
 *
 * @param dropdown The dropdown to query.
 * @returns The selected option index.
 */
 uint8_t uiDropdownGetSelectedIndex(const uidropdown_t *dropdown);
 /**
 * Returns the currently selected option's display string.
 *
 * @param dropdown The dropdown to query.
 * @returns The selected option string.
 */
 const char_t *uiDropdownGetSelectedOption(const uidropdown_t *dropdown);
 /**
 * Sets the selected option by index.
 *
 * @param dropdown The dropdown to update.
 * @param index The new selected option index. Must be < optionCount.
 */
 void uiDropdownSetSelectedIndex(uidropdown_t *dropdown, const uint8_t index);
 /**
 * Selects the next option, wrapping around to the first option past
 * the last.
 *
 * @param dropdown The dropdown to update.
 */
 void uiDropdownStepNext(uidropdown_t *dropdown);
 /**
 * Selects the previous option, wrapping around to the last option
 * before the first.
 *
 * @param dropdown The dropdown to update.
 */
 void uiDropdownStepPrev(uidropdown_t *dropdown);
 /**
 * Returns whether the dropdown is highlighted.
 *
 * @param dropdown The dropdown to query.
 * @returns True if highlighted.
 */
 bool_t uiDropdownIsHighlighted(const uidropdown_t *dropdown);
 /**
 * Sets the highlighted state of the dropdown.
 *
 * @param dropdown The dropdown to update.
 * @param highlighted The new highlighted state.
 */
 void uiDropdownSetHighlighted(
  uidropdown_t *dropdown,
  const bool_t highlighted
 );
 /**
 * Draws the dropdown at the given screen position: label, then the
 * currently selected option surrounded by cycle arrows.
 *
 * @param dropdown The dropdown to draw.
 * @param x Screen x position.
 * @param y Screen y position.
 * @return Any error that occurs.
 */
 errorret_t uiDropdownDraw(
  const uidropdown_t *dropdown,
  const float_t x,
  const float_t y
 );
 /**
 * Rebuilds the dropdown's cached value label ("< option >") from its
 * current selectedIndex. Called internally whenever selectedIndex
 * changes.
 *
 * @param dropdown The dropdown to update.
 */
 void uiDropdownRebuildValue(uidropdown_t *dropdown);
@@ -0,0 +1,70 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uilabel.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "util/string.h"
 #include "display/text/text.h"
 void uiLabelInit(uilabel_t *label, font_t *font) {
  assertNotNull(label, "Label cannot be NULL");
  assertNotNull(font, "Font cannot be NULL");
  memoryZero(label, sizeof(uilabel_t));
  label->font = font;
  label->color = COLOR_WHITE;
 }
 void uiLabelSetText(uilabel_t *label, const char_t *text) {
  assertNotNull(label, "Label cannot be NULL");
  assertNotNull(text, "Text cannot be NULL");
  assertStrLenMax(text, UI_LABEL_TEXT_MAX, "Label text too long");
  stringCopy(label->text, text, UI_LABEL_TEXT_MAX);
  label->spriteCount = textBuildSpriteCache(
    label->text, label->font, label->sprites, UI_LABEL_SPRITE_COUNT_MAX,
    &label->width, &label->height
  );
 }
 void uiLabelSetColor(uilabel_t *label, const color_t color) {
  assertNotNull(label, "Label cannot be NULL");
  label->color = color;
 }
 void uiLabelGetSize(
  const uilabel_t *label,
  int32_t *outWidth,
  int32_t *outHeight
 ) {
  assertNotNull(label, "Label cannot be NULL");
  assertNotNull(outWidth, "Output width cannot be NULL");
  assertNotNull(outHeight, "Output height cannot be NULL");
  *outWidth = label->width;
  *outHeight = label->height;
 }
 errorret_t uiLabelDraw(
  const uilabel_t *label,
  const float_t x,
  const float_t y
 ) {
  assertNotNull(label, "Label cannot be NULL");
  if(label->spriteCount == 0) errorOk();
  // Cached sprites are relative to (0,0); textDrawSpriteCache translates
  // into the requested screen position here instead of in
  // uiLabelSetText, so a label can be repositioned every frame without
  // rebuilding the (much more expensive) glyph/UV cache.
  spritebatchsprite_t scratch[UI_LABEL_SPRITE_COUNT_MAX];
  errorChain(textDrawSpriteCache(
    label->sprites, label->spriteCount, scratch, x, y, label->color,
    label->font->texture
  ));
  errorOk();
 }
@@ -0,0 +1,85 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "display/text/font.h"
 #include "display/spritebatch/spritebatchsprite.h"
 #include "display/color.h"
 #define UI_LABEL_TEXT_MAX 256
 #define UI_LABEL_SPRITE_COUNT_MAX UI_LABEL_TEXT_MAX
 typedef struct {
  char_t text[UI_LABEL_TEXT_MAX];
  color_t color;
  font_t *font;
  spritebatchsprite_t sprites[UI_LABEL_SPRITE_COUNT_MAX];
  uint32_t spriteCount;
  int32_t width;
  int32_t height;
 } uilabel_t;
 /**
 * Initializes a label, defaulting to white text and no text set.
 *
 * @param label The label to initialize.
 * @param font Font to use for rendering. Must outlive the label.
 */
 void uiLabelInit(uilabel_t *label, font_t *font);
 /**
 * Sets the label's text, rebuilding its cached sprites (glyph lookup, UV,
 * and layout) immediately. This is the only way the sprite cache gets
 * rebuilt -- uiLabelDraw never recomputes it, so call this whenever the
 * text changes rather than once up front and expecting it to stay in sync.
 *
 * @param label The label to update.
 * @param text Null-terminated string to display. Must be shorter than
 * UI_LABEL_TEXT_MAX.
 */
 void uiLabelSetText(uilabel_t *label, const char_t *text);
 /**
 * Sets the label's tint color. Cheap -- doesn't touch the sprite cache,
 * since color is applied via the draw material, not baked into sprites.
 *
 * @param label The label to update.
 * @param color The new tint color.
 */
 void uiLabelSetColor(uilabel_t *label, const color_t color);
 /**
 * Gets the measured size (in pixels) of the label's current text, cached
 * from the last uiLabelSetText call.
 *
 * @param label The label to query.
 * @param outWidth Pointer to store the width.
 * @param outHeight Pointer to store the height.
 */
 void uiLabelGetSize(
  const uilabel_t *label,
  int32_t *outWidth,
  int32_t *outHeight
 );
 /**
 * Draws the label's cached sprites at the given screen position in a
 * single batched buffer call. Does not recompute glyph layout -- call
 * uiLabelSetText first whenever the text changes.
 *
 * @param label The label to draw.
 * @param x Screen x position.
 * @param y Screen y position.
 * @return Any error that occurs.
 */
 errorret_t uiLabelDraw(
  const uilabel_t *label,
  const float_t x,
  const float_t y
 );
@@ -0,0 +1,293 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uimenu.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "display/text/text.h"
 #include "display/color.h"
 #include "ui/widget/uiwidgetlabel.h"
 #include "ui/widget/uibutton.h"
 #include "ui/widget/uitab.h"
 #include "ui/widget/uislider.h"
 #include "ui/widget/uidropdown.h"
 void uiMenuInit(
  uimenu_t *menu,
  uimenuselectedcallback_t selected,
  uimenuclosedcallback_t closed,
  uimenuchangedcallback_t changed
 ) {
  assertNotNull(menu, "Menu cannot be NULL");
  memoryZero(menu, sizeof(uimenu_t));
  menu->selected = selected;
  menu->closed = closed;
  menu->changed = changed;
 }
 void uiMenuSetItems(
  uimenu_t *menu,
  const uimenuitem_t *items,
  const uint8_t itemCount,
  const uint8_t columns
 ) {
  assertNotNull(menu, "Menu cannot be NULL");
  assertNotNull(items, "Items cannot be NULL");
  assertTrue(itemCount > 0, "Item count must be > 0");
  assertTrue(columns > 0, "Columns must be > 0");
  menu->items = (uimenuitem_t *)items;
  menu->itemCount = itemCount;
  menu->columns = columns;
 }
 void uiMenuSetPosition(uimenu_t *menu, const uint8_t x, const uint8_t y) {
  assertNotNull(menu, "Menu cannot be NULL");
  if(menu->focusItem == NULL) return;
  uiFocusSetPosition(menu->focusItem, x, y);
 }
 void uiMenuOpen(uimenu_t *menu) {
  assertNotNull(menu, "Menu cannot be NULL");
  assertNotNull(menu->items, "Menu items cannot be NULL");
  assertTrue(menu->itemCount > 0, "Menu item count must be > 0");
  assertTrue(menu->columns > 0, "Menu columns must be > 0");
  if(menu->focusItem != NULL) return;
  uint8_t focusable = uiMenuFocusableCount(menu);
  uint8_t rows = focusable > 0 ?
    (focusable + menu->columns - 1) / menu->columns : 1;
  menu->focusItem = uiFocusPush(
    menu->columns, rows,
    uiMenuFocusSelected,
    uiMenuFocusChanged,
    uiMenuFocusClosed,
    uiMenuFocusDirection,
    menu
  );
 }
 void uiMenuClose(uimenu_t *menu) {
  assertNotNull(menu, "Menu cannot be NULL");
  if(menu->focusItem == NULL) return;
  uiFocusPopItem(menu->focusItem);
  menu->focusItem = NULL;
 }
 bool_t uiMenuIsActive(const uimenu_t *menu) {
  assertNotNull(menu, "Menu cannot be NULL");
  return menu->focusItem != NULL;
 }
 errorret_t uiMenuDraw(
  const uimenu_t *menu,
  const float_t x,
  const float_t y,
  const float_t width,
  const float_t height
 ) {
  assertNotNull(menu, "Menu cannot be NULL");
  if(menu->itemCount == 0) errorOk();
  float_t colStep = width / (float_t)menu->columns;
  float_t rowHeight = (float_t)FONT_DEFAULT.tileset->tileHeight;
  uint8_t col = 0;
  uint8_t row = 0;
  for(uint8_t i = 0; i < menu->itemCount; i++) {
    const uimenuitem_t *item = &menu->items[i];
    if(item->type == UI_MENU_WIDGET_TYPE_LABEL) {
      if(col > 0) { row++; col = 0; }
      errorChain(uiWidgetLabelDraw(
        &item->label, x, y + (float_t)row * rowHeight
      ));
      row++;
      continue;
    }
    if(item->type == UI_MENU_WIDGET_TYPE_SPACER) {
      if(col > 0) { row++; col = 0; }
      row++;
      continue;
    }
    float_t ix = x + (float_t)col * colStep;
    float_t iy = y + (float_t)row * rowHeight;
    switch(item->type) {
      case UI_MENU_WIDGET_TYPE_CHECKBOX:
        errorChain(uiCheckboxDraw(&item->checkbox, ix, iy));
        break;
      case UI_MENU_WIDGET_TYPE_BUTTON:
        errorChain(uiButtonDraw(&item->button, ix, iy));
        break;
      case UI_MENU_WIDGET_TYPE_TAB:
        errorChain(uiTabDraw(&item->tab, ix, iy));
        break;
      case UI_MENU_WIDGET_TYPE_SLIDER:
        errorChain(uiSliderDraw(&item->slider, ix, iy));
        break;
      case UI_MENU_WIDGET_TYPE_DROPDOWN:
        errorChain(uiDropdownDraw(&item->dropdown, ix, iy));
        break;
      default:
        break;
    }
    col++;
    if(col >= menu->columns) { col = 0; row++; }
  }
  errorOk();
 }
 bool_t uiMenuFocusSelected(const uifocusitem_t *focusItem) {
  assertNotNull(focusItem, "Focus item cannot be NULL");
  assertNotNull(focusItem->user, "Focus item user cannot be NULL");
  uimenu_t *menu = (uimenu_t *)focusItem->user;
  if(menu->selected == NULL) return true;
  uint8_t slot = focusItem->y * menu->columns + focusItem->x;
  uint8_t index = uiMenuFocusSlotToIndex(menu, slot);
  if(index == 0xFF) return true;
  menu->selected(menu, index, &menu->items[index]);
  return true;
 }
 bool_t uiMenuFocusChanged(const uifocusitem_t *focusItem) {
  assertNotNull(focusItem, "Focus item cannot be NULL");
  assertNotNull(focusItem->user, "Focus item user cannot be NULL");
  uimenu_t *menu = (uimenu_t *)focusItem->user;
  uint8_t focusSlot = focusItem->y * menu->columns + focusItem->x;
  uint8_t slot = 0;
  for(uint8_t i = 0; i < menu->itemCount; i++) {
    uimenuitem_t *item = &menu->items[i];
    if(
      item->type == UI_MENU_WIDGET_TYPE_LABEL ||
      item->type == UI_MENU_WIDGET_TYPE_SPACER
    ) continue;
    uiMenuItemSetHighlighted(item, slot == focusSlot);
    slot++;
  }
  if(menu->changed == NULL) return true;
  uint8_t index = uiMenuFocusSlotToIndex(menu, focusSlot);
  if(index == 0xFF) return true;
  menu->changed(menu, index, &menu->items[index]);
  return true;
 }
 bool_t uiMenuFocusClosed(const uifocusitem_t *focusItem) {
  assertNotNull(focusItem, "Focus item cannot be NULL");
  assertNotNull(focusItem->user, "Focus item user cannot be NULL");
  uimenu_t *menu = (uimenu_t *)focusItem->user;
  menu->focusItem = NULL;
  for(uint8_t i = 0; i < menu->itemCount; i++) {
    uiMenuItemSetHighlighted(&menu->items[i], false);
  }
  if(menu->closed != NULL) menu->closed(menu);
  return true;
 }
 bool_t uiMenuFocusDirection(
  const uifocusitem_t *focusItem,
  const uifocusdirection_t direction
 ) {
  assertNotNull(focusItem, "Focus item cannot be NULL");
  assertNotNull(focusItem->user, "Focus item user cannot be NULL");
  if(direction != UI_FOCUS_DIRECTION_LEFT && direction != UI_FOCUS_DIRECTION_RIGHT) {
    return false;
  }
  uimenu_t *menu = (uimenu_t *)focusItem->user;
  uint8_t slot = focusItem->y * menu->columns + focusItem->x;
  uint8_t index = uiMenuFocusSlotToIndex(menu, slot);
  if(index == 0xFF) return false;
  uimenuitem_t *item = &menu->items[index];
  bool_t right = direction == UI_FOCUS_DIRECTION_RIGHT;
  if(item->type == UI_MENU_WIDGET_TYPE_SLIDER) {
    if(right) {
      uiSliderStepUp(&item->slider);
    } else {
      uiSliderStepDown(&item->slider);
    }
    return true;
  }
  if(item->type == UI_MENU_WIDGET_TYPE_CHECKBOX) {
    uiCheckboxToggle(&item->checkbox);
    return true;
  }
  if(item->type == UI_MENU_WIDGET_TYPE_DROPDOWN) {
    if(right) {
      uiDropdownStepNext(&item->dropdown);
    } else {
      uiDropdownStepPrev(&item->dropdown);
    }
    return true;
  }
  return false;
 }
 uint8_t uiMenuFocusableCount(const uimenu_t *menu) {
  assertNotNull(menu, "Menu cannot be NULL");
  uint8_t count = 0;
  for(uint8_t i = 0; i < menu->itemCount; i++) {
    uimenuwidgettype_t t = menu->items[i].type;
    if(t != UI_MENU_WIDGET_TYPE_LABEL && t != UI_MENU_WIDGET_TYPE_SPACER) count++;
  }
  return count;
 }
 uint8_t uiMenuFocusSlotToIndex(const uimenu_t *menu, const uint8_t slot) {
  assertNotNull(menu, "Menu cannot be NULL");
  uint8_t focusable = 0;
  for(uint8_t i = 0; i < menu->itemCount; i++) {
    uimenuwidgettype_t t = menu->items[i].type;
    if(t == UI_MENU_WIDGET_TYPE_LABEL || t == UI_MENU_WIDGET_TYPE_SPACER) continue;
    if(focusable == slot) return i;
    focusable++;
  }
  return 0xFF;
 }
 void uiMenuLabelInit(uimenuitem_t *item, const char_t *text) {
  assertNotNull(item, "Item cannot be NULL");
  assertNotNull(text, "Text cannot be NULL");
  uiWidgetLabelInit(&item->label, &FONT_DEFAULT);
  uiWidgetLabelSetText(&item->label, text);
 }
 void uiMenuItemSetHighlighted(uimenuitem_t *item, const bool_t highlighted) {
  if(item->type == UI_MENU_WIDGET_TYPE_CHECKBOX) {
    uiCheckboxSetHighlighted(&item->checkbox, highlighted);
  } else if(item->type == UI_MENU_WIDGET_TYPE_BUTTON) {
    uiButtonSetHighlighted(&item->button, highlighted);
  } else if(item->type == UI_MENU_WIDGET_TYPE_TAB) {
    uiTabSetActive(&item->tab, highlighted);
  } else if(item->type == UI_MENU_WIDGET_TYPE_SLIDER) {
    uiSliderSetHighlighted(&item->slider, highlighted);
  } else if(item->type == UI_MENU_WIDGET_TYPE_DROPDOWN) {
    uiDropdownSetHighlighted(&item->dropdown, highlighted);
  }
 }
@@ -0,0 +1,292 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "ui/focus/uifocus.h"
 #include "ui/widget/uiwidgetlabel.h"
 #include "ui/widget/uibutton.h"
 #include "ui/widget/uicheckbox.h"
 #include "ui/widget/uitab.h"
 #include "ui/widget/uislider.h"
 #include "ui/widget/uidropdown.h"
 typedef struct uimenu_s uimenu_t;
 typedef enum {
  UI_MENU_WIDGET_TYPE_NONE,
  UI_MENU_WIDGET_TYPE_LABEL,
  UI_MENU_WIDGET_TYPE_SPACER,
  UI_MENU_WIDGET_TYPE_CHECKBOX,
  UI_MENU_WIDGET_TYPE_BUTTON,
  UI_MENU_WIDGET_TYPE_TAB,
  UI_MENU_WIDGET_TYPE_SLIDER,
  UI_MENU_WIDGET_TYPE_DROPDOWN,
 } uimenuwidgettype_t;
 typedef struct {
  uimenuwidgettype_t type;
  union {
    uiwidgetlabel_t label;
    uicheckbox_t checkbox;
    uibutton_t button;
    uitab_t tab;
    uislider_t slider;
    uidropdown_t dropdown;
  };
 } uimenuitem_t;
 typedef void (*uimenuselectedcallback_t)(
  const uimenu_t *menu,
  const uint8_t index,
  const uimenuitem_t *item
 );
 typedef void (*uimenuchangedcallback_t)(
  const uimenu_t *menu,
  const uint8_t index,
  const uimenuitem_t *item
 );
 typedef void (*uimenuclosedcallback_t)(const uimenu_t *menu);
 typedef struct uimenu_s {
  uimenuitem_t *items;
  uint8_t itemCount;
  uint8_t columns;
  uifocusitem_t *focusItem;
  uimenuselectedcallback_t selected;
  uimenuclosedcallback_t closed;
  uimenuchangedcallback_t changed;
  void *user;
 } uimenu_t;
 /**
 * Initializes a menu, clearing all items and focus state.
 *
 * @param menu The menu to initialize.
 * @param items The list of items to display in the menu.
 * @param itemCount The number of items in the list.
 * @param columns The number of columns to display the items in.
 * @param selected The callback to invoke when an item is selected.
 * @param closed The callback to invoke when the menu is closed.
 * @param changed The callback to invoke when the menu changes.
 */
 void uiMenuInit(
  uimenu_t *menu,
  uimenuselectedcallback_t selected,
  uimenuclosedcallback_t closed,
  uimenuchangedcallback_t changed
 );
 /**
 * Sets the items to display in the menu.
 *
 * @param menu The menu to update.
 * @param items The list of items to display in the menu.
 * @param itemCount The number of items in the list.
 * @param columns The number of columns to display the items in.
 */
 void uiMenuSetItems(
  uimenu_t *menu,
  const uimenuitem_t *items,
  const uint8_t itemCount,
  const uint8_t columns
 );
 /**
 * Sets the position of the menu on the screen.
 *
 * @param menu The menu to position.
 * @param x The x-coordinate to position the menu at.
 * @param y The y-coordinate to position the menu at.
 */
 void uiMenuSetPosition(uimenu_t *menu, const uint8_t x, const uint8_t y);
 /**
 * Pushes a menu onto the UI focus stack, making it the active menu.
 *
 * @param menu The menu to push.
 */
 void uiMenuOpen(uimenu_t *menu);
 /**
 * Pops a menu from the UI focus stack, removing it from the active menu.
 * 
 * @param menu The menu to pop.
 */
 void uiMenuClose(uimenu_t *menu);
 /**
 * Returns whether the menu is currently active (on the UI focus stack).
 *
 * @param menu The menu to query.
 * @returns True if the menu is active.
 */
 bool_t uiMenuIsActive(const uimenu_t *menu);
 /**
 * Draws the menu at the specified position and size.
 *
 * @param menu The menu to draw.
 * @param x The x-coordinate to draw the menu at.
 * @param y The y-coordinate to draw the menu at.
 * @param width The width of the menu.
 * @param height The height of the menu.
 * @returns An error code indicating success or failure.
 */
 errorret_t uiMenuDraw(
  const uimenu_t *menu,
  const float_t x,
  const float_t y,
  const float_t width,
  const float_t height
 );
 /**
 * Returns the number of focusable (non-label) items in the menu.
 *
 * @param menu The menu to query.
 * @returns Count of non-label items.
 */
 uint8_t uiMenuFocusableCount(const uimenu_t *menu);
 /**
 * Maps a flat focus slot index to the corresponding item array index,
 * skipping over label items which are not focusable.
 *
 * @param menu The menu to query.
 * @param slot The focus slot index (y * columns + x).
 * @returns The item array index, or 0xFF if out of range.
 */
 uint8_t uiMenuFocusSlotToIndex(const uimenu_t *menu, const uint8_t slot);
 /**
 * Sets the highlighted/active state on a menu item, dispatching to the
 * matching widget's setter based on its type. No-op for label/spacer
 * items and any other type with no highlight concept.
 *
 * @param item The item to update.
 * @param highlighted The new highlighted/active state.
 */
 void uiMenuItemSetHighlighted(uimenuitem_t *item, const bool_t highlighted);
 /**
 * Initializes a menu item as a standalone label, caching its text.
 * Used internally by the MENU_LABEL helper macro.
 *
 * @param item The item to initialize.
 * @param text Display text.
 */
 void uiMenuLabelInit(uimenuitem_t *item, const char_t *text);
 /**
 * Internal focus callback  -  forwards selection to the menu's selected handler.
 *
 * @param focusItem The active focus item; user field must point to uimenu_t.
 * @returns True.
 */
 bool_t uiMenuFocusSelected(const uifocusitem_t *focusItem);
 /**
 * Internal focus callback  -  updates widget highlights and fires changed.
 *
 * @param focusItem The active focus item; user field must point to uimenu_t.
 * @returns True.
 */
 bool_t uiMenuFocusChanged(const uifocusitem_t *focusItem);
 /**
 * Internal focus callback  -  clears focusItem and fires the closed handler.
 *
 * @param focusItem The active focus item; user field must point to uimenu_t.
 * @returns True.
 */
 bool_t uiMenuFocusClosed(const uifocusitem_t *focusItem);
 /**
 * Internal focus callback  -  gives the focused item's widget a chance to
 * handle LEFT/RIGHT itself (e.g. a slider adjusting its value) before
 * falling back to the default cell-to-cell movement.
 *
 * @param focusItem The active focus item; user field must point to uimenu_t.
 * @param direction The direction that was pressed or held.
 * @returns True if the focused widget handled the direction.
 */
 bool_t uiMenuFocusDirection(
  const uifocusitem_t *focusItem,
  const uifocusdirection_t direction
 );
 // Helper macros
 #define MENU_BEGIN(menuPtr, itemsArray, selected, closed, changed) \
  uimenu_t *menu = (menuPtr); \
  uiMenuInit(menu, selected, closed, changed); \
  menu->items = (itemsArray); \
  uint8_t menuIndex = 0; \
  uint8_t menuCapacity = sizeof(itemsArray) / sizeof((itemsArray)[0])
 #define MENU_LABEL(text) \
  assertTrue(menuIndex < menuCapacity, "Menu item count exceeds capacity"); \
  menu->items[menuIndex].type = UI_MENU_WIDGET_TYPE_LABEL; \
  uiMenuLabelInit(&menu->items[menuIndex], text); \
  ++menuIndex
 #define MENU_SPACER() \
  assertTrue(menuIndex < menuCapacity, "Menu item count exceeds capacity"); \
  menu->items[menuIndex].type = UI_MENU_WIDGET_TYPE_SPACER; \
  ++menuIndex
 #define MENU_CHECKBOX(label) \
  assertTrue(menuIndex < menuCapacity, "Menu item count exceeds capacity"); \
  menu->items[menuIndex].type = UI_MENU_WIDGET_TYPE_CHECKBOX; \
  uiCheckboxInit(&menu->items[menuIndex].checkbox, label); \
  ++menuIndex
 #define MENU_BUTTON(label) \
  assertTrue(menuIndex < menuCapacity, "Menu item count exceeds capacity"); \
  menu->items[menuIndex].type = UI_MENU_WIDGET_TYPE_BUTTON; \
  uiButtonInit(&menu->items[menuIndex].button, label); \
  ++menuIndex
 #define MENU_TAB(label) \
  assertTrue(menuIndex < menuCapacity, "Menu item count exceeds capacity"); \
  menu->items[menuIndex].type = UI_MENU_WIDGET_TYPE_TAB; \
  uiTabInit(&menu->items[menuIndex].tab, label); \
  ++menuIndex
 #define MENU_SLIDER_FLOAT(label, value, min, max, step) \
  assertTrue(menuIndex < menuCapacity, "Menu item count exceeds capacity"); \
  menu->items[menuIndex].type = UI_MENU_WIDGET_TYPE_SLIDER; \
  uiSliderInitFloat( \
    &menu->items[menuIndex].slider, label, value, min, max, step \
  ); \
  ++menuIndex
 #define MENU_SLIDER_INT(label, value, min, max, step) \
  assertTrue(menuIndex < menuCapacity, "Menu item count exceeds capacity"); \
  menu->items[menuIndex].type = UI_MENU_WIDGET_TYPE_SLIDER; \
  uiSliderInitInt( \
    &menu->items[menuIndex].slider, label, value, min, max, step \
  ); \
  ++menuIndex
 #define MENU_DROPDOWN(label, options, optionCount, selectedIndex) \
  assertTrue(menuIndex < menuCapacity, "Menu item count exceeds capacity"); \
  menu->items[menuIndex].type = UI_MENU_WIDGET_TYPE_DROPDOWN; \
  uiDropdownInit( \
    &menu->items[menuIndex].dropdown, label, options, optionCount, \
    selectedIndex \
  ); \
  ++menuIndex
 #define MENU_END(itemsArray, columns) \
  uiMenuSetItems(menu, (itemsArray), menuIndex, (columns))
 //EOF
@@ -0,0 +1,15 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uiscrolling.h"
 #include "assert/assert.h"
 void uiScrollingInit(uiscrolling_t *scrolling) {
  assertNotNull(scrolling, "Scrolling container cannot be NULL");
  // Nothing to initialize yet -- uiscrolling_t is currently a
  // placeholder with no fields.
 }
@@ -0,0 +1,21 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 typedef struct {
 } uiscrolling_t;
 /**
 * Initializes a scrolling container. Currently a placeholder -- no
 * scrolling behavior is implemented yet.
 *
 * @param scrolling The scrolling container to initialize.
 */
 void uiScrollingInit(uiscrolling_t *scrolling);
@@ -0,0 +1,282 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uislider.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "util/math.h"
 #include "util/string.h"
 #include "display/text/text.h"
 #include "display/color.h"
 #include "display/spritebatch/spritebatch.h"
 #include "display/texture/texture.h"
 #include "display/shader/shaderunlit.h"
 void uiSliderInitFloat(
  uislider_t *slider,
  const char_t *label,
  const float_t value,
  const float_t min,
  const float_t max,
  const float_t step
 ) {
  assertNotNull(slider, "Slider cannot be NULL");
  assertNotNull(label, "Label cannot be NULL");
  assertTrue(max > min, "Slider max must be greater than min");
  assertTrue(step > 0.0f, "Slider step must be greater than zero");
  memoryZero(slider, sizeof(uislider_t));
  uiWidgetLabelInit(&slider->label, &FONT_DEFAULT);
  uiWidgetLabelSetText(&slider->label, label);
  uiWidgetLabelInit(&slider->valueLabel, &FONT_DEFAULT);
  slider->type = UI_SLIDER_TYPE_FLOAT;
  slider->min.f = min;
  slider->max.f = max;
  slider->step.f = step;
  slider->value.f = mathClamp(value, min, max);
  uiSliderRebuildValueLabel(slider);
  uiSliderRebuildGeometry(slider);
 }
 void uiSliderInitInt(
  uislider_t *slider,
  const char_t *label,
  const int32_t value,
  const int32_t min,
  const int32_t max,
  const int32_t step
 ) {
  assertNotNull(slider, "Slider cannot be NULL");
  assertNotNull(label, "Label cannot be NULL");
  assertTrue(max > min, "Slider max must be greater than min");
  assertTrue(step > 0, "Slider step must be greater than zero");
  memoryZero(slider, sizeof(uislider_t));
  uiWidgetLabelInit(&slider->label, &FONT_DEFAULT);
  uiWidgetLabelSetText(&slider->label, label);
  uiWidgetLabelInit(&slider->valueLabel, &FONT_DEFAULT);
  slider->type = UI_SLIDER_TYPE_INT;
  slider->min.i = min;
  slider->max.i = max;
  slider->step.i = step;
  slider->value.i = mathClamp(value, min, max);
  uiSliderRebuildValueLabel(slider);
  uiSliderRebuildGeometry(slider);
 }
 float_t uiSliderGetFloat(const uislider_t *slider) {
  assertNotNull(slider, "Slider cannot be NULL");
  return slider->type == UI_SLIDER_TYPE_INT ?
    (float_t)slider->value.i : slider->value.f;
 }
 int32_t uiSliderGetInt(const uislider_t *slider) {
  assertNotNull(slider, "Slider cannot be NULL");
  assertTrue(
    slider->type == UI_SLIDER_TYPE_INT, "Slider is not an int slider"
  );
  return slider->value.i;
 }
 void uiSliderSetFloat(uislider_t *slider, const float_t value) {
  assertNotNull(slider, "Slider cannot be NULL");
  assertTrue(
    slider->type == UI_SLIDER_TYPE_FLOAT, "Slider is not a float slider"
  );
  slider->value.f = mathClamp(value, slider->min.f, slider->max.f);
  uiSliderRebuildValueLabel(slider);
  uiSliderRebuildGeometry(slider);
 }
 void uiSliderSetInt(uislider_t *slider, const int32_t value) {
  assertNotNull(slider, "Slider cannot be NULL");
  assertTrue(
    slider->type == UI_SLIDER_TYPE_INT, "Slider is not an int slider"
  );
  slider->value.i = mathClamp(value, slider->min.i, slider->max.i);
  uiSliderRebuildValueLabel(slider);
  uiSliderRebuildGeometry(slider);
 }
 void uiSliderStepUp(uislider_t *slider) {
  assertNotNull(slider, "Slider cannot be NULL");
  if(slider->type == UI_SLIDER_TYPE_INT) {
    int32_t next = slider->value.i + slider->step.i;
    uiSliderSetInt(slider, next > slider->max.i ? slider->min.i : next);
  } else {
    float_t next = slider->value.f + slider->step.f;
    uiSliderSetFloat(slider, next > slider->max.f ? slider->min.f : next);
  }
 }
 void uiSliderStepDown(uislider_t *slider) {
  assertNotNull(slider, "Slider cannot be NULL");
  if(slider->type == UI_SLIDER_TYPE_INT) {
    int32_t next = slider->value.i - slider->step.i;
    uiSliderSetInt(slider, next < slider->min.i ? slider->max.i : next);
  } else {
    float_t next = slider->value.f - slider->step.f;
    uiSliderSetFloat(slider, next < slider->min.f ? slider->max.f : next);
  }
 }
 float_t uiSliderGetRatio(const uislider_t *slider) {
  assertNotNull(slider, "Slider cannot be NULL");
  if(slider->type == UI_SLIDER_TYPE_INT) {
    if(slider->max.i == slider->min.i) return 0.0f;
    return (float_t)(slider->value.i - slider->min.i) /
      (float_t)(slider->max.i - slider->min.i);
  }
  if(slider->max.f == slider->min.f) return 0.0f;
  return (slider->value.f - slider->min.f) / (slider->max.f - slider->min.f);
 }
 int32_t uiSliderGetStepCount(const uislider_t *slider) {
  assertNotNull(slider, "Slider cannot be NULL");
  if(slider->type != UI_SLIDER_TYPE_INT || slider->step.i <= 0) return 0;
  return (slider->max.i - slider->min.i) / slider->step.i;
 }
 bool_t uiSliderIsHighlighted(const uislider_t *slider) {
  assertNotNull(slider, "Slider cannot be NULL");
  return slider->highlighted;
 }
 void uiSliderSetHighlighted(uislider_t *slider, const bool_t highlighted) {
  assertNotNull(slider, "Slider cannot be NULL");
  slider->highlighted = highlighted;
  color_t color = highlighted ? COLOR_RED : COLOR_WHITE;
  uiWidgetLabelSetColor(&slider->label, color);
  uiWidgetLabelSetColor(&slider->valueLabel, color);
 }
 errorret_t uiSliderDraw(
  const uislider_t *slider,
  const float_t x,
  const float_t y
 ) {
  assertNotNull(slider, "Slider cannot be NULL");
  errorChain(uiWidgetLabelDraw(&slider->label, x, y));
  shadermaterial_t trackMaterial = {
    .unlit = {
      .color = COLOR_DARK_GRAY,
      .texture = &TEXTURE_WHITE
    }
  };
  spritebatchsprite_t track = spriteBatchSpriteTranslate(
    &slider->cachedTrack, x, y
  );
  errorChain(spriteBatchBuffer(&track, 1, &SHADER_UNLIT, trackMaterial));
  if(slider->cachedFillVisible) {
    shadermaterial_t fillMaterial = {
      .unlit = {
        .color = slider->highlighted ? COLOR_RED : COLOR_WHITE,
        .texture = &TEXTURE_WHITE
      }
    };
    spritebatchsprite_t fill = spriteBatchSpriteTranslate(
      &slider->cachedFill, x, y
    );
    errorChain(spriteBatchBuffer(&fill, 1, &SHADER_UNLIT, fillMaterial));
  }
  if(slider->cachedMarkerCount > 0) {
    spritebatchsprite_t markers[UI_SLIDER_STEP_MARKERS_MAX];
    for(int32_t i = 0; i < slider->cachedMarkerCount; i++) {
      markers[i] = spriteBatchSpriteTranslate(&slider->cachedMarkers[i], x, y);
    }
    shadermaterial_t markerMaterial = {
      .unlit = {
        .color = COLOR_WHITE,
        .texture = &TEXTURE_WHITE
      }
    };
    errorChain(spriteBatchBuffer(
      markers, slider->cachedMarkerCount, &SHADER_UNLIT, markerMaterial
    ));
  }
  errorChain(uiWidgetLabelDraw(
    &slider->valueLabel,
    x + slider->cachedTrack.max[0] + UI_SLIDER_GAP,
    y
  ));
  errorOk();
 }
 void uiSliderRebuildValueLabel(uislider_t *slider) {
  char_t valueText[UI_WIDGET_LABEL_TEXT_MAX];
  if(slider->type == UI_SLIDER_TYPE_INT) {
    stringFormat(
      valueText, UI_WIDGET_LABEL_TEXT_MAX - 1, "%d", slider->value.i
    );
  } else {
    stringFormat(
      valueText, UI_WIDGET_LABEL_TEXT_MAX - 1, "%.2f", slider->value.f
    );
  }
  uiWidgetLabelSetText(&slider->valueLabel, valueText);
 }
 void uiSliderRebuildGeometry(uislider_t *slider) {
  int32_t labelW, labelH;
  uiWidgetLabelGetSize(&slider->label, &labelW, &labelH);
  float_t trackX = (float_t)labelW + UI_SLIDER_GAP;
  float_t trackY = ((float_t)labelH - UI_SLIDER_TRACK_HEIGHT) * 0.5f;
  slider->cachedTrack = (spritebatchsprite_t){
    .min = { trackX, trackY, 0.0f },
    .max = {
      trackX + UI_SLIDER_TRACK_WIDTH, trackY + UI_SLIDER_TRACK_HEIGHT, 0.0f
    },
    .uvMin = { 0.0f, 0.0f },
    .uvMax = { 1.0f, 1.0f }
  };
  float_t fillWidth = UI_SLIDER_TRACK_WIDTH * uiSliderGetRatio(slider);
  slider->cachedFillVisible = fillWidth > 0.0f;
  if(slider->cachedFillVisible) {
    slider->cachedFill = (spritebatchsprite_t){
      .min = { trackX, trackY, 0.0f },
      .max = { trackX + fillWidth, trackY + UI_SLIDER_TRACK_HEIGHT, 0.0f },
      .uvMin = { 0.0f, 0.0f },
      .uvMax = { 1.0f, 1.0f }
    };
  }
  int32_t stepCount = uiSliderGetStepCount(slider);
  if(stepCount > 0 && stepCount < UI_SLIDER_STEP_MARKERS_MAX) {
    for(int32_t i = 0; i <= stepCount; i++) {
      float_t markerX = trackX +
        UI_SLIDER_TRACK_WIDTH * (float_t)i / (float_t)stepCount;
      slider->cachedMarkers[i] = (spritebatchsprite_t){
        .min = {
          markerX - UI_SLIDER_STEP_MARKER_WIDTH * 0.5f,
          trackY - UI_SLIDER_STEP_MARKER_OVERHANG,
          0.0f
        },
        .max = {
          markerX + UI_SLIDER_STEP_MARKER_WIDTH * 0.5f,
          trackY + UI_SLIDER_TRACK_HEIGHT + UI_SLIDER_STEP_MARKER_OVERHANG,
          0.0f
        },
        .uvMin = { 0.0f, 0.0f },
        .uvMax = { 1.0f, 1.0f }
      };
    }
    slider->cachedMarkerCount = stepCount + 1;
  } else {
    slider->cachedMarkerCount = 0;
  }
 }
@@ -0,0 +1,215 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "ui/widget/uiwidgetlabel.h"
 #include "display/spritebatch/spritebatchsprite.h"
 #define UI_SLIDER_TRACK_WIDTH 80.0f
 #define UI_SLIDER_TRACK_HEIGHT 4.0f
 #define UI_SLIDER_STEP_MARKER_WIDTH 2.0f
 #define UI_SLIDER_STEP_MARKER_OVERHANG 1.0f
 #define UI_SLIDER_GAP 4.0f
 /**
 * Number of discrete steps below which an int slider renders individual
 * step markers on its track instead of a smooth fill.
 */
 #define UI_SLIDER_STEP_MARKERS_MAX 10
 typedef enum {
  UI_SLIDER_TYPE_FLOAT,
  UI_SLIDER_TYPE_INT,
  UI_SLIDER_TYPE_COUNT
 } uislidertype_t;
 typedef union {
  float_t f;
  int32_t i;
 } uislidervalue_t;
 typedef struct {
  uiwidgetlabel_t label;
  uiwidgetlabel_t valueLabel;
  uislidertype_t type;
  uislidervalue_t value;
  uislidervalue_t min;
  uislidervalue_t max;
  uislidervalue_t step;
  bool_t highlighted;
  // Track/fill/marker geometry, cached relative to origin (0,0) and only
  // rebuilt when the value or step configuration changes (see
  // uiSliderRebuildGeometry) -- uiSliderDraw just translates these into
  // position instead of re-deriving them every frame.
  spritebatchsprite_t cachedTrack;
  spritebatchsprite_t cachedFill;
  bool_t cachedFillVisible;
  spritebatchsprite_t cachedMarkers[UI_SLIDER_STEP_MARKERS_MAX];
  int32_t cachedMarkerCount;
 } uislider_t;
 /**
 * Initializes a floating point slider.
 *
 * @param slider The slider to initialize.
 * @param label Display label.
 * @param value Initial value, clamped to [min, max].
 * @param min Minimum value.
 * @param max Maximum value.
 * @param step The amount a single step moves the value by.
 */
 void uiSliderInitFloat(
  uislider_t *slider,
  const char_t *label,
  const float_t value,
  const float_t min,
  const float_t max,
  const float_t step
 );
 /**
 * Initializes an integer slider.
 *
 * @param slider The slider to initialize.
 * @param label Display label.
 * @param value Initial value, clamped to [min, max].
 * @param min Minimum value.
 * @param max Maximum value.
 * @param step The amount a single step moves the value by.
 */
 void uiSliderInitInt(
  uislider_t *slider,
  const char_t *label,
  const int32_t value,
  const int32_t min,
  const int32_t max,
  const int32_t step
 );
 /**
 * Returns the slider's current value as a float. Works for both slider
 * types; int values are widened to float.
 *
 * @param slider The slider to query.
 * @returns The current value.
 */
 float_t uiSliderGetFloat(const uislider_t *slider);
 /**
 * Returns the slider's current value as an int. Only valid for
 * UI_SLIDER_TYPE_INT sliders.
 *
 * @param slider The slider to query.
 * @returns The current value.
 */
 int32_t uiSliderGetInt(const uislider_t *slider);
 /**
 * Sets the slider's value, clamped to [min, max]. Only valid for
 * UI_SLIDER_TYPE_FLOAT sliders.
 *
 * @param slider The slider to update.
 * @param value The new value.
 */
 void uiSliderSetFloat(uislider_t *slider, const float_t value);
 /**
 * Sets the slider's value, clamped to [min, max]. Only valid for
 * UI_SLIDER_TYPE_INT sliders.
 *
 * @param slider The slider to update.
 * @param value The new value.
 */
 void uiSliderSetInt(uislider_t *slider, const int32_t value);
 /**
 * Moves the slider's value up by one step, wrapping around to its min
 * if the step would exceed its max.
 *
 * @param slider The slider to update.
 */
 void uiSliderStepUp(uislider_t *slider);
 /**
 * Moves the slider's value down by one step, wrapping around to its
 * max if the step would go below its min.
 *
 * @param slider The slider to update.
 */
 void uiSliderStepDown(uislider_t *slider);
 /**
 * Returns the slider's current value normalized to a 0..1 range based
 * on its min/max.
 *
 * @param slider The slider to query.
 * @returns The normalized value.
 */
 float_t uiSliderGetRatio(const uislider_t *slider);
 /**
 * Returns the number of discrete steps between min and max. Always 0
 * for float sliders.
 *
 * @param slider The slider to query.
 * @returns The step count.
 */
 int32_t uiSliderGetStepCount(const uislider_t *slider);
 /**
 * Returns whether the slider is highlighted.
 *
 * @param slider The slider to query.
 * @returns True if highlighted.
 */
 bool_t uiSliderIsHighlighted(const uislider_t *slider);
 /**
 * Sets the highlighted state of the slider.
 *
 * @param slider The slider to update.
 * @param highlighted The new highlighted state.
 */
 void uiSliderSetHighlighted(uislider_t *slider, const bool_t highlighted);
 /**
 * Draws the slider at the given screen position: label, then track,
 * then the current value as text. Int sliders with fewer than
 * UI_SLIDER_STEP_MARKERS_MAX discrete steps render a marker per step
 * instead of a plain track.
 *
 * @param slider The slider to draw.
 * @param x Screen x position.
 * @param y Screen y position.
 * @return Any error that occurs.
 */
 errorret_t uiSliderDraw(
  const uislider_t *slider,
  const float_t x,
  const float_t y
 );
 /**
 * Rebuilds the slider's cached value label from its current value.
 * Called internally whenever value changes.
 *
 * @param slider The slider to update.
 */
 void uiSliderRebuildValueLabel(uislider_t *slider);
 /**
 * Rebuilds the slider's cached track/fill/marker geometry (relative to
 * origin (0,0)) from its current label size, value, and step
 * configuration. Called internally on init and whenever the value
 * changes -- uiSliderDraw never recomputes this itself.
 *
 * @param slider The slider to update.
 */
 void uiSliderRebuildGeometry(uislider_t *slider);
@@ -0,0 +1,69 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uitab.h"
 #include "assert/assert.h"
 #include "display/text/text.h"
 #include "display/color.h"
 #include "display/spritebatch/spritebatch.h"
 #include "display/texture/texture.h"
 #include "display/shader/shaderunlit.h"
 void uiTabInit(uitab_t *tab, const char_t *label) {
  assertNotNull(tab, "Tab cannot be NULL");
  assertNotNull(label, "Label cannot be NULL");
  uiWidgetLabelInit(&tab->label, &FONT_DEFAULT);
  uiWidgetLabelSetText(&tab->label, label);
  tab->active = false;
  uiTabRebuildBackground(tab);
 }
 bool_t uiTabIsActive(const uitab_t *tab) {
  assertNotNull(tab, "Tab cannot be NULL");
  return tab->active;
 }
 void uiTabSetActive(uitab_t *tab, const bool_t active) {
  assertNotNull(tab, "Tab cannot be NULL");
  tab->active = active;
 }
 errorret_t uiTabDraw(
  const uitab_t *tab,
  const float_t x,
  const float_t y
 ) {
  assertNotNull(tab, "Tab cannot be NULL");
  spritebatchsprite_t sprite = spriteBatchSpriteTranslate(
    &tab->cachedBackground, x, y
  );
  shadermaterial_t material = {
    .unlit = {
      .color = tab->active ? COLOR_GREEN : COLOR_RED,
      .texture = &TEXTURE_WHITE
    }
  };
  errorChain(spriteBatchBuffer(&sprite, 1, &SHADER_UNLIT, material));
  errorChain(uiWidgetLabelDraw(&tab->label, x, y));
  errorOk();
 }
 void uiTabRebuildBackground(uitab_t *tab) {
  assertNotNull(tab, "Tab cannot be NULL");
  int32_t labelW, labelH;
  uiWidgetLabelGetSize(&tab->label, &labelW, &labelH);
  tab->cachedBackground = (spritebatchsprite_t){
    .min = { 0.0f, 0.0f, 0.0f },
    .max = { (float_t)labelW, (float_t)labelH, 0.0f },
    .uvMin = { 0.0f, 0.0f },
    .uvMax = { 1.0f, 1.0f }
  };
 }
@@ -0,0 +1,70 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "ui/widget/uiwidgetlabel.h"
 #include "display/spritebatch/spritebatchsprite.h"
 typedef struct {
  uiwidgetlabel_t label;
  bool_t active;
  // Background quad, cached relative to origin (0,0) from the label's
  // size at init -- uiTabDraw only translates this into position, since
  // active/inactive only changes the material color, not the geometry.
  spritebatchsprite_t cachedBackground;
 } uitab_t;
 /**
 * Initializes a tab.
 *
 * @param tab The tab to initialize.
 * @param label Display label.
 */
 void uiTabInit(uitab_t *tab, const char_t *label);
 /**
 * Returns whether the tab is active.
 *
 * @param tab The tab to query.
 * @returns True if active.
 */
 bool_t uiTabIsActive(const uitab_t *tab);
 /**
 * Sets the active state of the tab.
 *
 * @param tab The tab to update.
 * @param active The new active state.
 */
 void uiTabSetActive(uitab_t *tab, const bool_t active);
 /**
 * Draws the tab at the given screen position. Active tabs draw with a
 * green background; inactive tabs draw with a red background.
 *
 * @param tab The tab to draw.
 * @param x Screen x position.
 * @param y Screen y position.
 * @return Any error that occurs.
 */
 errorret_t uiTabDraw(
  const uitab_t *tab,
  const float_t x,
  const float_t y
 );
 /**
 * Rebuilds the tab's cached background quad (relative to origin (0,0))
 * from its current label size. Called internally by uiTabInit -- the
 * background's geometry never changes afterwards, since the tab has no
 * API to change its label text.
 *
 * @param tab The tab to update.
 */
 void uiTabRebuildBackground(uitab_t *tab);
@@ -0,0 +1,66 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uiwidgetlabel.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "util/string.h"
 #include "display/text/text.h"
 void uiWidgetLabelInit(uiwidgetlabel_t *label, font_t *font) {
  assertNotNull(label, "Label cannot be NULL");
  assertNotNull(font, "Font cannot be NULL");
  memoryZero(label, sizeof(uiwidgetlabel_t));
  label->font = font;
  label->color = COLOR_WHITE;
 }
 void uiWidgetLabelSetText(uiwidgetlabel_t *label, const char_t *text) {
  assertNotNull(label, "Label cannot be NULL");
  assertNotNull(text, "Text cannot be NULL");
  assertStrLenMax(text, UI_WIDGET_LABEL_TEXT_MAX, "Label text too long");
  stringCopy(label->text, text, UI_WIDGET_LABEL_TEXT_MAX);
  label->spriteCount = textBuildSpriteCache(
    label->text, label->font, label->sprites,
    UI_WIDGET_LABEL_SPRITE_COUNT_MAX, &label->width, &label->height
  );
 }
 void uiWidgetLabelSetColor(uiwidgetlabel_t *label, const color_t color) {
  assertNotNull(label, "Label cannot be NULL");
  label->color = color;
 }
 void uiWidgetLabelGetSize(
  const uiwidgetlabel_t *label,
  int32_t *outWidth,
  int32_t *outHeight
 ) {
  assertNotNull(label, "Label cannot be NULL");
  assertNotNull(outWidth, "Output width cannot be NULL");
  assertNotNull(outHeight, "Output height cannot be NULL");
  *outWidth = label->width;
  *outHeight = label->height;
 }
 errorret_t uiWidgetLabelDraw(
  const uiwidgetlabel_t *label,
  const float_t x,
  const float_t y
 ) {
  assertNotNull(label, "Label cannot be NULL");
  if(label->spriteCount == 0) errorOk();
  spritebatchsprite_t scratch[UI_WIDGET_LABEL_SPRITE_COUNT_MAX];
  errorChain(textDrawSpriteCache(
    label->sprites, label->spriteCount, scratch, x, y, label->color,
    label->font->texture
  ));
  errorOk();
 }
@@ -0,0 +1,90 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "display/text/font.h"
 #include "display/spritebatch/spritebatchsprite.h"
 #include "display/color.h"
 // A cached, cheap-to-redraw label sized for embedding directly inside
 // small widgets (buttons, checkboxes, sliders, ...) rather than
 // referencing text by pointer and re-deriving glyph geometry every
 // frame. Capacity is intentionally much smaller than uilabel_t's -- it
 // gets embedded by value in every widget instance (and inside
 // uimenuitem_t's union, which is often arrayed), so keeping it small
 // matters on memory-constrained targets. See uilabel_t for the
 // general-purpose, larger-capacity equivalent.
 #define UI_WIDGET_LABEL_TEXT_MAX 64
 #define UI_WIDGET_LABEL_SPRITE_COUNT_MAX UI_WIDGET_LABEL_TEXT_MAX
 typedef struct {
  char_t text[UI_WIDGET_LABEL_TEXT_MAX];
  color_t color;
  font_t *font;
  spritebatchsprite_t sprites[UI_WIDGET_LABEL_SPRITE_COUNT_MAX];
  uint32_t spriteCount;
  int32_t width;
  int32_t height;
 } uiwidgetlabel_t;
 /**
 * Initializes a widget label, defaulting to white text and no text set.
 *
 * @param label The label to initialize.
 * @param font Font to use for rendering. Must outlive the label.
 */
 void uiWidgetLabelInit(uiwidgetlabel_t *label, font_t *font);
 /**
 * Sets the label's text, rebuilding its cached sprites immediately.
 * Call this whenever the displayed text changes -- uiWidgetLabelDraw
 * never recomputes it.
 *
 * @param label The label to update.
 * @param text Null-terminated string to display. Must be shorter than
 * UI_WIDGET_LABEL_TEXT_MAX.
 */
 void uiWidgetLabelSetText(uiwidgetlabel_t *label, const char_t *text);
 /**
 * Sets the label's tint color. Cheap -- doesn't touch the sprite cache.
 *
 * @param label The label to update.
 * @param color The new tint color.
 */
 void uiWidgetLabelSetColor(uiwidgetlabel_t *label, const color_t color);
 /**
 * Gets the measured size (in pixels) of the label's current text, cached
 * from the last uiWidgetLabelSetText call.
 *
 * @param label The label to query.
 * @param outWidth Pointer to store the width.
 * @param outHeight Pointer to store the height.
 */
 void uiWidgetLabelGetSize(
  const uiwidgetlabel_t *label,
  int32_t *outWidth,
  int32_t *outHeight
 );
 /**
 * Draws the label's cached sprites at the given screen position in a
 * single batched buffer call. Does not recompute glyph layout.
 *
 * @param label The label to draw.
 * @param x Screen x position.
 * @param y Screen y position.
 * @return Any error that occurs.
 */
 errorret_t uiWidgetLabelDraw(
  const uiwidgetlabel_t *label,
  const float_t x,
  const float_t y
 );
@@ -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
    uitextbox.c
    uitextboxmain.c
 )
@@ -0,0 +1,276 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uitextbox.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "util/string.h"
 #include "time/time.h"
 #include "display/text/text.h"
 #include "display/color.h"
 #include "display/spritebatch/spritebatch.h"
 #include "display/shader/shaderunlit.h"
 #include "ui/frame/uiframe.h"
 void uiTextboxInit(
  uitextbox_t *box,
  char_t *text,
  const uint32_t maxLength,
  uitextboxline_t *lines,
  const uint32_t linesMax
 ) {
  assertNotNull(box, "Textbox cannot be NULL");
  assertNotNull(text, "Text buffer cannot be NULL");
  assertTrue(maxLength >= 1, "maxLength must be at least 1");
  assertNotNull(lines, "Lines buffer cannot be NULL");
  assertTrue(linesMax >= 1, "linesMax must be at least 1");
  memoryZero(box, sizeof(uitextbox_t));
  box->text = text;
  box->maxLength = maxLength;
  box->lines = lines;
  box->linesMax = linesMax;
  box->glyphsBuiltForPage = -1;
 }
 void uiTextboxSetText(uitextbox_t *box, const char_t *text) {
  assertNotNull(box, "Textbox cannot be NULL");
  assertNotNull(text, "Text cannot be NULL");
  stringCopy(box->text, text, box->maxLength);
  box->currentPage = 0;
  box->scroll = 0;
  box->layoutWidth = 0.0f;
  box->layoutHeight = 0.0f;
  box->glyphsBuiltForPage = -1;
 }
 void uiTextboxBuildLayout(
  uitextbox_t *box,
  const float_t width,
  const float_t height
 ) {
  assertNotNull(box, "Textbox cannot be NULL");
  box->glyphsBuiltForPage = -1;
  box->layoutWidth = width;
  box->layoutHeight = height;
  box->lineCount = 0;
  box->pageCount = 1;
  float_t fontW = (float_t)FONT_DEFAULT.tileset->tileWidth;
  float_t fontH = (float_t)FONT_DEFAULT.tileset->tileHeight;
  if(fontW <= 0.0f || fontH <= 0.0f) return;
  box->charsPerLine = (int32_t)(width / fontW);
  box->linesPerPage = (int32_t)(height / (fontH + UI_TEXTBOX_LINE_SPACING));
  if(box->linesPerPage > UI_TEXTBOX_LINES_PER_PAGE_MAX) {
    box->linesPerPage = UI_TEXTBOX_LINES_PER_PAGE_MAX;
  }
  if(box->charsPerLine <= 0 || box->linesPerPage <= 0) return;
  if(box->text[0] == '\0') return;
  char_t *src = box->text;
  int32_t i = 0;
  while(src[i] != '\0' && box->lineCount < (int32_t)box->linesMax) {
    if(src[i] == '\t') {
      i++;
      int32_t rem = box->lineCount % box->linesPerPage;
      int32_t pad = rem > 0 ? box->linesPerPage - rem : 0;
      while(pad > 0 && box->lineCount < (int32_t)box->linesMax) {
        box->lines[box->lineCount].start = i;
        box->lines[box->lineCount].count = 0;
        box->lineCount++;
        pad--;
      }
      continue;
    }
    int32_t lineStart = i;
    int32_t lineWidth = 0;
    while(src[i] != '\0') {
      char_t c = src[i];
      if(c == '\n') { i++; break; }
      if(c == '\t') break;
      if(c == ' ') {
        int32_t wordLen = 0;
        int32_t j = i + 1;
        while(
          src[j] != ' ' && src[j] != '\n' &&
          src[j] != '\t' && src[j] != '\0'
        ) {
          wordLen++;
          j++;
        }
        if(lineWidth > 0 && lineWidth + 1 + wordLen > box->charsPerLine) {
          i++;
          break;
        }
        lineWidth++;
        i++;
      } else {
        if(lineWidth >= box->charsPerLine) break;
        lineWidth++;
        i++;
      }
    }
    box->lines[box->lineCount].start = lineStart;
    box->lines[box->lineCount].count = lineWidth;
    box->lineCount++;
  }
  if(box->lineCount == 0) {
    box->pageCount = 1;
  } else {
    box->pageCount =
      (box->lineCount + box->linesPerPage - 1) / box->linesPerPage;
  }
 }
 errorret_t uiTextboxUpdate(uitextbox_t *box) {
  assertNotNull(box, "Textbox cannot be NULL");
  #ifdef DUSK_TIME_DYNAMIC
    if(TIME.dynamicUpdate) errorOk();
  #endif
  if(!uiTextboxPageIsComplete(box)) {
    box->scroll += UI_TEXTBOX_SCROLL_CHARS_PER_TICK;
  }
  errorOk();
 }
 errorret_t uiTextboxDraw(
  uitextbox_t *box,
  const float_t x,
  const float_t y,
  const float_t width,
  const float_t height
 ) {
  assertNotNull(box, "Textbox cannot be NULL");
  float_t startX = (float_t)UI_FRAME_START_X;
  float_t startY = (float_t)UI_FRAME_START_Y;
  float_t contentX = x + startX;
  float_t contentY = y + startY;
  float_t contentW = width - 2.0f * startX;
  float_t contentH = height - 2.0f * startY;
  if(contentW != box->layoutWidth || contentH != box->layoutHeight) {
    uiTextboxBuildLayout(box, contentW, contentH);
  }
  errorChain(uiFrameDrawCached(&box->frameCache, x, y, width, height));
  if(box->lineCount == 0 || box->text[0] == '\0') errorOk();
  if(box->glyphsBuiltForPage != box->currentPage) {
    uiTextboxBuildPageGlyphs(box);
  }
  if(box->glyphCount == 0) errorOk();
  int32_t visibleCount = 0;
  while(
    visibleCount < box->glyphCount &&
    box->glyphs[visibleCount].revealAt <= box->scroll
  ) visibleCount++;
  if(visibleCount == 0) errorOk();
  spritebatchsprite_t scratch[UI_TEXTBOX_PAGE_GLYPHS_MAX];
  for(int32_t i = 0; i < visibleCount; i++) {
    scratch[i] = spriteBatchSpriteTranslate(
      &box->glyphs[i].sprite, contentX, contentY
    );
  }
  shadermaterial_t material = {
    .unlit = {
      .color = COLOR_WHITE,
      .texture = FONT_DEFAULT.texture
    }
  };
  errorChain(spriteBatchBuffer(scratch, visibleCount, &SHADER_UNLIT, material));
  errorOk();
 }
 void uiTextboxBuildPageGlyphs(uitextbox_t *box) {
  assertNotNull(box, "Textbox cannot be NULL");
  box->glyphCount = 0;
  int32_t pageFirst = box->currentPage * box->linesPerPage;
  int32_t pageLast = pageFirst + box->linesPerPage;
  if(pageLast > box->lineCount) pageLast = box->lineCount;
  float_t fontW = (float_t)FONT_DEFAULT.tileset->tileWidth;
  float_t fontH = (float_t)FONT_DEFAULT.tileset->tileHeight;
  int32_t consumed = 0;
  for(int32_t li = pageFirst; li < pageLast; li++) {
    uitextboxline_t *line = &box->lines[li];
    float_t lineY =
      (float_t)(li - pageFirst) * (fontH + UI_TEXTBOX_LINE_SPACING);
    for(int32_t ci = 0; ci < line->count; ci++) {
      consumed++;
      char_t c = box->text[line->start + ci];
      if(c == ' ') continue;
      assertTrue(
        box->glyphCount < UI_TEXTBOX_PAGE_GLYPHS_MAX,
        "Textbox page produces too many glyphs"
      );
      uitextboxglyph_t *glyph = &box->glyphs[box->glyphCount++];
      glyph->sprite = textGetSprite(
        (vec2){ (float_t)ci * fontW, lineY }, c, &FONT_DEFAULT
      );
      glyph->revealAt = consumed;
    }
  }
  box->glyphsBuiltForPage = box->currentPage;
 }
 int32_t uiTextboxGetPageCharCount(const uitextbox_t *box) {
  assertNotNull(box, "Textbox cannot be NULL");
  int32_t first = box->currentPage * box->linesPerPage;
  int32_t last = first + box->linesPerPage;
  if(last > box->lineCount) last = box->lineCount;
  int32_t total = 0;
  for(int32_t i = first; i < last; i++) {
    total += box->lines[i].count;
  }
  return total;
 }
 bool_t uiTextboxPageIsComplete(const uitextbox_t *box) {
  assertNotNull(box, "Textbox cannot be NULL");
  return box->scroll >= uiTextboxGetPageCharCount(box);
 }
 bool_t uiTextboxHasNextPage(const uitextbox_t *box) {
  assertNotNull(box, "Textbox cannot be NULL");
  return box->currentPage + 1 < box->pageCount;
 }
 void uiTextboxNextPage(uitextbox_t *box) {
  assertNotNull(box, "Textbox cannot be NULL");
  if(!uiTextboxHasNextPage(box)) return;
  box->currentPage++;
  box->scroll = 0;
 }
@@ -0,0 +1,175 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 #include "ui/frame/uiframe.h"
 #include "display/spritebatch/spritebatchsprite.h"
 #define UI_TEXTBOX_LINES_PER_PAGE_MAX 4
 #define UI_TEXTBOX_SCROLL_CHARS_PER_TICK 1
 #define UI_TEXTBOX_LINE_SPACING 0.0f
 // Fixed capacity for a page's cached glyph sprites (see uitextboxglyph_t).
 // Sized generously above UI_TEXTBOX_LINES_PER_PAGE_MAX worth of glyphs at
 // typical textbox widths; uiTextboxBuildPageGlyphs asserts if a page
 // somehow produces more than this.
 #define UI_TEXTBOX_PAGE_GLYPHS_MAX 512
 typedef struct {
  int32_t start;
  int32_t count;
 } uitextboxline_t;
 // A single visible glyph's cached sprite (relative to the textbox's
 // content origin, i.e. (0,0)) plus the scroll value at/after which it
 // becomes visible -- lets uiTextboxDraw turn the typewriter scroll into
 // a simple prefix-count instead of recomputing glyph geometry every
 // frame.
 typedef struct {
  spritebatchsprite_t sprite;
  int32_t revealAt;
 } uitextboxglyph_t;
 typedef struct {
  char_t *text;
  uint32_t maxLength;
  uitextboxline_t *lines;
  uint32_t linesMax;
  int32_t lineCount;
  int32_t charsPerLine;
  int32_t linesPerPage;
  int32_t pageCount;
  // last dimensions used for layout; rebuild triggers when these change
  float_t layoutWidth;
  float_t layoutHeight;
  int32_t currentPage;
  int32_t scroll;
  // Cached glyph sprites for the current page (see uitextboxglyph_t),
  // rebuilt only when currentPage no longer matches
  // glyphsBuiltForPage -- not every frame/scroll tick.
  uitextboxglyph_t glyphs[UI_TEXTBOX_PAGE_GLYPHS_MAX];
  int32_t glyphCount;
  int32_t glyphsBuiltForPage;
  uiframecache_t frameCache;
 } uitextbox_t;
 /**
 * Initializes a textbox, zeroing all state and binding it to caller-owned
 * text and line storage.
 *
 * @param box The textbox to initialize.
 * @param text Caller-owned buffer the textbox copies its text into.
 * @param maxLength Capacity of text, in characters.
 * @param lines Caller-owned buffer the textbox lays lines out into.
 * @param linesMax Capacity of lines, in entries.
 */
 void uiTextboxInit(
  uitextbox_t *box,
  char_t *text,
  const uint32_t maxLength,
  uitextboxline_t *lines,
  const uint32_t linesMax
 );
 /**
 * Copies text into the textbox and marks layout as dirty.
 * Resets currentPage and scroll to 0.
 *
 * @param box The textbox to update.
 * @param text Null-terminated source string.
 */
 void uiTextboxSetText(uitextbox_t *box, const char_t *text);
 /**
 * Rebuilds word-wrap and page layout for the given draw dimensions.
 * Called automatically by uiTextboxDraw when width or height changes.
 *
 * @param box The textbox to rebuild.
 * @param width Available content width in pixels.
 * @param height Available content height in pixels.
 */
 void uiTextboxBuildLayout(
  uitextbox_t *box,
  const float_t width,
  const float_t height
 );
 /**
 * Advances the typewriter scroll by UI_TEXTBOX_SCROLL_CHARS_PER_TICK.
 * Skipped on dynamic ticks.
 *
 * @param box The textbox to update.
 * @returns Any error that occurs.
 */
 errorret_t uiTextboxUpdate(uitextbox_t *box);
 /**
 * Draws the textbox frame and visible text. Rebuilds layout automatically
 * if width or height differs from the last draw call.
 *
 * @param box The textbox to draw.
 * @param x Screen x position.
 * @param y Screen y position.
 * @param width Draw width in pixels.
 * @param height Draw height in pixels.
 * @returns Any error that occurs.
 */
 errorret_t uiTextboxDraw(
  uitextbox_t *box,
  const float_t x,
  const float_t y,
  const float_t width,
  const float_t height
 );
 /**
 * Returns the total visible char count for the current page.
 *
 * @param box The textbox to query.
 * @returns Total chars on the current page.
 */
 int32_t uiTextboxGetPageCharCount(const uitextbox_t *box);
 /**
 * Returns true when scroll has fully revealed the current page.
 *
 * @param box The textbox to query.
 * @returns True if the current page is fully visible.
 */
 bool_t uiTextboxPageIsComplete(const uitextbox_t *box);
 /**
 * Returns true when there is at least one more page after the current one.
 *
 * @param box The textbox to query.
 * @returns True if a next page exists.
 */
 bool_t uiTextboxHasNextPage(const uitextbox_t *box);
 /**
 * Advances to the next page and resets scroll to 0.
 * Has no effect if already on the last page.
 *
 * @param box The textbox to advance.
 */
 void uiTextboxNextPage(uitextbox_t *box);
 /**
 * Rebuilds the cached glyph sprites (see uitextboxglyph_t) for the
 * current page from its line layout. Called automatically by
 * uiTextboxDraw whenever currentPage no longer matches the page the
 * cache was last built for.
 *
 * @param box The textbox to rebuild.
 */
 void uiTextboxBuildPageGlyphs(uitextbox_t *box);
@@ -0,0 +1,121 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uitextboxmain.h"
 #include "ui/focus/uifocus.h"
 #include "display/screen/screen.h"
 #include "display/text/text.h"
 #include "display/color.h"
 #include "display/spritebatch/spritebatch.h"
 #include "display/shader/shaderunlit.h"
 #include "ui/frame/uiframe.h"
 uitextboxmain_t UI_TEXTBOX_MAIN;
 static uifocusitem_t *focusItem = NULL;
 errorret_t uiTextboxMainInit(void) {
  uiTextboxInit(
    &UI_TEXTBOX_MAIN.box,
    UI_TEXTBOX_MAIN.text, UI_TEXTBOX_MAIN_TEXT_MAX,
    UI_TEXTBOX_MAIN.lines, UI_TEXTBOX_MAIN_LINES_MAX
  );
  errorOk();
 }
 void uiTextboxMainSetText(const char_t *text) {
  uiTextboxSetText(&UI_TEXTBOX_MAIN.box, text);
  if(focusItem != NULL) return;
  focusItem = uiFocusPush(
    1, 1,
    uiTextboxMainFocusSelected,
    NULL,
    uiTextboxMainFocusClosed,
    NULL,
    NULL
  );
 }
 errorret_t uiTextboxMainUpdate(void) {
  if(focusItem == NULL) errorOk();
  return uiTextboxUpdate(&UI_TEXTBOX_MAIN.box);
 }
 errorret_t uiTextboxMainDraw(void) {
  if(focusItem == NULL) errorOk();
  float_t fontH = (float_t)FONT_DEFAULT.tileset->tileHeight;
  float_t h = (float_t)UI_TEXTBOX_MAIN_LINES * fontH +
    (float_t)(UI_TEXTBOX_MAIN_LINES - 1) * UI_TEXTBOX_LINE_SPACING +
    2.0f * (float_t)UI_FRAME_START_Y;
  float_t w = (float_t)SCREEN.scanWidth;
  float_t x = (float_t)SCREEN.scanX;
  float_t y = (float_t)(SCREEN.scanY + SCREEN.scanHeight) - h;
  errorChain(uiTextboxDraw(&UI_TEXTBOX_MAIN.box, x, y, w, h));
  if(!uiTextboxPageIsComplete(&UI_TEXTBOX_MAIN.box)) errorOk();
  float_t fontW = (float_t)FONT_DEFAULT.tileset->tileWidth;
  float_t contentX = x + (float_t)UI_FRAME_START_X;
  float_t contentY = y + (float_t)UI_FRAME_START_Y;
  float_t contentW = w - 2.0f * (float_t)UI_FRAME_START_X;
  float_t contentH = h - 2.0f * (float_t)UI_FRAME_START_Y;
  shadermaterial_t material = {
    .unlit = {
      .color = COLOR_WHITE,
      .texture = FONT_DEFAULT.texture
    }
  };
  spritebatchsprite_t caret = textGetSprite(
    (vec2){
      contentX + contentW - fontW,
      contentY + contentH - fontH
    },
    'v',
    &FONT_DEFAULT
  );
  errorChain(spriteBatchBuffer(&caret, 1, &SHADER_UNLIT, material));
  errorOk();
 }
 bool_t uiTextboxMainPageIsComplete(void) {
  return uiTextboxPageIsComplete(&UI_TEXTBOX_MAIN.box);
 }
 bool_t uiTextboxMainHasNextPage(void) {
  return uiTextboxHasNextPage(&UI_TEXTBOX_MAIN.box);
 }
 void uiTextboxMainNextPage(void) {
  uiTextboxNextPage(&UI_TEXTBOX_MAIN.box);
 }
 bool_t uiTextboxMainIsActive(void) {
  return focusItem != NULL;
 }
 bool_t uiTextboxMainFocusSelected(const uifocusitem_t *item) {
  if(!uiTextboxPageIsComplete(&UI_TEXTBOX_MAIN.box)) {
    UI_TEXTBOX_MAIN.box.scroll =
      uiTextboxGetPageCharCount(&UI_TEXTBOX_MAIN.box);
    return true;
  }
  if(uiTextboxHasNextPage(&UI_TEXTBOX_MAIN.box)) {
    uiTextboxNextPage(&UI_TEXTBOX_MAIN.box);
    return true;
  }
  uiFocusPopItem(focusItem);
  return true;
 }
 bool_t uiTextboxMainFocusClosed(const uifocusitem_t *item) {
  focusItem = NULL;
  return true;
 }
@@ -0,0 +1,94 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "uitextbox.h"
 #include "ui/focus/uifocusitem.h"
 #define UI_TEXTBOX_MAIN_LINES 4
 #define UI_TEXTBOX_MAIN_TEXT_MAX 1024
 #define UI_TEXTBOX_MAIN_LINES_MAX 64
 typedef struct {
  uitextbox_t box;
  char_t text[UI_TEXTBOX_MAIN_TEXT_MAX];
  uitextboxline_t lines[UI_TEXTBOX_MAIN_LINES_MAX];
 } uitextboxmain_t;
 extern uitextboxmain_t UI_TEXTBOX_MAIN;
 /**
 * Initializes UI_TEXTBOX_MAIN.
 *
 * @returns Any error that occurs.
 */
 errorret_t uiTextboxMainInit(void);
 /**
 * Copies text into UI_TEXTBOX_MAIN and resets page and scroll.
 *
 * @param text Null-terminated source string.
 */
 void uiTextboxMainSetText(const char_t *text);
 /**
 * Advances the typewriter scroll for UI_TEXTBOX_MAIN.
 *
 * @returns Any error that occurs.
 */
 errorret_t uiTextboxMainUpdate(void);
 /**
 * Draws UI_TEXTBOX_MAIN full-width at the bottom of the screen.
 * Position and size are derived from SCREEN each call.
 *
 * @returns Any error that occurs.
 */
 errorret_t uiTextboxMainDraw(void);
 /**
 * Returns true when the current page is fully scrolled in.
 *
 * @returns True if the current page is complete.
 */
 bool_t uiTextboxMainPageIsComplete(void);
 /**
 * Returns true when at least one more page follows the current one.
 *
 * @returns True if a next page exists.
 */
 bool_t uiTextboxMainHasNextPage(void);
 /**
 * Advances UI_TEXTBOX_MAIN to the next page and resets scroll.
 * Has no effect if already on the last page.
 */
 void uiTextboxMainNextPage(void);
 /**
 * Returns true when UI_TEXTBOX_MAIN has focus (is visible and active).
 *
 * @returns True if the textbox is currently active.
 */
 bool_t uiTextboxMainIsActive(void);
 /**
 * Internal focus callback - skip scroll or advance page or dismiss.
 *
 * @param item The active focus item.
 * @returns True.
 */
 bool_t uiTextboxMainFocusSelected(const uifocusitem_t *item);
 /**
 * Internal focus callback - clears the focus item pointer on dismiss.
 *
 * @param item The focus item being closed.
 * @returns True.
 */
 bool_t uiTextboxMainFocusClosed(const uifocusitem_t *item);
@@ -0,0 +1,35 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "uitestlabel.h"
 #include "ui/widget/uilabel.h"
 #include "display/text/text.h"
 #include "display/screen/screen.h"
 #include "engine/engine.h"
 uilabel_t UI_TEST_LABEL;
 errorret_t uiTestLabelInit() {
  uiLabelInit(&UI_TEST_LABEL, &FONT_DEFAULT);
  uiLabelSetText(&UI_TEST_LABEL, "duskrpg");
  errorOk();
 }
 errorret_t uiTestLabelDraw() {
  int32_t versionWidth, versionHeight;
  textMeasure(ENGINE.version, &FONT_DEFAULT, &versionWidth, &versionHeight);
  errorChain(uiLabelDraw(
    &UI_TEST_LABEL,
    (float_t)(SCREEN.scanX + SCREEN.scanWidth - UI_TEST_LABEL.width),
    (float_t)(
      SCREEN.scanY + SCREEN.scanHeight - versionHeight -
      UI_TEST_LABEL.height
    )
  ));
  errorOk();
 }
@@ -0,0 +1,24 @@
 /**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "error/error.h"
 /**
 * Initializes the test label, a smoke test for the duskrpg-side UI
 * element extension point (uielementgame.h).
 *
 * @return Any error that occurs.
 */
 errorret_t uiTestLabelInit();
 /**
 * Draws the test label above the engine's debug version number.
 *
 * @return Any error that occurs.
 */
 errorret_t uiTestLabelDraw();
@@ -1,49 +0,0 @@
 /**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "script/scriptcontext.h"
 #include "debug/debug.h"
 #include "assert/assert.h"
 #include "rpg/overworld/map.h"
 int moduleMapLoad(lua_State *L) {
  assertNotNull(L, "Lua state cannot be NULL");
  if(!lua_isstring(L, 1)) {
    luaL_error(L, "Expected string map filename");
    return 0;
  }
  // Potentially provide up to 3 params
  chunkpos_t initial = { .x = 0, .y = 0, .z = 0 };
  if(lua_isnumber(L, 2)) {
    initial.x = (chunkunit_t)luaL_checkinteger(L, 2);
  }
  if(lua_isnumber(L, 3)) {
    initial.y = (chunkunit_t)luaL_checkinteger(L, 3);
  }
  if(lua_isnumber(L, 4)) {
    initial.z = (chunkunit_t)luaL_checkinteger(L, 4);
  }
  // Load the map.
  errorret_t ret = mapLoad(luaL_checkstring(L, 1), initial);
  if(ret.code != ERROR_OK) {
    luaL_error(L, "Failed to load map");
    errorCatch(errorPrint(ret));
    return 0;
  }
  return 0;
 }
 void moduleMapSystem(scriptcontext_t *context) {
  assertNotNull(context, "Script context cannot be NULL");
  lua_register(context->luaState, "mapLoad", moduleMapLoad);
 }
@@ -1,17 +0,0 @@
 # Copyright (c) 2025 Dominic Masters
 # 
 # This software is released under the MIT License.
 # https://opensource.org/licenses/MIT
 # Sources
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    rpg.c
    rpgcamera.c
    rpgtextbox.c
 )
 # Subdirs
 add_subdirectory(cutscene)
 add_subdirectory(entity)
 add_subdirectory(overworld)
@@ -1,14 +0,0 @@
 # Copyright (c) 2025 Dominic Masters
 #
 # This software is released under the MIT License.
 # https://opensource.org/licenses/MIT
 # Sources
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    cutscenesystem.c
    cutscenemode.c
 )
 # Subdirs
 add_subdirectory(item)
@@ -1,14 +0,0 @@
 /**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "rpg/cutscene/item/cutsceneitem.h"
 typedef struct cutscene_s {
  const cutsceneitem_t *items;
  uint8_t itemCount;
 } cutscene_t;
@@ -1,19 +0,0 @@
 /**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "rpg/cutscene/cutscenesystem.h"
 bool_t cutsceneModeIsInputAllowed() {
  switch(CUTSCENE_SYSTEM.mode) {
    case CUTSCENE_MODE_FULL_FREEZE:
    case CUTSCENE_MODE_INPUT_FREEZE:
      return false;
    default:
      return true;
  }
 }
@@ -1,26 +0,0 @@
 /**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "dusk.h"
 typedef enum {
  CUTSCENE_MODE_NONE,
  CUTSCENE_MODE_FULL_FREEZE,
  CUTSCENE_MODE_INPUT_FREEZE,
  CUTSCENE_MODE_GAMEPLAY
 } cutscenemode_t;
 // Default mode for all cutscenes.
 #define CUTSCENE_MODE_INITIAL CUTSCENE_MODE_INPUT_FREEZE
 /**
 * Check if input is allowed in the current cutscene mode.
 * 
 * @return true if input is allowed, false otherwise.
 */
 bool_t cutsceneModeIsInputAllowed();
@@ -1,56 +0,0 @@
 /**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "cutscenesystem.h"
 #include "util/memory.h"
 cutscenesystem_t CUTSCENE_SYSTEM;
 void cutsceneSystemInit() {
  memoryZero(&CUTSCENE_SYSTEM, sizeof(cutscenesystem_t));
 }
 void cutsceneSystemStartCutscene(const cutscene_t *cutscene) {
  CUTSCENE_SYSTEM.scene = cutscene;
  CUTSCENE_SYSTEM.mode = CUTSCENE_MODE_INITIAL;
  CUTSCENE_SYSTEM.currentItem = 0xFF;// Set to 0xFF so start wraps.
  cutsceneSystemNext();
 }
 void cutsceneSystemUpdate() {
  if(CUTSCENE_SYSTEM.scene == NULL) return;
  const cutsceneitem_t *item = cutsceneSystemGetCurrentItem();
  cutsceneItemUpdate(item, &CUTSCENE_SYSTEM.data);
 }
 void cutsceneSystemNext() {
  if(CUTSCENE_SYSTEM.scene == NULL) return;
  CUTSCENE_SYSTEM.currentItem++;
  // End of the cutscene?
  if(
    CUTSCENE_SYSTEM.currentItem >= CUTSCENE_SYSTEM.scene->itemCount
  ) {
    CUTSCENE_SYSTEM.scene = NULL;
    CUTSCENE_SYSTEM.currentItem = 0xFF;
    CUTSCENE_SYSTEM.mode = CUTSCENE_MODE_NONE;
    return;
  }
  // Start item.
  const cutsceneitem_t *item = cutsceneSystemGetCurrentItem();
  memset(&CUTSCENE_SYSTEM.data, 0, sizeof(CUTSCENE_SYSTEM.data));
  cutsceneItemStart(item, &CUTSCENE_SYSTEM.data);
 }
 const cutsceneitem_t * cutsceneSystemGetCurrentItem() {
  if(CUTSCENE_SYSTEM.scene == NULL) return NULL;
  return &CUTSCENE_SYSTEM.scene->items[CUTSCENE_SYSTEM.currentItem];
 }
@@ -1,50 +0,0 @@
 /**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "cutscene.h"
 #include "cutscenemode.h"
 typedef struct {
  const cutscene_t *scene;
  uint8_t currentItem;
  // Data (used by the current item).
  cutsceneitemdata_t data;
  cutscenemode_t mode;
 } cutscenesystem_t;
 extern cutscenesystem_t CUTSCENE_SYSTEM;
 /**
 * Initialize the cutscene system.
 */
 void cutsceneSystemInit();
 /**
 * Start a cutscene.
 * 
 * @param cutscene Pointer to the cutscene to start.
 */
 void cutsceneSystemStartCutscene(const cutscene_t *cutscene);
 /**
 * Advance to the next item in the cutscene.
 */
 void cutsceneSystemNext();
 /**
 * Update the cutscene system for one frame.
 */
 void cutsceneSystemUpdate();
 /**
 * Get the current cutscene item.
 * 
 * @return Pointer to the current cutscene item.
 */
 const cutsceneitem_t * cutsceneSystemGetCurrentItem();
@@ -1,10 +0,0 @@
 # Copyright (c) 2025 Dominic Masters
 # 
 # This software is released under the MIT License.
 # https://opensource.org/licenses/MIT
 # Sources
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
  PUBLIC
    cutsceneitem.c
 )
@@ -1,11 +0,0 @@
 /**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "dusk.h"
 typedef void (*cutscenecallback_t)(void);
@@ -1,54 +0,0 @@
 /**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "rpg/cutscene/cutscenesystem.h"
 #include "input/input.h"
 #include "time/time.h"
 void cutsceneItemStart(const cutsceneitem_t *item, cutsceneitemdata_t *data) {
  switch(item->type) {
    case CUTSCENE_ITEM_TYPE_TEXT: {
      rpgTextboxShow(
        item->text.position,
        item->text.text
      );
      break;
    }
    case CUTSCENE_ITEM_TYPE_WAIT:
      data->wait = item->wait;
      break;
    case CUTSCENE_ITEM_TYPE_CALLBACK:
      if(item->callback != NULL) item->callback();
      break;
    case CUTSCENE_ITEM_TYPE_CUTSCENE:
      if(item->cutscene != NULL) cutsceneSystemStartCutscene(item->cutscene);
      break;
    default:
      break;
  }
 }
 void cutsceneItemUpdate(const cutsceneitem_t *item, cutsceneitemdata_t *data) {
  switch(item->type) {
    case CUTSCENE_ITEM_TYPE_TEXT:
      if(rpgTextboxIsVisible()) return;
      cutsceneSystemNext();
      break;
    case CUTSCENE_ITEM_TYPE_WAIT:
      data->wait -= TIME.delta;
      if(data->wait <= 0) cutsceneSystemNext();
      break;
    default:
      break;
  }
 }
@@ -1,53 +0,0 @@
 /**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "cutscenewait.h"
 #include "cutscenecallback.h"
 #include "cutscenetext.h"
 typedef struct cutscene_s cutscene_t;
 typedef enum {
  CUTSCENE_ITEM_TYPE_NULL,
  CUTSCENE_ITEM_TYPE_TEXT,
  CUTSCENE_ITEM_TYPE_CALLBACK,
  CUTSCENE_ITEM_TYPE_WAIT,
  CUTSCENE_ITEM_TYPE_CUTSCENE
 } cutsceneitemtype_t;
 typedef struct cutsceneitem_s {
  cutsceneitemtype_t type;
  // Arguments/Data that will be used when this item is invoked.
  union {
    cutscenetext_t text;
    cutscenecallback_t callback;
    cutscenewait_t wait;
    const cutscene_t *cutscene;
  };
 } cutsceneitem_t;
 typedef union {
  cutscenewaitdata_t wait;
 } cutsceneitemdata_t;
 /**
 * Start the given cutscene item.
 * 
 * @param item The cutscene item to start.
 * @param data The cutscene item data storage.
 */
 void cutsceneItemStart(const cutsceneitem_t *item, cutsceneitemdata_t *data);
 /**
 * Tick the given cutscene item (one frame).
 * 
 * @param item The cutscene item to tick.
 * @param data The cutscene item data storage.
 */
 void cutsceneItemUpdate(const cutsceneitem_t *item, cutsceneitemdata_t *data);
@@ -1,14 +0,0 @@
 /**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "rpg/rpgtextbox.h"
 typedef struct {
  char_t text[RPG_TEXTBOX_MAX_CHARS];
  rpgtextboxpos_t position;
 } cutscenetext_t;
@@ -1,12 +0,0 @@
 /**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "dusk.h"
 typedef float_t cutscenewait_t;
 typedef float_t cutscenewaitdata_t;
@@ -1,30 +0,0 @@
 /**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "rpg/cutscene/cutscenesystem.h"
 static const cutsceneitem_t TEST_CUTSCENE_ONE_ITEMS[] = {
  { .type = CUTSCENE_ITEM_TYPE_TEXT, .text = { .text = "This is a test cutscene.", .position = RPG_TEXTBOX_POS_BOTTOM } },
  { .type = CUTSCENE_ITEM_TYPE_WAIT, .wait = 2.0f },
  { .type = CUTSCENE_ITEM_TYPE_TEXT, .text = { .text = "It has multiple lines of text.\nAnd waits in between.", .position = RPG_TEXTBOX_POS_TOP } },
 };
 static const cutscene_t TEST_CUTSCENE_ONE = {
  .items = TEST_CUTSCENE_ONE_ITEMS,
  .itemCount = sizeof(TEST_CUTSCENE_ONE_ITEMS) / sizeof(cutsceneitem_t)
 };
 static const cutsceneitem_t TEST_CUTSCENE_TWO_ITEMS[] = {
  { .type = CUTSCENE_ITEM_TYPE_WAIT, .wait = 1.0f },
  { .type = CUTSCENE_ITEM_TYPE_CUTSCENE, .cutscene = &TEST_CUTSCENE_ONE },
 };
 static const cutscene_t TEST_CUTSCENE = {
  .items = TEST_CUTSCENE_TWO_ITEMS,
  .itemCount = sizeof(TEST_CUTSCENE_TWO_ITEMS) / sizeof(cutsceneitem_t)
 };
@@ -1,200 +0,0 @@
 /**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "entity.h"
 #include "assert/assert.h"
 #include "util/memory.h"
 #include "time/time.h"
 #include "util/math.h"
 #include "rpg/cutscene/cutscenemode.h"
 #include "rpg/overworld/map.h"
 entity_t ENTITIES[ENTITY_COUNT];
 void entityInit(entity_t *entity, const entitytype_t type) {
  assertNotNull(entity, "Entity pointer cannot be NULL");
  assertTrue(type < ENTITY_TYPE_COUNT, "Invalid entity type");
  assertTrue(type != ENTITY_TYPE_NULL, "Cannot have NULL entity type");
  assertTrue(
    entity >= ENTITIES && entity < ENTITIES + ENTITY_COUNT,
    "Entity pointer is out of bounds"
  );
  memoryZero(entity, sizeof(entity_t));
  entity->id = (uint8_t)(entity - ENTITIES);
  entity->type = type;
  if(ENTITY_CALLBACKS[type].init != NULL) ENTITY_CALLBACKS[type].init(entity);
 }
 void entityUpdate(entity_t *entity) {
  assertNotNull(entity, "Entity pointer cannot be NULL");
  assertTrue(entity->type < ENTITY_TYPE_COUNT, "Invalid entity type");
  assertTrue(entity->type != ENTITY_TYPE_NULL, "Cannot have NULL entity type");
  // What state is the entity in?
  if(entity->animation != ENTITY_ANIM_IDLE) {
    // Entity is mid animation, tick it (down).
    entity->animTime -= TIME.delta;
    if(entity->animTime <= 0) {
      entity->animation = ENTITY_ANIM_IDLE;
      entity->animTime = 0;
    }
    return;
  }
  // Movement code.
  if(
    cutsceneModeIsInputAllowed() &&
    ENTITY_CALLBACKS[entity->type].movement != NULL
  ) {
    ENTITY_CALLBACKS[entity->type].movement(entity);
  }
 }
 void entityTurn(entity_t *entity, const entitydir_t direction) {
  entity->direction = direction;
  entity->animation = ENTITY_ANIM_TURN;
  entity->animTime = ENTITY_ANIM_TURN_DURATION;
 }
 void entityWalk(entity_t *entity, const entitydir_t direction) {
  // TODO: Animation, delay, etc.
  entity->direction = direction;
  // Where are we moving?
  worldpos_t newPos = entity->position;
  {
    worldunits_t relX, relY;
    entityDirGetRelative(direction, &relX, &relY);
    newPos.x += relX;
    newPos.y += relY;
  }
  // Get tile under foot
  tile_t tileCurrent = mapGetTile(entity->position);
  tile_t tileNew = mapGetTile(newPos);
  bool_t fall = false;
  bool_t raise = false;
  // Are we walking up a ramp?
  if(
    tileIsRamp(tileCurrent) &&
    (
      // Can only walk UP the direction the ramp faces.
      (direction+TILE_SHAPE_RAMP_SOUTH) == tileCurrent ||
      // If diagonal ramp, can go up one of two ways only.
      (
        (
          tileCurrent == TILE_SHAPE_RAMP_SOUTHEAST &&
          (direction == ENTITY_DIR_SOUTH || direction == ENTITY_DIR_EAST)
        ) ||
        (
          tileCurrent == TILE_SHAPE_RAMP_SOUTHWEST &&
          (direction == ENTITY_DIR_SOUTH || direction == ENTITY_DIR_WEST)
        ) ||
        (
          tileCurrent == TILE_SHAPE_RAMP_NORTHEAST &&
          (direction == ENTITY_DIR_NORTH || direction == ENTITY_DIR_EAST)
        ) ||
        (
          tileCurrent == TILE_SHAPE_RAMP_NORTHWEST &&
          (direction == ENTITY_DIR_NORTH || direction == ENTITY_DIR_WEST)
        )
      )
    // Must be able to walk up.
    )
  ) {
    tileNew = TILE_SHAPE_NULL;// Force check for ramp above.
    worldpos_t abovePos = newPos;
    abovePos.z += 1;
    tile_t tileAbove = mapGetTile(abovePos);
    if(tileAbove != TILE_SHAPE_NULL && tileIsWalkable(tileAbove)) {
      // We can go up the ramp.
      raise = true;
    }
  } else if(tileNew == TILE_SHAPE_NULL && newPos.z > 0) {
    // Falling down?
    worldpos_t belowPos = newPos;
    belowPos.z -= 1;
    tile_t tileBelow = mapGetTile(belowPos);
    if(
      tileBelow != TILE_SHAPE_NULL &&
      tileIsRamp(tileBelow) &&
      (
        // This handles regular cardinal ramps
        (entityDirGetOpposite(direction)+TILE_SHAPE_RAMP_SOUTH) == tileBelow ||
        // This handles diagonal ramps
        (
          (
            tileBelow == TILE_SHAPE_RAMP_SOUTHEAST &&
            (direction == ENTITY_DIR_NORTH || direction == ENTITY_DIR_WEST)
          ) ||
          (
            tileBelow == TILE_SHAPE_RAMP_SOUTHWEST &&
            (direction == ENTITY_DIR_NORTH || direction == ENTITY_DIR_EAST)
          ) ||
          (
            tileBelow == TILE_SHAPE_RAMP_NORTHEAST &&
            (direction == ENTITY_DIR_SOUTH || direction == ENTITY_DIR_WEST)
          ) ||
          (
            tileBelow == TILE_SHAPE_RAMP_NORTHWEST &&
            (direction == ENTITY_DIR_SOUTH || direction == ENTITY_DIR_EAST)
          )
        )
      )
    ) {
      // We will fall to this tile.
      fall = true;
    }
  }
  // Can we walk here?
  if(!raise && !fall && !tileIsWalkable(tileNew)) return;// Blocked
  // Entity in way?
  entity_t *other = ENTITIES;
  do {
    if(other == entity) continue;
    if(other->type == ENTITY_TYPE_NULL) continue;
    if(!worldPosIsEqual(other->position, newPos)) continue;
    return;// Blocked
  } while(++other, other < &ENTITIES[ENTITY_COUNT]);
  entity->lastPosition = entity->position;
  entity->position = newPos;
  entity->animation = ENTITY_ANIM_WALK;
  entity->animTime = ENTITY_ANIM_WALK_DURATION;// TODO: Running vs walking
  if(raise) {
    entity->position.z += 1;
  } else if(fall) {
    entity->position.z -= 1;
  }
 }
 entity_t * entityGetAt(const worldpos_t position) {
  entity_t *ent = ENTITIES;
  do {
    if(ent->type == ENTITY_TYPE_NULL) continue;
    if(!worldPosIsEqual(ent->position, position)) continue;
    return ent;
  } while(++ent, ent < &ENTITIES[ENTITY_COUNT]);
  return NULL;
 }
 uint8_t entityGetAvailable() {
  entity_t *ent = ENTITIES;
  do {
    if(ent->type == ENTITY_TYPE_NULL) return ent - ENTITIES;
  } while(++ent, ent < &ENTITIES[ENTITY_COUNT]);
  return 0xFF;
 }
@@ -1,77 +0,0 @@
 /**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "entitydir.h"
 #include "entityanim.h"
 #include "entitytype.h"
 #include "npc.h"
 typedef struct map_s map_t;
 typedef struct entity_s {
  uint8_t id;
  entitytype_t type;
  entitytypedata_t data;
  // Movement
  entitydir_t direction;
  worldpos_t position;
  worldpos_t lastPosition;
  entityanim_t animation;
  float_t animTime;
 } entity_t;
 extern entity_t ENTITIES[ENTITY_COUNT];
 /**
 * Initializes an entity structure.
 * 
 * @param entity Pointer to the entity structure to initialize.
 * @param type The type of the entity.
 */
 void entityInit(entity_t *entity, const entitytype_t type);
 /**
 * Updates an entity.
 * 
 * @param entity Pointer to the entity structure to update.
 */
 void entityUpdate(entity_t *entity);
 /**
 * Turn an entity to face a new direction.
 * 
 * @param entity Pointer to the entity to turn.
 * @param direction The direction to face.
 */
 void entityTurn(entity_t *entity, const entitydir_t direction);
 /**
 * Make an entity walk in a direction.
 * 
 * @param entity Pointer to the entity to make walk.
 * @param direction The direction to walk in.
 */
 void entityWalk(entity_t *entity, const entitydir_t direction);
 /**
 * Gets the entity at a specific world position.
 * 
 * @param map Pointer to the map to check.
 * @param pos The world position to check.
 * @return Pointer to the entity at the position, or NULL if none.
 */
 entity_t *entityGetAt(const worldpos_t pos);
 /**
 * Gets an available entity index.
 * 
 * @return The index of an available entity, or 0xFF if none are available.
 */
 uint8_t entityGetAvailable();
@@ -1,18 +0,0 @@
 /**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #pragma once
 #include "dusk.h"
 #define ENTITY_ANIM_TURN_DURATION 0.06f
 #define ENTITY_ANIM_WALK_DURATION 0.1f
 typedef enum {
  ENTITY_ANIM_IDLE,
  ENTITY_ANIM_TURN,
  ENTITY_ANIM_WALK,
 } entityanim_t;
@@ -1,51 +0,0 @@
 /**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */
 #include "entitydir.h"
 #include "assert/assert.h"
 entitydir_t entityDirGetOpposite(const entitydir_t dir) {
  switch(dir) {
    case ENTITY_DIR_NORTH: return ENTITY_DIR_SOUTH;
    case ENTITY_DIR_SOUTH: return ENTITY_DIR_NORTH;
    case ENTITY_DIR_EAST:  return ENTITY_DIR_WEST;
    case ENTITY_DIR_WEST:  return ENTITY_DIR_EAST;
    default: return dir;
  }
 }
 void entityDirGetRelative(
  const entitydir_t from,
  worldunits_t *outX,
  worldunits_t *outY
 ) {
  assertValidEntityDir(from, "Invalid direction provided");
  assertNotNull(outX, "Output X pointer cannot be NULL");
  assertNotNull(outY, "Output Y pointer cannot be NULL");
  switch(from) {
    case ENTITY_DIR_NORTH:
      *outX = 0;
      *outY = -1;
      break;
    case ENTITY_DIR_EAST:
      *outX = 1;
      *outY = 0;
      break;
    case ENTITY_DIR_SOUTH:
      *outX = 0;
      *outY = 1;
      break;
    case ENTITY_DIR_WEST:
      *outX = -1;
      *outY = 0;
      break;
  }
 }
--- a/Show More
+++ b/Show More