chore: release v0.10.1

Dated record timestamps, per-sink timestamp format, and archive names
that keep the extension last (<stem>.<timestamp>.<ext>).

.gitignore

@@ -30,3 +30,4 @@ compile_commands.json
 # local data dumps / RE artifacts
 re-data/
 *.log
+*.log.[0-9]*

.gitlab-ci.yml

@@ -4,61 +4,334 @@ stages:
 
 variables:
   DOCKER_HOST: tcp://docker:2375
-  DOCKER_DRIVER: overlay2
   DOCKER_TLS_CERTDIR: ""
-  # Where to push the dev image. Leave empty to not push at all.
+  DOCKER_BUILDKIT: "1"
-  # Examples: "192.168.1.11:9090/<group>/openra3" or "docker.io/<user>/openra3"
+  # apt mirror used inside both images (override per pipeline if needed)
-  IMAGE_NAME: ""
   APT_MIRROR: "http://mirrors.tuna.tsinghua.edu.cn/ubuntu"
+  # Debian images need the Debian (not Ubuntu) mirror path: the two repos live
+  # under /debian and /debian-security on the same host.
+  DEBIAN_APT_MIRROR: "http://mirrors.tuna.tsinghua.edu.cn/debian"
+  # Images are shared through Harbor (plain HTTP), never as artifacts.
+  HARBOR_HOST: "192.168.1.11:9090"
+  HARBOR_PROJECT: "openra3"
+  IMAGE: "$HARBOR_HOST/$HARBOR_PROJECT/$CI_PROJECT_NAME"
 
-image_build:
+# dind: pull docker.io through the intranet Harbor proxy (plain HTTP ->
+# --insecure-registry) and enable the containerd snapshotter so the *docker*
+# driver can export the registry BuildKit cache (the classic overlay2 driver
+# rejects it). Anchor is an array, so `services: *dind` stays an array.
+.dind: &dind
+  - name: docker:dind
+    command:
+      - --registry-mirror=http://192.168.1.11:9090/dockerhub
+      - --insecure-registry=192.168.1.11:9090
+      - --feature=containerd-snapshotter=true
+
+# Retry helper for transient network failures (login / build / push / pull).
+.retry: &retry
+  - |
+    retry() {
+      n=0
+      until "$@"; do
+        n=$((n + 1))
+        [ "$n" -ge 5 ] && { echo "failed after $n tries: $*" >&2; return 1; }
+        echo "attempt $n failed, retrying: $*" >&2
+        sleep 15
+      done
+    }
+
+# --- build the two isolated toolchain images and push them to Harbor ----------
+linux_image:
   stage: image
   image: docker:latest
-  services:
+  services: *dind
-    - name: docker:dind
-      # Pull docker.io images through the intranet Harbor pull-through cache;
-      # plain HTTP registry, hence --insecure-registry.
-      command:
-        - --registry-mirror=http://192.168.1.11:9090/dockerhub
-        - --insecure-registry=192.168.1.11:9090
-  script:
-    - docker build --target dev -t openra3-dev:local --build-arg APT_MIRROR=$APT_MIRROR .
-    - docker save openra3-dev:local -o dev-image.tar
-    - |
-      if [ -n "$IMAGE_NAME" ]; then
-        # add `docker login` here if IMAGE_NAME points to a private registry
-        docker tag openra3-dev:local $IMAGE_NAME:$CI_COMMIT_SHORT_SHA
-        docker push $IMAGE_NAME:$CI_COMMIT_SHORT_SHA
-      fi
-  artifacts:
-    name: "dev-image-$CI_COMMIT_SHORT_SHA"
-    paths:
-      - dev-image.tar
-    expire_in: 1 day
   tags:
     - docker
+  before_script: *retry
+  script:
+    - retry sh -c 'echo "$HARBOR_PASSWORD" | docker login "$HARBOR_HOST" -u "$HARBOR_USERNAME" --password-stdin'
+    - |
+      retry docker build \
+        --cache-from type=registry,ref=$IMAGE:cache-linux,insecure=true \
+        --cache-to type=registry,ref=$IMAGE:cache-linux,mode=max,insecure=true \
+        --build-arg APT_MIRROR=$APT_MIRROR \
+        --target dev \
+        -t $IMAGE:$CI_COMMIT_SHORT_SHA-linux \
+        -f Dockerfile .
+    - retry docker push $IMAGE:$CI_COMMIT_SHORT_SHA-linux
 
-build_test_package:
+windows_image:
+  stage: image
+  image: docker:latest
+  services: *dind
+  tags:
+    - docker
+  before_script: *retry
+  script:
+    - retry sh -c 'echo "$HARBOR_PASSWORD" | docker login "$HARBOR_HOST" -u "$HARBOR_USERNAME" --password-stdin'
+    - |
+      retry docker build \
+        --cache-from type=registry,ref=$IMAGE:cache-windows,insecure=true \
+        --cache-to type=registry,ref=$IMAGE:cache-windows,mode=max,insecure=true \
+        --build-arg APT_MIRROR=$APT_MIRROR \
+        --target dev \
+        -t $IMAGE:$CI_COMMIT_SHORT_SHA-windows \
+        -f Dockerfile.win .
+    - retry docker push $IMAGE:$CI_COMMIT_SHORT_SHA-windows
+
+# --- build and test each target ----------------------------------------------
+build_linux:
   stage: build
   image: docker:latest
-  services:
+  services: *dind
-    - name: docker:dind
-      command:
-        - --registry-mirror=http://192.168.1.11:9090/dockerhub
-        - --insecure-registry=192.168.1.11:9090
-  needs:
-    - image_build
-  before_script:
-    - docker load -i dev-image.tar
-  script:
-    - docker run --rm -v "$(pwd):/work" -w /work openra3-dev:local cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
-    - docker run --rm -v "$(pwd):/work" -w /work openra3-dev:local cmake --build build -j
-    - docker run --rm -v "$(pwd):/work" -w /work openra3-dev:local ctest --test-dir build --output-on-failure
-    - docker run --rm -v "$(pwd):/work" -w /work openra3-dev:local bash -c "mkdir -p artifacts_bin && cp build/bin/openra3 artifacts_bin/"
-  artifacts:
-    name: "$CI_PROJECT_NAME-executables-$CI_COMMIT_SHORT_SHA"
-    paths:
-      - artifacts_bin/
-    expire_in: 7 days
   tags:
     - docker
+  needs:
+    - linux_image
+  before_script: *retry
+  script:
+    - retry sh -c 'echo "$HARBOR_PASSWORD" | docker login "$HARBOR_HOST" -u "$HARBOR_USERNAME" --password-stdin'
+    - retry docker pull $IMAGE:$CI_COMMIT_SHORT_SHA-linux
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-linux cmake -S . -B build/linux -G Ninja -DCMAKE_BUILD_TYPE=Release -DOPENRA3_DISTRO_TAG=ubuntu26.04
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-linux cmake --build build/linux -j
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-linux ctest --test-dir build/linux --output-on-failure
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-linux bash -c "cd build/linux && cpack -G DEB"
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-linux bash -c "mkdir -p artifacts/linux && cp build/linux/bin/openra3 build/linux/*.deb artifacts/linux/"
+  artifacts:
+    name: "$CI_PROJECT_NAME-linux-$CI_COMMIT_SHORT_SHA"
+    paths:
+      - artifacts/linux/
+    expire_in: 7 days
+
+build_windows:
+  stage: build
+  image: docker:latest
+  services: *dind
+  tags:
+    - docker
+  needs:
+    - windows_image
+  before_script: *retry
+  script:
+    - retry sh -c 'echo "$HARBOR_PASSWORD" | docker login "$HARBOR_HOST" -u "$HARBOR_USERNAME" --password-stdin'
+    - retry docker pull $IMAGE:$CI_COMMIT_SHORT_SHA-windows
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-windows
+        cmake -S . -B build/windows -G Ninja
+          -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/llvm-mingw-x86_64.cmake
+          -DCMAKE_BUILD_TYPE=Release
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-windows cmake --build build/windows -j
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-windows cmake --build build/windows --target openra3_msi
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-windows bash -c "cd build/windows && cpack -G ZIP"
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-windows bash -c "mkdir -p artifacts/windows && cp build/windows/bin/openra3.exe build/windows/bin/SDL3.dll build/windows/bin/*.msi build/windows/*.zip artifacts/windows/"
+  artifacts:
+    name: "$CI_PROJECT_NAME-windows-$CI_COMMIT_SHORT_SHA"
+    paths:
+      - artifacts/windows/
+    expire_in: 7 days
+
+# --- arm64 + Debian toolchain images -----------------------------------------
+linux_arm64_image:
+  stage: image
+  image: docker:latest
+  services: *dind
+  tags:
+    - docker
+  before_script: *retry
+  script:
+    - retry sh -c 'echo "$HARBOR_PASSWORD" | docker login "$HARBOR_HOST" -u "$HARBOR_USERNAME" --password-stdin'
+    - |
+      retry docker build \
+        --cache-from type=registry,ref=$IMAGE:cache-linux-arm64,insecure=true \
+        --cache-to type=registry,ref=$IMAGE:cache-linux-arm64,mode=max,insecure=true \
+        --build-arg APT_MIRROR=$APT_MIRROR \
+        --target dev \
+        -t $IMAGE:$CI_COMMIT_SHORT_SHA-linux-arm64 \
+        -f Dockerfile.linux-arm64 .
+    - retry docker push $IMAGE:$CI_COMMIT_SHORT_SHA-linux-arm64
+
+windows_arm64_image:
+  stage: image
+  image: docker:latest
+  services: *dind
+  tags:
+    - docker
+  before_script: *retry
+  script:
+    - retry sh -c 'echo "$HARBOR_PASSWORD" | docker login "$HARBOR_HOST" -u "$HARBOR_USERNAME" --password-stdin'
+    - |
+      retry docker build \
+        --cache-from type=registry,ref=$IMAGE:cache-windows-arm64,insecure=true \
+        --cache-to type=registry,ref=$IMAGE:cache-windows-arm64,mode=max,insecure=true \
+        --build-arg APT_MIRROR=$APT_MIRROR \
+        --target dev \
+        -t $IMAGE:$CI_COMMIT_SHORT_SHA-windows-arm64 \
+        -f Dockerfile.win-arm64 .
+    - retry docker push $IMAGE:$CI_COMMIT_SHORT_SHA-windows-arm64
+
+debian_image:
+  stage: image
+  image: docker:latest
+  services: *dind
+  tags:
+    - docker
+  before_script: *retry
+  script:
+    - retry sh -c 'echo "$HARBOR_PASSWORD" | docker login "$HARBOR_HOST" -u "$HARBOR_USERNAME" --password-stdin'
+    - |
+      retry docker build \
+        --cache-from type=registry,ref=$IMAGE:cache-debian,insecure=true \
+        --cache-to type=registry,ref=$IMAGE:cache-debian,mode=max,insecure=true \
+        --build-arg APT_MIRROR=$DEBIAN_APT_MIRROR \
+        --target dev \
+        -t $IMAGE:$CI_COMMIT_SHORT_SHA-debian \
+        -f Dockerfile.debian .
+    - retry docker push $IMAGE:$CI_COMMIT_SHORT_SHA-debian
+
+debian_arm64_image:
+  stage: image
+  image: docker:latest
+  services: *dind
+  tags:
+    - docker
+  before_script: *retry
+  script:
+    - retry sh -c 'echo "$HARBOR_PASSWORD" | docker login "$HARBOR_HOST" -u "$HARBOR_USERNAME" --password-stdin'
+    - |
+      retry docker build \
+        --cache-from type=registry,ref=$IMAGE:cache-debian-arm64,insecure=true \
+        --cache-to type=registry,ref=$IMAGE:cache-debian-arm64,mode=max,insecure=true \
+        --build-arg APT_MIRROR=$DEBIAN_APT_MIRROR \
+        --target dev \
+        -t $IMAGE:$CI_COMMIT_SHORT_SHA-debian-arm64 \
+        -f Dockerfile.debian-arm64 .
+    - retry docker push $IMAGE:$CI_COMMIT_SHORT_SHA-debian-arm64
+
+# --- build each target (binary + packages) -----------------------------------
+build_linux_arm64:
+  stage: build
+  image: docker:latest
+  services: *dind
+  tags:
+    - docker
+  needs:
+    - linux_arm64_image
+  before_script: *retry
+  script:
+    - retry sh -c 'echo "$HARBOR_PASSWORD" | docker login "$HARBOR_HOST" -u "$HARBOR_USERNAME" --password-stdin'
+    - retry docker pull $IMAGE:$CI_COMMIT_SHORT_SHA-linux-arm64
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-linux-arm64 cmake -S . -B build/linux-arm64 -G Ninja -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/clang-aarch64-linux-gnu.cmake -DCMAKE_BUILD_TYPE=Release -DOPENRA3_DISTRO_TAG=ubuntu26.04
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-linux-arm64 cmake --build build/linux-arm64 -j
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-linux-arm64 bash -c "cd build/linux-arm64 && cpack -G DEB"
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-linux-arm64 bash -c "mkdir -p artifacts/linux-arm64 && cp build/linux-arm64/bin/openra3 build/linux-arm64/*.deb artifacts/linux-arm64/"
+  artifacts:
+    name: "$CI_PROJECT_NAME-linux-arm64-$CI_COMMIT_SHORT_SHA"
+    paths:
+      - artifacts/linux-arm64/
+    expire_in: 7 days
+
+build_windows_arm64:
+  stage: build
+  image: docker:latest
+  services: *dind
+  tags:
+    - docker
+  needs:
+    - windows_arm64_image
+  before_script: *retry
+  script:
+    - retry sh -c 'echo "$HARBOR_PASSWORD" | docker login "$HARBOR_HOST" -u "$HARBOR_USERNAME" --password-stdin'
+    - retry docker pull $IMAGE:$CI_COMMIT_SHORT_SHA-windows-arm64
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-windows-arm64 cmake -S . -B build/windows-arm64 -G Ninja -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/llvm-mingw-aarch64.cmake -DCMAKE_BUILD_TYPE=Release
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-windows-arm64 cmake --build build/windows-arm64 -j
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-windows-arm64 bash -c "cd build/windows-arm64 && cpack -G ZIP"
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-windows-arm64 bash -c "mkdir -p artifacts/windows-arm64 && cp build/windows-arm64/bin/openra3.exe build/windows-arm64/bin/SDL3.dll build/windows-arm64/*.zip artifacts/windows-arm64/"
+  artifacts:
+    name: "$CI_PROJECT_NAME-windows-arm64-$CI_COMMIT_SHORT_SHA"
+    paths:
+      - artifacts/windows-arm64/
+    expire_in: 7 days
+
+build_debian:
+  stage: build
+  image: docker:latest
+  services: *dind
+  tags:
+    - docker
+  needs:
+    - debian_image
+  before_script: *retry
+  script:
+    - retry sh -c 'echo "$HARBOR_PASSWORD" | docker login "$HARBOR_HOST" -u "$HARBOR_USERNAME" --password-stdin'
+    - retry docker pull $IMAGE:$CI_COMMIT_SHORT_SHA-debian
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-debian cmake -S . -B build/debian -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_STDLIB_MODULES_JSON=/usr/lib/llvm-19/lib/libc++.modules.json -DOPENRA3_DISTRO_TAG=debian13
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-debian cmake --build build/debian -j
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-debian ctest --test-dir build/debian --output-on-failure
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-debian bash -c "cd build/debian && cpack -G DEB"
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-debian bash -c "mkdir -p artifacts/debian && cp build/debian/bin/openra3 build/debian/*.deb artifacts/debian/"
+  artifacts:
+    name: "$CI_PROJECT_NAME-debian-$CI_COMMIT_SHORT_SHA"
+    paths:
+      - artifacts/debian/
+    expire_in: 7 days
+
+build_debian_arm64:
+  stage: build
+  image: docker:latest
+  services: *dind
+  tags:
+    - docker
+  needs:
+    - debian_arm64_image
+  before_script: *retry
+  script:
+    - retry sh -c 'echo "$HARBOR_PASSWORD" | docker login "$HARBOR_HOST" -u "$HARBOR_USERNAME" --password-stdin'
+    - retry docker pull $IMAGE:$CI_COMMIT_SHORT_SHA-debian-arm64
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-debian-arm64 cmake -S . -B build/debian-arm64 -G Ninja -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/clang-aarch64-linux-gnu.cmake -DCMAKE_BUILD_TYPE=Release -DOPENRA3_AARCH64_CC=clang-19 -DOPENRA3_AARCH64_CXX=clang++-19 -DOPENRA3_AARCH64_STDLIB_MODULES_JSON=/usr/lib/llvm-19/lib/libc++.modules.json -DOPENRA3_DISTRO_TAG=debian13
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-debian-arm64 cmake --build build/debian-arm64 -j
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-debian-arm64 bash -c "cd build/debian-arm64 && cpack -G DEB"
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-debian-arm64 bash -c "mkdir -p artifacts/debian-arm64 && cp build/debian-arm64/bin/openra3 build/debian-arm64/*.deb artifacts/debian-arm64/"
+  artifacts:
+    name: "$CI_PROJECT_NAME-debian-arm64-$CI_COMMIT_SHORT_SHA"
+    paths:
+      - artifacts/debian-arm64/
+    expire_in: 7 days
+# --- WebAssembly (Emscripten) -------------------------------------------------
+wasm_image:
+  stage: image
+  image: docker:latest
+  services: *dind
+  tags:
+    - docker
+  before_script: *retry
+  script:
+    - retry sh -c 'echo "$HARBOR_PASSWORD" | docker login "$HARBOR_HOST" -u "$HARBOR_USERNAME" --password-stdin'
+    - |
+      retry docker build \
+        --cache-from type=registry,ref=$IMAGE:cache-wasm,insecure=true \
+        --cache-to type=registry,ref=$IMAGE:cache-wasm,mode=max,insecure=true \
+        --build-arg APT_MIRROR=$APT_MIRROR \
+        --target dev \
+        -t $IMAGE:$CI_COMMIT_SHORT_SHA-wasm \
+        -f Dockerfile.wasm .
+    - retry docker push $IMAGE:$CI_COMMIT_SHORT_SHA-wasm
+
+build_wasm:
+  stage: build
+  image: docker:latest
+  services: *dind
+  tags:
+    - docker
+  needs:
+    - wasm_image
+  before_script: *retry
+  script:
+    - retry sh -c 'echo "$HARBOR_PASSWORD" | docker login "$HARBOR_HOST" -u "$HARBOR_USERNAME" --password-stdin'
+    - retry docker pull $IMAGE:$CI_COMMIT_SHORT_SHA-wasm
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-wasm cmake -S . -B build/wasm -G Ninja -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/emscripten-wasm.cmake -DCMAKE_BUILD_TYPE=Release
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-wasm cmake --build build/wasm -j
+    - docker run --rm -v "$(pwd):/work" -w /work $IMAGE:$CI_COMMIT_SHORT_SHA-wasm bash -c "mkdir -p artifacts/wasm && cp build/wasm/bin/index.html build/wasm/bin/openra3.js build/wasm/bin/openra3.wasm build/wasm/bin/openra3.worker.js artifacts/wasm/ && cp build/wasm/bin/openra3.data artifacts/wasm/ 2>/dev/null || true"
+  artifacts:
+    name: "$CI_PROJECT_NAME-wasm-$CI_COMMIT_SHORT_SHA"
+    paths:
+      - artifacts/wasm/
+    expire_in: 7 days

CMakeLists.txt

@@ -1,10 +1,32 @@
-cmake_minimum_required(VERSION 3.28)
+cmake_minimum_required(VERSION 3.30)
 
-project(OpenRA3 VERSION 0.0.1 LANGUAGES CXX)
+# --- C++26 modules + `import std;` (clang + libc++) -------------------------
+# CMake gates `import std` behind an experimental value documented in
+# Help/dev/experimental.rst for the CMake version in use.
+set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD "d0edc3af-4c50-42ea-a356-e2862fe7a444")
 
+# Path to the standard-library module description. A cross toolchain overrides
+# this before the compiler is probed; this default targets the Linux LLVM
+# package. Skipped for Emscripten, whose toolchain supplies its own sysroot
+# modules.json.
+if(NOT CMAKE_CXX_STDLIB_MODULES_JSON AND NOT DEFINED ENV{EMSDK})
+    set(CMAKE_CXX_STDLIB_MODULES_JSON "/usr/lib/llvm-21/lib/libc++.modules.json")
+endif()
+
+# libc++ must be selected before the compiler is probed: CMake builds its
+# internal standard-library module target during `project()`, and that target
+# only sees `CMAKE_CXX_FLAGS` (not later `add_compile_options`). The standard
+# and extension settings must also be in place before `project()` so the
+# internal `std.pcm` is built with the same configuration as our modules.
+set(CMAKE_CXX_FLAGS_INIT "-stdlib=libc++")
+set(CMAKE_EXE_LINKER_FLAGS_INIT "-stdlib=libc++")
+set(CMAKE_SHARED_LINKER_FLAGS_INIT "-stdlib=libc++")
 set(CMAKE_CXX_STANDARD 26)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
+set(CMAKE_CXX_SCAN_FOR_MODULES ON)
+
+project(OpenRA3 VERSION 0.9.0 LANGUAGES C CXX)
 
 if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
     set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type" FORCE)
@@ -14,124 +36,578 @@ set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
 
 option(OPENRA3_WERROR "Treat warnings as errors" OFF)
 
+# Windows: statically link the C++ runtime (libc++, libunwind) so the .exe only
+# needs SDL3.dll next to it at runtime.
+if(WIN32)
+    add_link_options(-static)
+endif()
+
 function(openra3_target_defaults target)
-    target_compile_options(${target} PRIVATE -Wall -Wextra -Wpedantic)
+    target_compile_options(${target} PRIVATE -Wall -Wextra)
+    set_property(TARGET ${target} PROPERTY CXX_MODULE_STD ON)
     if(OPENRA3_WERROR)
         target_compile_options(${target} PRIVATE -Werror)
     endif()
 endfunction()
 
-# --- engine core: fundamental types, math, strings, random, message stream ---
+# --- SDL3: pkg-config on Linux, or an explicit MinGW root for Windows --------
+add_library(openra3_sdl3 INTERFACE)
+set(OPENRA3_HAS_SDL3 OFF)
+# The triple-named subdirectory inside a MinGW SDL3 development package
+# (`<root>/<triple>/{include,lib,bin}`); x86_64 unless a toolchain overrides it.
+set(OPENRA3_SDL3_MINGW_TRIPLE "x86_64-w64-mingw32" CACHE STRING "SDL3 MinGW triple subdirectory")
+if(EMSCRIPTEN)
+    # The wasm build runs the engine on a Web Worker and renders into an
+    # OffscreenCanvas (ra3.webgpu / ra3.wasmgl), so it links no SDL: SDL3's
+    # Emscripten port is main-thread DOM only and cannot run in a worker.
+elseif(OPENRA3_SDL3_ROOT)
+    target_include_directories(openra3_sdl3 INTERFACE "${OPENRA3_SDL3_ROOT}/${OPENRA3_SDL3_MINGW_TRIPLE}/include")
+    target_link_libraries(openra3_sdl3 INTERFACE "${OPENRA3_SDL3_ROOT}/${OPENRA3_SDL3_MINGW_TRIPLE}/lib/libSDL3.dll.a")
+    set(OPENRA3_HAS_SDL3 ON)
+else()
+    find_package(PkgConfig QUIET)
+    if(PkgConfig_FOUND)
+        pkg_check_modules(SDL3 QUIET IMPORTED_TARGET sdl3)
+    endif()
+    if(SDL3_FOUND)
+        target_link_libraries(openra3_sdl3 INTERFACE PkgConfig::SDL3)
+        set(OPENRA3_HAS_SDL3 ON)
+    endif()
+endif()
+if(OPENRA3_HAS_SDL3)
+    message(STATUS "OpenRA3: SDL3 found - windowed viewer enabled")
+else()
+    message(STATUS "OpenRA3: SDL3 not found - offscreen BMP output only")
+endif()
+
+# --- Vulkan: vendored volk + headers, so no Vulkan SDK is needed ---------------
+# The loader is resolved at runtime (volk dlopen/LoadLibrary), which lets the
+# same source build the Vulkan backend on Linux and on the MinGW Windows target.
+# WebAssembly has no Vulkan, so the viewer is off there (the null backend).
+if(EMSCRIPTEN)
+    set(OPENRA3_VULKAN_DEFAULT OFF)
+else()
+    set(OPENRA3_VULKAN_DEFAULT ON)
+endif()
+option(OPENRA3_VULKAN "Build the Vulkan viewer" ${OPENRA3_VULKAN_DEFAULT})
+set(OPENRA3_HAS_VULKAN OFF)
+if(OPENRA3_VULKAN AND OPENRA3_HAS_SDL3 AND NOT EMSCRIPTEN)
+    set(OPENRA3_HAS_VULKAN ON)
+endif()
+if(OPENRA3_HAS_VULKAN)
+    message(STATUS "OpenRA3: Vulkan viewer enabled (vendored volk)")
+else()
+    message(STATUS "OpenRA3: Vulkan viewer disabled - offscreen image only")
+endif()
+
+if(NOT EMSCRIPTEN)
+    add_library(ra3_volk STATIC third_party/volk/volk.c)
+    target_include_directories(ra3_volk PUBLIC third_party/volk third_party/vulkan/include)
+    target_compile_definitions(ra3_volk PUBLIC VK_NO_PROTOTYPES)
+endif()
+
+# Embed the committed SPIR-V blobs into a generated header at configure time.
+# Regenerate with shaders/compile.sh after editing a .vert/.frag.
+function(openra3_embed_spirv out_header)
+    set(content "// Generated by CMake from shaders/generated/*.spv.\n")
+    string(APPEND content "#pragma once\n#include <cstddef>\n#include <cstdint>\n\nnamespace ra3_shaders {\n")
+    foreach(spv IN LISTS ARGN)
+        if(NOT EXISTS "${spv}")
+            message(FATAL_ERROR "Missing precompiled shader ${spv}; run shaders/compile.sh")
+        endif()
+        get_filename_component(base "${spv}" NAME)
+        string(MAKE_C_IDENTIFIER "${base}" ident)
+        file(READ "${spv}" hex HEX)
+        string(LENGTH "${hex}" hexlen)
+        math(EXPR words "${hexlen} / 8")
+        string(REGEX REPLACE "(..)(..)(..)(..)" "0x\\4\\3\\2\\1," words_list "${hex}")
+        string(APPEND content "inline constexpr std::uint32_t ${ident}[] = {${words_list}};\n")
+        string(APPEND content "inline constexpr std::size_t ${ident}_words = ${words};\n\n")
+    endforeach()
+    string(APPEND content "} // namespace ra3_shaders\n")
+    file(WRITE "${out_header}" "${content}")
+endfunction()
+
+# Embed the HLSL sources as string literals. The Direct3D backends compile them
+# at runtime with d3dcompiler_47, so no HLSL compiler is needed at build time
+# (the Windows target cross-compiles from Linux).
+function(openra3_embed_hlsl out_header)
+    set(content "// Generated by CMake from shaders/*.hlsl.\n")
+    string(APPEND content "#pragma once\n\nnamespace ra3_shaders {\n")
+    foreach(src IN LISTS ARGN)
+        if(NOT EXISTS "${src}")
+            message(FATAL_ERROR "Missing HLSL shader ${src}")
+        endif()
+        get_filename_component(base "${src}" NAME_WE)
+        string(MAKE_C_IDENTIFIER "${base}" ident)
+        string(APPEND ident "_hlsl")
+        file(READ "${src}" text)
+        string(APPEND content "inline constexpr const char ${ident}[] = R\"RA3HLSL(${text})RA3HLSL\";\n\n")
+    endforeach()
+    string(APPEND content "} // namespace ra3_shaders\n")
+    file(WRITE "${out_header}" "${content}")
+endfunction()
+
+# Embed the GLSL ES sources for the WebGL backend as string literals (compiled
+# at runtime by the browser's GL, like the HLSL for Direct3D).
+function(openra3_embed_glsl out_header)
+    set(content "// Generated by CMake from shaders/*.glsl.\n")
+    string(APPEND content "#pragma once\n\nnamespace ra3_shaders {\n")
+    foreach(src IN LISTS ARGN)
+        if(NOT EXISTS "${src}")
+            message(FATAL_ERROR "Missing GLSL shader ${src}")
+        endif()
+        get_filename_component(base "${src}" NAME_WE)
+        string(MAKE_C_IDENTIFIER "${base}" ident)
+        string(APPEND ident "_glsl")
+        file(READ "${src}" text)
+        string(APPEND content "inline constexpr const char ${ident}[] = R\"RA3GLSL(${text})RA3GLSL\";\n\n")
+    endforeach()
+    string(APPEND content "} // namespace ra3_shaders\n")
+    file(WRITE "${out_header}" "${content}")
+endfunction()
+
+# Embed the WGSL sources for the WebGPU backend as string literals (compiled at
+# runtime by the browser's WebGPU, like the GLSL/HLSL for the other backends).
+function(openra3_embed_wgsl out_header)
+    set(content "// Generated by CMake from shaders/*.wgsl.\n")
+    string(APPEND content "#pragma once\n\nnamespace ra3_shaders {\n")
+    foreach(src IN LISTS ARGN)
+        if(NOT EXISTS "${src}")
+            message(FATAL_ERROR "Missing WGSL shader ${src}")
+        endif()
+        get_filename_component(base "${src}" NAME_WE)
+        string(MAKE_C_IDENTIFIER "${base}" ident)
+        string(APPEND ident "_wgsl")
+        file(READ "${src}" text)
+        string(APPEND content "inline constexpr const char ${ident}[] = R\"RA3WGSL(${text})RA3WGSL\";\n\n")
+    endforeach()
+    string(APPEND content "} // namespace ra3_shaders\n")
+    file(WRITE "${out_header}" "${content}")
+endfunction()
+
+# --- logging (vendored libenderlog, MIT) -------------------------------------
+# A standalone C++26 module logger (`import ender.log;`) with a per-run
+# archiving file sink. libc++ has no <stacktrace>, so on this toolchain the
+# module records call sites but no stacks; it defaults ENDERLOG_HAS_STACKTRACE
+# to 0 without any define.
+add_library(ra3_enderlog STATIC)
+target_sources(ra3_enderlog PUBLIC FILE_SET CXX_MODULES FILES third_party/libenderlog/src/ender.log.cppm)
+target_compile_features(ra3_enderlog PUBLIC cxx_std_26)
+openra3_target_defaults(ra3_enderlog)
+
+# --- RA3 built-in asset containers (vendored libra3assets) --------------------
+# Reader/writer for the files the retail game ships: `BIG4` archives, the EA
+# RefPack codec, SAGE `.csf` string tables and `.map` (`CkMp`) containers, plus
+# the compiled `BinaryAsset` streams. A sibling of libenderlog: C++26 modules
+# (`import ra3.assets;`) importing the standard library. It owns the on-disk
+# format knowledge, so `ra3.fs` / `ra3.map` / `ra3.terrain` become thin adapters.
+add_library(ra3_assets STATIC)
+target_sources(ra3_assets PUBLIC FILE_SET CXX_MODULES FILES
+    third_party/libra3assets/src/assets.cppm
+    third_party/libra3assets/src/error.cppm
+    third_party/libra3assets/src/bytes.cppm
+    third_party/libra3assets/src/refpack.cppm
+    third_party/libra3assets/src/big.cppm
+    third_party/libra3assets/src/binary.cppm
+    third_party/libra3assets/src/csf.cppm
+    third_party/libra3assets/src/map.cppm)
+target_compile_features(ra3_assets PUBLIC cxx_std_26)
+openra3_target_defaults(ra3_assets)
+
+# --- engine core -------------------------------------------------------------
 add_library(ra3_core STATIC)
-target_sources(ra3_core
+target_sources(ra3_core PUBLIC FILE_SET CXX_MODULES FILES src/core/ra3.core.cppm)
-    PUBLIC FILE_SET CXX_MODULES FILES
-        src/core/ra3.core.cppm
-)
 openra3_target_defaults(ra3_core)
 
-# --- game logic: objects, players, teams, spatial partition, game loop ---
+# --- game logic --------------------------------------------------------------
 add_library(ra3_logic STATIC)
-target_sources(ra3_logic
+target_sources(ra3_logic PUBLIC FILE_SET CXX_MODULES FILES src/logic/ra3.logic.cppm)
-    PUBLIC FILE_SET CXX_MODULES FILES
-        src/logic/ra3.logic.cppm
-)
 target_link_libraries(ra3_logic PUBLIC ra3_core)
 openra3_target_defaults(ra3_logic)
 
-# --- client: headless display/input abstraction and the client facade ---
+# --- RA3 gameplay data (real balance) ----------------------------------------
+add_library(ra3_data STATIC)
+target_sources(ra3_data PUBLIC FILE_SET CXX_MODULES FILES src/data/ra3.data.cppm)
+target_link_libraries(ra3_data PUBLIC ra3_core)
+openra3_target_defaults(ra3_data)
+
+# --- client ------------------------------------------------------------------
 add_library(ra3_client STATIC)
-target_sources(ra3_client
+target_sources(ra3_client PUBLIC FILE_SET CXX_MODULES FILES src/client/ra3.client.cppm)
-    PUBLIC FILE_SET CXX_MODULES FILES
-        src/client/ra3.client.cppm
-)
 target_link_libraries(ra3_client PUBLIC ra3_core ra3_logic)
 openra3_target_defaults(ra3_client)
 
-# --- RA3 game definitions: factions, player templates, science, special powers ---
+# --- RA3 game definitions ----------------------------------------------------
 add_library(ra3_game STATIC)
-target_sources(ra3_game
+target_sources(ra3_game PUBLIC FILE_SET CXX_MODULES FILES src/game/ra3.game.cppm)
-    PUBLIC FILE_SET CXX_MODULES FILES
-        src/game/ra3.game.cppm
-)
 target_link_libraries(ra3_game PUBLIC ra3_core ra3_logic)
 openra3_target_defaults(ra3_game)
 
-# --- filesystem: BIG4 archives, RefPack codec, local install locator ---
+# --- filesystem: BIG4 + RefPack (adapter over libra3assets) -------------------
 add_library(ra3_fs STATIC)
-target_sources(ra3_fs
+target_sources(ra3_fs PUBLIC FILE_SET CXX_MODULES FILES src/fs/ra3.fs.cppm)
-    PUBLIC FILE_SET CXX_MODULES FILES
+target_link_libraries(ra3_fs PUBLIC ra3_core ra3_assets)
-        src/fs/ra3.fs.cppm
-)
-target_link_libraries(ra3_fs PUBLIC ra3_core)
 openra3_target_defaults(ra3_fs)
 
-# --- map discovery/loading (real .big data, user's local install) ---
+# --- map discovery/loading ---------------------------------------------------
 add_library(ra3_map STATIC)
-target_sources(ra3_map
+target_sources(ra3_map PUBLIC FILE_SET CXX_MODULES FILES src/map/ra3.map.cppm)
-    PUBLIC FILE_SET CXX_MODULES FILES
+target_link_libraries(ra3_map PUBLIC ra3_core ra3_fs ra3_assets)
-        src/map/ra3.map.cppm
-)
-target_link_libraries(ra3_map PUBLIC ra3_core ra3_fs)
 openra3_target_defaults(ra3_map)
 
-# --- minimal headless skirmish simulation ---
+# --- minimal skirmish simulation --------------------------------------------
 add_library(ra3_skirmish STATIC)
-target_sources(ra3_skirmish
+target_sources(ra3_skirmish PUBLIC FILE_SET CXX_MODULES FILES src/skirmish/ra3.skirmish.cppm)
-    PUBLIC FILE_SET CXX_MODULES FILES
+target_link_libraries(ra3_skirmish PUBLIC ra3_core ra3_logic ra3_game ra3_data ra3_map)
-        src/skirmish/ra3.skirmish.cppm
-)
-target_link_libraries(ra3_skirmish PUBLIC ra3_core ra3_logic ra3_game ra3_map)
 openra3_target_defaults(ra3_skirmish)
 
-# --- software renderer: framebuffer, TGA decode, BMP encode, map compositing ---
+# --- software renderer -------------------------------------------------------
 add_library(ra3_render STATIC)
-target_sources(ra3_render
+target_sources(ra3_render PUBLIC FILE_SET CXX_MODULES FILES src/render/ra3.render.cppm)
-    PUBLIC FILE_SET CXX_MODULES FILES
-        src/render/ra3.render.cppm
-)
 target_link_libraries(ra3_render PUBLIC ra3_core)
 openra3_target_defaults(ra3_render)
 
-# --- windowed viewer: SDL3 when available, otherwise a null backend ---
+# --- real map terrain (HeightMapData / BlendTileData) ------------------------
-find_package(PkgConfig QUIET)
+add_library(ra3_terrain STATIC)
-if(PkgConfig_FOUND)
+target_sources(ra3_terrain PUBLIC FILE_SET CXX_MODULES FILES src/terrain/ra3.terrain.cppm)
-    pkg_check_modules(SDL3 QUIET IMPORTED_TARGET sdl3)
+target_link_libraries(ra3_terrain PUBLIC ra3_core ra3_fs ra3_render ra3_assets)
-endif()
+openra3_target_defaults(ra3_terrain)
+
+# --- map static art (compiled W3D meshes) ------------------------------------
+add_library(ra3_models STATIC)
+target_sources(ra3_models PUBLIC FILE_SET CXX_MODULES FILES src/models/ra3.models.cppm)
+target_link_libraries(ra3_models PUBLIC ra3_core ra3_fs ra3_render)
+openra3_target_defaults(ra3_models)
+
+# A map's terrain carries the objects placed on it (props/buildings).
+target_link_libraries(ra3_terrain PUBLIC ra3_models)
+
+# The presentation facade imports render + terrain (for the terrain capability).
+target_link_libraries(ra3_client PUBLIC ra3_render ra3_terrain)
+
+# --- windowed viewer (SDL3 or null) -----------------------------------------
 add_library(ra3_ui STATIC)
-if(SDL3_FOUND)
+if(OPENRA3_HAS_SDL3)
-    target_sources(ra3_ui
+    target_sources(ra3_ui PUBLIC FILE_SET CXX_MODULES FILES src/ui/ra3.ui.sdl.cppm)
-        PUBLIC FILE_SET CXX_MODULES FILES
+    target_link_libraries(ra3_ui PUBLIC ra3_core ra3_render ra3_client openra3_sdl3)
-            src/ui/ra3.ui.sdl.cppm
-    )
-    target_link_libraries(ra3_ui PUBLIC ra3_core ra3_render PkgConfig::SDL3)
-    message(STATUS "OpenRA3: SDL3 ${SDL3_VERSION} found - windowed viewer enabled")
 else()
-    target_sources(ra3_ui
+    target_sources(ra3_ui PUBLIC FILE_SET CXX_MODULES FILES src/ui/ra3.ui.null.cppm)
-        PUBLIC FILE_SET CXX_MODULES FILES
+    target_link_libraries(ra3_ui PUBLIC ra3_core ra3_render ra3_client)
-            src/ui/ra3.ui.null.cppm
-    )
-    target_link_libraries(ra3_ui PUBLIC ra3_core ra3_render)
-    message(STATUS "OpenRA3: SDL3 not found - offscreen BMP output only")
 endif()
 openra3_target_defaults(ra3_ui)
 
-# --- umbrella module re-exporting the whole SDK ---
+# --- Vulkan viewer (SDL3 surface + Vulkan, or null fallback) ------------------
+add_library(ra3_vulkan STATIC)
+if(OPENRA3_HAS_VULKAN AND OPENRA3_HAS_SDL3)
+    openra3_embed_spirv(
+        "${CMAKE_CURRENT_BINARY_DIR}/generated/shaders_embedded.hpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/generated/scene.vert.spv"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/generated/scene.frag.spv"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/generated/terrain.vert.spv"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/generated/terrain.frag.spv"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/generated/object.vert.spv"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/generated/object.frag.spv"
+    )
+    # The blobs are read at configure time, so re-run CMake when they change.
+    set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/generated/scene.vert.spv"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/generated/scene.frag.spv"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/generated/terrain.vert.spv"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/generated/terrain.frag.spv"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/generated/object.vert.spv"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/generated/object.frag.spv")
+    target_sources(ra3_vulkan PUBLIC FILE_SET CXX_MODULES FILES src/vulkan/ra3.vulkan.sdl.cppm)
+    target_include_directories(ra3_vulkan PRIVATE "${CMAKE_CURRENT_BINARY_DIR}/generated")
+    target_link_libraries(ra3_vulkan PUBLIC ra3_core ra3_render ra3_terrain ra3_client openra3_sdl3 ra3_volk)
+else()
+    target_sources(ra3_vulkan PUBLIC FILE_SET CXX_MODULES FILES src/vulkan/ra3.vulkan.null.cppm)
+    target_link_libraries(ra3_vulkan PUBLIC ra3_core ra3_render ra3_client)
+endif()
+openra3_target_defaults(ra3_vulkan)
+
+# --- Direct3D viewer (D3D11 + D3D12, or null fallback) ------------------------
+# Direct3D is Windows-only, so the real backends build only for the MinGW target;
+# every other platform links the `ra3.dx.null` fallback that fails `init` cleanly.
+option(OPENRA3_DX "Build the Direct3D 11/12 viewer" ON)
+set(OPENRA3_HAS_DX OFF)
+if(OPENRA3_DX AND WIN32 AND OPENRA3_HAS_SDL3)
+    set(OPENRA3_HAS_DX ON)
+endif()
+if(OPENRA3_HAS_DX)
+    message(STATUS "OpenRA3: Direct3D 11/12 viewer enabled (runtime HLSL via d3dcompiler)")
+else()
+    message(STATUS "OpenRA3: Direct3D viewer disabled - offscreen image only")
+endif()
+add_library(ra3_dx STATIC)
+if(OPENRA3_HAS_DX)
+    openra3_embed_hlsl(
+        "${CMAKE_CURRENT_BINARY_DIR}/generated/dx_shaders_embedded.hpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/dx_scene.hlsl"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/dx_terrain.hlsl"
+    )
+    set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/dx_scene.hlsl"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/dx_terrain.hlsl")
+    target_sources(ra3_dx PUBLIC FILE_SET CXX_MODULES FILES src/dx/ra3.dx.cppm)
+    target_include_directories(ra3_dx PRIVATE "${CMAKE_CURRENT_BINARY_DIR}/generated")
+    target_link_libraries(ra3_dx PUBLIC ra3_core ra3_render ra3_terrain ra3_client ra3_enderlog openra3_sdl3 d3d11 d3d12 dxgi d3dcompiler)
+else()
+    target_sources(ra3_dx PUBLIC FILE_SET CXX_MODULES FILES src/dx/ra3.dx.null.cppm)
+    target_link_libraries(ra3_dx PUBLIC ra3_core ra3_render ra3_client)
+endif()
+openra3_target_defaults(ra3_dx)
+
+# --- wasm worker viewer (SDL-free OffscreenCanvas + WebGL2, or null fallback) --
+# The default wasm backend: the engine runs on a plain Web Worker and renders
+# into an OffscreenCanvas transferred from the page, with no SDL. Non-wasm builds
+# link the null stub (init fails, so desktop backends are unaffected).
+option(OPENRA3_WASMGL "Build the SDL-free wasm worker viewer (Emscripten)" ON)
+set(OPENRA3_HAS_WASMGL OFF)
+if(OPENRA3_WASMGL AND EMSCRIPTEN)
+    set(OPENRA3_HAS_WASMGL ON)
+endif()
+add_library(ra3_wasmgl STATIC)
+if(OPENRA3_HAS_WASMGL)
+    message(STATUS "OpenRA3: SDL-free wasm worker viewer enabled")
+    openra3_embed_glsl(
+        "${CMAKE_CURRENT_BINARY_DIR}/generated/wasmgl_glsl_embedded.hpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/webgl_scene_vert.glsl"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/webgl_scene_frag.glsl"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/webgl_terrain_vert.glsl"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/webgl_terrain_frag.glsl"
+    )
+    set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/webgl_scene_vert.glsl"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/webgl_scene_frag.glsl"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/webgl_terrain_vert.glsl"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/webgl_terrain_frag.glsl")
+    target_sources(ra3_wasmgl PUBLIC FILE_SET CXX_MODULES FILES src/wasmgl/ra3.wasmgl.cppm)
+    target_include_directories(ra3_wasmgl PRIVATE "${CMAKE_CURRENT_BINARY_DIR}/generated")
+    target_link_libraries(ra3_wasmgl PUBLIC ra3_core ra3_render ra3_terrain ra3_client ra3_enderlog)
+    # Target WebGL2 so GLES3-only entry points (glTexImage3D, VAOs, ...) link.
+    target_link_options(ra3_wasmgl PUBLIC -sMIN_WEBGL_VERSION=2 -sMAX_WEBGL_VERSION=2)
+else()
+    message(STATUS "OpenRA3: SDL-free wasm worker viewer disabled (non-wasm) - null backend")
+    target_sources(ra3_wasmgl PUBLIC FILE_SET CXX_MODULES FILES src/wasmgl/ra3.wasmgl.null.cppm)
+    target_link_libraries(ra3_wasmgl PUBLIC ra3_core ra3_render ra3_client)
+endif()
+openra3_target_defaults(ra3_wasmgl)
+
+# --- wasm WebGPU viewer (Dawn emdawnwebgpu, or null fallback) ------------------
+# A peer of ra3.wasmgl in the same Web Worker; web WebGPU is WGSL-only, so it has
+# its own WGSL shaders (the Vulkan SPIR-V blobs cannot be used on the web). The
+# `--use-port=emdawnwebgpu` port is downloaded/cached by Emscripten and linked
+# into the final module.
+option(OPENRA3_WEBGPU "Build the WebGPU wasm viewer (Emscripten emdawnwebgpu)" ON)
+set(OPENRA3_HAS_WEBGPU OFF)
+if(OPENRA3_WEBGPU AND EMSCRIPTEN)
+    set(OPENRA3_HAS_WEBGPU ON)
+endif()
+add_library(ra3_webgpu STATIC)
+if(OPENRA3_HAS_WEBGPU)
+    message(STATUS "OpenRA3: WebGPU wasm viewer enabled (emdawnwebgpu)")
+    openra3_embed_wgsl(
+        "${CMAKE_CURRENT_BINARY_DIR}/generated/webgpu_wgsl_embedded.hpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/webgpu_scene.wgsl"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/webgpu_terrain.wgsl"
+    )
+    set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/webgpu_scene.wgsl"
+        "${CMAKE_CURRENT_SOURCE_DIR}/shaders/webgpu_terrain.wgsl")
+    target_sources(ra3_webgpu PUBLIC FILE_SET CXX_MODULES FILES src/webgpu/ra3.webgpu.cppm)
+    target_include_directories(ra3_webgpu PRIVATE "${CMAKE_CURRENT_BINARY_DIR}/generated")
+    # CMake's module dependency scanner does not process `--use-port`, so point
+    # the include path at the (image-baked) port package explicitly.
+    set(OPENRA3_EMDAWNWEBGPU_DIR "$ENV{EMSDK}/upstream/emscripten/cache/ports/emdawnwebgpu/emdawnwebgpu_pkg")
+    target_include_directories(ra3_webgpu SYSTEM PRIVATE
+        "${OPENRA3_EMDAWNWEBGPU_DIR}/webgpu_cpp/include"
+        "${OPENRA3_EMDAWNWEBGPU_DIR}/webgpu/include")
+    target_compile_options(ra3_webgpu PUBLIC --use-port=emdawnwebgpu)
+    target_link_options(ra3_webgpu PUBLIC --use-port=emdawnwebgpu)
+    target_link_libraries(ra3_webgpu PUBLIC ra3_core ra3_render ra3_terrain ra3_client ra3_wasmgl ra3_enderlog)
+else()
+    message(STATUS "OpenRA3: WebGPU wasm viewer disabled (non-wasm) - null backend")
+    target_sources(ra3_webgpu PUBLIC FILE_SET CXX_MODULES FILES src/webgpu/ra3.webgpu.null.cppm)
+    target_link_libraries(ra3_webgpu PUBLIC ra3_core ra3_render ra3_client)
+endif()
+openra3_target_defaults(ra3_webgpu)
+
+# --- display backend selection ------------------------------------------------
+add_library(ra3_display STATIC)
+target_sources(ra3_display PUBLIC FILE_SET CXX_MODULES FILES src/display/ra3.display.cppm)
+target_link_libraries(ra3_display PUBLIC ra3_core ra3_render ra3_terrain ra3_client ra3_ui ra3_vulkan ra3_dx ra3_wasmgl ra3_webgpu)
+openra3_target_defaults(ra3_display)
+
+# --- umbrella -----------------------------------------------------------------
 add_library(ra3 STATIC)
-target_sources(ra3
+target_sources(ra3 PUBLIC FILE_SET CXX_MODULES FILES src/ra3.cppm)
-    PUBLIC FILE_SET CXX_MODULES FILES
+target_link_libraries(ra3 PUBLIC ra3_core ra3_logic ra3_client ra3_data ra3_game ra3_fs ra3_map ra3_skirmish ra3_render ra3_terrain ra3_models ra3_display
-        src/ra3.cppm
+    ra3_ui ra3_vulkan ra3_dx ra3_wasmgl ra3_webgpu ra3_enderlog)
-)
-target_link_libraries(ra3 PUBLIC ra3_core ra3_logic ra3_client ra3_game ra3_fs ra3_map ra3_skirmish ra3_render ra3_ui)
 openra3_target_defaults(ra3)
 
-# --- the headless game executable ---
+# --- executable ---------------------------------------------------------------
 add_executable(openra3 apps/openra3/main.cpp)
 target_link_libraries(openra3 PRIVATE ra3)
 openra3_target_defaults(openra3)
 
-# --- unit tests ---
+if(WIN32 AND OPENRA3_SDL3_ROOT)
+    add_custom_command(TARGET openra3 POST_BUILD
+        COMMAND ${CMAKE_COMMAND} -E copy_if_different
+            "${OPENRA3_SDL3_ROOT}/${OPENRA3_SDL3_MINGW_TRIPLE}/bin/SDL3.dll"
+            "$<TARGET_FILE_DIR:openra3>")
+endif()
+
+if(EMSCRIPTEN)
+    # Emit openra3.js/.wasm. The engine runs inside apps/web/openra3.worker.js
+    # (a plain Web Worker), which the page (apps/web/index.html) loads and hands
+    # an OffscreenCanvas; so there is no Emscripten HTML shell here - both web
+    # files are copied next to the module.
+    set_target_properties(openra3 PROPERTIES SUFFIX ".js")
+    target_link_options(openra3 PRIVATE
+        -sFORCE_FILESYSTEM=1
+        # index.html input glue calls the exported openra3_* functions via ccall.
+        "-sEXPORTED_RUNTIME_METHODS=ccall,cwrap")
+    add_custom_command(TARGET openra3 POST_BUILD
+        COMMAND ${CMAKE_COMMAND} -E copy_if_different
+            "${CMAKE_CURRENT_SOURCE_DIR}/apps/web/index.html"
+            "${CMAKE_CURRENT_SOURCE_DIR}/apps/web/openra3.worker.js"
+            "$<TARGET_FILE_DIR:openra3>"
+        COMMENT "Copying the OpenRA3 web page and worker bootstrap")
+    # On-demand assets: `OPENRA3_WEB_MANIFEST` is a JSON `{"files": [...]}` listing
+    # every asset relative to the assets root (generate it with
+    # scripts/make_web_manifest.py). Only that small manifest is preloaded, to
+    # /assets.manifest.json; at startup the worker registers every listed file as
+    # an Emscripten lazy file, so the browser fetches each asset when the engine
+    # first opens it (serve the tree at <root>/assets, or pass serve.py --assets).
+    set(OPENRA3_WEB_MANIFEST "" CACHE FILEPATH "Assets manifest JSON, embedded as /assets.manifest.json for lazy loading")
+    if(OPENRA3_WEB_MANIFEST AND EXISTS "${OPENRA3_WEB_MANIFEST}")
+        target_link_options(openra3 PRIVATE "--embed-file=${OPENRA3_WEB_MANIFEST}@/assets.manifest.json")
+    endif()
+    # Legacy: preload a whole assets directory into the virtual FS at /assets (the
+    # monolithic path the lazy worker backend replaces). Only used when no manifest
+    # is given, since lazy files cannot shadow a preloaded tree.
+    set(OPENRA3_WEB_ASSETS "" CACHE PATH "Assets directory preloaded into the wasm FS at /assets (legacy)")
+    if(NOT (OPENRA3_WEB_MANIFEST AND EXISTS "${OPENRA3_WEB_MANIFEST}") AND OPENRA3_WEB_ASSETS AND EXISTS "${OPENRA3_WEB_ASSETS}")
+        target_link_options(openra3 PRIVATE "--preload-file=${OPENRA3_WEB_ASSETS}@/assets")
+    endif()
+endif()
+
+# --- packaging (.deb / .msi / portable archives) -----------------------------
+# CPack produces the release artifacts in one shot:
+#   Linux   -> DEB (dependencies derived from the binary with dpkg-shlibdeps)
+#              plus a portable .tar.gz
+#   Windows -> a Windows Installer .msi (built with wixl from msitools when the
+#              WiX tools are absent, so the Linux cross image can make it) plus a
+#              portable .zip with the exe and SDL3.dll
+# OPENRA3_DISTRO_TAG (e.g. ubuntu26.04) is appended to the Linux file name so the
+# per-distro images do not collide.
+install(TARGETS openra3 RUNTIME DESTINATION bin)
+if(WIN32 AND OPENRA3_SDL3_ROOT)
+    install(FILES "${OPENRA3_SDL3_ROOT}/${OPENRA3_SDL3_MINGW_TRIPLE}/bin/SDL3.dll" DESTINATION bin)
+endif()
+
+set(OPENRA3_DISTRO_TAG "" CACHE STRING "Distro tag appended to package file names (e.g. ubuntu26.04)")
+set(CPACK_PACKAGE_NAME "openra3")
+set(CPACK_PACKAGE_VENDOR "OpenRA3")
+set(CPACK_PACKAGE_CONTACT "OpenRA3 <noreply@openra3.invalid>")
+set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "OpenRA3 - a from-scratch reimplementation of Red Alert 3")
+set(CPACK_PACKAGE_HOMEPAGE_URL "https://git.ender.cool/EnderTheCoder/openra3")
+set(CPACK_PACKAGE_VERSION "${PROJECT_VERSION}")
+set(CPACK_PACKAGE_EXECUTABLES "openra3" "OpenRA3")
+set(CPACK_STRIP_FILES ON)
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/LICENSE")
+    set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/LICENSE")
+endif()
+
+if(WIN32)
+    if(CMAKE_SYSTEM_PROCESSOR STREQUAL "aarch64")
+        set(OPENRA3_WIN_ARCH "arm64")
+    else()
+        set(OPENRA3_WIN_ARCH "x86_64")
+    endif()
+    set(CPACK_PACKAGE_FILE_NAME "openra3-${PROJECT_VERSION}-windows-${OPENRA3_WIN_ARCH}")
+    # Portable .zip (exe + SDL3.dll).
+    set(CPACK_GENERATOR "ZIP")
+
+    # A Windows Installer (.msi) straight from the Linux cross build via wixl
+    # (msitools). wixl 0.106 has no arm64 support, so the MSI is offered for
+    # x86_64 and ARM64 ships the portable zip.
+    find_program(OPENRA3_WIXL wixl)
+    if(OPENRA3_WIXL AND NOT CMAKE_SYSTEM_PROCESSOR STREQUAL "aarch64")
+        configure_file("${CMAKE_CURRENT_SOURCE_DIR}/cmake/packaging/openra3.wxs.in"
+                       "${CMAKE_CURRENT_BINARY_DIR}/openra3.wxs" @ONLY)
+        add_custom_target(openra3_msi
+            COMMAND "${OPENRA3_WIXL}" --arch x64
+                    -D "exe=$<TARGET_FILE:openra3>"
+                    -D "dll=${OPENRA3_SDL3_ROOT}/${OPENRA3_SDL3_MINGW_TRIPLE}/bin/SDL3.dll"
+                    -o "$<TARGET_FILE_DIR:openra3>/${CPACK_PACKAGE_FILE_NAME}.msi"
+                    "${CMAKE_CURRENT_BINARY_DIR}/openra3.wxs"
+            DEPENDS openra3
+            COMMENT "Building Windows Installer (${CPACK_PACKAGE_FILE_NAME}.msi) with wixl"
+            VERBATIM)
+    endif()
+else()
+    if(CMAKE_SYSTEM_PROCESSOR STREQUAL "aarch64")
+        set(CPACK_DEBIAN_PACKAGE_ARCHITECTURE "arm64")
+    else()
+        set(CPACK_DEBIAN_PACKAGE_ARCHITECTURE "amd64")
+    endif()
+    set(CPACK_PACKAGE_FILE_NAME "openra3_${PROJECT_VERSION}_${CPACK_DEBIAN_PACKAGE_ARCHITECTURE}${OPENRA3_DISTRO_TAG}")
+    set(CPACK_GENERATOR "TGZ;DEB")
+    set(CPACK_DEBIAN_PACKAGE_SHLIBDEPS ON)
+    set(CPACK_DEBIAN_PACKAGE_SECTION "games")
+    set(CPACK_DEBIAN_PACKAGE_PRIORITY "optional")
+endif()
+include(CPack)
+
+# --- extracted assets ---------------------------------------------------------
+# At build time, extract the retail assets into <exe_dir>/assets so the
+# executable is self-contained (no --game-dir at run time). This drives the
+# ra3tools Python scripts (the game install + Python, no target executable), so
+# it also runs for a cross-build when the install is mounted into the container
+# and RA3_GAME_DIR points at it. The engine's own map/terrain reader is embedded
+# in the exe (run `openra3 extract` on a native host if you prefer).
+set(RA3_GAME_DIR "C:/Red Alert 3" CACHE PATH "Red Alert 3 installation used to extract assets")
+set(RA3TOOLS_DIR "C:/Users/Ender/CLionProjects/ra3-headless/ra3tools" CACHE PATH "ra3tools scripts (asset extraction)")
+find_program(OPENRA3_PYTHON NAMES python3 python)
+set(PYTHON_EXECUTABLE "${OPENRA3_PYTHON}" CACHE FILEPATH "Python interpreter used to run ra3tools")
+option(OPENRA3_EXTRACT_ALL "Extract every asset (models/textures/audio/movies) via ra3tools" ON)
+
+if(EXISTS "${RA3_GAME_DIR}/Data" AND OPENRA3_PYTHON)
+    add_custom_command(
+        OUTPUT "${CMAKE_BINARY_DIR}/.assets_stamp"
+        COMMAND ${CMAKE_COMMAND}
+            "-DGAME_DIR=${RA3_GAME_DIR}"
+            "-DOUT=$<TARGET_FILE_DIR:openra3>/assets"
+            "-DPYTHON=${PYTHON_EXECUTABLE}"
+            "-DRA3TOOLS=${RA3TOOLS_DIR}"
+            "-DEXTRACT_ALL=$<IF:$<BOOL:${OPENRA3_EXTRACT_ALL}>,ON,OFF>"
+            "-DSTAMP=${CMAKE_BINARY_DIR}/.assets_stamp"
+            -P "${CMAKE_CURRENT_SOURCE_DIR}/cmake/extract_assets.cmake"
+        DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/cmake/extract_assets.cmake"
+        COMMENT "Extracting Red Alert 3 assets to $<TARGET_FILE_DIR:openra3>/assets"
+        VERBATIM)
+    add_custom_target(openra3_assets ALL DEPENDS "${CMAKE_BINARY_DIR}/.assets_stamp")
+else()
+    message(STATUS "OpenRA3: asset extraction skipped (RA3_GAME_DIR '${RA3_GAME_DIR}' or Python not found)")
+endif()
+
+# --- tests --------------------------------------------------------------------
 enable_testing()
 add_executable(ra3_tests tests/ra3_tests.cpp)
 target_link_libraries(ra3_tests PRIVATE ra3)
 openra3_target_defaults(ra3_tests)
 add_test(NAME ra3_tests COMMAND ra3_tests)
+
+# libra3assets' own dependency-free unit tests (RefPack + BIG4 + BinaryAsset +
+# CSF + CkMp round-trips), built against the vendored copy so the upstream
+# suite keeps guarding the readers OpenRA3 now relies on.
+add_executable(ra3assets_unit
+    third_party/libra3assets/tests/test_main.cpp
+    third_party/libra3assets/tests/test_assets.cpp)
+target_include_directories(ra3assets_unit PRIVATE third_party/libra3assets/tests)
+target_link_libraries(ra3assets_unit PRIVATE ra3_assets)
+target_compile_features(ra3assets_unit PRIVATE cxx_std_26)
+openra3_target_defaults(ra3assets_unit)
+add_test(NAME ra3assets_unit COMMAND ra3assets_unit)

Dockerfile

@@ -1,7 +1,9 @@
 # syntax=docker/dockerfile:1
 
-# dev target: full toolchain + debug tools for development and debugging.
+# Linux build environment. Isolated from the Windows cross image (Dockerfile.win)
-# Base image and compiler are the latest stable (ubuntu:26.04 ships gcc/g++ 16).
+# so the two toolchains and their standard libraries never interfere.
+#
+# dev target: clang + libc++ (for `import std;`) + SDL3 + debug tools.
 FROM ubuntu:26.04 AS dev
 
 ENV DEBIAN_FRONTEND=noninteractive
@@ -23,44 +25,49 @@ RUN --mount=type=cache,target=/var/lib/apt,sharing=locked \
         sleep 5; \
     done \
     && apt-get -o Acquire::Retries=5 install -y --no-install-recommends \
-        build-essential \
         ca-certificates \
+        clang-21 \
+        clang-tools-21 \
         cmake \
-        g++-16 \
+        dpkg-dev \
+        file \
         gdb \
         git \
+        libc++-21-dev \
+        libc++abi-21-dev \
         libsdl3-dev \
+        libvulkan-dev \
         ninja-build \
         pkg-config \
     && rm -rf /var/lib/apt/lists/*
 
-# Pin the toolchain to GCC 16 (the distro default is still GCC 15).
+ENV CC=clang-21
-ENV CC=gcc-16
+ENV CXX=clang++-21
-ENV CXX=g++-16
-RUN update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-16 100 \
-    && update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-16 100 \
-    && update-alternatives --install /usr/bin/c++ c++ /usr/bin/g++-16 100
 
 WORKDIR /work
 COPY . .
 
-# C++26 modules need CMake >= 3.28, the Ninja generator and a module-aware gcc.
+RUN cmake -S . -B build/linux -G Ninja -DCMAKE_BUILD_TYPE=Release -DOPENRA3_DISTRO_TAG=ubuntu26.04 \
-RUN cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
+    && cmake --build build/linux -j \
-    && cmake --build build -j \
+    && ctest --test-dir build/linux --output-on-failure \
-    && ctest --test-dir build --output-on-failure
+    && (cd build/linux && cpack -G DEB)
 
 # deploy target: runtime dependencies + final binary, minimal and fast.
 FROM ubuntu:26.04 AS deploy
 
 ENV DEBIAN_FRONTEND=noninteractive
 
-RUN apt-get -o Acquire::Retries=5 update \
+RUN --mount=type=cache,target=/var/lib/apt,sharing=locked \
-    && apt-get -o Acquire::Retries=5 install -y --no-install-recommends \
+    --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    apt-get -o Acquire::Retries=5 update \
+    &&     apt-get -o Acquire::Retries=5 install -y --no-install-recommends \
+        libc++1 \
+        libc++abi1 \
         libsdl3-0 \
-        libstdc++6 \
+        libvulkan1 \
     && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app
-COPY --from=dev /work/build/bin/openra3 /app/openra3
+COPY --from=dev /work/build/linux/bin/openra3 /app/openra3
 
 ENTRYPOINT ["/app/openra3"]

Dockerfile.debian

@@ -0,0 +1,87 @@
+# syntax=docker/dockerfile:1
+
+# Debian build environment (latest stable, Debian 13 "trixie") producing a .deb
+# alongside the binary. Separate from Dockerfile (Ubuntu 26.04) because the
+# distro and its libc++/SDL3 versions differ, and a .deb's dependencies must be
+# generated against the distro it targets.
+#
+# Toolchain: clang-19 + libc++-19 (for `import std;`). Debian 13 ships CMake
+# 3.31, whose experimental `import std` gate value the project does not target,
+# so an upstream CMake is installed from the Kitware tarball.
+
+FROM debian:stable AS dev
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+ARG APT_MIRROR=""
+RUN if [ -n "$APT_MIRROR" ]; then \
+        sed -i -e "s|http://deb.debian.org/debian|${APT_MIRROR}|g" \
+               -e "s|http://security.debian.org/debian-security|${APT_MIRROR}|g" \
+               /etc/apt/sources.list /etc/apt/sources.list.d/*.sources 2>/dev/null || true; \
+    fi
+
+RUN --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    for attempt in 1 2 3 4 5; do \
+        apt-get -o Acquire::Retries=5 update && break; \
+        echo "apt-get update failed (attempt $attempt), retrying"; \
+        sleep 5; \
+    done \
+    && apt-get -o Acquire::Retries=5 install -y --no-install-recommends \
+        ca-certificates \
+        clang-19 \
+        clang-tools-19 \
+        curl \
+        dpkg-dev \
+        file \
+        libc++-19-dev \
+        libc++abi-19-dev \
+        libsdl3-dev \
+        libunwind-19-dev \
+        lld-19 \
+        ninja-build \
+        pkg-config \
+        python3 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Upstream CMake, because Debian 13's 3.31 experimental gate does not enable the
+# `import std;` support the project relies on.
+ARG CMAKE_VERSION=4.2.3
+RUN mkdir -p /opt/cmake \
+    && curl -fL "https://github.com/Kitware/CMake/releases/download/v${CMAKE_VERSION}/cmake-${CMAKE_VERSION}-linux-x86_64.tar.gz" \
+        | tar -xz -C /opt/cmake --strip-components=1
+ENV PATH="/opt/cmake/bin:${PATH}"
+
+ENV CC=clang-19
+ENV CXX=clang++-19
+
+WORKDIR /work
+COPY . .
+
+RUN cmake -S . -B build/debian -G Ninja \
+        -DCMAKE_BUILD_TYPE=Release \
+        -DCMAKE_CXX_STDLIB_MODULES_JSON=/usr/lib/llvm-19/lib/libc++.modules.json \
+        -DOPENRA3_DISTRO_TAG=debian13 \
+    && cmake --build build/debian -j \
+    && ctest --test-dir build/debian --output-on-failure \
+    && (cd build/debian && cpack -G DEB)
+
+# deploy target: runtime dependencies + final binary, minimal and fast.
+FROM debian:stable AS deploy
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    apt-get -o Acquire::Retries=5 update \
+    &&     apt-get -o Acquire::Retries=5 install -y --no-install-recommends \
+        libc++1-19 \
+        libc++abi1-19 \
+        libsdl3-0 \
+        libvulkan1 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY --from=dev /work/build/debian/bin/openra3 /app/openra3
+
+ENTRYPOINT ["/app/openra3"]

Dockerfile.debian-arm64

@@ -0,0 +1,86 @@
+# syntax=docker/dockerfile:1
+
+# Debian build environment for Linux on ARM64 (aarch64-linux-gnu), producing an
+# arm64 .deb. Cross-compiled from amd64 with Debian's clang-19 + libc++-19 and
+# the arm64 packages installed via dpkg multiarch.
+
+FROM debian:stable AS dev
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+ARG APT_MIRROR=""
+RUN if [ -n "$APT_MIRROR" ]; then \
+        sed -i -e "s|http://deb.debian.org/debian|${APT_MIRROR}|g" \
+               -e "s|http://security.debian.org/debian-security|${APT_MIRROR}|g" \
+               /etc/apt/sources.list /etc/apt/sources.list.d/*.sources 2>/dev/null || true; \
+    fi
+
+RUN dpkg --add-architecture arm64
+
+RUN --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    for attempt in 1 2 3 4 5; do \
+        apt-get -o Acquire::Retries=5 update && break; \
+        echo "apt-get update failed (attempt $attempt), retrying"; \
+        sleep 5; \
+    done \
+    && apt-get -o Acquire::Retries=5 install -y --no-install-recommends \
+        ca-certificates \
+        clang-19 \
+        clang-tools-19 \
+        curl \
+        dpkg-dev \
+        file \
+        gcc-aarch64-linux-gnu \
+        libc++-19-dev:arm64 \
+        libc++abi-19-dev:arm64 \
+        libsdl3-dev:arm64 \
+        libunwind-19-dev:arm64 \
+        lld-19 \
+        ninja-build \
+        pkg-config \
+        python3 \
+    && rm -rf /var/lib/apt/lists/*
+
+ARG CMAKE_VERSION=4.2.3
+RUN mkdir -p /opt/cmake \
+    && curl -fL "https://github.com/Kitware/CMake/releases/download/v${CMAKE_VERSION}/cmake-${CMAKE_VERSION}-linux-x86_64.tar.gz" \
+        | tar -xz -C /opt/cmake --strip-components=1
+ENV PATH="/opt/cmake/bin:${PATH}"
+
+ENV CC=clang-19
+ENV CXX=clang++-19
+# Point pkg-config at the arm64 packages so SDL3 resolves to the aarch64 build.
+ENV PKG_CONFIG_LIBDIR=/usr/lib/aarch64-linux-gnu/pkgconfig
+
+WORKDIR /work
+COPY . .
+
+RUN cmake -S . -B build/debian-arm64 -G Ninja \
+        -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/clang-aarch64-linux-gnu.cmake \
+        -DCMAKE_BUILD_TYPE=Release \
+        -DOPENRA3_AARCH64_CC=clang-19 \
+        -DOPENRA3_AARCH64_CXX=clang++-19 \
+        -DOPENRA3_AARCH64_STDLIB_MODULES_JSON=/usr/lib/llvm-19/lib/libc++.modules.json \
+        -DOPENRA3_DISTRO_TAG=debian13 \
+    && cmake --build build/debian-arm64 -j \
+    && (cd build/debian-arm64 && cpack -G DEB)
+
+FROM --platform=linux/arm64 debian:stable AS deploy
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    apt-get -o Acquire::Retries=5 update \
+    &&     apt-get -o Acquire::Retries=5 install -y --no-install-recommends \
+        libc++1-19 \
+        libc++abi1-19 \
+        libsdl3-0 \
+        libvulkan1 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY --from=dev /work/build/debian-arm64/bin/openra3 /app/openra3
+
+ENTRYPOINT ["/app/openra3"]

Dockerfile.linux-arm64

@@ -0,0 +1,84 @@
+# syntax=docker/dockerfile:1
+
+# Linux on ARM64 cross-build environment (aarch64-linux-gnu), isolated from the
+# x86_64 Linux image and the Windows images.
+#
+# Toolchain: clang-21 + libc++ with the arm64 libc++ (for `import std;`), the
+# arm64 glibc from `gcc-aarch64-linux-gnu`, arm64 SDL3 from `libsdl3-dev:arm64`,
+# and lld as the linker. The arm64 packages are installed with dpkg multiarch
+# (`arm64` added to the sources); the native clang/cmake build tools stay amd64.
+
+FROM ubuntu:26.04 AS dev
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+ARG APT_MIRROR=""
+RUN if [ -n "$APT_MIRROR" ]; then \
+        sed -i -e "s|http://archive.ubuntu.com/ubuntu|${APT_MIRROR}|g" \
+               -e "s|http://security.ubuntu.com/ubuntu|${APT_MIRROR}|g" \
+               -e "s|http://ports.ubuntu.com/ubuntu-ports|${APT_MIRROR}|g" \
+               /etc/apt/sources.list /etc/apt/sources.list.d/*.sources 2>/dev/null || true; \
+    fi
+
+# Enable the arm64 architecture on top of the emulated amd64 userland.
+RUN dpkg --add-architecture arm64
+
+RUN --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    for attempt in 1 2 3 4 5; do \
+        apt-get -o Acquire::Retries=5 update && break; \
+        echo "apt-get update failed (attempt $attempt), retrying"; \
+        sleep 5; \
+    done \
+    && apt-get -o Acquire::Retries=5 install -y --no-install-recommends \
+        ca-certificates \
+        clang-21 \
+        cmake \
+        dpkg-dev \
+        file \
+        gcc-aarch64-linux-gnu \
+        libc++-21-dev:arm64 \
+        libc++abi-21-dev:arm64 \
+        libsdl3-dev:arm64 \
+        libunwind-21-dev:arm64 \
+        lld-21 \
+        ninja-build \
+        pkg-config \
+        python3 \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV CC=clang-21
+ENV CXX=clang++-21
+# Point pkg-config at the arm64 packages so SDL3 resolves to the aarch64 build.
+ENV PKG_CONFIG_LIBDIR=/usr/lib/aarch64-linux-gnu/pkgconfig
+
+WORKDIR /work
+COPY . .
+
+RUN cmake -S . -B build/linux-arm64 -G Ninja \
+        -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/clang-aarch64-linux-gnu.cmake \
+        -DCMAKE_BUILD_TYPE=Release \
+        -DOPENRA3_DISTRO_TAG=ubuntu26.04 \
+    && cmake --build build/linux-arm64 -j \
+    && (cd build/linux-arm64 && cpack -G DEB)
+
+# deploy target: runtime dependencies + final binary, minimal and fast. This is
+# an arm64 image; build it on (or with emulation for) an arm64 host.
+FROM --platform=linux/arm64 ubuntu:26.04 AS deploy
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    apt-get -o Acquire::Retries=5 update \
+    &&     apt-get -o Acquire::Retries=5 install -y --no-install-recommends \
+        libc++1 \
+        libc++abi1 \
+        libsdl3-0 \
+        libvulkan1 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY --from=dev /work/build/linux-arm64/bin/openra3 /app/openra3
+
+ENTRYPOINT ["/app/openra3"]

Dockerfile.wasm

@@ -0,0 +1,56 @@
+# syntax=docker/dockerfile:1
+
+# WebAssembly build environment (Emscripten), producing openra3.js/.wasm plus the
+# `index.html` page and `openra3.worker.js` bootstrap. The engine runs on a plain
+# Web Worker (WebGL2 and WebGPU backends), with lazy on-demand assets.
+#
+# The emsdk image ships CMake 3.28, whose experimental `import std` support is
+# too old for the project, so an upstream CMake is layered on top.
+
+FROM emscripten/emsdk:6.0.10 AS dev
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+ARG APT_MIRROR=""
+RUN if [ -n "$APT_MIRROR" ]; then \
+        sed -i -e "s|http://archive.ubuntu.com/ubuntu|${APT_MIRROR}|g" \
+               -e "s|http://security.ubuntu.com/ubuntu|${APT_MIRROR}|g" \
+               -e "s|http://ports.ubuntu.com/ubuntu-ports|${APT_MIRROR}|g" \
+               /etc/apt/sources.list /etc/apt/sources.list.d/*.sources 2>/dev/null || true; \
+    fi
+
+RUN --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    for attempt in 1 2 3 4 5; do \
+        apt-get -o Acquire::Retries=5 update && break; \
+        echo "apt-get update failed (attempt $attempt), retrying"; \
+        sleep 5; \
+    done \
+    && apt-get -o Acquire::Retries=5 install -y --no-install-recommends \
+        ca-certificates \
+        curl \
+        ninja-build \
+    && rm -rf /var/lib/apt/lists/*
+
+# Upstream CMake, because the emsdk image's 3.28 cannot build the project.
+ARG CMAKE_VERSION=4.2.3
+RUN mkdir -p /opt/cmake \
+    && curl -fL "https://github.com/Kitware/CMake/releases/download/v${CMAKE_VERSION}/cmake-${CMAKE_VERSION}-linux-x86_64.tar.gz" \
+        | tar -xz -C /opt/cmake --strip-components=1
+ENV PATH="/opt/cmake/bin:${PATH}"
+
+# Pre-fetch the emdawnwebgpu port into the image. The WebGPU backend needs
+# <webgpu/webgpu_cpp.h>, and CMake's module dependency scanner does not process
+# `--use-port`, so a warm cache is required before the project is configured.
+RUN . /emsdk/emsdk_env.sh \
+    && printf '#include <webgpu/webgpu_cpp.h>\nint main(){}\n' > /tmp/wgpu_port.cpp \
+    && em++ -c /tmp/wgpu_port.cpp -o /tmp/wgpu_port.o --use-port=emdawnwebgpu \
+    && rm -f /tmp/wgpu_port.cpp /tmp/wgpu_port.o
+
+WORKDIR /work
+COPY . .
+
+RUN cmake -S . -B build/wasm -G Ninja \
+        -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/emscripten-wasm.cmake \
+        -DCMAKE_BUILD_TYPE=Release \
+    && cmake --build build/wasm -j

Dockerfile.win

@@ -0,0 +1,67 @@
+# syntax=docker/dockerfile:1
+
+# Windows cross-build environment (x86_64), fully isolated from the Linux image
+# in Dockerfile so the two toolchains and standard libraries never interfere.
+#
+# Toolchain: llvm-mingw (clang + libc++ + the libc++ `std` module, MSVCRT
+# runtime) with the official SDL3 MinGW development package.
+
+FROM ubuntu:26.04 AS dev
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+ARG APT_MIRROR=""
+RUN if [ -n "$APT_MIRROR" ]; then \
+        sed -i -e "s|http://archive.ubuntu.com/ubuntu|${APT_MIRROR}|g" \
+               -e "s|http://security.ubuntu.com/ubuntu|${APT_MIRROR}|g" \
+               -e "s|http://ports.ubuntu.com/ubuntu-ports|${APT_MIRROR}|g" \
+               /etc/apt/sources.list /etc/apt/sources.list.d/*.sources 2>/dev/null || true; \
+    fi
+
+RUN --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    for attempt in 1 2 3 4 5; do \
+        apt-get -o Acquire::Retries=5 update && break; \
+        echo "apt-get update failed (attempt $attempt), retrying"; \
+        sleep 5; \
+    done \
+    && apt-get -o Acquire::Retries=5 install -y --no-install-recommends \
+        ca-certificates \
+        cmake \
+        curl \
+        ninja-build \
+        python3 \
+        wixl \
+        xz-utils \
+    && rm -rf /var/lib/apt/lists/*
+
+# Pinned toolchain + SDL3 versions (override with --build-arg to bump).
+ARG LLVM_MINGW_VERSION=20260908
+ARG LLVM_MINGW_FLAVOR=msvcrt
+ARG SDL3_VERSION=3.4.16
+
+RUN mkdir -p /opt/llvm-mingw /opt/sdl3-mingw \
+    && curl -fL "https://github.com/mstorsjo/llvm-mingw/releases/download/${LLVM_MINGW_VERSION}/llvm-mingw-${LLVM_MINGW_VERSION}-${LLVM_MINGW_FLAVOR}-ubuntu-22.04-x86_64.tar.xz" \
+        | tar -xJ -C /opt/llvm-mingw --strip-components=1 \
+    && curl -fL "https://github.com/libsdl-org/SDL/releases/download/release-${SDL3_VERSION}/SDL3-devel-${SDL3_VERSION}-mingw.tar.gz" \
+        | tar -xz -C /opt/sdl3-mingw --strip-components=1
+
+ENV OPENRA3_LLVM_MINGW_ROOT=/opt/llvm-mingw
+ENV OPENRA3_SDL3_ROOT=/opt/sdl3-mingw
+
+WORKDIR /work
+COPY . .
+
+RUN cmake -S . -B build/windows -G Ninja \
+        -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/llvm-mingw-x86_64.cmake \
+        -DCMAKE_BUILD_TYPE=Release \
+    && cmake --build build/windows -j \
+    && cmake --build build/windows --target openra3_msi \
+    && (cd build/windows && cpack -G ZIP)
+
+# package target: the .exe plus the SDL3 runtime DLL.
+FROM ubuntu:26.04 AS package
+
+WORKDIR /app
+COPY --from=dev /work/build/windows/bin/openra3.exe /app/
+COPY --from=dev /work/build/windows/bin/SDL3.dll /app/

Dockerfile.win-arm64

@@ -0,0 +1,77 @@
+# syntax=docker/dockerfile:1
+
+# Windows on ARM64 cross-build environment (aarch64-w64-mingw32), isolated from
+# the x86_64 Windows image and the Linux images.
+#
+# Toolchain: the same multi-target llvm-mingw as Dockerfile.win (clang + libc++ +
+# the libc++ `std` module, MSVCRT runtime), targeting aarch64. The official SDL
+# release ships no MinGW ARM64 dev package, so SDL3 comes from MSYS2's clangarm64
+# repository, staged into the `<triple>/{include,lib,bin}` layout the toolchain
+# expects.
+
+FROM ubuntu:26.04 AS dev
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+ARG APT_MIRROR=""
+RUN if [ -n "$APT_MIRROR" ]; then \
+        sed -i -e "s|http://archive.ubuntu.com/ubuntu|${APT_MIRROR}|g" \
+               -e "s|http://security.ubuntu.com/ubuntu|${APT_MIRROR}|g" \
+               -e "s|http://ports.ubuntu.com/ubuntu-ports|${APT_MIRROR}|g" \
+               /etc/apt/sources.list /etc/apt/sources.list.d/*.sources 2>/dev/null || true; \
+    fi
+
+RUN --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    for attempt in 1 2 3 4 5; do \
+        apt-get -o Acquire::Retries=5 update && break; \
+        echo "apt-get update failed (attempt $attempt), retrying"; \
+        sleep 5; \
+    done \
+    && apt-get -o Acquire::Retries=5 install -y --no-install-recommends \
+        ca-certificates \
+        cmake \
+        curl \
+        ninja-build \
+        python3 \
+        xz-utils \
+        zstd \
+    && rm -rf /var/lib/apt/lists/*
+
+# Pinned toolchain + SDL3 versions (override with --build-arg to bump).
+ARG LLVM_MINGW_VERSION=20260908
+ARG LLVM_MINGW_FLAVOR=msvcrt
+# SDL3 for aarch64-w64-mingw32 from MSYS2's clangarm64 repo (name includes the
+# MSYS2 package release, hence the `-1`).
+ARG MSYS2_SDL3_PKG=mingw-w64-clang-aarch64-sdl3-3.4.16-1-any.pkg.tar.zst
+
+RUN mkdir -p /opt/llvm-mingw \
+    && curl -fL "https://github.com/mstorsjo/llvm-mingw/releases/download/${LLVM_MINGW_VERSION}/llvm-mingw-${LLVM_MINGW_VERSION}-${LLVM_MINGW_FLAVOR}-ubuntu-22.04-x86_64.tar.xz" \
+        | tar -xJ -C /opt/llvm-mingw --strip-components=1
+
+RUN mkdir -p /opt/sdl3-aarch64/aarch64-w64-mingw32/include /opt/sdl3-aarch64/aarch64-w64-mingw32/lib /opt/sdl3-aarch64/aarch64-w64-mingw32/bin \
+    && curl -fL "https://repo.msys2.org/mingw/clangarm64/${MSYS2_SDL3_PKG}" -o /tmp/sdl3.pkg.tar.zst \
+    && mkdir -p /tmp/sdl3 && tar --zstd -xf /tmp/sdl3.pkg.tar.zst -C /tmp/sdl3 \
+    && cp -r /tmp/sdl3/clangarm64/include/SDL3 /opt/sdl3-aarch64/aarch64-w64-mingw32/include/ \
+    && cp /tmp/sdl3/clangarm64/lib/libSDL3.dll.a /opt/sdl3-aarch64/aarch64-w64-mingw32/lib/ \
+    && cp /tmp/sdl3/clangarm64/bin/SDL3.dll /opt/sdl3-aarch64/aarch64-w64-mingw32/bin/ \
+    && rm -rf /tmp/sdl3 /tmp/sdl3.pkg.tar.zst
+
+ENV OPENRA3_LLVM_MINGW_ROOT=/opt/llvm-mingw
+ENV OPENRA3_SDL3_ROOT=/opt/sdl3-aarch64
+
+WORKDIR /work
+COPY . .
+
+RUN cmake -S . -B build/windows-arm64 -G Ninja \
+        -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/llvm-mingw-aarch64.cmake \
+        -DCMAKE_BUILD_TYPE=Release \
+    && cmake --build build/windows-arm64 -j \
+    && (cd build/windows-arm64 && cpack -G ZIP)
+
+# package target: the .exe plus the SDL3 runtime DLL.
+FROM ubuntu:26.04 AS package
+
+WORKDIR /app
+COPY --from=dev /work/build/windows-arm64/bin/openra3.exe /app/
+COPY --from=dev /work/build/windows-arm64/bin/SDL3.dll /app/

README.md

@@ -1,7 +1,8 @@
 # OpenRA3
 
 A from-scratch, portable re-implementation of **Command & Conquer: Red Alert 3**
-in **C++26** using **C++ modules**, built with **GCC 16**.
+in **C++26** using **C++ modules** and `import std;`, built with **Clang** for
+both **Linux** and **Windows**.
 
 Red Alert 3 runs SAGE 2.0. EA never released that engine's C++ source, but it
 did open-source the closely related SAGE 1.0 engine as
@@ -17,11 +18,27 @@ Ghidra.
 
 ## Status
 
-OpenRA3 is at **v0.0.1**. The engine compiles and runs headless, and a **minimal
+OpenRA3 is at **v0.8.0**. The engine compiles and runs headless, and a **minimal
 skirmish** is playable: it reads a real multiplayer map out of your install,
-recovers the player start waypoints, and simulates two sides earning credits,
+recovers the player start waypoints, and simulates two sides building a base,
-training units and fighting until one base falls. The map and match state can be
+extracting ore and fighting until one side is wiped out. The balance is the
-**rendered** to a window (SDL3) or to an image.
+**retail Red Alert 3 balance**, pinned in `ra3.data` from EA's open RA3 XML:
+damage types, `ArmorTemplate` percentages, weapon target masks, build costs and
+the ore economy. Presentation offers **Vulkan** (`ra3.vulkan`), **Direct3D 11 / 12**
+(`ra3.dx`), **WebGPU** (`ra3.webgpu`, the wasm worker backend) and **WebGL 2**
+(`ra3.wasmgl`, the SDL-free wasm worker fallback) GPU backends with an SDL
+software blit and null fallbacks; the backend is selectable from the in-game menu
+and the software renderer still produces headless images. Terrain tiles
+cross-fade the way the retail `Terrain.fx` does (a per-cell blend ramp plus a
+gutter-padded atlas), so material boundaries are smooth instead of a grid of
+hard lines; the **buildings and props a map places** are decoded from the retail
+compiled `W3DMesh` art (the uncompressed `worldbuilder.bin` stream and its
+embedded DDS textures) and drawn with a depth test over the terrain. An
+in-window **menu** lists the maps by their localized name and
+exposes every render/skirmish option for tweaking before launch. The whole tree
+builds for **Linux** (clang + libc++) and cross-compiles to **Windows**
+(`openra3.exe` + `SDL3.dll`) with llvm-mingw — both using C++26 modules and
+`import std;`.
 
 ```text
 $ openra3 skirmish --game-dir "/game" --map map_mp_2_feasel4
@@ -29,9 +46,9 @@ OpenRA3 skirmish  map=map_mp_2_feasel4  source=archive:map_mp_2_feasel4  seed=1
 start positions:
   P0 (1338, 1940)
   P1 (1291, 1404)
-result: decided  winner=0  frames=3397 (113.2 s)
+result: decided  winner=0  frames=9293 (309.8 s)
-  P0 Commander  Allied  money=   129 units=19 kills=21 losses=3
+  P0 Commander  Allied  money=   700 units=15 kills=21 losses=15
-  P1 AI         Soviet  money=   840 units= 0 kills=3 losses=21
+  P1 AI         Soviet  money=   376 units= 0 kills=15 losses=21
 ```
 
 ## Offline only
@@ -44,15 +61,25 @@ tested without any external service.
 
 ## Assets
 
-The engine reads the retail game from your local install:
+The runtime reads a portable `assets/` folder **next to the executable** — there
+is no `--game-dir` at run time. The build extracts it from your install:
 
-- default path `C:\Red Alert 3`, or `--game-dir DIR`, or `$RA3_GAME_DIR`;
+- `openra3_assets` (build target) runs `cmake/extract_assets.cmake`, which
-- `Data\MapsMultiplayer.big` is read for the map catalog;
+  - extracts every map (double-unwrapped `CkMp`) and terrain TGA into `assets/`
-- maps are unpacked from `BIG4` + RefPack and their start waypoints recovered.
+    via the engine's own `openra3 extract`;
+  - with `-DOPENRA3_EXTRACT_ALL=ON` (default) also dumps **every** `.big` entry
+    plus models, textures (`.png`), sound effects/voice and movie audio via the
+    [`ra3-headless/ra3tools`](https://github.com/) scripts.
+- CMake cache vars: `RA3_GAME_DIR` (default `C:/Red Alert 3`), `RA3TOOLS_DIR`
+  (the `ra3tools` scripts), `PYTHON_EXECUTABLE`.
+- The step is skipped when the exe cannot run on the build host (a Windows
+  cross-build in a Linux container); the exe then extracts maps/terrain on first
+  launch, and the full dump can be run explicitly:
+  `cmake --build <build> --target openra3_assets` on a native host, or
+  `openra3 extract --game-dir DIR --out DIR`.
 
-**No game data is committed or distributed.** `reference/` (the GPLv3 Generals
+**No game data is committed or distributed.** `reference/`, `assets/` and the
-source) and any extracted assets are git-ignored; `tools/fetch_reference.sh`
+ra3tools checkout are git-ignored. Without an install the engine falls back to a
-fetches the former on demand. Without an install, the engine falls back to a
 built-in test map so the project still builds and runs in CI.
 
 ## Layout
@@ -61,70 +88,254 @@ built-in test map so the project still builds and runs in CI.
 | --- | --- |
 | `src/core/ra3.core.cppm` | fundamental types, math, strings, random, message stream |
 | `src/logic/ra3.logic.cppm` | objects, players, teams, spatial partition, game loop |
-| `src/client/ra3.client.cppm` | display abstraction + client facade / frame loop |
+| `src/client/ra3.client.cppm` | `display` abstraction + shared interactive loops + client facade |
+| `src/display/ra3.display.cppm` | picks the backend (Vulkan/D3D11/D3D12/WebGL, then SDL) for the app |
 | `src/game/ra3.game.cppm` | RA3 sides, player templates, skirmish defaults |
+| `src/data/ra3.data.cppm` | retail RA3 balance: damage types, armour, weapons, units, economy |
 | `src/fs/ra3.fs.cppm` | `BIG4` archives, RefPack codec, local install locator |
-| `src/map/ra3.map.cppm` | map catalog, `EAR`/RefPack unwrap, start waypoints |
+| `src/map/ra3.map.cppm` | map catalog, `EAR`/RefPack unwrap, start waypoints, `gamestrings.csf` display names |
-| `src/skirmish/ra3.skirmish.cppm` | units, economy, AI, combat, win condition |
+| `src/skirmish/ra3.skirmish.cppm` | base building, economy, AI, combat, win condition |
-| `src/render/ra3.render.cppm` | ARGB framebuffer, TGA decode, BMP encode, map compositing |
+| `src/terrain/ra3.terrain.cppm` | `CkMp` terrain: `HeightMapData`, `BlendTileData` (tiles + blends), `Terrain.big` tiles |
-| `src/ui/ra3.ui.*.cppm` | SDL3 window viewer (null backend when SDL3 is absent) |
+| `src/models/ra3.models.cppm` | compiled `W3DMesh` art (BAB stream + DDS textures) for the objects a map places |
+| `src/render/ra3.render.cppm` | ARGB framebuffer, TGA decode, BMP encode, map compositing, bitmap-font text |
+| `src/ui/ra3.ui.*.cppm` | SDL3 window viewer and menu (null backend when SDL3 is absent) |
+| `src/vulkan/ra3.vulkan.*.cppm` | Vulkan presentation backend and menu (null fallback without a loader) |
+| `src/dx/ra3.dx.*.cppm` | Direct3D 11/12 presentation backend (runtime HLSL; null fallback off Windows) |
+| `src/wasmgl/ra3.wasmgl.*.cppm` | SDL-free wasm backend: engine on a Web Worker, WebGL2 on an OffscreenCanvas, lazy assets (null fallback off Emscripten) |
+| `src/webgpu/ra3.webgpu.*.cppm` | WebGPU wasm backend (Dawn `emdawnwebgpu`, WGSL; the default on wasm, falls back to `ra3.wasmgl`) |
+| `third_party/libenderlog/` | vendored C++26 module logger (`import ender.log;`, MIT) with a native stack fallback for libc++ |
 | `src/ra3.cppm` | umbrella module re-exporting the SDK |
-| `apps/openra3/main.cpp` | `maps` / `skirmish` CLI |
+| `apps/openra3/main.cpp` | `menu` / `maps` / `skirmish` / `render` CLI |
 | `tests/ra3_tests.cpp` | smoke tests (run via `ctest`) |
 | `tools/` | reference fetch + Ghidra-driven reconstruction helpers |
-| `docs/` | architecture, reverse-engineering notes, roadmap |
+| `docs/` | architecture & master plan, reverse-engineering notes |
-| `Dockerfile` | `dev` (toolchain) and `deploy` (runtime) targets |
+| `Dockerfile` | Linux build image (`dev` toolchain + `deploy` runtime) |
-| `.gitlab-ci.yml` | build → test → package pipeline |
+| `Dockerfile.win` | isolated Windows cross-build image (llvm-mingw + SDL3 MinGW) |
+| `cmake/toolchains/` | `llvm-mingw-x86_64.cmake` cross toolchain |
+| `scripts/` | `build-linux.sh` / `build-windows.sh` one-shot builders |
+| `.gitlab-ci.yml` | build both targets → test → package pipeline |
+
+## Why Clang + `import std;`
+
+The engine never `#include`s the standard library: every module does
+`import std;`. CMake's support for that (`CXX_MODULE_STD`) works today with
+Clang + libc++. Linux uses the distro clang (LLVM 21); Windows cross-compiles
+with [llvm-mingw](https://github.com/mstorsjo/llvm-mingw) (clang 23 + libc++ +
+the libc++ `std` module). The two toolchains live in **separate images** so
+their compilers and standard libraries never interfere.
 
 ## Build
 
-The host needs no toolchain: build inside the container.
+The host needs no toolchain: each target builds inside its own image.
 
 ```bash
-docker build --target dev -t openra3-dev:local .
+# Linux (amd64)   -> build/linux/bin/openra3 + .deb
+scripts/build-linux.sh
 
-docker run --rm -v "$PWD:/work" -w /work openra3-dev:local cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
+# Linux/arm64     -> build/linux-arm64/bin/openra3 + .deb   (cross)
-docker run --rm -v "$PWD:/work" -w /work openra3-dev:local cmake --build build -j
+scripts/build-linux-arm64.sh
-docker run --rm -v "$PWD:/work" -w /work openra3-dev:local ctest --test-dir build --output-on-failure
+
+# Debian (amd64)  -> build/debian/bin/openra3 + .deb
+scripts/build-debian.sh
+
+# Debian (arm64)  -> build/debian-arm64/bin/openra3 + .deb   (cross)
+scripts/build-debian-arm64.sh
+
+# Windows (x86_64) -> build/windows/bin/openra3.exe + SDL3.dll, .zip, .msi
+scripts/build-windows.sh
+
+# Windows (arm64)  -> build/windows-arm64/bin/openra3.exe + SDL3.dll, .zip   (cross)
+scripts/build-windows-arm64.sh
+
+# WebAssembly      -> build/wasm/bin/index.html (+ openra3.js/.wasm, openra3.worker.js)
+scripts/build-wasm.sh
+```
+
+Every target is cross-built from x86_64 Linux in its own image: llvm-mingw for
+the Windows targets, clang + libc++ with dpkg multiarch for the arm64 targets,
+and Debian/Ubuntu-specific images for the `.deb` packages.
+
+Or drive Docker directly:
+
+```bash
+docker build --target dev -t openra3-linux:local .
+docker run --rm -v "$PWD:/work" -w /work openra3-linux:local \
+    cmake -S . -B build/linux -G Ninja -DCMAKE_BUILD_TYPE=Release
+docker run --rm -v "$PWD:/work" -w /work openra3-linux:local cmake --build build/linux -j
+docker run --rm -v "$PWD:/work" -w /work openra3-linux:local ctest --test-dir build/linux --output-on-failure
+
+docker build -f Dockerfile.win --target dev -t openra3-windows:local .
+docker run --rm -v "$PWD:/work" -w /work openra3-windows:local \
+    cmake -S . -B build/windows -G Ninja \
+        -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/llvm-mingw-x86_64.cmake \
+        -DCMAKE_BUILD_TYPE=Release
+docker run --rm -v "$PWD:/work" -w /work openra3-windows:local cmake --build build/windows -j
 ```
 
 Behind a slow or blocked mirror, pass `--build-arg APT_MIRROR=<url>`.
 
+The two images are deliberately separate so the Linux (clang + libc++) and
+Windows (llvm-mingw + MinGW SDL3) toolchains never interfere. The Windows demo
+is `build/windows/bin/openra3.exe` next to `SDL3.dll`:
+
+```powershell
+# show a real map in a Vulkan window
+openra3.exe render --game-dir "C:\Red Alert 3" --vulkan
+```
+
+Vulkan is provided by **vendored volk + headers** (`third_party/`), resolved at
+runtime, so neither image needs a Vulkan SDK.
+
+## WebAssembly
+
+OpenRA3 also builds to **WebAssembly** with Emscripten (`scripts/build-wasm.sh`),
+producing `openra3.js` + `.wasm` plus the `index.html` page and
+`openra3.worker.js` bootstrap. The browser gets the same GPU renderer as the
+desktop builds: the engine runs on a **Web Worker** (no SDL, no blocking of the
+page) and draws into an **OffscreenCanvas** handed over by the page. The default
+wasm backend is **`ra3.webgpu`** (WebGPU, WGSL shaders via Emscripten's
+`emdawnwebgpu` port); it falls back to **`ra3.wasmgl`** (WebGL2, the GLSL ES
+ports of the desktop shaders) when WebGPU is unavailable. The page keeps the DOM
+(input, resize) and forwards events to the worker, so the main thread stays
+responsive.
+
+Because the runtime's main thread lives in the worker, its filesystem is local
+to it and assets load **on demand**: point `OPENRA3_WEB_ASSETS` at the extracted
+asset tree and the build embeds an `assets.manifest.json`; at startup the worker
+registers every listed file as a lazy file, so the browser fetches a file only
+when the engine first opens it (entering a map pulls just that map and the tiles
+it uses, not the whole tree).
+
+```bash
+# build (generates the manifest from the extracted assets, embeds it)
+OPENRA3_WEB_ASSETS=/path/to/assets scripts/build-wasm.sh
+
+# serve the build output (Range-capable, COOP/COEP; --assets is the lazy tree)
+python3 apps/web/serve.py --root build/wasm/bin --assets /path/to/assets
+# open http://localhost:8199/index.html
+```
+
+The engine's frame loops are blocking; the wasm build yields to the worker's
+event loop via Asyncify (`display::sleep_frame` calls `emscripten_sleep`), so
+the page repaints and handles input. Log records go to `console.log` at their
+real level (the console sink uses stdout on the web instead of stderr). Without
+`OPENRA3_WEB_ASSETS` the module still loads and starts, but exits at the menu
+because no maps are found.
+
+## Packages
+
+CPack produces the release artifacts; the Docker images and CI run it for every
+target.
+
+| Target | Portable | Installer |
+| --- | --- | --- |
+| Linux amd64 (Ubuntu 26.04) | `.tar.gz` | `openra3_<v>_amd64ubuntu26.04.deb` |
+| Linux arm64 (Ubuntu 26.04) | `.tar.gz` | `openra3_<v>_arm64ubuntu26.04.deb` |
+| Linux amd64 (Debian 13) | `.tar.gz` | `openra3_<v>_amd64debian13.deb` |
+| Linux arm64 (Debian 13) | `.tar.gz` | `openra3_<v>_arm64debian13.deb` |
+| Windows x86_64 | `openra3-<v>-windows-x86_64.zip` | `openra3-<v>-windows-x86_64.msi` |
+| Windows arm64 | `openra3-<v>-windows-arm64.zip` | (WiX-only; see below) |
+
+The `.deb` dependencies are derived from the binary with `dpkg-shlibdeps`. The
+`.msi` is built with **wixl** (msitools) straight from the Linux cross image;
+wixl 0.106 has no arm64 support, so Windows/ARM64 ships the portable `.zip`
+(the MSI toolchain for ARM64 would be WiX v4 via the .NET SDK).
+
+## Logging
+
+Every run writes `openra3.log` in a per-user `logs/` folder — on Windows
+`%LOCALAPPDATA%\OpenRA3\logs`, elsewhere `$XDG_STATE_HOME/openra3/logs`
+(falling back to `~/.local/state/openra3/logs`) — created on first use and kept
+out of the binary's own directory, through the vendored
+[`libenderlog`](third_party/libenderlog) module (`import ender.log;`). A file
+sink archives the previous log to `openra3.<YYYYmmdd-HHMMSS>.log` on open, so
+each run gets its own file; the active file rotates at 4 MiB and the last 10
+archives are kept. Records at **`warn` and above** carry a call stack (Windows
+`CaptureStackBackTrace` / POSIX `execinfo`, because libc++ has no
+`<stacktrace>`). A hard crash also writes `openra3_crash.log` alongside it with
+the faulting module and a raw backtrace.
+
 ## Running a skirmish
 
 ```bash
 # list the maps in your install
-docker run --rm -v "/path/to/Red Alert 3:/game:ro" openra3-dev:local \
+docker run --rm -v "/path/to/Red Alert 3:/game:ro" openra3-linux:local \
-    ./build/bin/openra3 maps --game-dir /game
+    /work/build/linux/bin/openra3 maps --game-dir /game
 
 # play a headless skirmish on a real map
-docker run --rm -v "/path/to/Red Alert 3:/game:ro" openra3-dev:local \
+docker run --rm -v "/path/to/Red Alert 3:/game:ro" openra3-linux:local \
-    ./build/bin/openra3 skirmish --game-dir /game --map map_mp_2_feasel4 --seed 7
+    /work/build/linux/bin/openra3 skirmish --game-dir /game --map map_mp_2_feasel4 --seed 7
 ```
 
+The Windows build is a native `openra3.exe` — copy it next to `SDL3.dll` and run
+it from `cmd`/PowerShell, e.g. `openra3.exe skirmish --game-dir "C:\Red Alert 3"`.
+
 `--frames N` caps the simulation length (default 15 minutes of game time at
 30 Hz). The result is deterministic for a given map and seed.
 
+## Menu
+
+Run `openra3` with no arguments (or `openra3 menu`) to open a window listing the
+maps by their **localized display name** (read from the install's
+`gamestrings.csf`, e.g. `map_mp_2_feasel4` → "Battlebase Beta") with their id
+below. The `Options` column exposes every `render`/`skirmish` parameter — mode
+(3D terrain / top-down / skirmish), window size, camera pitch/yaw/height, FOV,
+zoom, terrain scale, terrain pitch, world size, seed, frame cap, the overview
+thumbnail toggle and a BMP output path. `Up`/`Down` selects, `Left`/`Right`
+changes a value (or moves the text caret on the BMP field), `Tab` switches
+between the map list and the options, `Enter` starts and `Esc` quits. Starting a
+3D or top-down view opens the viewer; closing it returns to the menu. When no
+window backend is available the same flow falls back to a console picker, and
+`openra3 menu-preview` renders one menu frame to a BMP for inspection.
+
 ## Rendering the map
 
-The renderer draws the map's own overview art, a world grid and the match state
+`render` draws the **real terrain**: it parses the map's `HeightMapData`
-(start markers in yellow, player 0 in blue, player 1 in red).
+(elevation grid) and `BlendTileData` (per-cell tile index plus the per-cell
+`Blends`/`ThreeWayBlends` and their `BlendDescription`s), loads the tile
+textures from `Data\Terrain.big` (RefPack + TGA), and rasterises the map with an
+elevation shade. Each cell cross-fades into its blend neighbour with the same
+linear ramp the retail `Terrain.fx` uses, so material transitions are smooth; on
+the GPU path the tile atlas is padded with a replicated gutter so filtering
+never bleeds between tiles. It also draws the **buildings and props the map
+places**: the `ObjectsList` chunk is decoded into `(type, position, angle)`
+instances, the type resolves to its compiled `W3DMesh` parts in the map's art
+stream (`Data\WBData.big`'s uncompressed `worldbuilder.bin`), the embedded DDS
+textures are decoded, bind-pose skinning places each mesh's bone-space vertices
+(`W3DHierarchy`), and the scene is flattened into one world-space triangle soup.
+The terrain raymarcher writes a depth value so the model pass depth-tests
+against the relief; the GPU path draws it in a second pipeline (shared camera
+basis, with a small depth bias so ground decals do not z-fight) and the software
+path rasterises it with a z-buffer. Match state is
+overlaid (start markers in yellow, player 0 in blue, player 1 in red).
+`--thumbnail` uses the old `<map>_art.tga` overview instead.
+
+> **Roads / sidewalks** are drawn too: the map stores each as a
+> `RoadType::Start`/`End` pair of objects, and `render` emits a flat textured
+> ribbon along each segment, lifted onto the terrain with a small depth bias so
+> it does not clip into the ground.
 
 **Offscreen image** (works anywhere, no display needed):
 
 ```bash
-docker run --rm -v "/path/to/Red Alert 3:/game:ro" -v "$PWD/out:/out" openra3-dev:local \
+docker run --rm -v "/path/to/Red Alert 3:/game:ro" -v "$PWD/out:/out" openra3-linux:local \
-    /work/build/bin/openra3 render --game-dir /game --map map_mp_2_feasel4 --out /out/map.bmp
+    /work/build/linux/bin/openra3 render --game-dir /game --map map_mp_2_feasel4 --out /out/map.bmp
 ```
 
-**Interactive window** (SDL3; drag to pan, wheel to zoom, Esc to quit). In a
+On Windows the same command runs natively: `openra3.exe render --game-dir
-container you need an X server on the host — on Windows run
+"C:\Red Alert 3" --map map_mp_2_feasel4` opens an SDL3 window.
+
+**Interactive window** (Vulkan with `--vulkan`, otherwise SDL3). The camera
+follows the retail tactical view: it opens centred on the first player's start,
+the wheel zooms, pushing the cursor against a screen edge scrolls, dragging with
+the left button pans, and Esc quits. `--zoom Z` sets the initial zoom (1 fits
+the whole map). In a container you need an X server on the host — on Windows run
 [VcXsrv](https://sourceforge.net/projects/vcxsrv/) and launch it with "Disable
 access control", then:
 
 ```bash
 docker run --rm -v "/path/to/Red Alert 3:/game:ro" -e DISPLAY=host.docker.internal:0.0 \
-    openra3-dev:local /work/build/bin/openra3 render --game-dir /game --map map_mp_2_feasel4
+    openra3-linux:local /work/build/linux/bin/openra3 render --game-dir /game --map map_mp_2_feasel4
 ```
 
 If no display is available the viewer falls back to writing `openra3_view.bmp`.

VERSION

@@ -1 +1 @@
-0.1.0
+0.10.1

apps/web/index.html

@@ -0,0 +1,101 @@
+<!doctype html>
+<!-- OpenRA3 web page. The engine runs inside openra3.worker.js: the page owns the
+     DOM (input, resize) and transfers #canvas to the worker as an OffscreenCanvas,
+     so the engine never blocks the main thread. -->
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
+    <title>OpenRA3</title>
+    <style>
+        html, body { margin: 0; height: 100%; background: #1a0a08; overflow: hidden; }
+        #canvas { display: block; width: 100vw; height: 100vh; outline: none; cursor: default; }
+        #loading { position: absolute; inset: 0; display: flex; align-items: center; justify-content: center;
+                   color: #ecbe50; font: 16px/1.4 monospace; pointer-events: none; }
+    </style>
+</head>
+<body>
+    <canvas id="canvas" tabindex="-1" oncontextmenu="event.preventDefault()"></canvas>
+    <div id="loading">Loading OpenRA3…</div>
+    <script>
+        (function () {
+            var canvas = document.getElementById('canvas');
+            var loading = document.getElementById('loading');
+            // `?nocache` busts the worker, module and wasm fetches (development),
+            // so a rebuild is picked up without clearing the browser cache.
+            var bust = location.search.indexOf('nocache') >= 0 ? Date.now() : 0;
+            var worker = new Worker('openra3.worker.js' + (bust ? '?v=' + bust : ''));
+
+            var ready = false;
+            var pending = []; // input queued until the runtime is up
+
+            function post(message) {
+                if (ready) {
+                    worker.postMessage(message);
+                } else {
+                    pending.push(message);
+                }
+            }
+
+            function backingSize() {
+                var dpr = window.devicePixelRatio || 1;
+                return {
+                    width: Math.max(1, Math.round(window.innerWidth * dpr)),
+                    height: Math.max(1, Math.round(window.innerHeight * dpr)),
+                };
+            }
+
+            worker.onmessage = function (event) {
+                var data = event.data || {};
+                if (data.log) { console.log(data.log); return; }
+                if (data.ready) {
+                    ready = true;
+                    if (loading) loading.remove();
+                    for (var i = 0; i < pending.length; i++) worker.postMessage(pending[i]);
+                    pending = [];
+                    return;
+                }
+                if (typeof data.openra3Frames === 'number') { window.openra3Frames = data.openra3Frames; }
+            };
+
+            // Hand the canvas to the worker as an OffscreenCanvas. After this the
+            // page can no longer size or draw it; the worker owns it.
+            var size = backingSize();
+            var offscreen = canvas.transferControlToOffscreen();
+            worker.postMessage({ canvas: offscreen, width: size.width, height: size.height, bust: bust }, [offscreen]);
+
+            // ---- input: the page owns the DOM, the worker owns the game --------
+            window.addEventListener('keydown', function (event) {
+                post({ type: 'key', code: event.code, down: true });
+                if (event.code === 'Tab' || event.code === 'Space' || event.code.indexOf('Arrow') === 0) event.preventDefault();
+            }, false);
+            window.addEventListener('keyup', function (event) {
+                post({ type: 'key', code: event.code, down: false });
+            }, false);
+            window.addEventListener('keypress', function (event) {
+                if (event.charCode) post({ type: 'text', char: event.charCode });
+            }, false);
+
+            canvas.addEventListener('mousedown', function (event) {
+                post({ type: 'mousebutton', x: event.clientX, y: event.clientY, left: event.button === 0 });
+            }, false);
+            window.addEventListener('mousemove', function (event) {
+                post({ type: 'mousemove', x: event.clientX, y: event.clientY, dx: event.movementX, dy: event.movementY,
+                       left: (event.buttons & 1) !== 0 });
+            }, false);
+            window.addEventListener('wheel', function (event) {
+                post({ type: 'wheel', deltaY: event.deltaY });
+            }, { passive: true });
+            window.addEventListener('contextmenu', function (event) { event.preventDefault(); });
+
+            window.addEventListener('resize', function () {
+                var next = backingSize();
+                post({ type: 'resize', width: next.width, height: next.height });
+            });
+            window.addEventListener('beforeunload', function () {
+                if (ready) worker.postMessage({ type: 'quit' });
+            });
+        })();
+    </script>
+</body>
+</html>

apps/web/openra3.worker.js

@@ -0,0 +1,114 @@
+'use strict';
+// OpenRA3 WebAssembly worker bootstrap.
+//
+// The whole Emscripten runtime runs here (not on the page main thread), so the
+// runtime's filesystem is local to this worker: `FS.createLazyFile` can use
+// synchronous XHR to fetch assets on demand without blocking the page.
+//
+// Protocol with index.html:
+//   page -> worker  { canvas, width, height }   (once, transfers the OffscreenCanvas)
+//   page -> worker  { type: 'key' | 'text' | 'mousebutton' | 'mousemove' | 'wheel' | 'resize' | 'quit', ... }
+//   worker -> page  { log } | { ready } | { openra3Frames }
+//
+// The Emscripten runtime is started by importScripts('openra3.js') once the
+// canvas has arrived; main() then runs here and yields via Asyncify.
+
+// Forward worker warnings/errors (including WebGPU validation messages from the
+// runtime) to the page, which logs them to the main console.
+(function () {
+    var origError = console.error.bind(console);
+    var origWarn = console.warn.bind(console);
+    console.error = function () {
+        origError.apply(null, arguments);
+        try { self.postMessage({ log: '[worker error] ' + Array.prototype.join.call(arguments, ' ') }); } catch (e) {}
+    };
+    console.warn = function () {
+        origWarn.apply(null, arguments);
+        try { self.postMessage({ log: '[worker warn] ' + Array.prototype.join.call(arguments, ' ') }); } catch (e) {}
+    };
+})();
+
+self.Module = {
+    print: function (text) {
+        self.postMessage({ log: String(text) });
+    },
+    printErr: function (text) {
+        self.postMessage({ log: String(text) });
+    },
+    onRuntimeInitialized: function () {
+        self.postMessage({ ready: true });
+    },
+};
+
+var openra3Started = false;
+
+self.onmessage = function (event) {
+    var data = event.data;
+    if (!data) return;
+
+    if (!openra3Started) {
+        if (!data.canvas) return;
+        openra3Started = true;
+        var canvas = data.canvas;
+        if (data.width && data.height) {
+            canvas.width = data.width;
+            canvas.height = data.height;
+        }
+        self.Module.canvas = canvas;
+
+        var start = function () {
+            // `?nocache` on the page forces a fresh module + wasm fetch, so a
+            // rebuild is picked up without clearing the browser cache.
+            var bust = data.bust ? ('?v=' + data.bust) : '';
+            if (bust) self.Module.locateFile = function (path) { return path + bust; };
+            try {
+                importScripts('openra3.js' + bust);
+            } catch (error) {
+                self.postMessage({ log: 'OpenRA3 worker failed to start: ' + error });
+            }
+        };
+
+        // The WebGPU backend starts from a device created here (`Module.
+        // preinitializedWebGPUDevice`); the WebGL backend ignores it. If WebGPU
+        // is unavailable the runtime falls back to WebGL.
+        if (typeof navigator !== 'undefined' && navigator.gpu) {
+            navigator.gpu.requestAdapter().then(function (adapter) {
+                if (!adapter) { start(); return; }
+                adapter.requestDevice().then(function (device) {
+                    self.Module.preinitializedWebGPUDevice = device;
+                    start();
+                }).catch(start);
+            }).catch(start);
+        } else {
+            start();
+        }
+        return;
+    }
+
+    // Input is only meaningful once the runtime has initialized its exports.
+    switch (data.type) {
+    case 'key':
+        if (self.Module.ccall) self.Module.ccall('openra3_key', null, ['string', 'number'], [data.code, data.down ? 1 : 0]);
+        break;
+    case 'text':
+        if (self.Module._openra3_text) self.Module._openra3_text(data.char | 0);
+        break;
+    case 'mousebutton':
+        if (self.Module._openra3_mouse_button) self.Module._openra3_mouse_button(data.x, data.y, data.left ? 1 : 0);
+        break;
+    case 'mousemove':
+        if (self.Module._openra3_mouse_move) self.Module._openra3_mouse_move(data.x, data.y, data.dx, data.dy, data.left ? 1 : 0);
+        break;
+    case 'wheel':
+        if (self.Module._openra3_wheel) self.Module._openra3_wheel(data.deltaY);
+        break;
+    case 'resize':
+        if (self.Module._openra3_resize) self.Module._openra3_resize(data.width | 0, data.height | 0);
+        break;
+    case 'quit':
+        if (self.Module._openra3_quit) self.Module._openra3_quit();
+        break;
+    default:
+        break;
+    }
+};

apps/web/serve.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""Static file server with HTTP Range support, for the OpenRA3 wasm build.
+
+Emscripten's lazy file reads stream assets back as byte ranges, so the server
+must honour the ``Range`` header -- Python's stdlib ``http.server`` does not.
+
+    python3 apps/web/serve.py --root build/wasm/bin --port 8199
+    # then open http://localhost:8199/index.html
+
+Serve ``--root`` containing ``index.html``, ``openra3.js``, ``openra3.wasm``,
+``openra3.worker.js`` and ``assets.manifest.json``. The lazy asset tree is
+mounted from ``--assets`` (its files are then fetched from ``/assets/<rel>`` on
+demand); without ``--assets`` the tree is expected under ``--root`` itself.
+"""
+
+import argparse
+import functools
+import os
+import re
+import sys
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+
+_RANGE = re.compile(r"bytes=(\d*)-(\d*)$")
+
+
+class RangeHandler(SimpleHTTPRequestHandler):
+    # Directory served for ``/assets/...`` (set in main); None means "under root".
+    assets_dir = None
+
+    def translate_path(self, path):
+        if self.assets_dir:
+            prefix = "/assets/"
+            if path == "/assets" or path.startswith(prefix):
+                rel = path[len(prefix):] if path.startswith(prefix) else ""
+                rel = rel.split("?", 1)[0].split("#", 1)[0]
+                parts = [p for p in rel.split("/") if p and p != ".."]
+                return os.path.join(self.assets_dir, *parts)
+        return super().translate_path(path)
+
+    # Cross-origin isolation (kept for SharedArrayBuffer-style features and the
+    # WebGPU/pthread paths). no-store keeps the dev loop honest: a stale
+    # openra3.js/.wasm in the browser cache hides new builds (the worker's
+    # importScripts especially).
+    def end_headers(self):
+        self.send_header("Cross-Origin-Opener-Policy", "same-origin")
+        self.send_header("Cross-Origin-Embedder-Policy", "require-corp")
+        self.send_header("Cache-Control", "no-store, max-age=0")
+        super().end_headers()
+
+    def send_head(self):
+        header = self.headers.get("Range")
+        if not header:
+            return super().send_head()
+
+        path = self.translate_path(self.path)
+        if os.path.isdir(path):
+            return super().send_head()
+        try:
+            handle = open(path, "rb")
+        except OSError:
+            self.send_error(404, "File not found")
+            return None
+
+        match = _RANGE.match(header.strip())
+        if not match:
+            handle.close()
+            return super().send_head()
+
+        size = os.fstat(handle.fileno()).st_size
+        start = int(match.group(1)) if match.group(1) else 0
+        end = int(match.group(2)) if match.group(2) else size - 1
+        if start > end or start >= size:
+            handle.close()
+            self.send_error(416, "Requested Range Not Satisfiable")
+            return None
+        end = min(end, size - 1)
+
+        self.send_response(206)
+        self.send_header("Content-Type", self.guess_type(path))
+        self.send_header("Accept-Ranges", "bytes")
+        self.send_header("Content-Range", f"bytes {start}-{end}/{size}")
+        self.send_header("Content-Length", str(end - start + 1))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        handle.seek(start)
+        self._remaining = end - start + 1
+        return handle
+
+    def copyfile(self, source, outputfile):
+        remaining = getattr(self, "_remaining", None)
+        if remaining is None:
+            return super().copyfile(source, outputfile)
+        try:
+            while remaining > 0:
+                chunk = source.read(min(65536, remaining))
+                if not chunk:
+                    break
+                outputfile.write(chunk)
+                remaining -= len(chunk)
+        finally:
+            self._remaining = None
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="OpenRA3 wasm dev server")
+    parser.add_argument("--root", default="build/wasm/bin", help="directory to serve")
+    parser.add_argument("--assets", default=None, help="directory served for /assets (the lazy asset tree)")
+    parser.add_argument("--port", type=int, default=8199)
+    parser.add_argument("--bind", default="127.0.0.1")
+    args = parser.parse_args()
+
+    if not os.path.isdir(args.root):
+        print(f"root not found: {args.root}", file=sys.stderr)
+        return 1
+    if args.assets and not os.path.isdir(args.assets):
+        print(f"assets not found: {args.assets}", file=sys.stderr)
+        return 1
+    RangeHandler.assets_dir = os.path.abspath(args.assets) if args.assets else None
+    handler = functools.partial(RangeHandler, directory=args.root)
+    server = ThreadingHTTPServer((args.bind, args.port), handler)
+    print(f"serving {args.root} at http://{args.bind}:{args.port}/index.html")
+    if RangeHandler.assets_dir:
+        print(f"  /assets -> {RangeHandler.assets_dir}")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cmake/extract_assets.cmake

@@ -0,0 +1,54 @@
+# Extract the retail assets into OUT using the ra3tools scripts. Driven by the
+# openra3_assets target and run with `cmake -P`, so it needs only Python and the
+# game install - no target executable, and therefore works for a cross-build too
+# (mount the install into the container and pass RA3_GAME_DIR).
+#
+# Variables (all required unless noted):
+#   GAME_DIR     Red Alert 3 install root
+#   OUT          destination folder (next to the executable)
+#   PYTHON       python interpreter
+#   RA3TOOLS     path to ra3-headless/ra3tools
+#   EXTRACT_ALL  ON to also dump every asset (models/textures/audio/movies)
+#   STAMP        stamp file to write on completion
+
+function(run)
+    execute_process(COMMAND ${ARGN} RESULT_VARIABLE _rc)
+    if(NOT _rc EQUAL 0)
+        message(WARNING "extract step failed (${_rc}): ${ARGN}")
+    endif()
+endfunction()
+
+file(MAKE_DIRECTORY "${OUT}")
+
+if(NOT EXISTS "${RA3TOOLS}/ra3_big.py")
+    message(WARNING "ra3tools not found at '${RA3TOOLS}'; skipping asset extraction")
+else()
+    # Maps + overview art: raw .big payloads; the engine unwraps EAR/RefPack.
+    run("${PYTHON}" "${RA3TOOLS}/ra3_big.py" extract "${GAME_DIR}/Data/MapsMultiplayer.big" --match "*.map" --out "${OUT}/maps")
+    run("${PYTHON}" "${RA3TOOLS}/ra3_big.py" extract "${GAME_DIR}/Data/MapsMultiplayer.big" --match "*_art.tga" --out "${OUT}/maps")
+
+    # Terrain tile textures (the engine samples these for the map).
+    foreach(archive Terrain.big Core11.big)
+        if(EXISTS "${GAME_DIR}/Data/${archive}")
+            run("${PYTHON}" "${RA3TOOLS}/ra3_big.py" extract "${GAME_DIR}/Data/${archive}" --match "*.tga" --out "${OUT}/terrain")
+        endif()
+    endforeach()
+
+    if(EXTRACT_ALL)
+        message(STATUS "extracting every .big entry to ${OUT}/raw")
+        run("${PYTHON}" "${RA3TOOLS}/ra3_big.py" extract-all --game-dir "${GAME_DIR}" --out "${OUT}/raw" --match "*")
+
+        if(EXISTS "${RA3TOOLS}/ra3_binary.py")
+            message(STATUS "extracting models + textures (static stream)")
+            run("${PYTHON}" "${RA3TOOLS}/ra3_binary.py" export "${GAME_DIR}/Data/StaticStream.big" --models --textures --png --by-source --out "${OUT}/art")
+
+            message(STATUS "extracting audio (sound effects + voice)")
+            run("${PYTHON}" "${RA3TOOLS}/ra3_binary.py" export "${GAME_DIR}/Data/EnglishAudio.big" --stream audio --audio --out "${OUT}/audio")
+
+            message(STATUS "extracting movie audio")
+            run("${PYTHON}" "${RA3TOOLS}/ra3_big.py" extract "${GAME_DIR}/Data/EnglishMovieAudio.big" --match "*.snd" --out "${OUT}/movies")
+        endif()
+    endif()
+endif()
+
+file(TOUCH "${STAMP}")

cmake/packaging/openra3.wxs.in

@@ -0,0 +1,39 @@
+<?xml version='1.0' encoding='utf-8'?>
+<!--
+  Windows Installer source for OpenRA3, driven by wixl (msitools) so the Linux
+  cross-build image can produce the .msi. `exe` and `dll` are passed with
+  wixl -D; the version is substituted at configure time.
+-->
+<Wix xmlns='http://schemas.microsoft.com/wix/2006/wi'>
+  <Product Id='*'
+           Name='OpenRA3'
+           Language='1033'
+           Version='@PROJECT_VERSION@'
+           Manufacturer='OpenRA3'
+           UpgradeCode='6C6B1F4E-0B9A-4C2E-9E2A-2E4D7B5C1A31'>
+    <Package Id='*' InstallerVersion='500' Compressed='yes' InstallScope='perMachine'/>
+    <Media Id='1' Cabinet='openra3.cab' EmbedCab='yes'/>
+
+    <Directory Id='TARGETDIR' Name='SourceDir'>
+      <Directory Id='ProgramFiles64Folder'>
+        <Directory Id='INSTALLFOLDER' Name='OpenRA3'>
+          <Component Id='MainExecutable' Guid='1F2E3D4C-5B6A-4798-8C1D-2E3F4A5B6C7D'>
+            <File Id='OpenRA3Exe' Name='openra3.exe' Source='$(var.exe)' KeyPath='yes'>
+              <Shortcut Id='StartMenuShortcut' Directory='ProgramMenuFolder' Name='OpenRA3'
+                        WorkingDirectory='INSTALLFOLDER' Advertise='no'/>
+            </File>
+          </Component>
+          <Component Id='SdlRuntime' Guid='2A3B4C5D-6E7F-4809-9D2E-3F4A5B6C7D8E'>
+            <File Id='Sdl3Dll' Name='SDL3.dll' Source='$(var.dll)' KeyPath='yes'/>
+          </Component>
+        </Directory>
+      </Directory>
+      <Directory Id='ProgramMenuFolder'/>
+    </Directory>
+
+    <Feature Id='Main' Title='OpenRA3' Level='1'>
+      <ComponentRef Id='MainExecutable'/>
+      <ComponentRef Id='SdlRuntime'/>
+    </Feature>
+  </Product>
+</Wix>

cmake/toolchains/clang-aarch64-linux-gnu.cmake

@@ -0,0 +1,53 @@
+# Cross-compile for Linux on ARM64 (aarch64-linux-gnu) from x86_64.
+#
+# clang-21 + libc++ (for `import std;`) with the arm64 libc++ and SDL3 taken
+# from Ubuntu's arm64 packages (installed with dpkg multiarch), and the arm64
+# glibc headers/libs from `gcc-aarch64-linux-gnu`. lld links the result; the C
+# multiarch include directory is added explicitly because clang does not always
+# infer Debian's `bits/` layout from the target triple alone.
+
+# The `import std` gate must be set before the compiler is probed; a toolchain
+# file is processed earlier than the project's own top-level settings.
+set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD "d0edc3af-4c50-42ea-a356-e2862fe7a444")
+
+set(CMAKE_SYSTEM_NAME Linux)
+set(CMAKE_SYSTEM_PROCESSOR aarch64)
+
+set(OPENRA3_AARCH64_TRIPLE "aarch64-linux-gnu")
+# Multiarch paths the arm64 packages install into.
+set(OPENRA3_AARCH64_INCLUDE "/usr/include/${OPENRA3_AARCH64_TRIPLE}")
+set(OPENRA3_AARCH64_LIB "/usr/lib/${OPENRA3_AARCH64_TRIPLE}")
+
+# Compiler + libc++ module description are cache vars so a distro with a
+# differently-versioned clang (e.g. Debian's clang-19) can override on the
+# command line.
+set(OPENRA3_AARCH64_CC "clang-21" CACHE STRING "aarch64 C compiler")
+set(OPENRA3_AARCH64_CXX "clang++-21" CACHE STRING "aarch64 C++ compiler")
+set(OPENRA3_AARCH64_STDLIB_MODULES_JSON "/usr/lib/llvm-21/lib/libc++.modules.json" CACHE FILEPATH
+    "libc++ std module description for the aarch64 target")
+
+set(CMAKE_C_COMPILER ${OPENRA3_AARCH64_CC})
+set(CMAKE_CXX_COMPILER ${OPENRA3_AARCH64_CXX})
+set(CMAKE_C_COMPILER_TARGET ${OPENRA3_AARCH64_TRIPLE})
+set(CMAKE_CXX_COMPILER_TARGET ${OPENRA3_AARCH64_TRIPLE})
+# CMake's standard-library detection does not pass COMPILER_TARGET, so without
+# this it probes the host standard library.
+set(CMAKE_C_COMPILER_ARG1 "--target=${OPENRA3_AARCH64_TRIPLE}")
+set(CMAKE_CXX_COMPILER_ARG1 "--target=${OPENRA3_AARCH64_TRIPLE}")
+
+# libc++ standard-library module description for the aarch64 target. On a
+# multiarch image only the arm64 libc++ is installed, so the standard path
+# already resolves to the aarch64 module description.
+set(CMAKE_CXX_STDLIB_MODULES_JSON "${OPENRA3_AARCH64_STDLIB_MODULES_JSON}")
+
+# Strip with the cross binutils, so CPack can strip the arm64 binary.
+set(CMAKE_STRIP aarch64-linux-gnu-strip)
+
+set(CMAKE_C_FLAGS_INIT "-isystem ${OPENRA3_AARCH64_INCLUDE}")
+set(CMAKE_CXX_FLAGS_INIT "-stdlib=libc++ -isystem ${OPENRA3_AARCH64_INCLUDE}")
+set(CMAKE_EXE_LINKER_FLAGS_INIT "-stdlib=libc++ -fuse-ld=lld -L${OPENRA3_AARCH64_LIB}")
+set(CMAKE_SHARED_LINKER_FLAGS_INIT "-stdlib=libc++ -fuse-ld=lld -L${OPENRA3_AARCH64_LIB}")
+
+# Run arm64 test binaries through qemu when it is installed, so `ctest` works
+# during the image build; harmless when the tests are only cross-compiled.
+set(CMAKE_CROSSCOMPILING_EMULATOR qemu-aarch64-static)

cmake/toolchains/emscripten-wasm.cmake

@@ -0,0 +1,55 @@
+# WebAssembly cross-build via Emscripten.
+#
+# Includes Emscripten's own platform toolchain (found through $EMSDK, set by the
+# emsdk image / `emsdk_env.sh`) and then layers the project's requirements:
+#
+#  * C++26 `import std;`. Emscripten ships the libc++ `std` module source and a
+#    modules.json in its sysroot; its toolchain wires that up, but only if
+#    `CMAKE_CXX_MODULE_STD` is on and no std-modules JSON has been set yet, so
+#    both are arranged before Emscripten.cmake is included and before the
+#    compiler is probed.
+#  * Global `-fexceptions`. Emscripten disables exceptions by default, and the
+#    libc++ `std` module must be built with the same setting as its consumers,
+#    or clang rejects the prebuilt module ("configuration mismatch"). The engine
+#    throws, so exceptions are enabled everywhere.
+#  * Asyncify turns `emscripten_sleep` (used by display::sleep_frame on
+#    Emscripten) into a yield: the engine's frame loops are blocking, and without
+#    yielding the worker freezes and never paints.
+#
+# No pthreads: the runtime's main thread runs inside a plain Web Worker started
+# by `apps/web/openra3.worker.js`, so its virtual filesystem is local to that
+# worker and `FS.createLazyFile` (synchronous XHR) is legal. Under
+# `PROXY_TO_PTHREAD` Emscripten proxies every filesystem syscall to the main
+# browser thread, where synchronous XHR is forbidden, so lazy assets cannot work
+# there - hence the plain worker. The SDL3 web port is only pulled in by the
+# legacy main-thread backend (OPENRA3_WASM_SDL).
+
+# `import std` support: the gate and the module switch must be in place before
+# Emscripten.cmake runs and before the compiler is probed.
+set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD "d0edc3af-4c50-42ea-a356-e2862fe7a444")
+set(CMAKE_CXX_MODULE_STD ON)
+# Let Emscripten.cmake point CMake at its own sysroot modules.json.
+unset(CMAKE_CXX_STDLIB_MODULES_JSON)
+
+if(DEFINED ENV{EMSDK})
+    set(OPENRA3_EMSCRIPTEN_CMAKE "$ENV{EMSDK}/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake")
+elseif(DEFINED ENV{EMSCRIPTEN_ROOT})
+    set(OPENRA3_EMSCRIPTEN_CMAKE "$ENV{EMSCRIPTEN_ROOT}/cmake/Modules/Platform/Emscripten.cmake")
+endif()
+if(NOT EXISTS "${OPENRA3_EMSCRIPTEN_CMAKE}")
+    message(FATAL_ERROR "Emscripten.cmake not found (set EMSDK); looked at '${OPENRA3_EMSCRIPTEN_CMAKE}'")
+endif()
+include("${OPENRA3_EMSCRIPTEN_CMAKE}")
+
+# Exceptions are used by the engine; keep them on globally so the std module and
+# its consumers agree.
+#
+# Asyncify turns `emscripten_sleep` (used by display::sleep_frame on Emscripten)
+# into a yield to the browser: the engine's frame loops are blocking, and
+# without yielding the worker freezes and never paints.
+set(CMAKE_CXX_FLAGS_INIT "-fexceptions -sASYNCIFY=1")
+set(CMAKE_C_FLAGS_INIT "-sASYNCIFY=1")
+set(CMAKE_EXE_LINKER_FLAGS_INIT
+    "-fexceptions -sDISABLE_EXCEPTION_CATCHING=0 -sALLOW_MEMORY_GROWTH=1 -sASYNCIFY=1")
+set(CMAKE_SHARED_LINKER_FLAGS_INIT
+    "-fexceptions -sDISABLE_EXCEPTION_CATCHING=0 -sALLOW_MEMORY_GROWTH=1 -sASYNCIFY=1")

cmake/toolchains/llvm-mingw-aarch64.cmake

@@ -0,0 +1,50 @@
+# Cross-compile for Windows on ARM64 (aarch64-w64-mingw32) with llvm-mingw:
+# clang + libc++ + the libc++ `std` module, targeting the MSVCRT MinGW runtime.
+# The same llvm-mingw release is multi-target, so only the target triple, the
+# SDL3 SDK and the sysroot paths differ from the x86_64 toolchain.
+
+# The `import std` gate must be set before the compiler is probed; a toolchain
+# file is processed earlier than the project's own top-level settings.
+set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD "d0edc3af-4c50-42ea-a356-e2862fe7a444")
+
+set(CMAKE_SYSTEM_NAME Windows)
+set(CMAKE_SYSTEM_PROCESSOR aarch64)
+
+set(OPENRA3_LLVM_MINGW_ROOT "/opt/llvm-mingw" CACHE PATH "llvm-mingw installation root")
+if(NOT EXISTS "${OPENRA3_LLVM_MINGW_ROOT}/bin/clang++")
+    message(FATAL_ERROR "llvm-mingw not found at ${OPENRA3_LLVM_MINGW_ROOT} (expected bin/clang++)")
+endif()
+
+# llvm-mingw's per-target prefix/sysroot for the ARM64 target.
+set(OPENRA3_MINGW_TRIPLE "aarch64-w64-mingw32")
+
+set(CMAKE_C_COMPILER "${OPENRA3_LLVM_MINGW_ROOT}/bin/clang")
+set(CMAKE_CXX_COMPILER "${OPENRA3_LLVM_MINGW_ROOT}/bin/clang++")
+set(CMAKE_C_COMPILER_TARGET ${OPENRA3_MINGW_TRIPLE})
+set(CMAKE_CXX_COMPILER_TARGET ${OPENRA3_MINGW_TRIPLE})
+# CMake's standard-library detection does not pass COMPILER_TARGET, so without
+# this it probes the host standard library. Putting the target in ARG1 makes
+# the probe see libc++ (the MinGW target's library).
+set(CMAKE_C_COMPILER_ARG1 "--target=${OPENRA3_MINGW_TRIPLE}")
+set(CMAKE_CXX_COMPILER_ARG1 "--target=${OPENRA3_MINGW_TRIPLE}")
+
+# libc++ standard-library module description for the MinGW target. Must be set
+# before the compiler is probed so CMake can build `import std;`.
+set(CMAKE_CXX_STDLIB_MODULES_JSON "${OPENRA3_LLVM_MINGW_ROOT}/${OPENRA3_MINGW_TRIPLE}/lib/libc++.modules.json")
+
+# Select libc++ explicitly so CMake's `import std` detection recognises the
+# standard library (llvm-mingw defaults to it, but CMake keys off -stdlib=).
+set(CMAKE_CXX_FLAGS_INIT "-stdlib=libc++")
+set(CMAKE_EXE_LINKER_FLAGS_INIT "-stdlib=libc++")
+set(CMAKE_SHARED_LINKER_FLAGS_INIT "-stdlib=libc++")
+
+# SDL3 for aarch64-w64-mingw32. The official SDL release ships no MinGW ARM64
+# dev package, so the image stages one from MSYS2's clangarm64 repo under this
+# root in the same `<triple>/{include,lib,bin}` layout.
+set(OPENRA3_SDL3_ROOT "/opt/sdl3-aarch64" CACHE PATH "SDL3 aarch64 MinGW development package root")
+set(OPENRA3_SDL3_MINGW_TRIPLE "${OPENRA3_MINGW_TRIPLE}" CACHE STRING "SDL3 MinGW triple subdirectory")
+
+set(CMAKE_FIND_ROOT_PATH "${OPENRA3_LLVM_MINGW_ROOT}/${OPENRA3_MINGW_TRIPLE}")
+set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
+set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

cmake/toolchains/llvm-mingw-x86_64.cmake

@@ -0,0 +1,45 @@
+# Cross-compile for Windows x86_64 with llvm-mingw: clang + libc++ + the
+# libc++ `std` module, targeting the MSVCRT MinGW runtime (which is what the
+# official SDL3 MinGW package links against).
+
+# The `import std` gate must be set before the compiler is probed; a toolchain
+# file is processed earlier than the project's own top-level settings.
+set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD "d0edc3af-4c50-42ea-a356-e2862fe7a444")
+
+set(CMAKE_SYSTEM_NAME Windows)
+set(CMAKE_SYSTEM_PROCESSOR x86_64)
+
+set(OPENRA3_LLVM_MINGW_ROOT "/opt/llvm-mingw" CACHE PATH "llvm-mingw installation root")
+if(NOT EXISTS "${OPENRA3_LLVM_MINGW_ROOT}/bin/clang++")
+    message(FATAL_ERROR "llvm-mingw not found at ${OPENRA3_LLVM_MINGW_ROOT} (expected bin/clang++)")
+endif()
+
+set(CMAKE_C_COMPILER "${OPENRA3_LLVM_MINGW_ROOT}/bin/clang")
+set(CMAKE_CXX_COMPILER "${OPENRA3_LLVM_MINGW_ROOT}/bin/clang++")
+set(CMAKE_C_COMPILER_TARGET x86_64-w64-mingw32)
+set(CMAKE_CXX_COMPILER_TARGET x86_64-w64-mingw32)
+# CMake's standard-library detection does not pass COMPILER_TARGET, so without
+# this it probes the host standard library. Putting the target in ARG1 makes
+# the probe see libc++ (the MinGW target's library).
+set(CMAKE_C_COMPILER_ARG1 "--target=x86_64-w64-mingw32")
+set(CMAKE_CXX_COMPILER_ARG1 "--target=x86_64-w64-mingw32")
+
+# libc++ standard-library module description for the MinGW target. Must be set
+# before the compiler is probed so CMake can build `import std;`.
+set(CMAKE_CXX_STDLIB_MODULES_JSON "${OPENRA3_LLVM_MINGW_ROOT}/x86_64-w64-mingw32/lib/libc++.modules.json")
+
+# Select libc++ explicitly so CMake's `import std` detection recognises the
+# standard library (llvm-mingw defaults to it, but CMake keys off -stdlib=).
+set(CMAKE_CXX_FLAGS_INIT "-stdlib=libc++")
+set(CMAKE_EXE_LINKER_FLAGS_INIT "-stdlib=libc++")
+set(CMAKE_SHARED_LINKER_FLAGS_INIT "-stdlib=libc++")
+
+# Official SDL3 MinGW development package (headers + import library + DLL).
+set(OPENRA3_SDL3_ROOT "/opt/sdl3-mingw" CACHE PATH "SDL3 MinGW development package root")
+# The triple-named subdirectory inside the SDL3 MinGW package.
+set(OPENRA3_SDL3_MINGW_TRIPLE "x86_64-w64-mingw32" CACHE STRING "SDL3 MinGW triple subdirectory")
+
+set(CMAKE_FIND_ROOT_PATH "${OPENRA3_LLVM_MINGW_ROOT}/x86_64-w64-mingw32")
+set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
+set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

docs/ARCHITECTURE.md

@@ -1,93 +1,860 @@
-# Architecture
+# Architecture & Master Plan
 
-OpenRA3 is organised as a stack of C++ modules. Each layer may import the ones
+OpenRA3 is a from-scratch, portable re-implementation of **Command & Conquer:
-below it, never the ones above.
+Red Alert 3** (SAGE 2.0) in **pure C++26** — C++ modules, `import std;`, no
+scripting language, no managed runtime, no other programming language anywhere
+in the tree. It is built with Clang + libc++ on Linux and cross-compiled to
+Windows with llvm-mingw.
+
+This document is two things at once:
+
+1. the **layer architecture** (how the modules sit on top of one another), and
+2. the **master plan** — the complete Red Alert 3 feature set decomposed three
+   levels deep into **Module → Function → Feature**, each tagged with its
+   implementation status and target milestone.
+
+The decomposition is the contract: every feature RA3 has is either implemented,
+being implemented, or explicitly planned here. Nothing is silently dropped.
+
+> **Scope.** Offline only. Single-player campaign, skirmish, Commander's
+> Challenge and LAN lockstep — never an online service, matchmaking, EA account
+> or GameSpy/Steam integration. The simulation is deterministic and
+> self-contained. No game assets or binaries are shipped; the engine reads the
+> user's own install at runtime.
+
+---
+
+## 1. Principles
+
+Same five rules as the rest of the tree, restated because the plan is written
+against them:
+
+1. **Pure C++.** One language. No Lua, no JS, no C#, no Python at runtime.
+   Python is allowed *only* in offline build tooling (`tools/`, cmake helper
+   scripts), never linked into `openra3`.
+2. **No raw owning pointers.** Ownership is `std::unique_ptr`; cross-references
+   are non-owning views (`thing *`, handles, indices).
+3. **Portable simulation.** No platform API in the foundation or simulation
+   layers. All platform concerns live behind `display` / `audio` / `video`.
+4. **Determinism.** Anything that can diverge between runs (RNG, iteration
+   order, float accumulation, hash order) is explicit, seeded and testable.
+5. **RE-traceable.** Every structure or constant taken from the retail
+   `ra3_1.12.game` (image base `0x400000`) or from the GPLv3 SAGE 1.0 reference
+   cites its origin. No asserted fact without a source.
+
+---
+
+## 2. Layer architecture
+
+Each layer may import the ones below it, never the ones above. The `ra3`
+umbrella module re-exports the SDK; applications import `ra3` only.
 
 ```
-                 ┌───────────────────────────────────────┐
+   L6  tooling / apps     openra3 (CLI)        tools/ (offline, Python allowed)
-   applications  │  openra3 (apps/openra3)               │
+                                  |  import ra3
-                 └───────────────────┬───────────────────┘
+   ---------------------------------------------------------------------------
-                                     │ import ra3
+                                  v
-                 ┌───────────────────▼───────────────────┐
+   L5  meta               ra3.i18n    ra3.mod    ra3.net (deferred)
-   umbrella      │  ra3  (re-exports everything)         │
+                                  |
-                 └───────────────────┬───────────────────┘
+   L4  match services     ra3.match   ra3.replay  ra3.save
-      ┌──────────────┬───────────────┼───────────────┬──────────────┐
+                                  |
-      ▼              ▼               ▼               ▼              ▼
+   L3  presentation       ra3.client ── ra3.render ── ra3.audio ── ra3.video
-  ra3.ui        ra3.render      ra3.skirmish    ra3.client      ra3.game
+                                  |             \        |
-  SDL3 window   framebuffer     match rules     display/loop    RA3 sides
+                                  |              \       v
-      │              │               │               │              │
+                                  |             ra3.display (backend pick)
-      └──────┬───────┘               └───────┬───────┘              │
+                                  |              /     |      \        \
-             ▼                               ▼                      │
+                                  v          ra3.ui  ra3.vulkan  ra3.dx   ra3.webgpu / ra3.wasmgl
-          ra3.core                       ra3.logic                  │
+                                  |          (SDL3)  (Vulkan)   (D3D11/12) (wasm workers)
-                                         simulation                 │
+   ---------------------------------------------------------------------------
-      ┌───────────────────────────────────────┬──────────────────────┘
+                                  v
-      ▼                                       ▼
+   L2  simulation         ra3.logic  ra3.modules  ra3.combat  ra3.movement
-  ra3.map                                 ra3.fs
+                          ra3.economy ra3.ai ra3.script ra3.powers ra3.shroud
-  map catalog                             BIG4 + RefPack
+                                  |
+   L1  data & assets      ra3.data ── ra3.assets ── ra3.map ── ra3.terrain
+                                  |                      |
+                                  v                      v
+                          ra3.fs (BIG4 / RefPack / install)
+                                  |
+   L0  foundation         ra3.core (types, math, containers, RNG, message bus)
 ```
 
-## Module responsibilities
+The current concrete modules (`ra3.core`, `ra3.logic`, `ra3.data`,
+`ra3.skirmish`, `ra3.fs`, `ra3.map`, `ra3.terrain`, `ra3.models`, `ra3.render`, `ra3.ui.*`,
+`ra3.vulkan.*`, `ra3.dx.*`, `ra3.webgpu.*`, `ra3.wasmgl.*`, `ra3.display`, `ra3.game`, `ra3.client`, and the
+vendored `ender.log`) are the **seeds** of the
+target modules below. `ra3.skirmish` and `ra3.game` will be absorbed into
+`ra3.ai` / `ra3.match`; new modules are added as their subsystems are recovered.
 
-### `ra3.core`
+### Status legend
-The vocabulary every other module shares, mirroring SAGE's `GameEngine/Common`:
-`real`/`int32`/`uint32`, `coord3d`/`coord2d`/`rgb_color`, `ascii_string` +
-`make_name_key`, the deterministic `random` stream, and the `message_stream`
-command bus (node layout derived from retail `MessageStream::appendMessage`,
-`0x0060c4a0`).
 
-### `ra3.logic`
+| Tag | Meaning |
-The deterministic simulation, mirroring SAGE's `GameLogic`: `thing` → `object`
+| --- | --- |
-with pluggable `update_module`s, `player`/`player_list`, the `partition_manager`
+| `[x]` | implemented and tested on `main` |
-spatial grid, and the 30 Hz `game_logic` driver (`prepare_new_game` /
+| `[~]` | partially implemented / works for the happy path |
-`start_new_game` / `update`).
+| `[ ]` | planned, not started |
+| `(vX.Y)` | target milestone (see the roll-up in §5) |
+| `!!` | needs reverse engineering before it can be built |
 
-### `ra3.client`
+| Function tag | Meaning |
-The presentation boundary: an abstract `display` with a `headless_display`
+| --- | --- |
-implementation, and `game_client`, the seam a future W3D/D3D9 renderer plugs
+| `D` | **done** — the function's features are largely present |
-into.
+| `P` | **partial** — some features present |
 
-### `ra3.game`
+---
-Red Alert 3 data that SAGE keeps in `PlayerTemplate`: the three sides
-(`faction` flags `Empire=2`, `Allied=4`, `Soviet=8`, `Random=7`, recovered from
-the retail skirmish setup) and skirmish defaults.
 
-### `ra3.fs`
+## 3. Master plan — Module → Function → Feature
-Reading the user's installation. Implements the `BIG4` archive container and
-EA's RefPack codec, plus `find_game_dir` (`--game-dir` / `$RA3_GAME_DIR` /
-`C:\Red Alert 3`). Only the archive index is held in memory; payloads are read
-on demand.
 
-### `ra3.map`
+### M00 `ra3.core` — foundation vocabulary `[D]`
-Map discovery and loading: scans `MapsMultiplayer.big` for main map entries,
-unwraps the two compression layers (`BIG4` RefPack → `EAR\0` wrapper → RefPack →
-`CkMp`), and recovers `Player_N_Start` waypoint coordinates. Degenerate
-extractions are rejected so the caller can fall back.
 
-### `ra3.skirmish`
+Mirrors SAGE `GameEngine/Common`. Everything else speaks this.
-The minimal match: two players, unit classes (harvester/infantry/tank/base),
-passive + harvester income, a simple build AI, movement and combat on a fixed
-30 Hz step, and a base-destruction win condition. Fully deterministic.
 
-### `ra3.render`
+- **F1 Types & math** `[D]`
-A dependency-free software renderer: an ARGB8888 `image` framebuffer with
+  - `[x]` `real` (float), `int32`/`uint32`/`uint16`/`uint8`, `bool` aliases
-blit/line/circle primitives, a TGA decoder for the game's map art, a 24-bit BMP
+  - `[x]` `coord2d` / `coord3d` vectors, dot/cross/length/normalize
-encoder for headless output, and `compose` which overlays a world grid and
+  - `[x]` `rgb_color` / `argb_color`, packing and lerp
-markers (start positions, live units) onto the map art.
+  - `[x]` geometry: `segment`, `triangle`, `plane`, ray/segment intersection
+  - `[ ]` fixed-point helpers for replay-stable accumulation `(v0.4)`
+  - `[ ]` matrix / quaternion (needed by W3D models) `(v0.6)`
+  - `[ ]` `KindOf` flag bitset (SAGE object taxonomy) `(v0.4)`
+- **F2 Containers** `[D]`
+  - `[x]` `ascii_string` + `make_name_key` (case-folded hash for data lookup)
+  - `[x]` intrusive doubly linked list (message stream node layout)
+  - `[x]` deterministic iteration-order map (insertion-ordered)
+  - `[ ]` object pool / arena for per-frame allocations `(v0.4)`
+  - `[ ]` interned string table `(v0.5)`
+- **F3 Deterministic RNG** `[D]`
+  - `[x]` seedable `random` stream (`game_logic` random)
+  - `[ ]` independent per-player / per-subsystem streams `(v0.4)`
+  - `[ ]` shuffle / weighted-pick primitives `(v0.4)`
+- **F4 Message stream** `[D]`
+  - `[x]` command bus with retail node layout (`appendMessage` `0x0060c4a0`)
+  - `[x]` ordered per-frame command drain
+  - `[ ]` command argument blocks (build/target/waypoint payloads) `(v0.4)`
+  - `[ ]` network/replay source tagging `(v0.4)`
+- **F5 Diagnostics** `[~]`
+  - `[x]` logging sink + assert macro
+  - `[ ]` scoped profiling timers, per-subsystem counters `(v0.4)`
+  - `[ ]` structured crash/report capture `(v0.8)`
+- **F6 Serialization primitives** `[~]`
+  - `[x]` little-endian byte reader/writer
+  - `[ ]` chunked binary reader/writer with versioning `(v0.5)`
+  - `[ ]` stable content hashing (replay/desync checks) `(v0.4)`
+- **F7 Localization primitives** `[~]` (see M26)
+  - `[x]` UTF-16 unit access, CSF low-byte `^0xFF` decode
+  - `[ ]` placeholder substitution, plural/gender rules `(v0.5)`
 
-### `ra3.ui`
+### M01 `ra3.fs` — containers & install `[D]`
-The windowed viewer. The SDL3 backend streams the rendered image to a texture
-with pan/zoom and Esc-to-quit; when the build has no SDL3, a null backend
-returns `false` so the caller writes an offscreen image instead.
 
-## Design rules
+- **F1 BIG archive** `[D]`
+  - `[x]` `BIG4` header parse (`fileSize` LE, `fileCount`/offsets BE) + name index
+  - `[x]` payload read on demand (index-only resident memory)
+  - `[ ]` `BIGF` (RefPack whole-archive) variant `!!` `(v0.5)`
+  - `[ ]` write support (pack/repack, used by tooling) `(v0.8)`
+- **F2 RefPack codec** `[D]`
+  - `[x]` decode: 2/3/4-byte commands, long-literal, stop opcode
+  - `[x]` `refpack_output_size` without full decompress
+  - `[ ]` encode (for tooling round-trips) `(v0.8)`
+- **F3 Install locator** `[D]`
+  - `[x]` `--game-dir` / `$RA3_GAME_DIR` / `C:\Red Alert 3` defaults
+  - `[ ]` registry / Steam / EA-app discovery `(v0.5)`
+  - `[ ]` Uprising as an optional content source `(v0.5)`
+- **F4 Virtual file system** `[~]`
+  - `[x]` layered archive mounts (loose files → `*.big`)
+  - `[ ]` patch/language precedence rules (newest `Lang-*.big` wins) `(v0.5)`
+  - `[ ]` case-insensitive lookup + path normalisation `(v0.5)`
+- **F5 Extraction targets** `[D]`
+  - `[x]` `openra3 extract` dumps maps/terrain to `assets/`
+  - `[ ]` full asset dump via `ra3tools` integration as a build target `(v0.5)`
+
+### M02 `ra3.data` — data schema & balance `[P]`
+
+- **F1 Data schema** `[ ]` `!!`
+  - `[ ]` SAGE INI parser (`#include`, `#define`, inheritance) `(v0.5)`
+  - `[ ]` XML rule schema
+  - `[ ]` `.manifest` compiled-blob schema `!!` `(v0.5)`
+- **F2 Compiled asset blobs** `[ ]` `!!`
+  - `[ ]` `global.bin` deserialisation `(v0.5)`
+  - `[ ]` `static.*.bin` deserialisation `(v0.5)`
+  - `[ ]` version/dependency validation `(v0.5)`
+- **F3 Balance tables** `[~]`
+  - `[x]` damage types, `ArmorTemplate` percentages
+  - `[x]` weapon target masks, weapon definitions
+  - `[x]` unit/structure build costs, times, prerequisites
+  - `[x]` ore economy constants
+  - `[ ]` read these from the install instead of pinned constants `(v0.5)`
+- **F4 Object definitions** `[ ]`
+  - `[ ]` `ThingTemplate`/`ObjectTemplate` inheritance graph `(v0.5)`
+  - `[ ]` module descriptor lists (per-object update/draw module sets)
+  - `[ ]` `WeaponTemplate`/`ArmorTemplate`/`LocomotorTemplate` stores
+- **F5 Faction & player templates** `[~]`
+  - `[x]` Allied / Soviet / Empire side flags (`2/4/8`), match templates
+  - `[ ]` commander/sub-commander definitions `(v0.7)`
+  - `[ ]` build/upgrade unlock trees per faction `(v0.5)`
+- **F6 Rules & settings** `[ ]`
+  - `[ ]` skirmish options (cash, crates, superweapons, speed, limits)
+  - `[ ]` bonus crate effect table
+  - `[ ]` AI personality tables
+  - `[ ]` map-specific rule overrides (`map.ini`)
+- **F7 Validation** `[ ]`
+  - `[ ]` schema diagnostics with source location
+  - `[ ]` cross-reference integrity (missing templates/refs)
+
+### M03 `ra3.assets` — runtime asset manager `[ ]`
+
+- **F1 Textures** `[~]`
+  - `[x]` TGA decode (`ra3.render`); 256×256 terrain cells
+  - `[ ]` DDS / DXT compressed textures `(v0.5)`
+  - `[ ]` atlas + mip generation, gutter padding (GPU) `[~]`
+  - `[ ]` async upload / streaming `(v0.6)`
+- **F2 Models** `[~]`
+  - `[x]` compiled `W3DMesh` decode (vertex buffer + D3D9 declaration + triangle list) from the BAB static/worldbuilder stream
+  - `[x]` embedded DDS textures (DXT1/3/5 + uncompressed RGB) → ARGB
+  - `[x]` `W3DHierarchy` decode + static bind-pose skinning (bone-space vertices)
+  - `[ ]` W3D container/hierarchy animation, LOD sets, collision meshes `!!` `(v0.6)`
+- **F3 Animation** `[ ]` `!!`
+  - `[ ]` W3D animation chunks, bone poses `(v0.6)`
+  - `[ ]` blend trees / transition animations
+- **F4 Audio** `[ ]` `!!`
+  - `[ ]` audio container + codec decode `(v0.7)`
+  - `[ ]` cue/event tables (unit responses, weapon foley)
+- **F5 Fonts & glyphs** `[ ]`
+  - `[ ]` bitmap/vector font load; CJK coverage `(v0.5)`
+- **F6 Asset registry** `[ ]`
+  - `[ ]` cache with ref counting, eviction `(v0.6)`
+  - `[ ]` name-key lookup into the data schema
+- **F7 UI art (`.apt`)** `[ ]` `!!`
+  - `[ ]` RA3 interface art decode (HUD/command bar) `(v0.7)`
+
+### M04 `ra3.map` — map catalog & loader `[D]`
+
+- **F1 Catalog** `[D]`
+  - `[x]` scan `MapsMultiplayer.big` for main map entries
+  - `[ ]` campaign + challenge map catalog `(v0.7)`
+- **F2 Compiled map (`CkMp`)** `[D]`
+  - `[x]` double unwrap (`BIG4` RefPack → `EAR\0` → RefPack → `CkMp`)
+  - `[x]` name table + chunk list (`{index,version,size,data}`)
+  - `[ ]` full typed chunk dispatch for all chunk kinds `(v0.5)`
+- **F3 Start positions** `[~]`
+  - `[x]` `Player_N_Start` waypoint scan → `coord3d`
+  - `[ ]` `MPPositionList` layout for maps without waypoints `!!` `(v0.5)`
+- **F4 Metadata** `[~]`
+  - `[x]` display names from `gamestrings.csf` (`MAP:<ID>`)
+  - `[ ]` player count, size, supported game modes `(v0.5)`
+- **F5 Map rules** `[ ]`
+  - `[ ]` `map.ini` override application `(v0.5)`
+- **F6 Preview art** `[~]`
+  - `[x]` `<map>_art.tga` overview decode (`--thumbnail`)
+- **F7 Validation & fallback** `[D]`
+  - `[x]` reject degenerate extractions, fall back to built-in test map
+  - `[ ]` integrity/version checks with actionable errors `(v0.5)`
+
+### M05 `ra3.terrain` — terrain `[P]`
+
+- **F1 Heightmap** `[D]`
+  - `[x]` `HeightMapData` v6 (grid, border, `u16` elevations, scale)
+  - `[ ]` multi-resolution / LOD height sampling `(v0.6)`
+- **F2 Blend tiles** `[D]`
+  - `[x]` `BlendTileData` v27: tile grid, blends/three-way/cliff tables
+  - `[x]` `BlendDescription` parse; `secondaryTile` decode
+  - `[x]` retail `Terrain.fx` blend ramp (`blend_factor`, axis flags)
+- **F3 Terrain textures** `[D]`
+  - `[x]` `art\terrain\*.tga` from `Terrain.big` / `Core11.big`
+  - `[x]` cell atlas with replicated gutter (GPU bleeding fix)
+  - `[ ]` continuous 32 px / Morton layout (kill residual grid lines) `(v0.4)`
+- **F4 Water** `[ ]` `!!`
+  - `[ ]` water height/type, sea level `(v0.6)`
+  - `[ ]` animated waves + shoreline blending `(v0.6)`
+  - `[ ]` shroud-aware water rendering `(v0.6)`
+- **F5 Cliffs & roads** `[ ]` `!!`
+  - `[x]` `CliffTextures` table parsed
+  - `[ ]` cliff mesh + `CliffTextureMapping` UV remap `(v0.6)`
+  - `[ ]` roads and bridges (passability + render) `(v0.6)`
+- **F6 Terrain lighting** `[ ]`
+  - `[ ]` per-vertex normals, cell lighting, global light `(v0.6)`
+- **F7 Terrain queries** `[~]`
+  - `[x]` height lookup (render)
+  - `[ ]` passability grid (ground/naval/amphibious/air) `(v0.4)`
+  - `[ ]` buildability grid (flatness, slope, water) `(v0.4)`
+
+### M06 `ra3.logic` — simulation core `[P]`
+
+- **F1 Objects & things** `[~]`
+  - `[x]` `thing` → `object` with pluggable `update_module`s
+  - `[x]` global object registry with stable ids
+  - `[ ]` handle/reference system (survives deletion) `(v0.4)`
+  - `[ ]` object destruction lifecycle + death dispatch `(v0.4)`
+- **F2 Players & teams** `[~]`
+  - `[x]` `player` / `player_list`
+  - `[x]` money (`std::vector<Money*>`) and power fields
+  - `[x]` team assignment and relations
+  - `[ ]` diplomacy matrix, ally vision sharing `(v0.5)`
+- **F3 Partition manager** `[~]`
+  - `[x]` spatial grid, neighborhood queries
+  - `[ ]` cell-resolution + large-object multi-cell registration `(v0.4)`
+- **F4 Game loop** `[~]`
+  - `[x]` 30 Hz deterministic step with frame counter
+  - `[x]` `prepare_new_game` / `start_new_game` two-phase start
+  - `[ ]` per-tick module scheduling with stable ordering `(v0.4)`
+- **F5 Commands** `[~]`
+  - `[x]` `message_stream` bus
+  - `[ ]` typed commands (build, attack, move, ability, sell, repair) `(v0.4)`
+  - `[ ]` command validation + feedback (insufficient funds, etc.) `(v0.4)`
+- **F6 Determinism** `[~]`
+  - `[x]` seeded logic random
+  - `[ ]` replay-hash of state per tick `(v0.4)`
+  - `[ ]` float determinism policy / fixed-point where required `(v0.4)`
+- **F7 Victory / defeat** `[~]`
+  - `[x]` team-wipe / base-destruction win condition
+  - `[ ]` surrender, disconnection, timed, objective victories `(v0.5)`
+  - `[ ]` score / stats accumulation `(v0.8)`
+
+### M07 `ra3.modules` — object update & draw modules `[P]`
+
+- **F1 Module system** `[~]`
+  - `[x]` update modules attached to objects with a simple order
+  - `[ ]` module descriptor data-binding (from `ThingTemplate`) `(v0.5)`
+  - `[ ]` interface queries (get WeaponModule / ContainModule on demand) `(v0.4)`
+- **F2 Locomotor** `[ ]`
+  - `[ ]` movement state machine (idle/moving/attacking) `(v0.4)`
+- **F3 Weapon module** `[~]`
+  - `[x]` simple weapons on units, auto-target + fire
+  - `[ ]` multi-weapon slots, turret aiming/rotation `(v0.4)`
+  - `[ ]` reload/clip, deploy/undeploy states `(v0.6)`
+- **F4 Contain** `[ ]`
+  - `[ ]` transport passenger slots, load/unload `(v0.4)`
+  - `[ ]` garrison of civilian structures `(v0.6)`
+  - `[ ]` paradrop / airdrop `(v0.6)`
+- **F5 Production** `[~]`
+  - `[x]` pay-as-you-go build queue on a factory
+  - `[ ]` per-factory queues, rally points, queue reordering `(v0.4)`
+  - `[ ]` building placement → production handoff `(v0.4)`
+- **F6 Power** `[~]`
+  - `[x]` power production/consumption fields
+  - `[ ]` brownout/blackout effects on radar + build speed `(v0.4)`
+- **F7 Upgrades** `[ ]`
+  - `[ ]` upgrade research, unlock dependent modules/weapons `(v0.5)`
+- **F8 Experience / veterancy** `[ ]`
+  - `[ ]` XP from kills, ranks (veteran/elite/heroic), bonuses `(v0.6)`
+  - `[ ]` chevron rendering `(v0.6)`
+- **F9 Special abilities** `[~]`
+  - `[ ]` secondary ability slots with cooldown, target/area types `(v0.6)`
+  - `[ ]` toggle/instant/targeted ability kinds `(v0.6)`
+- **F10 Stealth / disguise / detection** `[ ]`
+  - `[ ]` stealth states, detection radius, decloak on fire `(v0.6)`
+  - `[ ]` disguise (spy-like) and detection interaction `(v0.6)`
+- **F11 Structure modules** `[~]`
+  - `[x]` base structures, destruction
+  - `[ ]` construction/assembly animation, sell, repair `(v0.4)`
+  - `[ ]` walls/gates if present, defensive structures `(v0.6)`
+- **F12 Resource modules** `[~]`
+  - `[x]` harvester ↔ refinery ore cycle
+  - `[ ]` ore field spread/depletion, multiple miners, dock queue `(v0.4)`
+- **F13 Shroud modules** `[ ]`
+  - `[ ]` per-object shroud reveal / clearance `(v0.4)`
+- **F14 Draw modules** `[ ]`
+  - `[ ]` model draw, animation, particles, construction ghost, temp effects `(v0.6)`
+
+### M08 `ra3.combat` — weapons, warheads, damage `[P]`
+
+- **F1 Weapons** `[~]`
+  - `[x]` damage, range, rate of fire, target masks
+  - `[ ]` clip/burst, scatter, arc, continuous beam `(v0.4)`
+  - `[ ]` primary vs secondary weapon selection `(v0.4)`
+- **F2 Warheads** `[~]`
+  - `[x]` damage type + armor multiplier resolution
+  - `[ ]` radius/falloff, affects mask, death type on kill `(v0.4)`
+- **F3 Armor** `[~]`
+  - `[x]` `ArmorTemplate` percentage table
+  - `[ ]` armor upgrades and per-state armor `(v0.6)`
+- **F4 Damage application** `[~]`
+  - `[x]` damage resolution against armor
+  - `[ ]` conditional modifiers (from above, in air, moving) `(v0.4)`
+  - `[ ]` friendly-fire policy, self-damage `(v0.4)`
+- **F5 Projectiles** `[ ]`
+  - `[ ]` ballistic / laser / missile / beam / homing / arcing `(v0.4)`
+  - `[ ]` projectile draw + impact VFX hook `(v0.6)`
+- **F6 Targeting** `[~]`
+  - `[x]` simple nearest/in-range acquisition
+  - `[ ]` priority scans (attack-move, guard, force-attack) `(v0.4)`
+  - `[ ]` re-targeting, leash, target ground `(v0.4)`
+- **F7 Special effects** `[ ]`
+  - `[ ]` EMP/stun, flame/radiation DoT, mind-control, shrink/grow `(v0.7)`
+- **F8 Death & corpses** `[ ]`
+  - `[ ]` death types, wrecks, gibs, salvage, rebuild `(v0.6)`
+
+### M09 `ra3.movement` — locomotion & pathfinding `[ ]`
+
+- **F1 Locomotors** `[ ]`
+  - `[ ]` ground / air / naval / amphibious / hover / teleport `!!` `(v0.4)`
+  - `[ ]` turn rates, acceleration, braking, banking `(v0.6)`
+- **F2 Pathfinding** `[ ]`
+  - `[ ]` grid A* over the passability grid `(v0.4)`
+  - `[ ]` hierarchical / jump-point refinement `(v0.6)`
+  - `[ ]` dynamic obstacle integration (buildings, units) `(v0.6)`
+- **F3 Steering & flocking** `[ ]`
+  - `[ ]` separation, avoidance, group cohesion `(v0.6)`
+  - `[ ]` formation slots (line/wedge/box) `(v0.6)`
+- **F4 Orders & waypoints** `[~]`
+  - `[x]` straight-line move toward a target (skirmish)
+  - `[ ]` waypoint queues, queued orders with shift `(v0.4)`
+  - `[ ]` guard / patrol / attack-move / stop / scatter `(v0.4)`
+- **F5 Collision & crush** `[ ]`
+  - `[ ]` unit-unit collision, pushing, crush damage `(v0.6)`
+- **F6 Naval & amphibious** `[ ]`
+  - `[ ]` water-only movement, amphibious land↔water transition `!!` `(v0.6)`
+- **F7 Transport & airdrop** `[ ]`
+  - `[ ]` boarding/unloading, airdrop descent `(v0.6)`
+
+### M10 `ra3.economy` — resources, power, construction `[P]`
+
+- **F1 Ore / resource** `[~]`
+  - `[x]` ore fields and harvester↔refinery cycle
+  - `[ ]` ore spread/regrowth, depletion, ore density `(v0.4)`
+- **F2 Power** `[~]`
+  - `[x]` power balance fields
+  - `[ ]` brownout/blackout consequences `(v0.4)`
+- **F3 Construction** `[~]`
+  - `[x]` pay-as-you-go queue, tech prerequisites, build times
+  - `[ ]` build-radius rules (structures must be in base vicinity) `(v0.4)`
+  - `[ ]` low-power build-speed penalty `(v0.4)`
+- **F4 Placement** `[ ]`
+  - `[ ]` placement grid, footprint validation, green/red ghost `(v0.4)`
+  - `[ ]` adjacency bonuses / prerequisite-adjacent structures `(v0.6)`
+- **F5 Repair & sell** `[ ]`
+  - `[ ]` structure repair over time, cost, sell refund `(v0.4)`
+  - `[ ]` unit repair pads if present `(v0.6)`
+- **F6 Rally points** `[ ]`
+  - `[ ]` factory rally, rally preview, waypoint rally `(v0.6)`
+- **F7 Income modifiers** `[ ]`
+  - `[ ]` bonus crates (cash/units/repair/heal, `random_bonus_crates`) `(v0.5)`
+
+### M11 `ra3.ai` — computer opponents `[P]`
+
+- **F1 Skirmish AI** `[~]`
+  - `[x]` simple build AI (base, ore, a couple of unit types)
+  - `[ ]` data-driven build orders per faction `(v0.5)`
+  - `[ ]` economy management (expand, defend harvesters) `(v0.5)`
+- **F2 Attack management** `[~]`
+  - `[x]` send units at the enemy base
+  - `[ ]` attack force assembly, waves, retreat/regroup `(v0.5)`
+  - `[ ]` targeting priorities (harvesters, key structures) `(v0.6)`
+- **F3 Team AI / diplomacy** `[ ]`
+  - `[ ]` allied coordination, shared attacks, base defense `(v0.6)`
+- **F4 Difficulty & personalities** `[ ]`
+  - `[ ]` easy/normal/hard modifiers, AI cheating options `(v0.5)`
+  - `[ ]` commander personalities (aggressive/turtle/air/naval) `(v0.7)`
+- **F5 Scouting** `[ ]`
+  - `[ ]` exploration, map awareness, threat response `(v0.6)`
+- **F6 Superweapon usage** `[ ]`
+  - `[ ]` AI powers/power targeting `(v0.7)`
+- **F7 Script hooks** `[ ]`
+  - `[ ]` AI cooperation with script triggers (campaign) `(v0.7)`
+
+### M12 `ra3.script` — triggers & missions `[ ]`
+
+- **F1 Trigger system** `[ ]` `!!`
+  - `[ ]` conditions (elapsed, object in region, destroyed, flag) `(v0.7)`
+  - `[ ]` actions (spawn, order, reveal, camera, dialog, win/lose) `(v0.7)`
+- **F2 Script engine** `[ ]` `!!`
+  - `[ ]` SAGE script language / mission script parse `(v0.7)`
+  - `[ ]` timers, counters, flags, per-player state `(v0.7)`
+- **F3 Campaign missions** `[ ]`
+  - `[ ]` mission objectives, sequential phases, briefing `(v0.8)`
+  - `[ ]` three faction campaigns (Allied/Soviet/Empire) `(v0.8)`
+- **F4 Reinforcements & spawns** `[ ]`
+  - `[ ]` scripted spawns, cinematic units, capture `(v0.8)`
+- **F5 Tutorials** `[ ]`
+  - `[ ]` tutorial message gates, camera lock/unlock actions `(v0.8)`
+- **F6 Co-op** `[ ]`
+  - `[ ]` co-op commander missions `(v0.9)`
+
+### M13 `ra3.powers` — superweapons & support powers `[ ]`
+
+- **F1 Superweapons** `[ ]` `!!`
+  - `[ ]` Allied Chronosphere `(v0.7)`
+  - `[ ]` Soviet Vacuum Imploder `(v0.7)`
+  - `[ ]` Empire Psionic Decimator `(v0.7)`
+  - `[ ]` charge timer, targeting, ready state, HUD `(v0.7)`
+- **F2 Support powers** `[ ]`
+  - `[ ]` per-faction powers (spy satellite, air support, etc.) `(v0.7)`
+  - `[ ]` cooldowns, targeting types, cost `(v0.7)`
+- **F3 Commander's Challenge powers** `[ ]`
+  - `[ ]` challenge-mode power loadouts `(v0.8)`
+
+### M14 `ra3.shroud` — fog of war & radar `[ ]`
+
+- **F1 Shroud** `[ ]`
+  - `[ ]` per-player unexplored grid `(v0.4)`
+- **F2 Fog of war** `[ ]`
+  - `[ ]` explored-but-unseen dimming `(v0.4)`
+- **F3 Reveal sources** `[ ]`
+  - `[ ]` units/structures reveal radius, abilities, spy satellite `(v0.6)`
+- **F4 Radar / minimap** `[ ]`
+  - `[ ]` radar texture, unit blips, radar-offline on low power `(v0.6)`
+- **F5 Shroud ↔ logic** `[ ]`
+  - `[ ]` targetability gating, option for AI to ignore shroud `(v0.4)`
+
+### M15 `ra3.client` — game client & shell `[P]`
+
+- **F1 Game client** `[~]`
+  - `[x]` `game_client` facade owning the sim, driving the frame loop
+  - `[ ]` sim/present decoupling, interpolation, catch-up `(v0.6)`
+- **F2 Tactical view / camera** `[~]`
+  - `[x]` controls: wheel zoom, edge scroll, clamped pan, open on player start
+  - `[x]` camera tuning table (`cameraMinHeight` …) + lock actions
+  - `[ ]` retail perspective camera, pitch/yaw, FOV (needs 3D terrain) `(v0.6)`
+- **F3 Selection** `[ ]`
+  - `[ ]` click select, drag-box, double-click type select `(v0.6)`
+  - `[ ]` control groups (Ctrl+N), type filters, select-all-of-type `(v0.6)`
+- **F4 Orders** `[ ]`
+  - `[ ]` contextual right-click orders, force-attack, force-move `(v0.6)`
+  - `[ ]` order queue with shift, formation move `(v0.6)`
+- **F5 Command bar** `[ ]` `!!`
+  - `[ ]` build/production palettes, ability buttons, portraits `(v0.7)`
+  - `[ ]` tooltips, cost/time, cooldown sweep, disabled states `(v0.7)`
+- **F6 HUD** `[ ]`
+  - `[x]` minimal match-state overlay (units, start markers)
+  - `[ ]` resource/power readouts, objectives, notifications `(v0.7)`
+  - `[ ]` EVA voice announcements hook `(v0.7)`
+- **F7 Shell menus** `[~]`
+  - `[x]` map list by localized name + full render/skirmish options; console fallback
+  - `[ ]` main menu, skirmish setup, faction/team/color pickers `(v0.7)`
+  - `[ ]` options (video/audio/keybinds), pause, load/save, credits `(v0.8)`
+- **F8 Feedback & cursors** `[ ]`
+  - `[ ]` action cursor, placement ghost, move/attack markers `(v0.6)`
+
+### M16 `ra3.render` — renderer & RHI `[P]`
+
+- **F1 RHI** `[ ]`
+  - `[ ]` device/queue/swapchain abstraction over Vulkan `(v0.6)`
+  - `[ ]` buffers, textures, samplers, descriptor sets, pipelines `(v0.6)`
+  - `[ ]` `present_terrain` is the seam where this lands today `[~]`
+- **F2 Render graph** `[ ]`
+  - `[ ]` pass scheduling, barriers, transient/aliased resources `(v0.6)`
+- **F3 Terrain render** `[~]`
+  - `[x]` top-down software + GPU heightfield with blend ramp + gutter atlas
+  - `[ ]` perspective terrain mesh, LOD, cliff `(v0.6)`
+  - `[x]` water surface in the raymarch: SAGE `Water.frag` port (ocean/river) `[~]`
+- **F4 Model render** `[~]`
+  - `[x]` static map-object triangle soup, world-space, depth-tested over the terrain (Vulkan + software)
+  - `[x]` bind-pose skinning (bone-space vertices) + ground-decal depth bias
+  - `[ ]` animated W3D draw, materials, team colors `!!` `(v0.6)`
+  - `[ ]` shadows, decals, ground marks `(v0.6)`
+- **F5 VFX** `[ ]`
+  - `[ ]` particle systems, beams, muzzle flashes, explosions `(v0.6)`
+  - `[ ]` shader effect graph (retail `.fxo` parity where feasible) `!!` `(v0.7)`
+- **F6 Sky & atmosphere** `[ ]`
+  - `[ ]` skybox, fog, weather, time-of-day `(v0.7)`
+- **F7 HUD render** `[ ]`
+  - `[ ]` 2D art layer, fonts, minimap/radar texture `(v0.7)`
+- **F8 Software renderer** `[D]`
+  - `[x]` ARGB framebuffer, blit/line/circle/text, TGA decode, BMP encode
+  - `[x]` map compositing, grid, markers; headless output
+- **F9 Post-processing** `[ ]`
+  - `[x]` underwater tint/fog in the terrain pass (retail `UnderwaterDeferred.fx`) `[~]`
+  - `[ ]` bloom, color grading, AA, resolution scaling `(v0.7)`
+
+### M16b shader porting status (retail `Data\Shaders.big` → `*.fxo`)
+
+The retail set is **88 compiled effects** (`Core12\shaders\compiled`, duplicated
+in `Misc`/`Shaders`; `Core5`/`Core8` ship only `terrain`; plus a 60-byte
+`null` stub). OpenRA3 implements the static-map subset only:
+
+- **Ported (approximate stand-ins, shared by all backends):** `Terrain.fx`
+  (`terrain.*`), the opaque diffuse subset of `BuildingsGeneric.fx` /
+  `BasicW3D.fx` / `ObjectsGeneric.fx` (`object.*`), and the SAGE water model
+  `Ocean.fx` (+ `OceanDisplacement`/`OceanNoVertexTexture`/`RiverWater`/
+  `RiverReflection`/`UnderwaterDeferred`, folded into the `terrain.*` water
+  branch — see `docs/REVERSE_ENGINEERING.md`). The retail water flow and bump
+  maps (`art/terrain/ra3_deepocean.tga`, `ra3_deepocean_nrm.tga`) ride as the
+  last two terrain-atlas layers, so no backend adds a binding.
+- **Not ported:** all faction/variant model shaders (`buildings*`, `objects*`,
+  `basicw3d*`, `defaultw3d*`, `normalmapped`, `tree`/`treesway`), instances/
+  animation (`infantry*`), particles and beams (`cpuparticle`, `gpuparticle*`,
+  `swarmparticle`, `laser*`, `lightning`, `fx*`, `tracer`, `trail`,
+  `connectionline`, `linerenderers`, `stream`, `rain`, `simple*`), shadows and
+  ground decals (`shadow`, `decal`, `outlines`, `occlusion`, `terraintracks`),
+  post-processing (`postfx_*`), and the 2D/misc shaders (`render2d`, `video`,
+  `bootupscreen`, `debug`, `errormissing`, `rotateenvironmentmap`,
+  `distortingobject`). The shared retail includes `shadowmap.fxh`, `ssao.fxh`,
+  `macrotexture.fxh`, `gamma.fxh` are likewise absent (`skinning.fxh` is done at
+  bind pose only).
+
+### M17 `ra3.ui` — platform layer & backends `[D]`
+
+- **F1 Display abstraction** `[D]`
+  - `[x]` shared primitives + interactive loops + `ui_event` mapping in the base
+  - `[x]` backends implement primitives only (SDL/Vulkan cannot drift)
+- **F2 SDL3 backend** `[D]`
+  - `[x]` window, streaming-texture blit, input polling
+  - `[ ]` gamepad support `(v0.8)`
+- **F3 Backend selection (`ra3.display`)** `[D]`
+  - `[x]` preferred backend + ordered fallback (Vulkan / D3D11 / D3D12 / SDL)
+  - `[x]` in-game Renderer option; report failure for offscreen fallback
+- **F4 Input mapping** `[~]`
+  - `[x]` keyboard/mouse state, modifier masks
+  - `[ ]` rebindable keybinds, mouse capture, scroll wheel events `(v0.6)`
+- **F5 Window modes** `[ ]`
+  - `[ ]` windowed/fullscreen/borderless, resize, multi-monitor `(v0.6)`
+- **F6 Null/headless backend** `[D]`
+  - `[x]` returns false so the tree builds and runs without SDL3/Vulkan
+
+### M18 `ra3.vulkan` — Vulkan backend `[P]`
+
+- **F1 Device & swapchain** `[~]`
+  - `[x]` embedded SPIR-V, SDL3 surface, present path
+  - `[ ]` formal RHI integration (see M16 F1) `(v0.6)`
+- **F2 Terrain presentation** `[D]`
+  - `[x]` GPU heightfield raymarch, mipmapped atlas, gutter, retail blend ramp
+- **F3 Materials & pipelines** `[~]`
+  - `[x]` static-model pipeline (vertex/index buffers, texture array, depth test)
+  - `[ ]` particle/HUD pipelines `(v0.6)`
+- **F4 Null fallback** `[D]`
+  - `[x]` report failure when no Vulkan loader is present
+
+### M18b `ra3.dx` — Direct3D 11 / 12 backend `[P]`
+
+- **F1 Device & swapchain** `[D]`
+  - `[x]` SDL3 window → HWND, DXGI flip-model swapchain, resize
+  - `[x]` runtime HLSL via `d3dcompiler_47` (no build-time shader compiler)
+- **F2 2D image path** `[D]`
+  - `[x]` BGRA scene texture + fullscreen-triangle blit (D3D11/D3D12)
+- **F3 Terrain presentation** `[D]`
+  - `[x]` GPU heightfield raymarch (HLSL port of `terrain.frag`), D3D11 and D3D12
+- **F4 Root signatures / PSOs (D3D12)** `[~]`
+  - `[x]` root constants, descriptor tables, static samplers, barriers
+  - `[ ]` shared RHI with Vulkan (see M16 F1) `(v0.6)`
+- **F5 Null fallback** `[D]`
+  - `[x]` non-Windows builds link a stub that fails `init`
+
+### M18d `ra3.wasmgl` — SDL-free wasm worker backend `[P]`
+
+- **F1 Device & canvas** `[D]`
+  - `[x]` Emscripten-only; engine runs on a plain Web Worker, WebGL2 on an
+    OffscreenCanvas transferred by the page (no SDL, no `PROXY_TO_PTHREAD`)
+  - `[x]` `specialHTMLTargets['#canvas']` lets `emscripten_webgl_create_context` find
+    the worker's OffscreenCanvas
+- **F2 2D image path** `[D]`
+  - `[x]` GLSL ES BGRA texture + fullscreen triangle (`.bgra` swizzle)
+- **F3 Terrain presentation** `[D]`
+  - `[x]` GPU heightfield raymarch (GLSL ES), including the `GL_R16`
+    (`0x822A`) heightmap and `GL_RGBA16` cell textures
+- **F4 On-demand assets** `[D]`
+  - `[x]` `assets.manifest.json` (from `scripts/make_web_manifest.py`) is embedded;
+    the worker registers every file with `FS.createLazyFile`, so only opened files
+    are fetched (a map pulls just its map + tiles)
+- **F5 Input** `[D]`
+  - `[x]` page owns DOM listeners and posts events to the worker's exported
+    `openra3_*` functions (no DOM callbacks in the worker)
+- **F6 Null fallback** `[D]`
+  - `[x]` non-Emscripten builds link a stub that fails `init`
+
+### M18e `ra3.webgpu` — WebGPU wasm backend `[P]`
+
+- **F1 Device & surface** `[D]`
+  - `[x]` Emscripten `emdawnwebgpu` port (Dawn C++ wrapper); the worker pre-creates
+    the device (`Module.preinitializedWebGPUDevice`) and a surface is configured on
+    the transferred OffscreenCanvas
+- **F2 WGSL shaders** `[D]`
+  - `[x]` web WebGPU is WGSL-only, so the scene/terrain shaders are WGSL ports
+    (the Vulkan SPIR-V blobs cannot be reused); the uniform layout and terrain data
+    plumbing are shared with Vulkan/WebGL
+- **F3 Terrain** `[D]`
+  - `[x]` GPU heightfield raymarch in WGSL (R16Uint heightmap, RGBA16Uint cell
+    record, RGBA8 atlas)
+- **F4 Selection & fallback** `[D]`
+  - `[x]` preferred wasm backend; falls back to `ra3.wasmgl` when no adapter is
+    available
+- **F5 Null fallback** `[D]`
+  - `[x]` non-Emscripten builds link a stub that fails `init`
+
+### M19 `ra3.audio` — audio `[ ]`
+
+- **F1 SFX** `[ ]`
+  - `[ ]` 3D positional sound from cues/events `(v0.7)`
+- **F2 Music** `[ ]`
+  - `[ ]` streaming music, playlists, combat stingers `(v0.7)`
+- **F3 Voice & EVA** `[ ]`
+  - `[ ]` unit response lines, announcer (EVA) events `(v0.7)`
+- **F4 Mixer** `[ ]`
+  - `[ ]` buses (master/sfx/music/voice), volume, ducking, reverb `(v0.7)`
+- **F5 Codecs** `[ ]` `!!`
+  - `[ ]` decode RA3 audio formats `(v0.7)`
+
+### M20 `ra3.video` — movies & cutscenes `[ ]`
+
+- **F1 Movie playback** `[ ]` `!!`
+  - `[ ]` intro/briefing/ending video decode + playback `(v0.8)`
+  - `[ ]` skip, subtitles, aspect handling `(v0.8)`
+- **F2 In-engine cutscenes** `[ ]`
+  - `[ ]` scripted camera + unit animation sequences `(v0.8)`
+
+### M21 `ra3.match` — game setup & match rules `[P]`
+
+- **F1 Game setup** `[~]`
+  - `[x]` map + two players + seed defaults
+  - `[ ]` faction/color/team/start-slot selection, AI personalities `(v0.7)`
+- **F2 Rules & options** `[ ]`
+  - `[ ]` starting cash, crates on/off, superweapons on/off, speed, limits `(v0.7)`
+- **F3 Match flow** `[~]`
+  - `[x]` `prepare_new_game` / `start_new_game` split mirroring retail
+  - `[ ]` loading progress, in-game start countdown `(v0.7)`
+- **F4 Factions** `[~]`
+  - `[x]` Allied / Soviet / Empire player templates
+  - `[ ]` full faction tech trees and rosters `(v0.5)`
+- **F5 Victory & scoring** `[~]`
+  - `[x]` team-wipe victory
+  - `[ ]` full victory conditions, post-match score screen `(v0.8)`
+
+### M22 `ra3.replay` — recording & playback `[ ]`
+
+- **F1 Recorder** `[ ]`
+  - `[ ]` capture command stream + seed + map id per match `(v0.4)`
+- **F2 Replay format** `[ ]`
+  - `[ ]` self-describing header, command log, checksums `(v0.4)`
+  - `[ ]` compatibility with retail `.RA3Replay` playback `!!` `(v0.9)`
+- **F3 Playback** `[ ]`
+  - `[ ]` deterministic re-simulation, speed control, seek `(v0.4)`
+- **F4 Golden replays** `[ ]`
+  - `[ ]` curated replay corpus as a regression test `(v0.4)`
+- **F5 Observer / spectator** `[ ]`
+  - `[ ]` watch live or recorded matches, fog option `(v0.9)`
+
+### M23 `ra3.save` — save/load & profiles `[ ]`
+
+- **F1 Save / load** `[ ]`
+  - `[ ]` full simulation state serialization (objects, modules, queues) `(v0.8)`
+  - `[ ]` versioned saves with migration `(v0.8)`
+- **F2 Profiles** `[ ]`
+  - `[ ]` player profile, stats, progress/unlocks `(v0.8)`
+- **F3 Options persistence** `[ ]`
+  - `[ ]` settings, keybinds, last-used skirmish config `(v0.7)`
+- **F4 Checkpoints** `[ ]`
+  - `[ ]` campaign checkpoint save/restore `(v0.9)`
+
+### M24 `ra3.mod` — data packages `[ ]`
+
+- **F1 Data packages** `[ ]`
+  - `[ ]` load order, override precedence, loose-file mounting `(v0.8)`
+- **F2 Content discovery** `[ ]`
+  - `[ ]` scan user mod dirs and additional `.big` archives `(v0.8)`
+- **F3 Mod validation** `[ ]`
+  - `[ ]` schema + reference checks, actionable errors `(v0.8)`
+
+### M25 `ra3.net` — LAN lockstep `[ ]` *(deferred, offline-only)*
+
+- **F1 Lockstep** `[ ]`
+  - `[ ]` deterministic lockstep over LAN, command-exchange only `(v1.0)`
+- **F2 Lobby & sync** `[ ]`
+  - `[ ]` lobby, slot/team assignment, start sync `(v1.0)`
+- **F3 Desync detection** `[ ]`
+  - `[ ]` state-hash comparison, desync report `(v1.0)`
+
+> No online service, matchmaking, EA account or third-party network
+> integration — ever. LAN only.
+
+### M26 `ra3.i18n` — localization `[P]`
+
+- **F1 CSF strings** `[~]`
+  - `[x]` parse `gamestrings.csf` (UTF-16 units, low byte `^0xFF`)
+  - `[x]` map display-name lookup (`MAP:<ID>`)
+  - `[ ]` full string-table load for all UI text `(v0.5)`
+- **F2 Language selection** `[~]`
+  - `[x]` newest `Lang-English*.big` wins
+  - `[ ]` all supported languages, fallback chain `(v0.5)`
+- **F3 Fonts & shaping** `[ ]`
+  - `[ ]` glyph coverage, CJK/RTL shaping where applicable `(v0.6)`
+- **F4 Substitution** `[ ]`
+  - `[ ]` placeholders, numbers, plurals `(v0.5)`
+
+### M27 `apps` — applications `[D]`
+
+- **F1 CLI** `[D]`
+  - `[x]` `menu` / `menu-preview` / `maps` / `skirmish` / `render` / `extract`
+  - `[ ]` `replay`, `benchmark`, `validate-data` subcommands `(v0.5)`
+- **F2 Extraction pipeline** `[~]`
+  - `[x]` `extract` → `assets/` (maps, terrain)
+  - `[ ]` full asset dump (models/textures/audio/movies) as a build target `(v0.5)`
+- **F3 Diagnostics** `[ ]`
+  - `[ ]` headless render/benchmark modes for CI `(v0.4)`
+
+### M28 `tools` — offline tooling `[~]`
+
+*(Python is permitted here; it is never linked into `openra3`.)*
+
+- **F1 Reference fetch** `[D]`
+  - `[x]` sparse-clone SAGE 1.0 reference into git-ignored `reference/`
+- **F2 Ghidra workflow** `[D]`
+  - `[x]` MCP-driven recovery loop + recovered symbol map (see RE doc)
+  - `[ ]` automated structure/table extractors `(v0.5)`
+- **F3 Format inspectors** `[ ]`
+  - `[ ]` BIG/RefPack/CkMp/W3D/APT dumpers `(v0.5)`
+- **F4 CI & packaging** `[D]`
+  - `[x]` GitLab CI builds both targets → test → package
+
+---
+
+## 4. Cross-cutting invariants
+
+These hold across **every** module above and are enforced in review:
+
+1. **Language** — runtime code is C++ only. Build tooling may use Python.
+2. **Ownership** — no raw owning pointers; `unique_ptr` for ownership, handles or
+   `thing *` views for references.
+3. **Layering** — a module imports only lower layers. `ra3.core` imports no
+   engine module and no platform API.
+4. **Determinism** — RNG, iteration, hashing and float use are explicit and
+   seedable; the logic step must be bit-reproducible for a given input stream.
+5. **RE-traceable** — retail structure/constant changes cite an address in
+   [`REVERSE_ENGINEERING.md`](REVERSE_ENGINEERING.md).
+6. **Offline** — no online service; LAN lockstep (M25) is the only networking,
+   and only command exchange.
+7. **No bundled assets** — game data is read from the user's install; nothing
+   from it is committed. The tree builds and runs in CI on a built-in test map.
+
+---
+
+## 5. Milestone mapping
+
+The plan rolls up to these releases:
+
+| Milestone | Modules advanced | Delivers |
+| --- | --- | --- |
+| `v0.3.x` (done) | M00, M01, M04, M05(F1–F3), M06, M07(partial), M08(partial), M10(partial), M16(F3,F8), M17, M18 | minimal deterministic skirmish, real terrain, Vulkan present, menu |
+| `v0.4.0` | M05(F4–F7), M06, M07, M08, M09(F1,F2,F4), M14, M22(F1–F4) | real update modules: locomotor, projectiles/warheads, placement, shroud, pathfinding, replay |
+| `v0.5.0` | M02, M03, M04(F3,F4), M08, M10(F3,F4), M11(F1,F2), M26 | data-driven content: deserialise `.bin`/`.manifest`, real rosters, maps, strings |
+| `v0.6.0` | M03(F1–F3), M07(F4,F6,F8,F14), M09(F2–F7), M16(F1,F2,F4,F5), M18(F3), M15(F1–F4,F8) | full renderer: perspective terrain, W3D models, in-game client + input |
+| `v0.7.0` | M13, M15(F5–F7), M19, M11(F4–F6), M20, M21 | HUD/command bar, audio, superweapons, Commander's Challenge |
+| `v0.8.0` | M12, M20(F1), M23, M24, M21(F5) | campaigns, cutscenes, save/load, mods |
+| `v0.9.0` | M22(F2,F5), M12(F6), M25 | retail replay playback, co-op, LAN lockstep |
+| `v1.0.0` | all | feature-complete offline RA3 |
+
+---
+
+## 6. Design rules
+
+The five rules the codebase is held to (restated from §1, with the concrete
+consequences that trip people up):
 
 1. **No raw owning pointers.** Ownership is `std::unique_ptr`; the partition
-   manager holds non-owning `thing *` views only.
+   manager and object registry hold non-owning `thing *` views only.
-2. **Portable simulation.** No platform APIs in `ra3.core` / `ra3.logic`. All
+2. **Portable simulation.** No platform APIs in `ra3.core` / simulation
-   platform concerns live behind `display`.
+   modules. All platform concerns live behind `display`.
 3. **Determinism.** Anything that can diverge between runs (random, iteration
    order) is explicit and seedable.
 4. **RE-traceable.** Where a structure or constant comes from the retail
    binary, the address is cited in the comment.
 5. **No bundled assets, no online.** Game data is read from the user's install
    and never committed; there is no networking or online service.
+
+---
+
+## 7. Where to start
+
+- New to the codebase: read this plan top-to-bottom (§3 is the feature set,
+  §5 the near-term order of work).
+- Picking up a feature: find its **Function** above, take the lowest-numbered
+  unmet `[ ]` **Feature**, and cite its supporting retail address.
+- Reverse engineering a subsystem: follow the loop in
+  [`REVERSE_ENGINEERING.md`](REVERSE_ENGINEERING.md); the `!!` tags above mark
+  the functions that still need a recovery pass before they can be built.

docs/REVERSE_ENGINEERING.md

@@ -78,6 +78,27 @@ Each holds an object pointer (0 when the subsystem is down).
   cash `+0x64`, player slots `+0xfc` (stride `0x5c`, 6 slots), faction at
   `slot + 0x18` (`Empire=2`, `Allied=4`, `Soviet=8`, `Random=7`).
 
+### Tactical view (camera)
+
+The in-game camera is the `TheTacticalView` object, held in the global at
+`0x00cdb7b4`. Its vtable accessors return zoom, pitch (current/target), yaw,
+world position and FOV; the debug overlay `FUN_005ef0a0` prints them through the
+format string at `0x00c0b900`. Mouse state is the singleton at `0x00ce9284`
+(cursor position vtable slot `+0x3c`, button down `+0x48`); the keyboard manager
+is `0x00ce927c` (modifier mask `+0x38`).
+
+Per-map camera tuning is a named-field table in `.rdata` (around
+`0x00c11a54`): `cameraMinHeight`, `cameraMaxHeight`, `cameraPitchAngle`,
+`cameraYawAngle`, `cameraScrollSpeedScalar`, `cameraGroundMinHeight`,
+`cameraGroundMaxHeight`. The map-load chunk `CHUNK_TacticalView`
+(`0x00beea14`, consumed near `0x00548a00`) seeds the view from the map; the
+tutorial actions `LOCK_CAMERA_SCROLL` / `LOCK_CAMERA_ZOOM` / `LOCK_CAMERA_ROTATION`
+gate the controls.
+
+OpenRA3 has no 3D terrain yet, so `ra3::render::view_camera` reproduces the
+*controls* - wheel zoom, screen-edge scroll, clamped pan and opening on the
+player's start - over the 2D map overview, not the retail perspective camera.
+
 ### Match start
 
 The BEGIN button calls `SkirmishGameOptionsMenu::start` (`0x00b28d60`), which
@@ -127,9 +148,270 @@ in `MPPositionList` instead yield no waypoints and fall back.
 Verified example (`map_mp_2_feasel4`): `Player_1_Start` = `(1338.9, 1940.5, 0)`,
 `Player_2_Start` = `(1290.8, 1404.9, 0)`.
 
+### Terrain (`ra3.terrain`)
+
+The `CkMp` tree is a flat chunk list: `"CkMp"`, `u32 assetCount`, the name
+table (`{ u8 len, name, u32 index }`, index descending from `assetCount`), then
+`{ u32 index, u16 version, u32 size, data }` per chunk. On
+`map_mp_2_feasel4` the terrain is `HeightMapData` v6 (540 x 600, border 20,
+`u16` elevations, scale `0.0390625`) and `BlendTileData` v27.
+
+`BlendTileData` opens with `NumTiles`, the `u16` tile grid, then the
+blend/three-way/cliff tables (`u16` for v27); the passability flag arrays that
+follow are not needed for rendering, so the texture table is located by
+scanning for its `{ cellStart, cellCount, cellSize, magic }` + `u16`-prefixed
+name entries. A tile value is `(cellIndex << 2) | variant`, and `cellIndex`
+indexes the global `TextureCellCount`-cell table (each texture owning
+`cellSize^2` 64 px cells). The textures themselves are
+`art\terrain\<stem>.tga` in `Terrain.big` / `Core11.big` (RefPack + 256x256
+TGA). Rendered top-down, `map_mp_2_feasel4` correlates 0.94 with the official
+`_art.tga` overview.
+
+### Terrain blending (`BlendTileData` tail)
+
+After the tile grid, `BlendTileData` stores three per-cell `u16` tables —
+`Blends`, `ThreeWayBlends` and `CliffTextures` — then `TextureCellCount`,
+`BlendsCount`, the texture table, two magic words and `BlendsCount - 1` blend
+descriptions (18 bytes each: `u32 secondaryTile`, four direction bytes,
+`u8 flags`, `u8 twoSided`, `u32 0xFFFFFFFF`, `u32 0x7ADA0000`). A non-zero
+`Blends[cell]` is a 1-based index into the descriptions; `secondaryTile` is a
+packed tile value (`secondaryTile >> 2` is its cell).
+
+The retail `Terrain.fx` (compiled `terrain.fxo`, parameters `Terrain.BaseTexture`,
+`Terrain.MacroTexture`, `MapCellSize`, `IsTerrainAtlasEnabled`; technique
+`TerrainTile`) cross-fades a cell's base tile into `secondaryTile` with a linear
+ramp selected by `BlendDirection`: `1` right, `2` top, `4` top-right, `8`
+top-left, where `flags` bit 0 flips the axis and bit 1 marks a two-sided
+diagonal. OpenSAGE's `Terrain.frag` reconstructs the exact
+`CalculateBlendFactor`; `ra3::terrain::blend_factor` and `shaders/terrain.frag`
+mirror it. The row axis is *not* inverted (73% of long-axis blends point at a
+neighbour of the same texture, versus 25% inverted). On `map_mp_2_feasel4`,
+33828 of 324000 cells carry a blend and there are 7094 descriptions.
+
+The GPU atlas pads every 64 px tile with a 2-texel replicated gutter. Packed
+edge-to-edge, bilinear/mipmap filtering averaged two unrelated tiles at every
+cell border — that cross-tile bleed was the visible grid line the hardware path
+drew. (`shaders/terrain.frag` samples `cell_stride = cell_texels + 2 * gutter`.)
+
+### Open question: per-cell tile sampling
+
+Measured on `map_mp_2_feasel4`, sampling each cell as its own 64 px block and
+restarting the UV every cell leaves a 1.39x edge spike at cell boundaries
+(43.4 vs 31.1 mean gradient at 8 px/cell). Two candidate mappings reduce it and
+need a visual decision against the retail art:
+
+| Mapping | Boundary/interior |
+| --- | --- |
+| per-cell 64 px block (current) | 1.39 |
+| OpenSAGE `BlendTileTextureIndex` Morton layout, 32 px block | 1.18 |
+| continuous `uv / (cellSize * 2)`, per OpenSAGE `Terrain.frag` | 1.11 |
+
+The retail `Terrain.frag` (OpenSAGE) samples the tile texture *continuously*
+(`uv / (CellSize * 2)`), so adjacent cells never restart the texture; our
+per-cell restart is the remaining source of grid lines. Switching the atlas
+from 64 px blocks to continuous 32 px regions (or the Morton 8x8 layout) is the
+next step, pending an art correlation check.
+
+### Compiled art (BinaryAssetBuilder) and map objects
+
+Retail RA3 ships no `.w3x`/`.w3d` files: BinaryAssetBuilder bakes every model,
+texture and script into a *binary asset stream* — a `.manifest` index plus a
+`.bin` of relocatable instance data (and optional `.relo`/`.imp` fixups). The
+layout (little-endian) is:
+
+```
+ManifestHeader (48 B)  isBigEndian u8, isLinked u8, version u16,
+                       streamChecksum, allTypesHash, assetCount u32,
+                       totalInstanceDataSize, maxInstance/maxRelocation/
+                       maxImportsChunkSize, assetReferenceBufferSize,
+                       referenceManifestNameBufferSize, assetNameBufferSize,
+                       sourceFileNameBufferSize
+AssetEntry (48 B) * count
+                       typeId, instanceId, typeHash, instanceHash,
+                       assetReferenceOffset i32, assetReferenceCount i32,
+                       nameOffset i32, sourceFileNameOffset i32,
+                       instanceDataSize i32, relocationDataSize i32,
+                       importsDataSize i32, tokenized u32
+then the reference / referenced-name / asset-name / source-name buffers
+```
+
+Asset names are `Type:Instance` (e.g. `W3DMesh:BB_GRASS02`). Instance pointers
+are stored as offsets from the start of the instance data (which begins at byte
+4 of `.bin`, after the stream checksum), so a slice is readable without the
+relocation stream.
+
+Each multiplayer map carries its own stream (`data\maps\official\<id>\map.bin`)
+but it is **linked**: only map-specific assets (the terrain texture atlas,
+scripts, `GameMap`) have data; the rendered props are imported and therefore
+have `instanceDataSize == 0`. The complete prop art (meshes + textures) lives in
+`Data\WBData.big`'s `data\worldbuilder.bin`, which is **uncompressed** (first
+four bytes are the stream checksum, not `10 FB`), so `ra3.models` reads the
+1.1 GB stream lazily — the manifest is parsed and only the needed instance
+slices are read.
+
+`W3DMesh` compiled layout (offsets from the instance start):
+
+```
++4   vertexBufferPtr        +52 triangleCount      +56 triangleItemPtr
++60  shaderNameLength       +64 shaderNamePtr
+vertexBuffer: +0 numVertices, +4 stride, +8 elementDataPtr,
+              +12 declarationBytes, +16 declarationPtr
+declaration:  text "p0:00:3f32 n0:0C:3f32 t0:1C:2f32" (D3D9 usage:index:offset:type)
+triangles:    triangleCount * { u32 indexCount, u32 indexPtr } (24 B each), u32 indices
+```
+
+The diffuse texture is found through the mesh's `FXShaderConstant`s
+(`+76` count, `+80` items): a texture-valued constant (TypeId `0xA59096A6`)
+names its role (`DiffuseTexture`, `NormalMap`, `SpecMap`) and points at a
+1-based index into the mesh's cross-asset references, which resolve by
+`(typeId, instanceId)`. The `Texture` instance embeds a standard DDS file (at
+`u32@+4`, or scan for `"DDS "`); `ra3.models::decode_dds` decodes DXT1/3/5 and
+uncompressed 16/24/32-bit.
+
+**Vertices are stored in bone space, not object space.** A mesh whose vertex
+declaration carries blend data (`i0:..:4u8 w0:..:4u8n`, e.g. buildings and
+vehicles) must be skinned; props without it (`BB_GRASS02`, `IF_STREETSEGMENT01`)
+are already in object space. The skeleton is a `W3DHierarchy` asset named after
+the mesh's instance prefix (`W3DMesh:FI_STRUCTURE_02.NEWSKIN_CIV01` →
+`W3DHierarchy:FI_STRUCTURE_02`). Compiled layout:
+
+```
+W3DHierarchy: u32 pad, u32 boneCount, u32 headerBytes, then boneCount records
+100 B each:
+    u32 nameHash, i32 parent (-1 = root), f32 translation[3],
+    f32 quaternion[4] (x, y, z, w), f32 matrix[12]
+```
+
+The default (bind) pose is rebuilt by composing each bone's local
+translation/quaternion down the parent chain, then `skinnedPos = Σ wᵢ ·
+(Rᵢ·p + Tᵢ)` (and the normal by the rotation only). `ra3.models` does this before
+placing the mesh at the map object's `(x, y, angle)`.
+
+The compiled shader (below) binds **one joint per vertex** — `WorldBones` holds
+64 bones as 2 `float4` each (quaternion `c[128+2j]`, translation `c[129+2j]`) —
+so the skin is rigid: `blendindices.x` selects the joint, remapped through the
+mesh's per-model **bone table** (vertex-descriptor `+0x14` = bone count,
+`+0x18` = `u16` bone indices into the `W3DHierarchy`). Applying the raw blend
+index without that remap tears models apart (`FI_BUILDING01`'s table is
+`[0,14,15,16,17,18]`, not `[0..5]`).
+
+The map objects that lie flat on the ground (sidewalks, deck pieces) are
+coplanar with the terrain; retail biases their depth in the shader so they do
+not z-fight. The object pass reproduces that with a small negative depth bias
+(Vulkan `depthBiasConstant/SlopeFactor`, and a half-unit bias in the software
+rasteriser).
+
+Meshes whose material has no diffuse texture (`DefaultW3D.fx`, `BasicW3D.fx` —
+`FXLIGHTS`/ambient helper billboards) are not opaque geometry and are skipped;
+drawing them fills the frame with garbage triangles. Likewise the
+`BuildingsGenericDamageFill.fx` **damage-fill** sub-meshes are skipped: they are
+the wrecked-interior shell (e.g. `CBBuilding_Wood`, an orange plank texture) that
+retail only reveals through damage holes, but our opaque pass would paint it over
+the main shell and tint whole buildings warm.
+
+### Official shader behaviour (`Shaders.big` → `*.fxo`)
+
+The compiled D3D9 effects in `Data\Shaders.big` name their parameters, so the
+model pipeline is recoverable. `buildingsgeneric.fxo` (`BuildingsGeneric.fx`)
+vertex stage: skinning (above), `World`/`ViewProjection`, and vertex color
+`c0` multiplied into the lit color
+(`(Ambient·AmbientColor + Σ DLᵢ.Color·max(N·DLᵢ,0)) · DiffuseColor · vertexColor`).
+Pixel stage samples `DiffuseTexture`/`NormalMap`/`SpecMap`/`DamagedTexture`/
+`CloudTexture` (all at **UV0**, except `DamagedTexture` at `v0.wz` = transposed
+UV1), then `final.rgb *= TintColor` and `*= ShroudTexture.rgb`. `DiffuseVelocity`
+is not used for static structures. So the diffuse texture is UV0 and is tinted by
+vertex color and `TintColor`; `basicw3d.fxo` instead modulates a single
+macro/lightmap with `(vertexColor + additive) * diffuse * 2` and has no normal
+map. (Recovered by disassembling the embedded `vs_3_0`/`ps_3_0` bytecode.)
+
+### Water / ocean (`Ocean.fx`, `OceanDisplacement.fx`, `RiverWater.fx`, `UnderwaterDeferred.fx`)
+
+The SAGE water surface is reconstructed by OpenSAGE as
+`Assets/Shaders/Water.vert`+`Water.frag` (same family as retail `Ocean.fx`). The
+surface is a world-space mesh drawn with alpha blending, fed by two render
+targets rendered before it: a **reflection** map (scene from the mirrored camera
+about `GlobalWaterSettings.ReflectionPlaneZ`) and a **refraction** map + depth.
+The fragment model (`Water.frag`) is:
+
+- `waterUV = worldPos.xy / 320`; a scrolling `WaterTexture` supplies both a
+  flow distortion (`(tex.xy*2-1)*0.05`) and the flow layer; a `BumpTexture`
+  supplies the surface `worldNormal`.
+- `fresnelFactor = dot(viewVector, +Z)`; reflection/refraction are sampled in
+  screen space (`gl_FragCoord / ViewportSize`), each displaced by the distortion.
+- `linearWaterDepth = linearize(RefractionDepth) - linearize(gl_FragCoord.z)`;
+  `alpha = clamp((linearWaterDepth/2)/TransparentWaterDepth, 0, TransparentWaterMinOpacity)`.
+- `final = diffuseColor * textureColor * cloudColor`, then mixed with
+  `mix(reflectionColor, refractionColor, fresnelFactor)` (both maps on) or just
+  one of them, per `IsRenderReflection` / `IsRenderRefraction`.
+- Per-time-of-day `WaterSet`: `WaterTexture`, `UScrollPerMS`/`VScrollPerMS`,
+  `DiffuseColor`, `TransparentDiffuseColor`; `WaterTransparency` supplies
+  `TransparentWaterDepth`/`TransparentWaterMinOpacity`, the skybox faces,
+  `RiverTransparencyMultiplier`, `ReflectionPlaneZ`/`ReflectionOn`.
+
+OpenRA3 has no water mesh or reflection/refraction targets (its terrain is
+raymarched), so the model is folded into the terrain pass (`shaders/terrain.frag`
+and its HLSL/GLSL-ES/WGSL twins): the ray's water-plane hit takes a scrolling
+wave normal built from the retail bump map combined with a de-gridded procedural
+wave, Schlick fresnel (F0 = 0.02), a sky reflection and a depth-graded
+refraction, SAGE diffuse + specular lighting, a depth-based transparency fade,
+and — when the camera is below `ReflectionPlaneZ` — an underwater tint/fog
+(`UnderwaterDeferred.fx`). The two retail maps
+`art/terrain/ra3_deepocean.tga` (flow/distortion) and `ra3_deepocean_nrm.tga`
+(bump normal) are appended as the **last two layers of the terrain atlas**
+(`ra3::terrain::build_gpu_terrain`, `water_flow = layer_count - 2`,
+`water_normal = layer_count - 1`), so every backend samples them with the
+existing atlas binding; absent maps fall back to a neutral layer. True
+reflection/refraction render targets are still the next step.
+`GPUParticleOceanDisplacement.fx` drives wave displacement from a GPU particle
+buffer and has no analogue here.
+
+
+The map's `ObjectsList` chunk is a list of nested `Object` assets —
+`Coord3D`, Z `angle`, `RoadType` u32, a `u16`-prefixed type-name and a property
+list whose keys index the shared name table (`ra3.map::parse_objects`). Each
+type resolves to the `W3DMesh` parts whose instance name equals it or starts
+with `<type>.`.
+
+### Roads / sidewalks (`Road` assets)
+
+The flat sidewalk and road decals are not meshes: the map places them as
+**consecutive pairs** of objects — a `RoadType::Start` (`2`) and a
+`RoadType::End` (`4`) at the segment's two ends (`Angled` `8`, `TightCurve`
+`64` and `EndCap` `128` are curve/cap flags; `BridgeStart/End` `16/32` are
+bridges). The road's type-name (`IslandFortressSidewalk01`, ...) resolves to a
+compiled `Road` asset in the same art stream:
+
+```
+Road: u32 version, u32 pad, u32 textureCount, f32 roadWidth, f32 pad,
+      f32 ???, then textureCount texture references (diffuse, normal)
+```
+
+`ra3.models` pairs the objects in file order, emits a flat quad ribbon of
+`roadWidth` along each segment (overlapping the joins by half a width), sampled
+with the diffuse texture, and lifts it onto the terrain. Retail gives roads a
+small depth offset toward the screen so they do not clip into the ground; the
+object pass reproduces that with the same negative depth bias used for the other
+ground decals (`depthBiasConstant/SlopeFactor` on Vulkan, a half-unit bias in the
+software rasteriser).
+
+### Map display names
+
+The skirmish map list labels live in `Data\English.big`'s
+`data\gamestrings.csf` (the newest `Lang-English*.big` wins) under
+`MAP:<UPPERCASE_ID>`, e.g. `MAP:MAP_MP_2_FEASEL4` = "Battlebase Beta". CSF
+values are UTF-16 code units whose low byte is XORed with `0xFF`
+(`ra3::map::parse_map_names`). `openra3 extract` writes the decoded table to
+`maps/map_names.tsv`; `openra3 menu` shows them instead of the raw map id.
+
+
 ### Still to recover
 
 - `MPPositionList` layout (per-player starts for maps without waypoints).
-- Map dimensions / `HeightMapData` / `BlendTileData`.
+- Cliff textures and the `CliffTextureMapping` UV remap (`CliffTextures` is
-- Compiled asset blobs (`map.bin`, `global.bin`, `static.*.bin`) and the
+  parsed but not yet drawn).
-  `.manifest` schema used to deserialise them.
+- The `Road` network mesher (the map's sidewalk/road objects reference `Road`
+  templates, not `W3DMesh` assets).
+- W3D container/hierarchy assembly and animation (props are drawn as their
+  static mesh parts; skinned/animated in-game models are not).
+- Compiled asset blobs (`global.bin`, `static.*.bin`) and the `.manifest`
+  schema used to deserialise them.

docs/ROADMAP.md

@@ -1,45 +0,0 @@
-# Roadmap
-
-OpenRA3 is a very large undertaking. This roadmap is deliberately honest about
-scope: reconstructing a 2008 RTS engine from a decompiler plus a related open
-engine is a multi-year, multi-person effort. The milestones below are ordered so
-that each one produces something that builds and runs.
-
-## Done
-
-- [x] **v0.0.1 — skeleton + minimal skirmish.** C++26 modules, GCC 16,
-      CMake/Ninja, Docker `dev`/`deploy`, GitLab CI. Reads `BIG4`/RefPack data
-      from a local install, recovers map start waypoints, and runs a
-      deterministic headless two-player skirmish to a decision.
-- [x] **v0.1.0 — map renderer + window.** Software ARGB framebuffer, TGA
-      decoder for the map art, BMP output, map/grid/unit compositing, and an
-      SDL3 window viewer (pan/zoom).
-
-## Next
-
-- [ ] **v0.1.1 — correct world calibration.** Parse the map heightmap
-      dimensions (and `MPPositionList` starts) so the unit overlay lines up with
-      the map art instead of using an assumed world size.
-- [ ] **v0.2.0 — data & file formats.** Parse compiled gameplay assets
-      (`GameObject`, `WeaponTemplate`, `ArmorTemplate`, `LocomotorTemplate`) so
-      units use the real balance numbers instead of OpenRA3's stand-ins.
-- [ ] **v0.3.0 — deterministic simulation.** Real update modules, locomotor
-      movement, weapons/damage/armour resolution, build queues and the tech
-      tree, pathfinding and shroud.
-- [ ] **v0.4.0 — AI.** Skirmish AI: build states, team composition, attack
-      waves (the reference tree's `AI*` modules).
-- [ ] **v0.5.0 — full renderer.** Terrain heightmap rendering, W3D models and a
-      D3D9/Vulkan/OpenGL client backend implementing `ra3::client::display`,
-      plus full input.
-- [ ] **v0.6.0 — content.** Load real maps, units, powers and strings; play a
-      skirmish end-to-end with a UI.
-
-## Cross-cutting tracks
-
-- **RE depth** — keep recovering retail layouts (see
-  [`REVERSE_ENGINEERING.md`](REVERSE_ENGINEERING.md)); every structure gets an
-  address citation and a test.
-- **Determinism & replay** — the logic random stream and frame ordering must be
-  reproducible; replay format and a golden-replay test suite.
-- **Offline only** — no online mode. Multiplayer, if pursued, is LAN lockstep on
-  the message stream, never an online service.

scripts/build-debian-arm64.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Build the Debian (latest stable) Linux/ARM64 target (.deb + binary).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+IMAGE="${OPENRA3_DEBIAN_ARM64_IMAGE:-openra3-debian-arm64:local}"
+BUILD_DIR="${1:-build/debian-arm64}"
+
+docker build --target dev -f "$ROOT/Dockerfile.debian-arm64" -t "$IMAGE" "$ROOT"
+docker run --rm -v "$ROOT:/work" -w /work "$IMAGE" cmake -S . -B "$BUILD_DIR" -G Ninja \
+    -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/clang-aarch64-linux-gnu.cmake \
+    -DCMAKE_BUILD_TYPE=Release \
+    -DOPENRA3_AARCH64_CC=clang-19 -DOPENRA3_AARCH64_CXX=clang++-19 \
+    -DOPENRA3_AARCH64_STDLIB_MODULES_JSON=/usr/lib/llvm-19/lib/libc++.modules.json \
+    -DOPENRA3_DISTRO_TAG=debian13
+docker run --rm -v "$ROOT:/work" -w /work "$IMAGE" cmake --build "$BUILD_DIR" -j
+docker run --rm -v "$ROOT:/work" -w /work "$IMAGE" bash -c "cd $BUILD_DIR && cpack -G DEB"
+
+echo "Debian arm64: $ROOT/$BUILD_DIR/bin/openra3 (+ .deb)"

scripts/build-debian.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Build the Debian (latest stable) target (.deb + binary) with the isolated image.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+IMAGE="${OPENRA3_DEBIAN_IMAGE:-openra3-debian:local}"
+BUILD_DIR="${1:-build/debian}"
+
+docker build --target dev -f "$ROOT/Dockerfile.debian" -t "$IMAGE" "$ROOT"
+docker run --rm -v "$ROOT:/work" -w /work "$IMAGE" cmake -S . -B "$BUILD_DIR" -G Ninja \
+    -DCMAKE_BUILD_TYPE=Release \
+    -DCMAKE_CXX_STDLIB_MODULES_JSON=/usr/lib/llvm-19/lib/libc++.modules.json \
+    -DOPENRA3_DISTRO_TAG=debian13
+docker run --rm -v "$ROOT:/work" -w /work "$IMAGE" cmake --build "$BUILD_DIR" -j
+docker run --rm -v "$ROOT:/work" -w /work "$IMAGE" bash -c "cd $BUILD_DIR && cpack -G DEB"
+
+echo "Debian: $ROOT/$BUILD_DIR/bin/openra3 (+ .deb)"

scripts/build-linux-arm64.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Build the Linux/ARM64 target (.deb + binary) with the isolated cross image.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+IMAGE="${OPENRA3_LINUX_ARM64_IMAGE:-openra3-linux-arm64:local}"
+BUILD_DIR="${1:-build/linux-arm64}"
+
+docker build --target dev -f "$ROOT/Dockerfile.linux-arm64" -t "$IMAGE" "$ROOT"
+docker run --rm -v "$ROOT:/work" -w /work "$IMAGE" cmake -S . -B "$BUILD_DIR" -G Ninja \
+    -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/clang-aarch64-linux-gnu.cmake \
+    -DCMAKE_BUILD_TYPE=Release -DOPENRA3_DISTRO_TAG=ubuntu26.04
+docker run --rm -v "$ROOT:/work" -w /work "$IMAGE" cmake --build "$BUILD_DIR" -j
+docker run --rm -v "$ROOT:/work" -w /work "$IMAGE" bash -c "cd $BUILD_DIR && cpack -G DEB"
+
+echo "Linux arm64: $ROOT/$BUILD_DIR/bin/openra3 (+ .deb)"

scripts/build-linux.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Build the Linux target inside its own isolated image (Dockerfile).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+IMAGE="${OPENRA3_LINUX_IMAGE:-openra3-linux:local}"
+BUILD_DIR="${1:-build/linux}"
+
+docker build --target dev -t "$IMAGE" "$ROOT"
+docker run --rm -v "$ROOT:/work" -w /work "$IMAGE" cmake -S . -B "$BUILD_DIR" -G Ninja -DCMAKE_BUILD_TYPE=Release
+docker run --rm -v "$ROOT:/work" -w /work "$IMAGE" cmake --build "$BUILD_DIR" -j
+docker run --rm -v "$ROOT:/work" -w /work "$IMAGE" ctest --test-dir "$BUILD_DIR" --output-on-failure
+
+echo "Linux build: $ROOT/$BUILD_DIR/bin/openra3"

scripts/build-wasm.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Build the WebAssembly target (openra3.js/.wasm + worker + page) with the
+# Emscripten image.
+#
+# The engine runs inside a plain Web Worker and renders into an OffscreenCanvas
+# with no SDL, so assets load on demand: point OPENRA3_WEB_ASSETS at the
+# extracted asset tree and the build generates an assets manifest, embeds it, and
+# registers every file as an Emscripten lazy file at startup. The browser then
+# fetches each asset only when the engine opens it.
+#
+#   OPENRA3_WEB_ASSETS=/path/to/assets scripts/build-wasm.sh
+#
+# open http://localhost:8199/index.html
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+IMAGE="${OPENRA3_WASM_IMAGE:-openra3-wasm:local}"
+BUILD_DIR="${1:-build/wasm}"
+
+docker build --target dev -f "$ROOT/Dockerfile.wasm" -t "$IMAGE" "$ROOT"
+
+mounts=(-v "$ROOT:/work")
+configure=(-DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/emscripten-wasm.cmake -DCMAKE_BUILD_TYPE=Release)
+serve_assets=()
+if [ -n "${OPENRA3_WEB_ASSETS:-}" ]; then
+    mounts+=(-v "$OPENRA3_WEB_ASSETS:/assets:ro")
+    manifest="$ROOT/$BUILD_DIR/assets.manifest.json"
+    mkdir -p "$(dirname "$manifest")"
+    python3 "$ROOT/scripts/make_web_manifest.py" --root "$OPENRA3_WEB_ASSETS" --out "$manifest"
+    configure+=(-DOPENRA3_WEB_MANIFEST="/work/$BUILD_DIR/assets.manifest.json")
+    serve_assets=(--assets "$OPENRA3_WEB_ASSETS")
+fi
+
+docker run --rm "${mounts[@]}" -w /work "$IMAGE" cmake -S . -B "$BUILD_DIR" -G Ninja "${configure[@]}"
+docker run --rm "${mounts[@]}" -w /work "$IMAGE" cmake --build "$BUILD_DIR" -j
+
+echo "WebAssembly: $ROOT/$BUILD_DIR/bin/index.html (+ openra3.js/.wasm, openra3.worker.js)"
+echo "serve:  python3 \"$ROOT/apps/web/serve.py\" --root \"$ROOT/$BUILD_DIR/bin\" ${serve_assets[*]:-}"

scripts/build-windows-arm64.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Build the Windows/ARM64 target (portable .zip) with the isolated cross image.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+IMAGE="${OPENRA3_WINDOWS_ARM64_IMAGE:-openra3-windows-arm64:local}"
+BUILD_DIR="${1:-build/windows-arm64}"
+
+docker build --target dev -f "$ROOT/Dockerfile.win-arm64" -t "$IMAGE" "$ROOT"
+docker run --rm -v "$ROOT:/work" -w /work "$IMAGE" cmake -S . -B "$BUILD_DIR" -G Ninja \
+    -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/llvm-mingw-aarch64.cmake \
+    -DCMAKE_BUILD_TYPE=Release
+docker run --rm -v "$ROOT:/work" -w /work "$IMAGE" cmake --build "$BUILD_DIR" -j
+docker run --rm -v "$ROOT:/work" -w /work "$IMAGE" bash -c "cd $BUILD_DIR && cpack -G ZIP"
+
+echo "Windows arm64: $ROOT/$BUILD_DIR/bin/openra3.exe (+ .zip)"

scripts/build-windows.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Build the Windows x86_64 target inside its own isolated image (Dockerfile.win).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+IMAGE="${OPENRA3_WINDOWS_IMAGE:-openra3-windows:local}"
+BUILD_DIR="${1:-build/windows}"
+
+docker build --target dev -f "$ROOT/Dockerfile.win" -t "$IMAGE" "$ROOT"
+docker run --rm -v "$ROOT:/work" -w /work "$IMAGE" \
+    cmake -S . -B "$BUILD_DIR" -G Ninja \
+        -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/llvm-mingw-x86_64.cmake \
+        -DCMAKE_BUILD_TYPE=Release
+docker run --rm -v "$ROOT:/work" -w /work "$IMAGE" cmake --build "$BUILD_DIR" -j
+
+echo "Windows build: $ROOT/$BUILD_DIR/bin/openra3.exe (+ SDL3.dll)"

scripts/make_web_manifest.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""Generate the wasm lazy-asset manifest.
+
+The wasm build runs the engine on a worker, where synchronous XHR is legal, so
+assets are registered with ``FS.createLazyFile`` instead of being preloaded: the
+browser fetches each file only when the engine first opens it. This script lists
+every file under the assets root (as POSIX-relative paths) as
+``{"files": [...]}``; CMake preloads the manifest to ``/assets.manifest.json``.
+
+    scripts/make_web_manifest.py --root /path/to/assets --out assets.manifest.json
+
+Serve the tree at ``<wasm-root>/assets`` (or use ``serve.py --assets``).
+"""
+
+import argparse
+import json
+import os
+import sys
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate the OpenRA3 wasm asset manifest")
+    parser.add_argument("--root", required=True, help="assets root to enumerate")
+    parser.add_argument("--out", required=True, help="manifest JSON to write")
+    args = parser.parse_args()
+
+    if not os.path.isdir(args.root):
+        print(f"root not found: {args.root}", file=sys.stderr)
+        return 1
+
+    files = []
+    for dirpath, dirnames, filenames in os.walk(args.root):
+        dirnames.sort()
+        for name in sorted(filenames):
+            rel = os.path.relpath(os.path.join(dirpath, name), args.root).replace(os.sep, "/")
+            files.append(rel)
+
+    with open(args.out, "w", encoding="utf-8") as handle:
+        json.dump({"files": files}, handle, separators=(",", ":"))
+        handle.write("\n")
+    print(f"wrote {args.out} ({len(files)} files)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

shaders/compile.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env sh
+# Regenerate the committed SPIR-V blobs under shaders/generated/.
+#
+# The build embeds the .spv files directly (see CMakeLists.txt), so no shader
+# compiler is needed to build OpenRA3. Run this only after editing a .vert/.frag.
+#
+# Needs one of: glslc (shaderc) or glslangValidator (glslang-tools). On a host
+# without either, use a throwaway container:
+#   docker run --rm -v "$PWD/shaders:/s" ubuntu:26.04 bash -c \
+#     "apt-get update -qq && apt-get install -y -qq glslang-tools && \
+#      cd /s && sh ./compile.sh"
+set -eu
+
+DIR="$(cd "$(dirname "$0")" && pwd)"
+OUT="$DIR/generated"
+mkdir -p "$OUT"
+
+compile() {
+    src="$1"
+    dst="$2"
+    if command -v glslc >/dev/null 2>&1; then
+        glslc "$src" -o "$dst"
+    else
+        glslangValidator -V "$src" -o "$dst"
+    fi
+}
+
+for name in scene terrain object; do
+    compile "$DIR/$name.vert" "$OUT/$name.vert.spv"
+    compile "$DIR/$name.frag" "$OUT/$name.frag.spv"
+done
+
+echo "wrote $OUT/{scene,terrain,object}.{vert,frag}.spv"

shaders/dx_scene.hlsl

@@ -0,0 +1,34 @@
+// 2D image blit for the Direct3D backends (the D3D port of scene.vert/scene.frag).
+//
+// The scene image is drawn as a single fullscreen triangle sampling the
+// software-rendered `ra3::render::image`. The constant buffer carries the
+// destination rectangle in window-normalized coordinates (y down), so the map
+// is letterboxed rather than stretched. D3D clip space has +Y up, so the vertex
+// position flips Y relative to the Vulkan shader (which relies on Vulkan's
+// +Y-down clip space); the sampled UVs and the image's top-left origin are
+// unchanged.
+
+cbuffer RectCB : register(b0) {
+    float4 rect; // xy = top-left (0..1), zw = size (0..1)
+};
+
+Texture2D scene_tex : register(t0);
+SamplerState scene_smp : register(s0);
+
+struct VSOut {
+    float4 pos : SV_Position;
+    float2 uv : TEXCOORD0;
+};
+
+VSOut VSMain(uint vertex_id : SV_VertexID) {
+    float2 p = float2((vertex_id << 1) & 2, vertex_id & 2);
+    VSOut o;
+    o.uv = (p - rect.xy) / rect.zw;
+    o.pos = float4(p.x * 2.0 - 1.0, 1.0 - p.y * 2.0, 0.0, 1.0);
+    return o;
+}
+
+float4 PSMain(VSOut input) : SV_Target {
+    if (input.uv.x < 0.0 || input.uv.x > 1.0 || input.uv.y < 0.0 || input.uv.y > 1.0) discard;
+    return scene_tex.Sample(scene_smp, input.uv);
+}

shaders/dx_terrain.hlsl

@@ -0,0 +1,358 @@
+// GPU heightfield raymarcher for the Direct3D backends (the D3D port of
+// terrain.vert/terrain.frag).
+//
+// Textures: heightmap (R16), a per-cell blend record (R16G16B16A16_UNORM: base
+// layer, blend layer, three-way layer, packed direction/flags; unpacked with
+// *65535) and a texture array of the tile materials (RGBA8, REPEAT). The
+// material is sampled continuously (`uv = cell / span`), as the retail
+// `Terrain.fx` / OpenSAGE `Terrain.frag` do, so it never restarts at a cell
+// edge; material boundaries cross-fade with the SAGE blend ramp.
+//
+// The water plane is shaded with a port of the SAGE water effect
+// (`Ocean.fx` / OpenSAGE `Water.frag`); the camera-below-water tint stands in
+// for `UnderwaterDeferred.fx`. See docs/REVERSE_ENGINEERING.md.
+//
+// The Vulkan push constants (20 floats) become a constant buffer.
+
+cbuffer TerrainCB : register(b0) {
+    float4 cam;     // x=target_x, y=target_y, z=yaw, w=height
+    float4 params;  // x=pitch, y=fov, z=water_z, w=has_water
+    float4 sun;     // xyz=sun dir, w=ambient
+    float4 mapinfo; // x=W, y=H, z=unused, w=z_scale
+    float4 misc;    // x=time, y=water kind (0=ocean,1=river), z=cells per repeat, w=aspect
+};
+
+Texture2D<float> heightmap : register(t0);
+Texture2D<float4> celldata : register(t1);
+Texture2DArray<float4> atlas : register(t2);
+SamplerState height_smp : register(s0);
+SamplerState cell_smp : register(s1);
+SamplerState atlas_smp : register(s2);
+
+static const float CELL = 10.0; // must match ra3::terrain::cell_size
+
+// SAGE water model constants (see docs/REVERSE_ENGINEERING.md).
+static const float WATER_SCALE = 1.0 / 320.0;
+static const float WATER_TRANSPARENT_DEPTH = 10.0;
+static const float WATER_MIN_OPACITY = 0.70;
+static const float WATER_RIVER_MULTIPLIER = 1.0;
+
+struct VSOut {
+    float4 pos : SV_Position;
+    float2 uv : TEXCOORD0;
+};
+
+VSOut VSMain(uint vertex_id : SV_VertexID) {
+    float2 p = float2((vertex_id << 1) & 2, vertex_id & 2);
+    VSOut o;
+    o.uv = p;
+    o.pos = float4(p.x * 2.0 - 1.0, 1.0 - p.y * 2.0, 0.0, 1.0);
+    return o;
+}
+
+float height_at(int2 c) {
+    c = clamp(c, int2(0, 0), int2((int) mapinfo.x - 1, (int) mapinfo.y - 1));
+    return heightmap.Load(int3(c, 0)) * 65535.0 * mapinfo.w;
+}
+
+float world_height(float wx, float wy) {
+    float world_w = mapinfo.x * CELL;
+    float world_h = mapinfo.y * CELL;
+    if (wx < 0.0 || wy < 0.0 || wx >= world_w || wy >= world_h) return -1.0e9;
+    int2 c = int2((int) (wx / CELL), (int) ((world_h - wy) / CELL));
+    return height_at(c);
+}
+
+float3 sky_color(float3 dir) {
+    float3 d = normalize(dir);
+    float3 sun_dir = normalize(sun.xyz);
+    float t = clamp(d.z, 0.0, 1.0);
+    float3 horizon = float3(0.70, 0.78, 0.85);
+    float3 zenith = float3(0.28, 0.48, 0.80);
+    float3 col = lerp(horizon, zenith, pow(t, 0.6));
+    float s = max(dot(d, sun_dir), 0.0);
+    col += float3(1.0, 0.95, 0.82) * pow(s, 300.0) * 1.6; // sun disk
+    col += float3(1.0, 0.90, 0.72) * pow(s, 8.0) * 0.18;  // glow
+    return col;
+}
+
+// The retail SAGE blend ramp: 0 at one edge of the cell, 1 at the opposite.
+// Direction: 1 right, 2 top, 4 top-right, 8 top-left; flag bit 0 flips,
+// bit 1 marks a two-sided diagonal.
+float blend_factor(uint direction, uint flags, float2 f) {
+    bool flipped = (flags & 1u) != 0u;
+    bool two_sided = (flags & 2u) != 0u;
+    if (flipped) {
+        if (direction == 1u) {
+            f.x = 1.0 - f.x;
+        } else if (direction == 2u || direction == 4u || direction == 8u) {
+            f.y = 1.0 - f.y;
+        }
+    }
+    if (direction == 1u) return f.x;
+    if (direction == 2u) return f.y;
+    if (direction == 4u) {
+        float s = (1.0 - f.x) + (1.0 - f.y);
+        return two_sided ? 1.0 - clamp(s - 1.0, 0.0, 1.0) : clamp(1.0 - s, 0.0, 1.0);
+    }
+    if (direction == 8u) {
+        float s = f.x + (1.0 - f.y);
+        return two_sided ? 1.0 - clamp(s - 1.0, 0.0, 1.0) : clamp(1.0 - s, 0.0, 1.0);
+    }
+    return 0.0;
+}
+
+// Sample one tile material layer at global cell coordinates. The texture repeats
+// every `span` cells with REPEAT addressing, so it never restarts at a cell edge.
+float3 sample_layer(uint layer, float wx, float wy) {
+    float span = max(misc.z, 1.0);
+    uint lw = 0;
+    uint lh = 0;
+    uint layer_count = 0;
+    atlas.GetDimensions(lw, lh, layer_count);
+    float l = (float) min(layer, layer_count > 0u ? layer_count - 1u : 0u);
+    return atlas.Sample(atlas_smp, float3(float2(wx, wy) / span, l)).rgb;
+}
+
+// ---- SAGE water (Ocean.fx / RiverWater.fx / Water.frag port) ----------------
+
+// Sample an atlas layer by an explicit layer index (the water flow/bump maps
+// are appended as the last two layers of the tile atlas).
+float3 water_tex(int layer, float2 uv) {
+    uint w = 0;
+    uint h = 0;
+    uint lc = 0;
+    atlas.GetDimensions(w, h, lc);
+    float l = (float) clamp(layer, 0, (int) lc - 1);
+    return atlas.Sample(atlas_smp, float3(uv, l)).rgb;
+}
+
+// Scrolling wave normal on the water plane: the retail bump map (atlas's last
+// layer), offset by the flow map (second-last layer) and combined with a
+// de-gridded procedural wave so the sun glint is irregular and always moving.
+float3 water_normal(float2 world_xy, float time) {
+    float2 q = world_xy * (WATER_SCALE * 6.0);
+    float a1 = q.x * 0.80 + q.y * 0.30 + time * 1.10;
+    float a2 = q.y * 0.95 - q.x * 0.45 - time * 1.30;
+    float a3 = (q.x + q.y) * 1.60 + time * 2.10;
+    float a4 = (q.x - q.y) * 2.30 - time * 1.70;
+    float dx = 0.224 * cos(a1) - 0.099 * cos(a2) + 0.256 * cos(a3) + 0.230 * cos(a4);
+    float dy = 0.084 * cos(a1) + 0.209 * cos(a2) + 0.256 * cos(a3) - 0.230 * cos(a4);
+    uint w = 0;
+    uint h = 0;
+    uint lc = 0;
+    atlas.GetDimensions(w, h, lc);
+    float3 flow = water_tex((int) lc - 2, q - float2(time * 0.010, time * 0.014)) * 2.0 - 1.0;
+    float3 bump = water_tex((int) lc - 1, q + flow.xy * 0.05 + float2(time * 0.006, time * 0.008)) * 2.0 - 1.0;
+    float sx = -dx * 0.30 + bump.x * 0.45;
+    float sy = -dy * 0.30 + bump.y * 0.45;
+    return normalize(float3(sx, sy, 1.0));
+}
+
+// Water.frag distortionPower * the flow texture: a small scrolling UV offset.
+float water_distortion(float2 world_xy, float time) {
+    float2 q = world_xy * (WATER_SCALE * 6.0);
+    return 0.05 * (sin(q.x * 0.9 + time * 0.7) + sin(q.y * 1.1 - time * 0.5));
+}
+
+// Water.frag GetCloudColor: no cloud texture is bound, so a slow low-frequency
+// scroll stands in.
+float3 water_cloud(float2 world_xy, float time) {
+    return float3(0.85 + 0.15 * sin((world_xy.x + world_xy.y) * 0.0007 - time * 0.05));
+}
+
+// Retail UnderwaterDeferred.fx: absorbs red and fogs with distance. Applied to
+// every output while the camera is below the water plane.
+float3 apply_underwater(float3 color, float dist, float cam_z, float water_z) {
+    if (cam_z >= water_z - 0.5) return color;
+    const float3 absorb = float3(0.35, 0.62, 0.75);
+    float fog = clamp(1.0 - exp(-dist * 0.00022), 0.0, 0.9);
+    return lerp(color * absorb, float3(0.02, 0.10, 0.16), fog);
+}
+
+// Water.frag: fresnel-mixed reflection (sky) and refraction (depth-graded
+// seabed), SAGE diffuse + specular lighting, cloud term, and a depth-based
+// transparency fade. `river` (>0.5) applies RiverTransparencyMultiplier.
+float3 water_shade(float3 hitpos, float3 dir, float dist) {
+    float time = misc.x;
+    float river = misc.y;
+    float seabed = world_height(hitpos.x, hitpos.y);
+    float depth = max(0.0, params.z - seabed);
+
+    float3 n = water_normal(hitpos.xy, time + water_distortion(hitpos.xy, time));
+    float3 sun_dir = normalize(sun.xyz);
+
+    // Schlick fresnel, water F0 = 0.02.
+    float cos_theta = clamp(dot(-dir, n), 0.0, 1.0);
+    float fresnel = 0.02 + 0.98 * pow(1.0 - cos_theta, 5.0);
+
+    // Reflection: the sky the surface mirrors. Refraction: the seabed, graded
+    // from shallow to deep and lit by the SAGE diffuse + specular model.
+    float3 reflection = sky_color(reflect(dir, n));
+    float3 shallow = float3(0.10, 0.34, 0.38);
+    float3 deep = float3(0.02, 0.12, 0.22);
+    float3 refraction = lerp(shallow, deep, clamp(depth / 40.0, 0.0, 1.0));
+
+    float ndotl = max(dot(n, sun_dir), 0.0);
+    float ambient = sun.w;
+    float3 diffuse = float3(ambient + (1.0 - ambient) * ndotl);
+    float3 half_v = normalize(sun_dir - dir);
+    float spec = pow(max(dot(n, half_v), 0.0), 90.0);
+
+    float3 color = lerp(refraction, reflection, clamp(fresnel, 0.0, 1.0)) * diffuse * water_cloud(hitpos.xy, time);
+    color += float3(1.0, 0.97, 0.9) * spec * 0.45;
+
+    // Depth-based transparency: shallow water shows the seabed, deep water goes
+    // opaque toward the deep colour.
+    float alpha = clamp(depth / WATER_TRANSPARENT_DEPTH, 0.0, 1.0) * WATER_MIN_OPACITY;
+    if (river > 0.5) alpha *= WATER_RIVER_MULTIPLIER;
+    color = lerp(refraction, color, clamp(alpha + 0.15, 0.0, 1.0));
+
+    // Distance haze toward the horizon, as the terrain.
+    float wfog = clamp(1.0 - exp(-dist * 0.00009), 0.0, 0.75);
+    return lerp(color, sky_color(float3(dir.x, dir.y, 0.0)), wfog);
+}
+
+float4 PSMain(VSOut input) : SV_Target {
+    float4 p = cam;
+    float pitch = clamp(params.x, 0.15, 1.45);
+    float fov = clamp(params.y, 0.3, 1.4);
+    float world_w = mapinfo.x * CELL;
+    float world_h = mapinfo.y * CELL;
+
+    float cp = cos(pitch);
+    float3 fwd = float3(cp * sin(p.z), cp * cos(p.z), -sin(pitch));
+    float3 right = normalize(cross(fwd, float3(0, 0, 1)));
+    float3 up = cross(right, fwd);
+
+    float target_z = world_height(p.x, p.y);
+    if (target_z < -1.0e8) target_z = 0.0;
+    float dist = p.w / sin(pitch);
+    float3 cam_pos = float3(p.x, p.y, target_z + p.w) - fwd * dist;
+
+    float2 ndc = float2(input.uv.x * 2.0 - 1.0, 1.0 - input.uv.y * 2.0);
+    float aspect = misc.w;
+    float th = tan(fov * 0.5);
+    float3 dir = normalize(fwd + right * ndc.x * th * aspect + up * ndc.y * th);
+
+    if (dir.z >= -1e-4) {
+        return float4(apply_underwater(sky_color(dir), 0.0, cam_pos.z, params.z), 1.0);
+    }
+
+    // Clip the ray to the map's XY rectangle: the boundary is an exact plane,
+    // so the silhouette there stays razor-sharp instead of stair-stepping
+    // across it. Outside the map is sky.
+    float t_enter = 0.0;
+    float t_exit = 1.0e30;
+    bool inside = true;
+    if (abs(dir.x) < 1e-6) {
+        inside = (cam_pos.x >= 0.0 && cam_pos.x <= world_w);
+    } else {
+        float a = (0.0 - cam_pos.x) / dir.x;
+        float b = (world_w - cam_pos.x) / dir.x;
+        t_enter = max(t_enter, min(a, b));
+        t_exit = min(t_exit, max(a, b));
+    }
+    if (inside) {
+        if (abs(dir.y) < 1e-6) {
+            inside = (cam_pos.y >= 0.0 && cam_pos.y <= world_h);
+        } else {
+            float a = (0.0 - cam_pos.y) / dir.y;
+            float b = (world_h - cam_pos.y) / dir.y;
+            t_enter = max(t_enter, min(a, b));
+            t_exit = min(t_exit, max(a, b));
+        }
+    }
+    if (!inside || t_exit <= 0.0) {
+        return float4(apply_underwater(sky_color(dir), 0.0, cam_pos.z, params.z), 1.0);
+    }
+
+    // March the heightfield cell by cell: the step is never longer than the
+    // time to cross one cell (dominant horizontal axis), while a clearance term
+    // lets the ray skip the empty air above the surface. Resolving every cell is
+    // what keeps cliff and map-edge silhouettes from quantising into huge
+    // stair-steps that crawl as the camera pans.
+    float horiz = max(abs(dir.x), abs(dir.y));
+    float cell_step = min(CELL / max(horiz, 1e-4), CELL * 32.0);
+    float t = max(t_enter, CELL * 0.5);
+    float prev = t;
+    bool hit = false;
+    float hit_t = 0.0;
+    for (int i = 0; i < 1024 && t <= t_exit; ++i) {
+        float3 w = cam_pos + dir * t;
+        float h = world_height(w.x, w.y);
+        float surface = (params.w > 0.5) ? max(h, params.z) : h;
+        if (w.z <= surface) {
+            hit = true;
+            hit_t = t;
+            break;
+        }
+        float clearance = (w.z - surface) / max(-dir.z, 1e-4);
+        prev = t;
+        t += clamp(clearance, cell_step, cell_step * 8.0);
+    }
+    if (!hit) {
+        return float4(apply_underwater(sky_color(dir), 0.0, cam_pos.z, params.z), 1.0);
+    }
+
+    // Refine the first crossing; with a sub-cell bracket this converges to the
+    // exact surface point.
+    float lo = prev;
+    float hi = hit_t;
+    for (int i = 0; i < 18; ++i) {
+        float mid = 0.5 * (lo + hi);
+        float3 w = cam_pos + dir * mid;
+        float h = world_height(w.x, w.y);
+        float surface = (params.w > 0.5) ? max(h, params.z) : h;
+        if (w.z <= surface) {
+            hi = mid;
+        } else {
+            lo = mid;
+        }
+    }
+    float3 hitpos = cam_pos + dir * hi;
+
+    float3 sun_dir = normalize(sun.xyz);
+    float ambient = sun.w;
+
+    if (params.w > 0.5 && hitpos.z <= params.z + 0.01) {
+        return float4(apply_underwater(water_shade(hitpos, dir, hi), hi, cam_pos.z, params.z), 1.0);
+    }
+
+    // Terrain: read the per-cell blend record, sample the base/blend/three-way
+    // material layers continuously and ramp between them across the cell.
+    float wx = hitpos.x / CELL;
+    float wy = (world_h - hitpos.y) / CELL;
+    int cx = clamp((int) wx, 0, (int) mapinfo.x - 1);
+    int cy = clamp((int) wy, 0, (int) mapinfo.y - 1);
+    float fx = wx - floor(wx);
+    float fy = wy - floor(wy);
+
+    uint4 record = (uint4) (celldata.Load(int3(cx, cy, 0)) * 65535.0 + 0.5);
+    uint packed = record.w;
+    uint dir1 = packed & 0xFu;
+    uint flags1 = (packed >> 4u) & 0x3u;
+    uint dir2 = (packed >> 8u) & 0xFu;
+    uint flags2 = (packed >> 12u) & 0x3u;
+
+    float2 fracUV = float2(fx, fy);
+    float3 c0 = sample_layer(record.x, wx, wy);
+    float3 c1 = sample_layer(record.y, wx, wy);
+    float3 c2 = sample_layer(record.z, wx, wy);
+    float f1 = blend_factor(dir1, flags1, fracUV);
+    float f2 = blend_factor(dir2, flags2, fracUV);
+    float3 albedo = lerp(lerp(c0, c1, f1), c2, f2);
+
+    // Per-pixel normal from the heightfield.
+    float hl = world_height(hitpos.x - CELL, hitpos.y);
+    float hr = world_height(hitpos.x + CELL, hitpos.y);
+    float hd = world_height(hitpos.x, hitpos.y - CELL);
+    float hu = world_height(hitpos.x, hitpos.y + CELL);
+    float3 n = normalize(float3(hl - hr, hd - hu, 2.0 * CELL));
+    float lambert = max(0.0, dot(n, sun_dir));
+    float3 lit = albedo * (ambient + (1.0 - ambient) * lambert);
+    // Distance haze toward the horizon so the map edge blends into the sky.
+    float fog = clamp(1.0 - exp(-hi * 0.00009), 0.0, 0.75);
+    lit = lerp(lit, sky_color(float3(dir.x, dir.y, 0.0)), fog);
+    return float4(apply_underwater(lit, hi, cam_pos.z, params.z), 1.0);
+}

shaders/object.frag

@@ -0,0 +1,36 @@
+#version 450
+
+// Static-map model fragment stage: sample the shared texture array and apply
+// the same directional sun the terrain uses. Cut-out props (trees, fences)
+// carry an alpha mask in their diffuse texture; discard the transparent texels
+// so the ground shows through.
+
+layout(binding = 0) uniform sampler2DArray atlas;
+
+layout(push_constant) uniform Push {
+    vec4 cam_pos;
+    vec4 fwd;
+    vec4 right;
+    vec4 up;
+    vec4 sun;
+} pc;
+
+layout(location = 0) in vec2 in_uv;
+layout(location = 1) in vec3 in_normal;
+layout(location = 2) flat in float in_layer;
+
+layout(location = 0) out vec4 out_color;
+
+void main() {
+    int layers = textureSize(atlas, 0).z;
+    int layer = clamp(int(in_layer + 0.5), 0, layers - 1);
+    vec4 tex = texture(atlas, vec3(in_uv, float(layer)));
+    if (tex.a < 0.5) discard;
+
+    vec3 n = normalize(in_normal);
+    if (!gl_FrontFacing) n = -n;
+    float lambert = max(0.0, dot(n, normalize(pc.sun.xyz)));
+    float ambient = pc.sun.w;
+    vec3 lit = tex.rgb * (ambient + (1.0 - ambient) * lambert);
+    out_color = vec4(lit, 1.0);
+}

shaders/object.vert

@@ -0,0 +1,45 @@
+#version 450
+
+// Static-map model vertex stage. Draws the world-space triangle soup built by
+// ra3::models (buildings and props the map places) against the exact camera the
+// terrain raymarcher uses, so both passes share one projection and depth test.
+//
+// The camera is passed as its orthonormal basis so the same math as
+// terrain.frag applies: ndc.x = dot(r, right) / (a * tan(fov/2) * aspect),
+// ndc.y = -dot(r, up) / (a * tan(fov/2)), depth = (a - NEAR) / (FAR - NEAR)
+// with `a = dot(r, fwd)` the view-space depth.
+
+layout(location = 0) in vec3 in_pos;
+layout(location = 1) in vec3 in_normal;
+layout(location = 2) in vec2 in_uv;
+layout(location = 3) in float in_layer;
+layout(location = 4) in float in_bias;
+
+layout(push_constant) uniform Push {
+    vec4 cam_pos; // xyz = eye position
+    vec4 fwd;     // xyz = forward
+    vec4 right;   // xyz = right, w = tan(fov / 2)
+    vec4 up;      // xyz = up,    w = tan(fov / 2) * aspect
+    vec4 sun;     // xyz = sun direction, w = ambient
+} pc;
+
+layout(location = 0) out vec2 out_uv;
+layout(location = 1) out vec3 out_normal;
+layout(location = 2) flat out float out_layer;
+
+const float NEAR = 10.0;
+const float FAR = 60000.0;
+
+void main() {
+    vec3 r = in_pos - pc.cam_pos.xyz;
+    float a = dot(r, pc.fwd.xyz);
+    float b = dot(r, pc.right.xyz);
+    float c = dot(r, pc.up.xyz);
+    float th = pc.right.w;
+    float th_aspect = pc.up.w;
+    float depth = clamp((a - in_bias - NEAR) / (FAR - NEAR), 0.0, 1.0);
+    gl_Position = vec4(b / th_aspect, -c / th, depth * a, a);
+    out_uv = in_uv;
+    out_normal = in_normal;
+    out_layer = in_layer;
+}

shaders/scene.frag

@@ -0,0 +1,11 @@
+#version 450
+
+layout(binding = 0) uniform sampler2D scene;
+
+layout(location = 0) in vec2 in_uv;
+layout(location = 0) out vec4 out_color;
+
+void main() {
+    if (in_uv.x < 0.0 || in_uv.x > 1.0 || in_uv.y < 0.0 || in_uv.y > 1.0) discard;
+    out_color = texture(scene, in_uv);
+}

shaders/scene.vert

@@ -0,0 +1,18 @@
+#version 450
+
+// Fullscreen triangle. The scene image is drawn as a single textured quad; the
+// push constant carries the destination rectangle (in window-normalized
+// coordinates, y down), so the map is letterboxed rather than stretched.
+layout(push_constant) uniform Push {
+    vec4 rect; // xy = top-left (0..1), zw = size (0..1)
+} pc;
+
+layout(location = 0) out vec2 out_uv;
+
+void main() {
+    // Vulkan clip space has +Y pointing DOWN, so p already runs top->bottom and
+    // matches the image's top-left origin; do NOT flip it (OpenGL would).
+    vec2 p = vec2((gl_VertexIndex << 1) & 2, gl_VertexIndex & 2);
+    out_uv = (p - pc.rect.xy) / pc.rect.zw;
+    gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
+}

shaders/terrain.frag

@@ -0,0 +1,340 @@
+#version 450
+
+// GPU heightfield raymarcher for the real RA3 terrain.
+//
+// Textures: heightmap (R16), a per-cell blend record (R16G16B16A16_UNORM: base
+// layer, blend layer, three-way layer, packed direction/flags; unpacked with
+// *65535) and a texture array of the tile materials (RGBA8, mipmapped, REPEAT).
+// The material is sampled **continuously** (`uv = cell / (2 * cellSize)`), as the
+// retail `Terrain.fx` / OpenSAGE `Terrain.frag` do, so it never restarts at a
+// cell edge; material boundaries cross-fade with the SAGE blend ramp.
+//
+// The water plane is shaded with a port of the SAGE water effect
+// (`Ocean.fx` / OpenSAGE `Water.frag`); the camera-below-water tint stands in
+// for `UnderwaterDeferred.fx`. See docs/REVERSE_ENGINEERING.md.
+layout(binding = 0) uniform sampler2D heightmap;
+layout(binding = 1) uniform sampler2D celldata;
+layout(binding = 2) uniform sampler2DArray atlas;
+
+layout(push_constant) uniform Push {
+    vec4 cam;     // x=target_x, y=target_y, z=yaw, w=height
+    vec4 params;  // x=pitch, y=fov, z=water_z, w=has_water
+    vec4 sun;     // xyz=sun dir, w=ambient
+    vec4 mapinfo; // x=W, y=H, z=unused, w=z_scale
+    vec4 misc;    // x=time, y=water kind (0=ocean,1=river), z=cells per repeat, w=aspect
+} pc;
+
+layout(location = 0) in vec2 in_uv;
+layout(location = 0) out vec4 out_color;
+
+const float CELL = 10.0; // must match ra3::terrain::cell_size
+
+// Must match object.vert: the shared projection writes the view-space depth
+// into gl_FragDepth so the static-map models depth-test against the terrain.
+const float NEAR = 10.0;
+const float FAR = 60000.0;
+
+// SAGE water model constants (see docs/REVERSE_ENGINEERING.md).
+const float WATER_SCALE = 1.0 / 320.0;      // Water.frag: worldPos.xy / 320
+const float WATER_TRANSPARENT_DEPTH = 10.0; // WaterTransparency.TransparentWaterDepth
+const float WATER_MIN_OPACITY = 0.70;       // WaterTransparency.TransparentWaterMinOpacity
+const float WATER_RIVER_MULTIPLIER = 1.0;   // WaterTransparency.RiverTransparencyMultiplier
+
+float height_at(ivec2 c) {
+    c = clamp(c, ivec2(0), ivec2(pc.mapinfo.xy) - 1);
+    return texelFetch(heightmap, c, 0).r * 65535.0 * pc.mapinfo.w;
+}
+
+float world_height(float wx, float wy) {
+    float world_w = pc.mapinfo.x * CELL;
+    float world_h = pc.mapinfo.y * CELL;
+    if (wx < 0.0 || wy < 0.0 || wx >= world_w || wy >= world_h) return -1.0e9;
+    ivec2 c = ivec2(int(wx / CELL), int((world_h - wy) / CELL));
+    return height_at(c);
+}
+
+vec3 sky_color(vec3 dir) {
+    vec3 d = normalize(dir);
+    vec3 sun_dir = normalize(pc.sun.xyz);
+    float t = clamp(d.z, 0.0, 1.0);
+    vec3 horizon = vec3(0.70, 0.78, 0.85);
+    vec3 zenith = vec3(0.28, 0.48, 0.80);
+    vec3 col = mix(horizon, zenith, pow(t, 0.6));
+    float sun = max(dot(d, sun_dir), 0.0);
+    col += vec3(1.0, 0.95, 0.82) * pow(sun, 300.0) * 1.6; // sun disk
+    col += vec3(1.0, 0.90, 0.72) * pow(sun, 8.0) * 0.18;  // glow
+    return col;
+}
+
+// The retail SAGE blend ramp: 0 at one edge of the cell, 1 at the opposite.
+// Direction: 1 right, 2 top, 4 top-right, 8 top-left; flag bit 0 flips,
+// bit 1 marks a two-sided diagonal.
+float blend_factor(uint direction, uint flags, vec2 f) {
+    bool flipped = (flags & 1u) != 0u;
+    bool two_sided = (flags & 2u) != 0u;
+    if (flipped) {
+        if (direction == 1u) {
+            f.x = 1.0 - f.x;
+        } else if (direction == 2u || direction == 4u || direction == 8u) {
+            f.y = 1.0 - f.y;
+        }
+    }
+    if (direction == 1u) return f.x;
+    if (direction == 2u) return f.y;
+    if (direction == 4u) {
+        float s = (1.0 - f.x) + (1.0 - f.y);
+        return two_sided ? 1.0 - clamp(s - 1.0, 0.0, 1.0) : clamp(1.0 - s, 0.0, 1.0);
+    }
+    if (direction == 8u) {
+        float s = f.x + (1.0 - f.y);
+        return two_sided ? 1.0 - clamp(s - 1.0, 0.0, 1.0) : clamp(1.0 - s, 0.0, 1.0);
+    }
+    return 0.0;
+}
+
+// Sample one tile material layer at global cell coordinates. The texture repeats
+// every `span` cells (SAGE `uv / (cellSize * 2)`) with REPEAT addressing, so it
+// never restarts at a cell edge.
+vec3 sample_layer(uint layer, float wx, float wy) {
+    float span = max(pc.misc.z, 1.0);
+    int layer_count = textureSize(atlas, 0).z;
+    float l = float(min(layer, uint(layer_count - 1)));
+    return texture(atlas, vec3(vec2(wx, wy) / span, l)).rgb;
+}
+
+// ---- SAGE water (Ocean.fx / RiverWater.fx / Water.frag port) ----------------
+
+// Sample an atlas layer by an explicit float layer index (the water flow/bump
+// maps are appended as the last two layers of the tile atlas).
+vec3 water_tex(int layer, vec2 uv) {
+    int lc = textureSize(atlas, 0).z;
+    float l = float(clamp(layer, 0, max(lc - 1, 0)));
+    return texture(atlas, vec3(uv, l)).rgb;
+}
+
+// Scrolling wave normal on the water plane: the retail bump map (atlas's last
+// layer), offset by the flow map (second-last layer) and combined with a
+// de-gridded procedural wave so the sun glint is irregular and always moving.
+vec3 water_normal(vec2 world_xy, float time) {
+    vec2 q = world_xy * (WATER_SCALE * 6.0);
+    float a1 = q.x * 0.80 + q.y * 0.30 + time * 1.10;
+    float a2 = q.y * 0.95 - q.x * 0.45 - time * 1.30;
+    float a3 = (q.x + q.y) * 1.60 + time * 2.10;
+    float a4 = (q.x - q.y) * 2.30 - time * 1.70;
+    float dx = 0.224 * cos(a1) - 0.099 * cos(a2) + 0.256 * cos(a3) + 0.230 * cos(a4);
+    float dy = 0.084 * cos(a1) + 0.209 * cos(a2) + 0.256 * cos(a3) - 0.230 * cos(a4);
+    int lc = textureSize(atlas, 0).z;
+    vec3 flow = water_tex(lc - 2, q - vec2(time * 0.010, time * 0.014)) * 2.0 - 1.0;
+    vec3 bump = water_tex(lc - 1, q + flow.xy * 0.05 + vec2(time * 0.006, time * 0.008)) * 2.0 - 1.0;
+    float sx = -dx * 0.30 + bump.x * 0.45;
+    float sy = -dy * 0.30 + bump.y * 0.45;
+    return normalize(vec3(sx, sy, 1.0));
+}
+
+// Water.frag distortionPower * the flow texture: a small scrolling UV offset.
+float water_distortion(vec2 world_xy, float time) {
+    vec2 q = world_xy * (WATER_SCALE * 6.0);
+    return 0.05 * (sin(q.x * 0.9 + time * 0.7) + sin(q.y * 1.1 - time * 0.5));
+}
+
+// Water.frag GetCloudColor: no cloud texture is bound, so a slow low-frequency
+// scroll stands in.
+vec3 water_cloud(vec2 world_xy, float time) {
+    return vec3(0.85 + 0.15 * sin((world_xy.x + world_xy.y) * 0.0007 - time * 0.05));
+}
+
+// Retail UnderwaterDeferred.fx: absorbs red and fogs with distance. Applied to
+// every output while the camera is below the water plane.
+vec3 apply_underwater(vec3 color, float dist, float cam_z, float water_z) {
+    if (cam_z >= water_z - 0.5) return color;
+    const vec3 absorb = vec3(0.35, 0.62, 0.75);
+    float fog = clamp(1.0 - exp(-dist * 0.00022), 0.0, 0.9);
+    return mix(color * absorb, vec3(0.02, 0.10, 0.16), fog);
+}
+
+// Water.frag: fresnel-mixed reflection (sky) and refraction (depth-graded
+// seabed), SAGE diffuse + specular lighting, cloud term, and a depth-based
+// transparency fade. `river` (>0.5) applies RiverTransparencyMultiplier.
+vec3 water_shade(vec3 hitpos, vec3 dir, float dist) {
+    float time = pc.misc.x;
+    float river = pc.misc.y;
+    float seabed = world_height(hitpos.x, hitpos.y);
+    float depth = max(0.0, pc.params.z - seabed);
+
+    vec3 n = water_normal(hitpos.xy, time + water_distortion(hitpos.xy, time));
+    vec3 sun = normalize(pc.sun.xyz);
+
+    // Schlick fresnel, water F0 = 0.02.
+    float cos_theta = clamp(dot(-dir, n), 0.0, 1.0);
+    float fresnel = 0.02 + 0.98 * pow(1.0 - cos_theta, 5.0);
+
+    // Reflection: the sky the surface mirrors. Refraction: the seabed, graded
+    // from shallow to deep and lit by the SAGE diffuse + specular model.
+    vec3 reflection = sky_color(reflect(dir, n));
+    vec3 shallow = vec3(0.10, 0.34, 0.38);
+    vec3 deep = vec3(0.02, 0.12, 0.22);
+    vec3 refraction = mix(shallow, deep, clamp(depth / 40.0, 0.0, 1.0));
+
+    float ndotl = max(dot(n, sun), 0.0);
+    float ambient = pc.sun.w;
+    vec3 diffuse = vec3(ambient + (1.0 - ambient) * ndotl);
+    vec3 half_v = normalize(sun - dir);
+    float spec = pow(max(dot(n, half_v), 0.0), 90.0);
+
+    vec3 color = mix(refraction, reflection, clamp(fresnel, 0.0, 1.0)) * diffuse * water_cloud(hitpos.xy, time);
+    color += vec3(1.0, 0.97, 0.9) * spec * 0.45;
+
+    // Depth-based transparency: shallow water shows the seabed, deep water goes
+    // opaque toward the deep colour.
+    float alpha = clamp(depth / WATER_TRANSPARENT_DEPTH, 0.0, 1.0) * WATER_MIN_OPACITY;
+    if (river > 0.5) alpha *= WATER_RIVER_MULTIPLIER;
+    color = mix(refraction, color, clamp(alpha + 0.15, 0.0, 1.0));
+
+    // Distance haze toward the horizon, as the terrain.
+    float wfog = clamp(1.0 - exp(-dist * 0.00009), 0.0, 0.75);
+    return mix(color, sky_color(vec3(dir.x, dir.y, 0.0)), wfog);
+}
+
+void main() {
+    vec4 p = pc.cam;
+    float pitch = clamp(pc.params.x, 0.15, 1.45);
+    float fov = clamp(pc.params.y, 0.3, 1.4);
+    float world_w = pc.mapinfo.x * CELL;
+    float world_h = pc.mapinfo.y * CELL;
+
+    float cp = cos(pitch);
+    vec3 fwd = vec3(cp * sin(p.z), cp * cos(p.z), -sin(pitch));
+    vec3 right = normalize(cross(fwd, vec3(0, 0, 1)));
+    vec3 up = cross(right, fwd);
+
+    float target_z = world_height(p.x, p.y);
+    if (target_z < -1.0e8) target_z = 0.0;
+    float dist = p.w / sin(pitch);
+    vec3 cam = vec3(p.x, p.y, target_z + p.w) - fwd * dist;
+
+    float aspect = 1.0; // set by caller implicitly via square-ish UV; corrected below
+    vec2 ndc = vec2(in_uv.x * 2.0 - 1.0, 1.0 - in_uv.y * 2.0);
+    // aspect passed in misc.w
+    aspect = pc.misc.w;
+    float th = tan(fov * 0.5);
+    vec3 dir = normalize(fwd + right * ndc.x * th * aspect + up * ndc.y * th);
+
+    if (dir.z >= -1e-4) {
+        gl_FragDepth = 1.0;
+        out_color = vec4(apply_underwater(sky_color(dir), 0.0, cam.z, pc.params.z), 1.0);
+        return;
+    }
+
+    // Clip the ray to the map's XY rectangle: the boundary is an exact plane,
+    // so the silhouette there stays razor-sharp instead of stair-stepping
+    // across it. Outside the map is sky.
+    float t_enter = 0.0;
+    float t_exit = 1.0e30;
+    bool inside = true;
+    if (abs(dir.x) < 1e-6) {
+        inside = (cam.x >= 0.0 && cam.x <= world_w);
+    } else {
+        float a = (0.0 - cam.x) / dir.x;
+        float b = (world_w - cam.x) / dir.x;
+        t_enter = max(t_enter, min(a, b));
+        t_exit = min(t_exit, max(a, b));
+    }
+    if (inside) {
+        if (abs(dir.y) < 1e-6) {
+            inside = (cam.y >= 0.0 && cam.y <= world_h);
+        } else {
+            float a = (0.0 - cam.y) / dir.y;
+            float b = (world_h - cam.y) / dir.y;
+            t_enter = max(t_enter, min(a, b));
+            t_exit = min(t_exit, max(a, b));
+        }
+    }
+    if (!inside || t_exit <= 0.0) {
+        gl_FragDepth = 1.0;
+        out_color = vec4(apply_underwater(sky_color(dir), 0.0, cam.z, pc.params.z), 1.0);
+        return;
+    }
+
+    // March the heightfield cell by cell: the step is never longer than the
+    // time to cross one cell (dominant horizontal axis), while a clearance term
+    // lets the ray skip the empty air above the surface. Resolving every cell is
+    // what keeps cliff and map-edge silhouettes from quantising into huge
+    // stair-steps that crawl as the camera pans.
+    float horiz = max(abs(dir.x), abs(dir.y));
+    float cell_step = min(CELL / max(horiz, 1e-4), CELL * 32.0);
+    float t = max(t_enter, CELL * 0.5);
+    float prev = t;
+    bool hit = false;
+    float hit_t = 0.0;
+    for (int i = 0; i < 1024 && t <= t_exit; ++i) {
+        vec3 w = cam + dir * t;
+        float h = world_height(w.x, w.y);
+        float surface = (pc.params.w > 0.5) ? max(h, pc.params.z) : h;
+        if (w.z <= surface) { hit = true; hit_t = t; break; }
+        float clearance = (w.z - surface) / max(-dir.z, 1e-4);
+        prev = t;
+        t += clamp(clearance, cell_step, cell_step * 8.0);
+    }
+    if (!hit) { gl_FragDepth = 1.0; out_color = vec4(apply_underwater(sky_color(dir), 0.0, cam.z, pc.params.z), 1.0); return; }
+
+    // Refine the first crossing; with a sub-cell bracket this converges to the
+    // exact surface point.
+    float lo = prev, hi = hit_t;
+    for (int i = 0; i < 18; ++i) {
+        float mid = 0.5 * (lo + hi);
+        vec3 w = cam + dir * mid;
+        float h = world_height(w.x, w.y);
+        float surface = (pc.params.w > 0.5) ? max(h, pc.params.z) : h;
+        if (w.z <= surface) hi = mid; else lo = mid;
+    }
+    vec3 hitpos = cam + dir * hi;
+
+    // View-space depth of the hit (project onto the forward axis), matching the
+    // projection object.vert applies to the model vertices.
+    gl_FragDepth = clamp((dot(hitpos - cam, fwd) - NEAR) / (FAR - NEAR), 0.0, 1.0);
+
+    vec3 sun = normalize(pc.sun.xyz);
+    float ambient = pc.sun.w;
+
+    if (pc.params.w > 0.5 && hitpos.z <= pc.params.z + 0.01) {
+        out_color = vec4(apply_underwater(water_shade(hitpos, dir, hi), hi, cam.z, pc.params.z), 1.0);
+        return;
+    }
+
+    // Terrain: read the per-cell blend record, sample the base/blend/three-way
+    // material layers continuously and ramp between them across the cell.
+    float wx = hitpos.x / CELL;
+    float wy = (world_h - hitpos.y) / CELL;
+    int cx = clamp(int(wx), 0, int(pc.mapinfo.x) - 1);
+    int cy = clamp(int(wy), 0, int(pc.mapinfo.y) - 1);
+    float fx = wx - floor(wx);
+    float fy = wy - floor(wy);
+
+    uvec4 record = uvec4(texelFetch(celldata, ivec2(cx, cy), 0) * 65535.0 + 0.5);
+    uint packed = record.w;
+    uint dir1 = packed & 0xFu;
+    uint flags1 = (packed >> 4u) & 0x3u;
+    uint dir2 = (packed >> 8u) & 0xFu;
+    uint flags2 = (packed >> 12u) & 0x3u;
+
+    vec2 fracUV = vec2(fx, fy);
+    vec3 c0 = sample_layer(record.x, wx, wy);
+    vec3 c1 = sample_layer(record.y, wx, wy);
+    vec3 c2 = sample_layer(record.z, wx, wy);
+    float f1 = blend_factor(dir1, flags1, fracUV);
+    float f2 = blend_factor(dir2, flags2, fracUV);
+    vec3 albedo = mix(mix(c0, c1, f1), c2, f2);
+
+    // Per-pixel normal from the heightfield.
+    float hl = world_height(hitpos.x - CELL, hitpos.y);
+    float hr = world_height(hitpos.x + CELL, hitpos.y);
+    float hd = world_height(hitpos.x, hitpos.y - CELL);
+    float hu = world_height(hitpos.x, hitpos.y + CELL);
+    vec3 n = normalize(vec3(hl - hr, hd - hu, 2.0 * CELL));
+    float lambert = max(0.0, dot(n, sun));
+    vec3 lit = albedo * (ambient + (1.0 - ambient) * lambert);
+    // Distance haze toward the horizon so the map edge blends into the sky.
+    float fog = clamp(1.0 - exp(-hi * 0.00009), 0.0, 0.75);
+    lit = mix(lit, sky_color(vec3(dir.x, dir.y, 0.0)), fog);
+    out_color = vec4(apply_underwater(lit, hi, cam.z, pc.params.z), 1.0);
+}

shaders/terrain.vert

@@ -0,0 +1,11 @@
+#version 450
+
+// Fullscreen triangle; the terrain is ray-marched in the fragment shader
+// (GPU), so the vertex stage only emits the screen UV.
+layout(location = 0) out vec2 out_uv;
+
+void main() {
+    vec2 p = vec2((gl_VertexIndex << 1) & 2, gl_VertexIndex & 2);
+    out_uv = p;
+    gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
+}

shaders/webgl_scene_frag.glsl

@@ -0,0 +1,15 @@
+#version 300 es
+// Samples the software-rendered scene image (the WebGL port of scene.frag).
+precision highp float;
+precision highp sampler2D;
+
+uniform sampler2D u_scene;
+
+in vec2 v_uv;
+out vec4 frag_color;
+
+void main() {
+    if (v_uv.x < 0.0 || v_uv.x > 1.0 || v_uv.y < 0.0 || v_uv.y > 1.0) discard;
+    // The engine stores 0xAARRGGBB (BGRA in memory), uploaded as GL_RGBA.
+    frag_color = texture(u_scene, v_uv).bgra;
+}

shaders/webgl_scene_vert.glsl

@@ -0,0 +1,15 @@
+#version 300 es
+// Fullscreen triangle for the 2D image path (the WebGL port of scene.vert).
+// WebGL clip space is +Y up, so the vertex position flips Y relative to the
+// Vulkan shader; the sampled UVs and the image's top-left origin are unchanged.
+precision highp float;
+
+uniform vec4 u_rect; // xy = top-left (0..1), zw = size (0..1)
+
+out vec2 v_uv;
+
+void main() {
+    vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
+    v_uv = (p - u_rect.xy) / u_rect.zw;
+    gl_Position = vec4(p.x * 2.0 - 1.0, 1.0 - p.y * 2.0, 0.0, 1.0);
+}

shaders/webgl_terrain_frag.glsl

@@ -0,0 +1,318 @@
+#version 300 es
+// GPU heightfield raymarcher for the real RA3 terrain (the WebGL port of
+// terrain.frag). The Vulkan push constants become a set of vec4 uniforms.
+precision highp float;
+precision highp int;
+precision highp sampler2D;
+precision highp sampler2DArray;
+
+uniform sampler2D u_heightmap;      // R16 heights
+uniform sampler2D u_celldata;       // per-cell blend record (RGBA16)
+uniform sampler2DArray u_atlas;     // tile material array (RGBA8)
+
+// One contiguous array so the host can upload all five vec4s with a single
+// glUniform4fv; the names keep the shader body identical to terrain.frag.
+uniform vec4 u_data[5];
+#define u_cam u_data[0]     // x=target_x, y=target_y, z=yaw, w=height
+#define u_params u_data[1]  // x=pitch, y=fov, z=water_z, w=has_water
+#define u_sun u_data[2]     // xyz=sun dir, w=ambient
+#define u_mapinfo u_data[3] // x=W, y=H, z=unused, w=z_scale
+#define u_misc u_data[4]    // x=time, y=unused, z=cells per texture repeat, w=aspect
+
+in vec2 v_uv;
+out vec4 frag_color;
+
+const float CELL = 10.0; // must match ra3::terrain::cell_size
+
+// SAGE water model constants (see docs/REVERSE_ENGINEERING.md).
+const float WATER_SCALE = 1.0 / 320.0;
+const float WATER_TRANSPARENT_DEPTH = 10.0;
+const float WATER_MIN_OPACITY = 0.70;
+const float WATER_RIVER_MULTIPLIER = 1.0;
+
+float height_at(ivec2 c) {
+    c = clamp(c, ivec2(0), ivec2(u_mapinfo.xy) - 1);
+    return texelFetch(u_heightmap, c, 0).r * 65535.0 * u_mapinfo.w;
+}
+
+float world_height(float wx, float wy) {
+    float world_w = u_mapinfo.x * CELL;
+    float world_h = u_mapinfo.y * CELL;
+    if (wx < 0.0 || wy < 0.0 || wx >= world_w || wy >= world_h) return -1.0e9;
+    ivec2 c = ivec2(int(wx / CELL), int((world_h - wy) / CELL));
+    return height_at(c);
+}
+
+vec3 sky_color(vec3 dir) {
+    vec3 d = normalize(dir);
+    vec3 sun_dir = normalize(u_sun.xyz);
+    float t = clamp(d.z, 0.0, 1.0);
+    vec3 horizon = vec3(0.70, 0.78, 0.85);
+    vec3 zenith = vec3(0.28, 0.48, 0.80);
+    vec3 col = mix(horizon, zenith, pow(t, 0.6));
+    float sun = max(dot(d, sun_dir), 0.0);
+    col += vec3(1.0, 0.95, 0.82) * pow(sun, 300.0) * 1.6; // sun disk
+    col += vec3(1.0, 0.90, 0.72) * pow(sun, 8.0) * 0.18;  // glow
+    return col;
+}
+
+// The retail SAGE blend ramp (see terrain.frag).
+float blend_factor(uint direction, uint flags, vec2 f) {
+    bool flipped = (flags & 1u) != 0u;
+    bool two_sided = (flags & 2u) != 0u;
+    if (flipped) {
+        if (direction == 1u) {
+            f.x = 1.0 - f.x;
+        } else if (direction == 2u || direction == 4u || direction == 8u) {
+            f.y = 1.0 - f.y;
+        }
+    }
+    if (direction == 1u) return f.x;
+    if (direction == 2u) return f.y;
+    if (direction == 4u) {
+        float s = (1.0 - f.x) + (1.0 - f.y);
+        return two_sided ? 1.0 - clamp(s - 1.0, 0.0, 1.0) : clamp(1.0 - s, 0.0, 1.0);
+    }
+    if (direction == 8u) {
+        float s = f.x + (1.0 - f.y);
+        return two_sided ? 1.0 - clamp(s - 1.0, 0.0, 1.0) : clamp(1.0 - s, 0.0, 1.0);
+    }
+    return 0.0;
+}
+
+vec3 sample_layer(uint layer, float wx, float wy) {
+    float span = max(u_misc.z, 1.0);
+    int layer_count = textureSize(u_atlas, 0).z;
+    float l = float(min(layer, uint(layer_count - 1)));
+    // The atlas is 0xAARRGGBB (BGRA in memory), uploaded as GL_RGBA.
+    return texture(u_atlas, vec3(vec2(wx, wy) / span, l)).bgr;
+}
+
+// ---- SAGE water (Ocean.fx / RiverWater.fx / Water.frag port) ----------------
+
+// Sample an atlas layer by an explicit layer index (the water flow/bump maps
+// are appended as the last two layers of the tile atlas). The atlas is
+// 0xAARRGGBB, so `.bgr` restores RGB (as `sample_layer`).
+vec3 water_tex(int layer, vec2 uv) {
+    int lc = textureSize(u_atlas, 0).z;
+    float l = float(clamp(layer, 0, max(lc - 1, 0)));
+    return texture(u_atlas, vec3(uv, l)).bgr;
+}
+
+// Scrolling wave normal on the water plane: the retail bump map (atlas's last
+// layer), offset by the flow map (second-last layer) and combined with a
+// de-gridded procedural wave so the sun glint is irregular and always moving.
+vec3 water_normal(vec2 world_xy, float time) {
+    vec2 q = world_xy * (WATER_SCALE * 6.0);
+    float a1 = q.x * 0.80 + q.y * 0.30 + time * 1.10;
+    float a2 = q.y * 0.95 - q.x * 0.45 - time * 1.30;
+    float a3 = (q.x + q.y) * 1.60 + time * 2.10;
+    float a4 = (q.x - q.y) * 2.30 - time * 1.70;
+    float dx = 0.224 * cos(a1) - 0.099 * cos(a2) + 0.256 * cos(a3) + 0.230 * cos(a4);
+    float dy = 0.084 * cos(a1) + 0.209 * cos(a2) + 0.256 * cos(a3) - 0.230 * cos(a4);
+    int lc = textureSize(u_atlas, 0).z;
+    vec3 flow = water_tex(lc - 2, q - vec2(time * 0.010, time * 0.014)) * 2.0 - 1.0;
+    vec3 bump = water_tex(lc - 1, q + flow.xy * 0.05 + vec2(time * 0.006, time * 0.008)) * 2.0 - 1.0;
+    float sx = -dx * 0.30 + bump.x * 0.45;
+    float sy = -dy * 0.30 + bump.y * 0.45;
+    return normalize(vec3(sx, sy, 1.0));
+}
+
+// Water.frag distortionPower * the flow texture: a small scrolling UV offset.
+float water_distortion(vec2 world_xy, float time) {
+    vec2 q = world_xy * (WATER_SCALE * 6.0);
+    return 0.05 * (sin(q.x * 0.9 + time * 0.7) + sin(q.y * 1.1 - time * 0.5));
+}
+
+// Water.frag GetCloudColor: no cloud texture is bound, so a slow scroll stands in.
+vec3 water_cloud(vec2 world_xy, float time) {
+    return vec3(0.85 + 0.15 * sin((world_xy.x + world_xy.y) * 0.0007 - time * 0.05));
+}
+
+// Retail UnderwaterDeferred.fx: absorbs red and fogs with distance.
+vec3 apply_underwater(vec3 color, float dist, float cam_z, float water_z) {
+    if (cam_z >= water_z - 0.5) return color;
+    const vec3 absorb = vec3(0.35, 0.62, 0.75);
+    float fog = clamp(1.0 - exp(-dist * 0.00022), 0.0, 0.9);
+    return mix(color * absorb, vec3(0.02, 0.10, 0.16), fog);
+}
+
+// Water.frag: fresnel-mixed sky reflection and depth-graded seabed refraction,
+// SAGE diffuse + specular lighting, cloud term, depth-based transparency fade.
+vec3 water_shade(vec3 hitpos, vec3 dir, float dist) {
+    float time = u_misc.x;
+    float river = u_misc.y;
+    float seabed = world_height(hitpos.x, hitpos.y);
+    float depth = max(0.0, u_params.z - seabed);
+
+    vec3 n = water_normal(hitpos.xy, time + water_distortion(hitpos.xy, time));
+    vec3 sun_dir = normalize(u_sun.xyz);
+
+    float cos_theta = clamp(dot(-dir, n), 0.0, 1.0);
+    float fresnel = 0.02 + 0.98 * pow(1.0 - cos_theta, 5.0);
+
+    vec3 reflection = sky_color(reflect(dir, n));
+    vec3 shallow = vec3(0.10, 0.34, 0.38);
+    vec3 deep = vec3(0.02, 0.12, 0.22);
+    vec3 refraction = mix(shallow, deep, clamp(depth / 40.0, 0.0, 1.0));
+
+    float ndotl = max(dot(n, sun_dir), 0.0);
+    float ambient = u_sun.w;
+    vec3 diffuse = vec3(ambient + (1.0 - ambient) * ndotl);
+    vec3 half_v = normalize(sun_dir - dir);
+    float spec = pow(max(dot(n, half_v), 0.0), 90.0);
+
+    vec3 color = mix(refraction, reflection, clamp(fresnel, 0.0, 1.0)) * diffuse * water_cloud(hitpos.xy, time);
+    color += vec3(1.0, 0.97, 0.9) * spec * 0.45;
+
+    float alpha = clamp(depth / WATER_TRANSPARENT_DEPTH, 0.0, 1.0) * WATER_MIN_OPACITY;
+    if (river > 0.5) alpha *= WATER_RIVER_MULTIPLIER;
+    color = mix(refraction, color, clamp(alpha + 0.15, 0.0, 1.0));
+
+    float wfog = clamp(1.0 - exp(-dist * 0.00009), 0.0, 0.75);
+    return mix(color, sky_color(vec3(dir.x, dir.y, 0.0)), wfog);
+}
+
+void main() {
+    vec4 p = u_cam;
+    float pitch = clamp(u_params.x, 0.15, 1.45);
+    float fov = clamp(u_params.y, 0.3, 1.4);
+    float world_w = u_mapinfo.x * CELL;
+    float world_h = u_mapinfo.y * CELL;
+
+    float cp = cos(pitch);
+    vec3 fwd = vec3(cp * sin(p.z), cp * cos(p.z), -sin(pitch));
+    vec3 right = normalize(cross(fwd, vec3(0, 0, 1)));
+    vec3 up = cross(right, fwd);
+
+    float target_z = world_height(p.x, p.y);
+    if (target_z < -1.0e8) target_z = 0.0;
+    float dist = p.w / sin(pitch);
+    vec3 cam = vec3(p.x, p.y, target_z + p.w) - fwd * dist;
+
+    vec2 ndc = vec2(v_uv.x * 2.0 - 1.0, 1.0 - v_uv.y * 2.0);
+    float aspect = u_misc.w;
+    float th = tan(fov * 0.5);
+    vec3 dir = normalize(fwd + right * ndc.x * th * aspect + up * ndc.y * th);
+
+    if (dir.z >= -1e-4) {
+        frag_color = vec4(apply_underwater(sky_color(dir), 0.0, cam.z, u_params.z), 1.0);
+        return;
+    }
+
+    // Clip the ray to the map's XY rectangle: the boundary is an exact plane,
+    // so the silhouette there stays razor-sharp instead of stair-stepping
+    // across it. Outside the map is sky.
+    float t_enter = 0.0;
+    float t_exit = 1.0e30;
+    bool inside = true;
+    if (abs(dir.x) < 1e-6) {
+        inside = (cam.x >= 0.0 && cam.x <= world_w);
+    } else {
+        float a = (0.0 - cam.x) / dir.x;
+        float b = (world_w - cam.x) / dir.x;
+        t_enter = max(t_enter, min(a, b));
+        t_exit = min(t_exit, max(a, b));
+    }
+    if (inside) {
+        if (abs(dir.y) < 1e-6) {
+            inside = (cam.y >= 0.0 && cam.y <= world_h);
+        } else {
+            float a = (0.0 - cam.y) / dir.y;
+            float b = (world_h - cam.y) / dir.y;
+            t_enter = max(t_enter, min(a, b));
+            t_exit = min(t_exit, max(a, b));
+        }
+    }
+    if (!inside || t_exit <= 0.0) {
+        frag_color = vec4(apply_underwater(sky_color(dir), 0.0, cam.z, u_params.z), 1.0);
+        return;
+    }
+
+    // March the heightfield cell by cell: the step is never longer than the
+    // time to cross one cell (dominant horizontal axis), while a clearance term
+    // lets the ray skip the empty air above the surface. Resolving every cell is
+    // what keeps cliff and map-edge silhouettes from quantising into huge
+    // stair-steps that crawl as the camera pans.
+    float horiz = max(abs(dir.x), abs(dir.y));
+    float cell_step = min(CELL / max(horiz, 1e-4), CELL * 32.0);
+    float t = max(t_enter, CELL * 0.5);
+    float prev = t;
+    bool hit = false;
+    float hit_t = 0.0;
+    for (int i = 0; i < 1024 && t <= t_exit; ++i) {
+        vec3 w = cam + dir * t;
+        float h = world_height(w.x, w.y);
+        float surface = (u_params.w > 0.5) ? max(h, u_params.z) : h;
+        if (w.z <= surface) {
+            hit = true;
+            hit_t = t;
+            break;
+        }
+        float clearance = (w.z - surface) / max(-dir.z, 1e-4);
+        prev = t;
+        t += clamp(clearance, cell_step, cell_step * 8.0);
+    }
+    if (!hit) {
+        frag_color = vec4(apply_underwater(sky_color(dir), 0.0, cam.z, u_params.z), 1.0);
+        return;
+    }
+
+    // Refine the first crossing; with a sub-cell bracket this converges to the
+    // exact surface point.
+    float lo = prev;
+    float hi = hit_t;
+    for (int i = 0; i < 18; ++i) {
+        float mid = 0.5 * (lo + hi);
+        vec3 w = cam + dir * mid;
+        float h = world_height(w.x, w.y);
+        float surface = (u_params.w > 0.5) ? max(h, u_params.z) : h;
+        if (w.z <= surface) {
+            hi = mid;
+        } else {
+            lo = mid;
+        }
+    }
+    vec3 hitpos = cam + dir * hi;
+
+    vec3 sun = normalize(u_sun.xyz);
+    float ambient = u_sun.w;
+
+    if (u_params.w > 0.5 && hitpos.z <= u_params.z + 0.01) {
+        frag_color = vec4(apply_underwater(water_shade(hitpos, dir, hi), hi, cam.z, u_params.z), 1.0);
+        return;
+    }
+
+    float wx = hitpos.x / CELL;
+    float wy = (world_h - hitpos.y) / CELL;
+    int cx = clamp(int(wx), 0, int(u_mapinfo.x) - 1);
+    int cy = clamp(int(wy), 0, int(u_mapinfo.y) - 1);
+    float fx = wx - floor(wx);
+    float fy = wy - floor(wy);
+
+    uvec4 record = uvec4(texelFetch(u_celldata, ivec2(cx, cy), 0) * 65535.0 + 0.5);
+    uint packed = record.w;
+    uint dir1 = packed & 0xFu;
+    uint flags1 = (packed >> 4u) & 0x3u;
+    uint dir2 = (packed >> 8u) & 0xFu;
+    uint flags2 = (packed >> 12u) & 0x3u;
+
+    vec2 fracUV = vec2(fx, fy);
+    vec3 c0 = sample_layer(record.x, wx, wy);
+    vec3 c1 = sample_layer(record.y, wx, wy);
+    vec3 c2 = sample_layer(record.z, wx, wy);
+    float f1 = blend_factor(dir1, flags1, fracUV);
+    float f2 = blend_factor(dir2, flags2, fracUV);
+    vec3 albedo = mix(mix(c0, c1, f1), c2, f2);
+
+    float hl = world_height(hitpos.x - CELL, hitpos.y);
+    float hr = world_height(hitpos.x + CELL, hitpos.y);
+    float hd = world_height(hitpos.x, hitpos.y - CELL);
+    float hu = world_height(hitpos.x, hitpos.y + CELL);
+    vec3 n = normalize(vec3(hl - hr, hd - hu, 2.0 * CELL));
+    float lambert = max(0.0, dot(n, sun));
+    vec3 lit = albedo * (ambient + (1.0 - ambient) * lambert);
+    float fog = clamp(1.0 - exp(-hi * 0.00009), 0.0, 0.75);
+    lit = mix(lit, sky_color(vec3(dir.x, dir.y, 0.0)), fog);
+    frag_color = vec4(apply_underwater(lit, hi, cam.z, u_params.z), 1.0);
+}

shaders/webgl_terrain_vert.glsl

@@ -0,0 +1,11 @@
+#version 300 es
+// Fullscreen triangle for the terrain raymarcher (the WebGL port of terrain.vert).
+precision highp float;
+
+out vec2 v_uv;
+
+void main() {
+    vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
+    v_uv = p;
+    gl_Position = vec4(p.x * 2.0 - 1.0, 1.0 - p.y * 2.0, 0.0, 1.0);
+}

shaders/webgpu_scene.wgsl

@@ -0,0 +1,38 @@
+// WebGPU counterpart of the 2D image path (the WGSL port of
+// webgl_scene_vert/frag.glsl and the Vulkan scene shaders).
+//
+// Bind group 0: uniform { rect: vec4<f32>; }, the scene texture and a sampler.
+// WebGPU clip space is +Y up, matching GL, so the vertex flips Y the same way.
+
+struct SceneUniforms {
+    rect: vec4<f32>, // xy = top-left (0..1), zw = size (0..1)
+};
+
+@group(0) @binding(0) var<uniform> u_scene: SceneUniforms;
+@group(0) @binding(1) var u_scene_tex: texture_2d<f32>;
+@group(0) @binding(2) var u_scene_samp: sampler;
+
+struct SceneOut {
+    @builtin(position) position: vec4<f32>,
+    @location(0) uv: vec2<f32>,
+};
+
+@vertex
+fn vs_main(@builtin(vertex_index) vertex_index: u32) -> SceneOut {
+    let p = vec2<f32>(f32((vertex_index << 1u) & 2u), f32(vertex_index & 2u));
+    var out: SceneOut;
+    out.uv = (p - u_scene.rect.xy) / u_scene.rect.zw;
+    out.position = vec4<f32>(p.x * 2.0 - 1.0, 1.0 - p.y * 2.0, 0.0, 1.0);
+    return out;
+}
+
+@fragment
+fn fs_main(in: SceneOut) -> @location(0) vec4<f32> {
+    // Only the destination rect is drawn; outside it the previous contents stay.
+    if (in.uv.x < 0.0 || in.uv.x > 1.0 || in.uv.y < 0.0 || in.uv.y > 1.0) {
+        discard;
+    }
+    // The image is 0xAARRGGBB (BGRA in memory); swizzle it back.
+    let c = textureSampleLevel(u_scene_tex, u_scene_samp, in.uv, 0.0);
+    return vec4<f32>(c.b, c.g, c.r, c.a);
+}

shaders/webgpu_terrain.wgsl

@@ -0,0 +1,334 @@
+// WebGPU counterpart of the GPU heightfield raymarcher (the WGSL port of
+// webgl_terrain_frag.glsl / terrain.frag). The Vulkan push constants become a
+// uniform buffer of five vec4s, laid out exactly as `ra3::wasmgl::detail::terrain_uniforms`.
+//
+// Bind group 0: uniform data[5], the R16 heightmap (u32), the RGBA16 cell record
+// (vec4<u32>), the RGBA8 tile atlas (array), and an atlas sampler.
+
+struct TerrainUniforms {
+    data: array<vec4<f32>, 5>,
+};
+
+@group(0) @binding(0) var<uniform> u: TerrainUniforms;
+@group(0) @binding(1) var u_heightmap: texture_2d<u32>;    // R16Uint heights
+@group(0) @binding(2) var u_celldata: texture_2d<u32>;     // RGBA16Uint blend record (texel is vec4<u32>)
+@group(0) @binding(3) var u_atlas: texture_2d_array<f32>;  // RGBA8 tile materials
+@group(0) @binding(4) var u_atlas_samp: sampler;
+
+const CELL: f32 = 10.0; // must match ra3::terrain::cell_size
+
+// SAGE water model constants (see docs/REVERSE_ENGINEERING.md).
+const WATER_SCALE: f32 = 1.0 / 320.0;
+const WATER_TRANSPARENT_DEPTH: f32 = 10.0;
+const WATER_MIN_OPACITY: f32 = 0.70;
+const WATER_RIVER_MULTIPLIER: f32 = 1.0;
+
+fn cam_uniform() -> vec4<f32> { return u.data[0]; }    // x=target_x, y=target_y, z=yaw, w=height
+fn params_uniform() -> vec4<f32> { return u.data[1]; } // x=pitch, y=fov, z=water_z, w=has_water
+fn sun_uniform() -> vec4<f32> { return u.data[2]; }    // xyz=sun dir, w=ambient
+fn mapinfo_uniform() -> vec4<f32> { return u.data[3]; }// x=W, y=H, z=unused, w=z_scale
+fn misc_uniform() -> vec4<f32> { return u.data[4]; }   // x=time, y=unused, z=cells per repeat, w=aspect
+
+struct TerrainOut {
+    @builtin(position) position: vec4<f32>,
+    @location(0) uv: vec2<f32>,
+};
+
+@vertex
+fn vs_main(@builtin(vertex_index) vertex_index: u32) -> TerrainOut {
+    let p = vec2<f32>(f32((vertex_index << 1u) & 2u), f32(vertex_index & 2u));
+    var out: TerrainOut;
+    out.uv = p;
+    out.position = vec4<f32>(p.x * 2.0 - 1.0, 1.0 - p.y * 2.0, 0.0, 1.0);
+    return out;
+}
+
+fn height_at(cell: vec2<i32>) -> f32 {
+    let limit = vec2<i32>(mapinfo_uniform().xy) - vec2<i32>(1);
+    let c = clamp(cell, vec2<i32>(0), limit);
+    return f32(textureLoad(u_heightmap, c, 0).r) * mapinfo_uniform().w;
+}
+
+fn world_height(wx: f32, wy: f32) -> f32 {
+    let world_w = mapinfo_uniform().x * CELL;
+    let world_h = mapinfo_uniform().y * CELL;
+    if (wx < 0.0 || wy < 0.0 || wx >= world_w || wy >= world_h) {
+        return -1.0e9;
+    }
+    let c = vec2<i32>(i32(wx / CELL), i32((world_h - wy) / CELL));
+    return height_at(c);
+}
+
+fn sky_color(dir: vec3<f32>) -> vec3<f32> {
+    let d = normalize(dir);
+    let sun_dir = normalize(sun_uniform().xyz);
+    let t = clamp(d.z, 0.0, 1.0);
+    let horizon = vec3<f32>(0.70, 0.78, 0.85);
+    let zenith = vec3<f32>(0.28, 0.48, 0.80);
+    var col = mix(horizon, zenith, pow(t, 0.6));
+    let sun = max(dot(d, sun_dir), 0.0);
+    col += vec3<f32>(1.0, 0.95, 0.82) * pow(sun, 300.0) * 1.6;
+    col += vec3<f32>(1.0, 0.90, 0.72) * pow(sun, 8.0) * 0.18;
+    return col;
+}
+
+// The retail SAGE blend ramp (see terrain.frag).
+fn blend_factor(direction: u32, flags: u32, f_in: vec2<f32>) -> f32 {
+    var f = f_in;
+    let flipped = (flags & 1u) != 0u;
+    let two_sided = (flags & 2u) != 0u;
+    if (flipped) {
+        if (direction == 1u) {
+            f.x = 1.0 - f.x;
+        } else if (direction == 2u || direction == 4u || direction == 8u) {
+            f.y = 1.0 - f.y;
+        }
+    }
+    if (direction == 1u) { return f.x; }
+    if (direction == 2u) { return f.y; }
+    if (direction == 4u) {
+        let s = (1.0 - f.x) + (1.0 - f.y);
+        return select(clamp(1.0 - s, 0.0, 1.0), 1.0 - clamp(s - 1.0, 0.0, 1.0), two_sided);
+    }
+    if (direction == 8u) {
+        let s = f.x + (1.0 - f.y);
+        return select(clamp(1.0 - s, 0.0, 1.0), 1.0 - clamp(s - 1.0, 0.0, 1.0), two_sided);
+    }
+    return 0.0;
+}
+
+fn sample_layer(layer: u32, wx: f32, wy: f32) -> vec3<f32> {
+    let span = max(misc_uniform().z, 1.0);
+    let layer_count = textureNumLayers(u_atlas);
+    let l = f32(min(layer, layer_count - 1u));
+    // The atlas is 0xAARRGGBB (BGRA in memory), uploaded as RGBA8.
+    let c = textureSampleLevel(u_atlas, u_atlas_samp, vec2<f32>(wx, wy) / span, i32(l), 0.0);
+    return vec3<f32>(c.b, c.g, c.r);
+}
+
+// ---- SAGE water (Ocean.fx / RiverWater.fx / Water.frag port) ----------------
+
+// Sample an atlas layer by an explicit layer index (the water flow/bump maps
+// are appended as the last two layers of the tile atlas). The atlas is
+// 0xAARRGGBB, so the b/g/r swap restores RGB (as `sample_layer`).
+fn water_tex(layer: i32, uv: vec2<f32>) -> vec3<f32> {
+    let lc = i32(textureNumLayers(u_atlas));
+    let l = clamp(layer, 0, max(lc - 1, 0));
+    let c = textureSampleLevel(u_atlas, u_atlas_samp, uv, l, 0.0);
+    return vec3<f32>(c.b, c.g, c.r);
+}
+
+// Scrolling wave normal on the water plane: the retail bump map (atlas's last
+// layer), offset by the flow map (second-last layer) and combined with a
+// de-gridded procedural wave so the sun glint is irregular and always moving.
+fn water_normal(world_xy: vec2<f32>, time: f32) -> vec3<f32> {
+    let q = world_xy * (WATER_SCALE * 6.0);
+    let a1 = q.x * 0.80 + q.y * 0.30 + time * 1.10;
+    let a2 = q.y * 0.95 - q.x * 0.45 - time * 1.30;
+    let a3 = (q.x + q.y) * 1.60 + time * 2.10;
+    let a4 = (q.x - q.y) * 2.30 - time * 1.70;
+    let dx = 0.224 * cos(a1) - 0.099 * cos(a2) + 0.256 * cos(a3) + 0.230 * cos(a4);
+    let dy = 0.084 * cos(a1) + 0.209 * cos(a2) + 0.256 * cos(a3) - 0.230 * cos(a4);
+    let lc = i32(textureNumLayers(u_atlas));
+    let flow = water_tex(lc - 2, q - vec2<f32>(time * 0.010, time * 0.014)) * 2.0 - 1.0;
+    let bump = water_tex(lc - 1, q + flow.xy * 0.05 + vec2<f32>(time * 0.006, time * 0.008)) * 2.0 - 1.0;
+    let sx = -dx * 0.30 + bump.x * 0.45;
+    let sy = -dy * 0.30 + bump.y * 0.45;
+    return normalize(vec3<f32>(sx, sy, 1.0));
+}
+
+// Water.frag distortionPower * the flow texture: a small scrolling UV offset.
+fn water_distortion(world_xy: vec2<f32>, time: f32) -> f32 {
+    let q = world_xy * (WATER_SCALE * 6.0);
+    return 0.05 * (sin(q.x * 0.9 + time * 0.7) + sin(q.y * 1.1 - time * 0.5));
+}
+
+// Water.frag GetCloudColor: no cloud texture is bound, so a slow scroll stands in.
+fn water_cloud(world_xy: vec2<f32>, time: f32) -> vec3<f32> {
+    return vec3<f32>(0.85 + 0.15 * sin((world_xy.x + world_xy.y) * 0.0007 - time * 0.05));
+}
+
+// Retail UnderwaterDeferred.fx: absorbs red and fogs with distance.
+fn apply_underwater(color: vec3<f32>, distance: f32, cam_z: f32, water_z: f32) -> vec3<f32> {
+    if (cam_z >= water_z - 0.5) { return color; }
+    let absorb = vec3<f32>(0.35, 0.62, 0.75);
+    let fog = clamp(1.0 - exp(-distance * 0.00022), 0.0, 0.9);
+    return mix(color * absorb, vec3<f32>(0.02, 0.10, 0.16), fog);
+}
+
+// Water.frag: fresnel-mixed sky reflection and depth-graded seabed refraction,
+// SAGE diffuse + specular lighting, cloud term, depth-based transparency fade.
+fn water_shade(hitpos: vec3<f32>, dir: vec3<f32>, distance: f32) -> vec3<f32> {
+    let time = misc_uniform().x;
+    let river = misc_uniform().y;
+    let seabed = world_height(hitpos.x, hitpos.y);
+    let depth = max(0.0, params_uniform().z - seabed);
+
+    let n = water_normal(hitpos.xy, time + water_distortion(hitpos.xy, time));
+    let sun_dir = normalize(sun_uniform().xyz);
+
+    let cos_theta = clamp(dot(-dir, n), 0.0, 1.0);
+    let fresnel = 0.02 + 0.98 * pow(1.0 - cos_theta, 5.0);
+
+    let reflection = sky_color(reflect(dir, n));
+    let shallow = vec3<f32>(0.10, 0.34, 0.38);
+    let deep = vec3<f32>(0.02, 0.12, 0.22);
+    let refraction = mix(shallow, deep, clamp(depth / 40.0, 0.0, 1.0));
+
+    let ndotl = max(dot(n, sun_dir), 0.0);
+    let ambient = sun_uniform().w;
+    let diffuse = vec3<f32>(ambient + (1.0 - ambient) * ndotl);
+    let half_v = normalize(sun_dir - dir);
+    let spec = pow(max(dot(n, half_v), 0.0), 90.0);
+
+    var color = mix(refraction, reflection, clamp(fresnel, 0.0, 1.0)) * diffuse * water_cloud(hitpos.xy, time);
+    color += vec3<f32>(1.0, 0.97, 0.9) * spec * 0.45;
+
+    var alpha = clamp(depth / WATER_TRANSPARENT_DEPTH, 0.0, 1.0) * WATER_MIN_OPACITY;
+    if (river > 0.5) { alpha *= WATER_RIVER_MULTIPLIER; }
+    color = mix(refraction, color, clamp(alpha + 0.15, 0.0, 1.0));
+
+    let wfog = clamp(1.0 - exp(-distance * 0.00009), 0.0, 0.75);
+    return mix(color, sky_color(vec3<f32>(dir.x, dir.y, 0.0)), wfog);
+}
+
+@fragment
+fn fs_main(in: TerrainOut) -> @location(0) vec4<f32> {
+    let p = cam_uniform();
+    let pitch = clamp(params_uniform().x, 0.15, 1.45);
+    let fov = clamp(params_uniform().y, 0.3, 1.4);
+    let world_w = mapinfo_uniform().x * CELL;
+    let world_h = mapinfo_uniform().y * CELL;
+
+    let cp = cos(pitch);
+    let fwd = vec3<f32>(cp * sin(p.z), cp * cos(p.z), -sin(pitch));
+    let right = normalize(cross(fwd, vec3<f32>(0.0, 0.0, 1.0)));
+    let up = cross(right, fwd);
+
+    var target_z = world_height(p.x, p.y);
+    if (target_z < -1.0e8) { target_z = 0.0; }
+    let dist = p.w / sin(pitch);
+    let cam = vec3<f32>(p.x, p.y, target_z + p.w) - fwd * dist;
+
+    let ndc = vec2<f32>(in.uv.x * 2.0 - 1.0, 1.0 - in.uv.y * 2.0);
+    let aspect = misc_uniform().w;
+    let th = tan(fov * 0.5);
+    let dir = normalize(fwd + right * ndc.x * th * aspect + up * ndc.y * th);
+
+    if (dir.z >= -1e-4) {
+        return vec4<f32>(apply_underwater(sky_color(dir), 0.0, cam.z, params_uniform().z), 1.0);
+    }
+
+    // Clip the ray to the map's XY rectangle: the boundary is an exact plane,
+    // so the silhouette there stays razor-sharp instead of stair-stepping
+    // across it. Outside the map is sky.
+    var t_enter = 0.0;
+    var t_exit = 1.0e30;
+    var inside = true;
+    if (abs(dir.x) < 1e-6) {
+        inside = (cam.x >= 0.0 && cam.x <= world_w);
+    } else {
+        let a = (0.0 - cam.x) / dir.x;
+        let b = (world_w - cam.x) / dir.x;
+        t_enter = max(t_enter, min(a, b));
+        t_exit = min(t_exit, max(a, b));
+    }
+    if (inside) {
+        if (abs(dir.y) < 1e-6) {
+            inside = (cam.y >= 0.0 && cam.y <= world_h);
+        } else {
+            let a = (0.0 - cam.y) / dir.y;
+            let b = (world_h - cam.y) / dir.y;
+            t_enter = max(t_enter, min(a, b));
+            t_exit = min(t_exit, max(a, b));
+        }
+    }
+    if (!inside || t_exit <= 0.0) {
+        return vec4<f32>(apply_underwater(sky_color(dir), 0.0, cam.z, params_uniform().z), 1.0);
+    }
+
+    // March the heightfield cell by cell: the step is never longer than the
+    // time to cross one cell (dominant horizontal axis), while a clearance term
+    // lets the ray skip the empty air above the surface. Resolving every cell is
+    // what keeps cliff and map-edge silhouettes from quantising into huge
+    // stair-steps that crawl as the camera pans.
+    let horiz = max(abs(dir.x), abs(dir.y));
+    let cell_step = min(CELL / max(horiz, 1e-4), CELL * 32.0);
+    var t = max(t_enter, CELL * 0.5);
+    var prev = t;
+    var hit = false;
+    var hit_t = 0.0;
+    for (var i = 0; i < 1024 && t <= t_exit; i = i + 1) {
+        let w = cam + dir * t;
+        let h = world_height(w.x, w.y);
+        let surface = select(h, max(h, params_uniform().z), params_uniform().w > 0.5);
+        if (w.z <= surface) {
+            hit = true;
+            hit_t = t;
+            break;
+        }
+        let clearance = (w.z - surface) / max(-dir.z, 1e-4);
+        prev = t;
+        t += clamp(clearance, cell_step, cell_step * 8.0);
+    }
+    if (!hit) {
+        return vec4<f32>(apply_underwater(sky_color(dir), 0.0, cam.z, params_uniform().z), 1.0);
+    }
+
+    // Refine the first crossing; with a sub-cell bracket this converges to the
+    // exact surface point.
+    var lo = prev;
+    var hi = hit_t;
+    for (var i = 0; i < 18; i = i + 1) {
+        let mid = 0.5 * (lo + hi);
+        let w = cam + dir * mid;
+        let h = world_height(w.x, w.y);
+        let surface = select(h, max(h, params_uniform().z), params_uniform().w > 0.5);
+        if (w.z <= surface) {
+            hi = mid;
+        } else {
+            lo = mid;
+        }
+    }
+    let hitpos = cam + dir * hi;
+
+    let sun = normalize(sun_uniform().xyz);
+    let ambient = sun_uniform().w;
+
+    if (params_uniform().w > 0.5 && hitpos.z <= params_uniform().z + 0.01) {
+        return vec4<f32>(apply_underwater(water_shade(hitpos, dir, hi), hi, cam.z, params_uniform().z), 1.0);
+    }
+
+    let wx = hitpos.x / CELL;
+    let wy = (world_h - hitpos.y) / CELL;
+    let cx = clamp(i32(wx), 0, i32(mapinfo_uniform().x) - 1);
+    let cy = clamp(i32(wy), 0, i32(mapinfo_uniform().y) - 1);
+    let fx = wx - floor(wx);
+    let fy = wy - floor(wy);
+
+    let record = textureLoad(u_celldata, vec2<i32>(cx, cy), 0);
+    let packed = record.w;
+    let dir1 = packed & 0xFu;
+    let flags1 = (packed >> 4u) & 0x3u;
+    let dir2 = (packed >> 8u) & 0xFu;
+    let flags2 = (packed >> 12u) & 0x3u;
+
+    let frac_uv = vec2<f32>(fx, fy);
+    let c0 = sample_layer(record.x, wx, wy);
+    let c1 = sample_layer(record.y, wx, wy);
+    let c2 = sample_layer(record.z, wx, wy);
+    let f1 = blend_factor(dir1, flags1, frac_uv);
+    let f2 = blend_factor(dir2, flags2, frac_uv);
+    let albedo = mix(mix(c0, c1, f1), c2, f2);
+
+    let hl = world_height(hitpos.x - CELL, hitpos.y);
+    let hr = world_height(hitpos.x + CELL, hitpos.y);
+    let hd = world_height(hitpos.x, hitpos.y - CELL);
+    let hu = world_height(hitpos.x, hitpos.y + CELL);
+    let n = normalize(vec3<f32>(hl - hr, hd - hu, 2.0 * CELL));
+    let lambert = max(0.0, dot(n, sun));
+    var lit = albedo * (ambient + (1.0 - ambient) * lambert);
+    let fog = clamp(1.0 - exp(-hi * 0.00009), 0.0, 0.75);
+    lit = mix(lit, sky_color(vec3<f32>(dir.x, dir.y, 0.0)), fog);
+    return vec4<f32>(apply_underwater(lit, hi, cam.z, params_uniform().z), 1.0);
+}

src/client/ra3.client.cppm

@@ -1,34 +1,553 @@
 module;
 
-#include <cstdint>
+#if defined(__EMSCRIPTEN__)
-#include <memory>
+// Yields to the browser (requires -sASYNCIFY); see display::sleep_frame.
-#include <string_view>
+extern "C" void emscripten_sleep(unsigned int ms);
+#endif
 
 export module ra3.client;
 
+import std;
+
 import ra3.core;
 import ra3.logic;
+import ra3.render;
+import ra3.terrain;
 
 /**
  * The presentation layer: an abstract output surface plus the client facade
  * that owns the simulation and drives the frame loop.
  *
- * A future W3D/D3D9 backend implements the same `display` interface; the
+ * Backends implement only the low-level primitives (`init`, `present`,
- * default headless backend keeps OpenRA3 runnable on a CPU-only box.
+ * `poll_event`, `window_size`, `key_down`, `shutdown`) and, optionally,
+ * `present_terrain`; the interactive loops (menu, image viewer, camera viewer,
+ * GPU terrain) and the loading screen live here once, so input mapping and the
+ * frame loop never diverge between the SDL and Vulkan backends. The loops
+ * assume the display is already initialized, which lets one window host a menu,
+ * a loading bar and a viewer in sequence.
  */
 export namespace ra3::client {
     using ra3::core::uint32;
+    using ra3::render::image;
+    using ra3::render::ui_event;
+    using ra3::render::ui_event_type;
+    using ra3::render::ui_key;
+    using ra3::render::view_rect;
+
+    /** Window parameters for a display. */
+    struct display_options {
+        std::string title = "OpenRA3";
+        int width = 1280;
+        int height = 720;
+        bool fullscreen = false;
+        int fps_limit = 0; ///< 0 = vertical sync (present throttled to the display).
+    };
+
+    /** Small overlays drawn on top of the GPU terrain (top-left FPS, corner minimap). */
+    struct terrain_overlay {
+        image label;             ///< top-left label (may be empty)
+        image minimap;           ///< bottom-right overview (may be empty)
+        bool label_changed = true;
+        bool minimap_changed = true;
+    };
 
     /**
-     * Abstract output surface presented once per logic frame.
+     * Abstract presentation surface.
      */
     class display {
     public:
         virtual ~display() = default;
 
-        virtual auto begin_frame() -> void = 0;
+        virtual auto begin_frame() -> void {}
-        virtual auto end_frame() -> void = 0;
+        virtual auto end_frame() -> void {}
+
+        /** Create the window and rendering objects. */
+        [[nodiscard]] virtual auto init(const display_options &options) -> bool = 0;
+        /** Draw `frame` scaled into `dest` (window coordinates). `changed` is
+         *  false when `frame` is the same image as the previous call, so the
+         *  backend may skip re-uploading its texture. */
+        [[nodiscard]] virtual auto present(const image &frame, const view_rect &dest, bool changed) -> bool = 0;
+        /** Pop one OS event into `out`; returns false when the queue is empty. */
+        [[nodiscard]] virtual auto poll_event(ui_event &out) -> bool = 0;
+        /** Current drawable size in pixels. */
+        [[nodiscard]] virtual auto window_size() const -> std::pair<int, int> = 0;
+        /** Whether a key is currently held (for panning). */
+        [[nodiscard]] virtual auto key_down(ui_key key) const -> bool = 0;
+        virtual auto shutdown() -> void = 0;
         [[nodiscard]] virtual auto name() const -> std::string_view = 0;
+
+        /**
+         * Optional GPU terrain path. The default reports `false`, so a low-end
+         * backend simply does not offer it; the Vulkan backend overrides it.
+         * `overlays` (FPS label, minimap) are drawn on top of the terrain.
+         */
+        [[nodiscard]] virtual auto present_terrain(const ra3::terrain::gpu_terrain &, const ra3::render::camera3d &, float, const terrain_overlay &) -> bool {
+            return false;
+        }
+
+        /** Whether this backend can draw the GPU terrain path. */
+        [[nodiscard]] virtual auto supports_terrain() const -> bool { return false; }
+
+        int fps_limit_ = 0; ///< 0 = vsync, >0 = target FPS cap, <0 = uncapped.
+
+        /** Throttle an idle frame according to the configured limit. */
+        auto sleep_frame() const -> void {
+#if defined(__EMSCRIPTEN__)
+            // The frame loops are blocking; on the web the only way to let the
+            // browser paint and handle input is to yield (Asyncify sleep).
+            const int fps = fps_limit_ > 0 ? fps_limit_ : 60;
+            emscripten_sleep(static_cast<unsigned>(std::max(1, 1000 / fps)));
+#else
+            if (fps_limit_ > 0) {
+                std::this_thread::sleep_for(std::chrono::milliseconds(std::max(1, 1000 / fps_limit_)));
+            } else if (fps_limit_ < 0) {
+                std::this_thread::yield();
+            }
+            // fps_limit_ == 0: vertical sync already blocks in present().
+#endif
+        }
+
+        // ---- shared interactive loops (assume `init` succeeded) --------------
+
+        /** Letterbox `frame` into the current window. */
+        [[nodiscard]] auto present_fit(const image &frame, bool changed) -> bool {
+            const auto [w, h] = this->window_size();
+            return this->present(frame, ra3::render::fit_rect(static_cast<float>(frame.width()), static_cast<float>(frame.height()), static_cast<float>(w),
+                                                              static_cast<float>(h)),
+                                 changed);
+        }
+
+        /** Draw a warm loading screen with a progress bar (0..1). */
+        auto present_progress(float progress, std::string_view label) -> void {
+            const auto [w, h] = this->window_size();
+            const auto frame = ra3::render::compose_progress(static_cast<uint32>(std::max(1, w)), static_cast<uint32>(std::max(1, h)), progress, label);
+            this->present_fit(frame, true);
+        }
+
+        /**
+         * Run a staged loader on this display: `load` is called with a `report`
+         * callback that draws a progress bar and pumps events (returning false
+         * if the user closed the window).
+         */
+        template<typename Loader>
+        [[nodiscard]] auto run_with_progress(Loader &&load) -> bool {
+            this->present_progress(0.0F, "Loading...");
+            const auto report = [&](float progress, std::string_view label) -> bool {
+                this->present_progress(progress, label);
+                ui_event event;
+                while (this->poll_event(event)) {
+                    if (event.type == ui_event_type::quit) return false;
+                }
+                return true;
+            };
+            return load(report);
+        }
+
+        /**
+         * Interactive menu. `frame` returns the image to display for an input
+         * event, or `nullopt` when nothing changed (so the previous frame is
+         * kept and nothing is recomposed/re-uploaded). It sets `done` to end
+         * the loop. `frame` is called with the current drawable size so text
+         * stays crisp on HiDPI displays.
+         */
+        [[nodiscard]] auto menu_loop(const std::function<std::optional<image>(const ui_event &, uint32, uint32, bool &)> &frame) -> bool {
+            auto [sw, sh] = this->window_size();
+            const auto w = static_cast<uint32>(std::max(1, sw));
+            const auto h = static_cast<uint32>(std::max(1, sh));
+            bool done = false;
+            auto first = frame({}, w, h, done);
+            if (!first) return false;
+            image current = std::move(*first);
+            if (!this->present_fit(current, true)) return false;
+            while (!done) {
+                ui_event event;
+                bool idle = true;
+                bool changed = false;
+                while (this->poll_event(event)) {
+                    idle = false;
+                    if (event.type == ui_event_type::quit) {
+                        done = true;
+                        break;
+                    }
+                    auto result = frame(event, w, h, done);
+                    if (done) break;
+                    if (result) {
+                        current = std::move(*result);
+                        changed = true;
+                    }
+                }
+                if (done) break;
+                if (changed) {
+                    if (!this->present_fit(current, true)) break;
+                } else if (idle) {
+                    if (!this->present_fit(current, false)) break;
+                    this->sleep_frame();
+                }
+            }
+            return true;
+        }
+
+        /**
+         * Pan/zoom viewer over a raster image, reproducing the retail tactical
+         * view controls (wheel zoom, edge scroll, drag pan).
+         */
+        [[nodiscard]] auto image_loop(const image &scene, ra3::render::view_camera camera) -> bool {
+            if (scene.empty()) return false;
+            camera.min_zoom = 1.0F;
+            camera.clamp_center();
+
+            float mouse_x = 0.0F;
+            float mouse_y = 0.0F;
+            bool running = true;
+            auto last = std::chrono::steady_clock::now();
+            while (running) {
+                ui_event event;
+                float drag_x = 0.0F;
+                float drag_y = 0.0F;
+                while (this->poll_event(event)) {
+                    if (event.type == ui_event_type::quit) {
+                        running = false;
+                    } else if (event.type == ui_event_type::key) {
+                        if (event.key == ui_key::cancel) {
+                            running = false;
+                        } else if (event.key == ui_key::page_up) {
+                            camera.zoom_by(camera.zoom_step);
+                        } else if (event.key == ui_key::page_down) {
+                            camera.zoom_by(1.0F / camera.zoom_step);
+                        }
+                    } else if (event.type == ui_event_type::mouse_move) {
+                        mouse_x = event.x;
+                        mouse_y = event.y;
+                        if (event.left) {
+                            drag_x += event.dx;
+                            drag_y += event.dy;
+                        }
+                    } else if (event.type == ui_event_type::wheel) {
+                        camera.zoom_by(event.wheel > 0.0F ? camera.zoom_step : (1.0F / camera.zoom_step));
+                    }
+                }
+                if (!running) break;
+
+                const auto now = std::chrono::steady_clock::now();
+                const auto dt = std::min(0.1F, std::chrono::duration<float>(now - last).count());
+                last = now;
+
+                const auto [w, h] = this->window_size();
+                auto view = camera.rect(static_cast<float>(scene.width()), static_cast<float>(scene.height()), static_cast<float>(w), static_cast<float>(h));
+                if (view.w > 0.0F && view.h > 0.0F && (drag_x != 0.0F || drag_y != 0.0F)) {
+                    camera.scroll(-drag_x / view.w, -drag_y / view.h);
+                }
+                camera.edge_scroll(mouse_x, mouse_y, static_cast<float>(w), static_cast<float>(h), dt);
+                view = camera.rect(static_cast<float>(scene.width()), static_cast<float>(scene.height()), static_cast<float>(w), static_cast<float>(h));
+                if (!this->present(scene, view, false)) break;
+                this->sleep_frame();
+            }
+            return true;
+        }
+
+        /**
+         * Interactive 3D camera over a software-rendered scene: the provider
+         * re-renders whenever the camera moves.
+         */
+        [[nodiscard]] auto camera_loop(const std::function<image(const ra3::render::camera3d &, uint32, uint32)> &provider, ra3::render::camera3d camera) -> bool {
+            auto [window_w, window_h] = this->window_size();
+            image current = provider(camera, static_cast<uint32>(std::max(1, window_w)), static_cast<uint32>(std::max(1, window_h)));
+            if (current.empty()) return false;
+            if (!this->present(current, {0.0F, 0.0F, static_cast<float>(window_w), static_cast<float>(window_h)}, true)) return false;
+
+            float mouse_x = 0.5F * static_cast<float>(window_w);
+            float mouse_y = 0.5F * static_cast<float>(window_h);
+            bool running = true;
+            auto last = std::chrono::steady_clock::now();
+            while (running) {
+                ui_event event;
+                float drag_x = 0.0F;
+                float drag_y = 0.0F;
+                bool dirty = false;
+                while (this->poll_event(event)) {
+                    if (event.type == ui_event_type::quit) {
+                        running = false;
+                    } else if (event.type == ui_event_type::key) {
+                        switch (event.key) {
+                        case ui_key::cancel: running = false; break;
+                        case ui_key::page_up: camera.height = std::clamp(camera.height / 1.15F, camera.min_height, camera.max_height); dirty = true; break;
+                        case ui_key::page_down: camera.height = std::clamp(camera.height * 1.15F, camera.min_height, camera.max_height); dirty = true; break;
+                        default: break;
+                        }
+                    } else if (event.type == ui_event_type::mouse_move) {
+                        mouse_x = event.x;
+                        mouse_y = event.y;
+                        if (event.middle) {
+                            drag_x += event.dx;
+                            drag_y += event.dy;
+                        }
+                    } else if (event.type == ui_event_type::wheel) {
+                        if (event.wheel != 0.0F) {
+                            camera.height = std::clamp(camera.height * (event.wheel > 0.0F ? (1.0F / 1.15F) : 1.15F), camera.min_height, camera.max_height);
+                            dirty = true;
+                        }
+                    }
+                }
+                if (!running) break;
+
+                const auto now = std::chrono::steady_clock::now();
+                const auto dt = std::min(0.1F, std::chrono::duration<float>(now - last).count());
+                last = now;
+
+                if (drag_x != 0.0F || drag_y != 0.0F) {
+                    camera.yaw -= drag_x * 0.005F;
+                    camera.pitch = std::clamp(camera.pitch + drag_y * 0.004F, 0.15F, 1.45F);
+                    dirty = true;
+                }
+
+                float move_x = 0.0F;
+                float move_y = 0.0F;
+                if (this->key_down(ui_key::up)) move_y += 1.0F;
+                if (this->key_down(ui_key::down)) move_y -= 1.0F;
+                if (this->key_down(ui_key::left)) move_x -= 1.0F;
+                if (this->key_down(ui_key::right)) move_x += 1.0F;
+                if (mouse_x <= 24.0F) {
+                    move_x -= 1.0F;
+                } else if (mouse_x >= static_cast<float>(window_w) - 24.0F) {
+                    move_x += 1.0F;
+                }
+                if (mouse_y <= 24.0F) {
+                    move_y += 1.0F;
+                } else if (mouse_y >= static_cast<float>(window_h) - 24.0F) {
+                    move_y -= 1.0F;
+                }
+                if (move_x != 0.0F || move_y != 0.0F) {
+                    const auto fwd_x = std::sin(camera.yaw);
+                    const auto fwd_y = std::cos(camera.yaw);
+                    const auto right_x = std::cos(camera.yaw);
+                    const auto right_y = -std::sin(camera.yaw);
+                    const auto step = camera.height * 0.9F * dt;
+                    camera.target_x += (fwd_x * move_y + right_x * move_x) * step;
+                    camera.target_y += (fwd_y * move_y + right_y * move_x) * step;
+                    dirty = true;
+                }
+
+                const auto latest = this->window_size();
+                if (latest.first != window_w || latest.second != window_h) {
+                    window_w = latest.first;
+                    window_h = latest.second;
+                    dirty = true;
+                }
+                if (dirty) {
+                    current = provider(camera, static_cast<uint32>(std::max(1, window_w)), static_cast<uint32>(std::max(1, window_h)));
+                    if (current.empty()) break;
+                    dirty = false;
+                }
+                if (!this->present(current, {0.0F, 0.0F, static_cast<float>(window_w), static_cast<float>(window_h)}, true)) break;
+                this->sleep_frame();
+            }
+            return true;
+        }
+
+        /**
+         * GPU terrain viewer. `present_terrain` draws the heightfield; the loop
+         * here owns the camera controls. The top-left shows the FPS (current /
+         * cap) tagged with the active backend name (e.g. `[vulkan]`) and, when
+         * `minimap_overview` is not empty, a corner minimap with the camera
+         * location is drawn.
+         */
+        [[nodiscard]] auto terrain_loop(const ra3::terrain::gpu_terrain &terrain, ra3::render::camera3d camera, const image &minimap_overview) -> bool {
+            if (terrain.width == 0U || terrain.height == 0U || !this->supports_terrain()) return false;
+
+            const auto world_w = static_cast<float>(terrain.width) * 10.0F;
+            const auto world_h = static_cast<float>(terrain.height) * 10.0F;
+            camera.target_x = std::clamp(camera.target_x, 0.0F, world_w);
+            camera.target_y = std::clamp(camera.target_y, 0.0F, world_h);
+
+            auto [window_w, window_h] = this->window_size();
+            const auto start = std::chrono::steady_clock::now();
+            auto last = start;
+            float mouse_x = 0.5F * static_cast<float>(window_w);
+            float mouse_y = 0.5F * static_cast<float>(window_h);
+
+            terrain_overlay overlay;
+            uint32 fps = 0;
+            int fps_frames = 0;
+            auto fps_window = start;
+            auto minimap_time = start;
+
+            bool running = true;
+            bool presented = false;
+            const auto default_camera = camera;
+            bool middle_dragged = false;
+            bool middle_down = false;
+            while (running) {
+                ui_event event;
+                float drag_x = 0.0F;
+                float drag_y = 0.0F;
+                bool camera_moved = false;
+                while (this->poll_event(event)) {
+                    if (event.type == ui_event_type::quit) {
+                        running = false;
+                    } else if (event.type == ui_event_type::key) {
+                        switch (event.key) {
+                        case ui_key::cancel: running = false; break;
+                        case ui_key::page_up: camera.height = std::clamp(camera.height / 1.15F, camera.min_height, camera.max_height); camera_moved = true; break;
+                        case ui_key::page_down: camera.height = std::clamp(camera.height * 1.15F, camera.min_height, camera.max_height); camera_moved = true; break;
+                        default: break;
+                        }
+                    } else if (event.type == ui_event_type::mouse_move) {
+                        mouse_x = event.x;
+                        mouse_y = event.y;
+                        // Retail RA3: the middle button orbits the camera; the
+                        // left button is selection only, not camera rotation.
+                        if (event.middle) {
+                            drag_x += event.dx;
+                            drag_y += event.dy;
+                            if (event.dx != 0.0F || event.dy != 0.0F) middle_dragged = true;
+                        }
+                    } else if (event.type == ui_event_type::wheel) {
+                        if (event.wheel != 0.0F) {
+                            camera.height = std::clamp(camera.height * (event.wheel > 0.0F ? (1.0F / 1.15F) : 1.15F), camera.min_height, camera.max_height);
+                            camera_moved = true;
+                        }
+                    } else if (event.type == ui_event_type::mouse_button && event.middle) {
+                        if (event.released) {
+                            if (middle_down && !middle_dragged) {
+                                camera.yaw = default_camera.yaw;
+                                camera.pitch = default_camera.pitch;
+                                camera.height = default_camera.height;
+                                camera_moved = true;
+                            }
+                            middle_down = false;
+                        } else {
+                            middle_down = true;
+                            middle_dragged = false;
+                        }
+                    }
+                }
+                if (!running) break;
+
+                const auto now = std::chrono::steady_clock::now();
+                const auto dt = std::min(0.1F, std::chrono::duration<float>(now - last).count());
+                last = now;
+
+                if (drag_x != 0.0F || drag_y != 0.0F) {
+                    // SAGE LookAtTranslator: middle-drag rotates yaw (X) and
+                    // pitch (Y) at 0.01 rad per pixel; pitch is clamped to +-36 deg.
+                    camera.yaw -= drag_x * 0.01F;
+                    camera.pitch = std::clamp(camera.pitch + drag_y * 0.01F, 0.15F, 1.45F);
+                    camera_moved = true;
+                }
+
+                float move_x = 0.0F;
+                float move_y = 0.0F;
+                if (this->key_down(ui_key::up)) move_y += 1.0F;
+                if (this->key_down(ui_key::down)) move_y -= 1.0F;
+                if (this->key_down(ui_key::left)) move_x -= 1.0F;
+                if (this->key_down(ui_key::right)) move_x += 1.0F;
+                if (mouse_x <= 24.0F) {
+                    move_x -= 1.0F;
+                } else if (mouse_x >= static_cast<float>(window_w) - 24.0F) {
+                    move_x += 1.0F;
+                }
+                if (mouse_y <= 24.0F) {
+                    move_y += 1.0F;
+                } else if (mouse_y >= static_cast<float>(window_h) - 24.0F) {
+                    move_y -= 1.0F;
+                }
+                if (move_x != 0.0F || move_y != 0.0F) {
+                    const auto fwd_x = std::sin(camera.yaw);
+                    const auto fwd_y = std::cos(camera.yaw);
+                    const auto right_x = std::cos(camera.yaw);
+                    const auto right_y = -std::sin(camera.yaw);
+                    const auto step = camera.height * 0.9F * dt;
+                    camera.target_x += (fwd_x * move_y + right_x * move_x) * step;
+                    camera.target_y += (fwd_y * move_y + right_y * move_x) * step;
+                    camera_moved = true;
+                }
+                camera.target_x = std::clamp(camera.target_x, 0.0F, world_w);
+                camera.target_y = std::clamp(camera.target_y, 0.0F, world_h);
+
+                const auto latest = this->window_size();
+                if (latest.first != window_w || latest.second != window_h) {
+                    window_w = latest.first;
+                    window_h = latest.second;
+                    camera_moved = true;
+                }
+
+                if (camera_moved) {
+                    ++fps_frames;
+                    const auto window_s = std::chrono::duration<float>(now - fps_window).count();
+                    if (window_s >= 0.4F) {
+                        fps = static_cast<uint32>(std::lround(static_cast<float>(fps_frames) / window_s));
+                        fps_frames = 0;
+                        fps_window = now;
+                        overlay.label = ra3::render::compose_fps_label(fps, fps_limit_, this->name());
+                        overlay.label_changed = true;
+                    }
+                } else {
+                    fps_frames = 0;
+                    fps_window = now;
+                }
+                const auto since_minimap = std::chrono::duration<float>(now - minimap_time).count();
+                if (!minimap_overview.empty() && (overlay.minimap.empty() || (camera_moved && since_minimap >= 0.15F))) {
+                    const auto u = camera.target_x / world_w;
+                    const auto v = 1.0F - camera.target_y / world_h;
+                    overlay.minimap = ra3::render::compose_minimap(minimap_overview, u, v);
+                    overlay.minimap_changed = true;
+                    minimap_time = now;
+                }
+
+                // Render only when the view changes: an idle terrain costs nothing.
+                if (camera_moved || !presented) {
+                    const auto time_s = std::chrono::duration<float>(now - start).count();
+                    if (!this->present_terrain(terrain, camera, time_s, overlay)) {
+                        return presented;
+                    }
+                    overlay.label_changed = false;
+                    overlay.minimap_changed = false;
+                    presented = true;
+                }
+                this->sleep_frame();
+            }
+            return true;
+        }
+
+        // ---- one-shot helpers (own the lifecycle) ----------------------------
+
+        [[nodiscard]] auto run_menu(const display_options &options, const std::function<std::optional<image>(const ui_event &, uint32, uint32, bool &)> &frame) -> bool {
+            if (!this->init(options)) return false;
+            (void)this->menu_loop(frame);
+            this->shutdown();
+            return true;
+        }
+
+        [[nodiscard]] auto run_image(const display_options &options, const image &scene, ra3::render::view_camera camera) -> bool {
+            if (scene.empty() || !this->init(options)) return false;
+            (void)this->image_loop(scene, camera);
+            this->shutdown();
+            return true;
+        }
+
+        [[nodiscard]] auto run_camera(const display_options &options, const std::function<image(const ra3::render::camera3d &, uint32, uint32)> &provider,
+                                      ra3::render::camera3d camera) -> bool {
+            if (!this->init(options)) return false;
+            (void)this->camera_loop(provider, camera);
+            this->shutdown();
+            return true;
+        }
+
+        [[nodiscard]] auto run_terrain(const display_options &options, const ra3::terrain::gpu_terrain &terrain, ra3::render::camera3d camera) -> bool {
+            if (!this->init(options)) return false;
+            (void)this->terrain_loop(terrain, camera, {});
+            this->shutdown();
+            return true;
+        }
+
+        /** GPU terrain viewer with a corner minimap overlay. */
+        [[nodiscard]] auto run_terrain(const display_options &options, const ra3::terrain::gpu_terrain &terrain, ra3::render::camera3d camera,
+                                       const image &minimap) -> bool {
+            if (!this->init(options)) return false;
+            (void)this->terrain_loop(terrain, camera, minimap);
+            this->shutdown();
+            return true;
+        }
     };
 
     /**
@@ -38,6 +557,12 @@ export namespace ra3::client {
     public:
         auto begin_frame() -> void override {}
         auto end_frame() -> void override {}
+        [[nodiscard]] auto init(const display_options &) -> bool override { return false; }
+        [[nodiscard]] auto present(const image &, const view_rect &, bool) -> bool override { return false; }
+        [[nodiscard]] auto poll_event(ui_event &) -> bool override { return false; }
+        [[nodiscard]] auto window_size() const -> std::pair<int, int> override { return {0, 0}; }
+        [[nodiscard]] auto key_down(ui_key) const -> bool override { return false; }
+        auto shutdown() -> void override {}
         [[nodiscard]] auto name() const -> std::string_view override { return "headless"; }
     };
 

src/core/ra3.core.cppm

@@ -1,20 +1,7 @@
-module;
-
-#include <cmath>
-#include <compare>
-#include <cstddef>
-#include <cstdint>
-#include <limits>
-#include <optional>
-#include <ostream>
-#include <span>
-#include <string>
-#include <string_view>
-#include <utility>
-#include <vector>
-
 export module ra3.core;
 
+import std;
+
 /**
  * Fundamental engine types shared by every OpenRA3 module.
  *
@@ -24,7 +11,7 @@ export module ra3.core;
  */
 export namespace ra3::core {
     inline constexpr int version_major = 0;
-    inline constexpr int version_minor = 1;
+    inline constexpr int version_minor = 3;
     inline constexpr int version_patch = 0;
 
     using real = float;

src/data/ra3.data.cppm

@@ -0,0 +1,615 @@
+export module ra3.data;
+
+import std;
+
+export import ra3.core;
+
+/**
+ * Faithful Red Alert 3 gameplay data.
+ *
+ * Every number in this module is taken from the retail game's own asset
+ * definitions. Two sources back it, both auditable:
+ *
+ *   1. EA's open-sourced RA3 asset XML (`CnC_Modding_Support/Red Alert 3/Xml`,
+ *      GPLv3) - the `*.xml` that `BinaryAssetBuilder` compiles into `*.big`.
+ *      The `ra3_id` on each record is the originating `GameObject` id, so a
+ *      value can be looked up in `Allied/Structures/AlliedPowerPlant.xml`,
+ *      `Allied/Infantry/AlliedScoutInfantry.xml`, etc.
+ *   2. The shipped `ArmorTemplate` percentages, cross-checked against the
+ *      compiled assets by the sibling `ra3-headless` extractor.
+ *
+ * The *semantics* of the fields (armour adjusts damage per damage type, a
+ * weapon's `AntiMask` decides what it may target, `UNRESISTABLE` bypasses
+ * armour) follow SAGE and are corroborated by the OpenSAGE re-implementation
+ * (GPLv3). Where a value is not yet recovered the field is documented as such.
+ *
+ * Nothing here is loaded from disk yet: the compiled `global.bin` /
+ * `static.*.bin` deserialiser is a later milestone, so the base-game balance
+ * used by `ra3.skirmish` is pinned as constants.
+ */
+export namespace ra3::data {
+    using ra3::core::int32;
+    using ra3::core::uint8;
+    using ra3::core::uint32;
+    using ra3::core::usize;
+
+    /**
+     * World units per terrain cell. RA3's `TheTerrainLogic` grid stores
+     * `1 / cellSize` at `grid + 0x38` and the layer reports `cellSize == 10`.
+     */
+    inline constexpr float cell_size = 10.0F;
+    inline constexpr float inv_cell_size = 1.0F / cell_size;
+
+    /**
+     * The simulation advances on a fixed 30 Hz logic tick, matching SAGE.
+     *
+     * Note: the sibling `ra3-sim` paces its own simulator at 15 ticks/s from
+     * `DAT_00cdbc1c = 1000 / 15`; `ra3-headless` (which drives the real binary)
+     * reports a fixed 30 Hz logic rate. OpenRA3 keeps the 30 Hz SAGE cadence
+     * used elsewhere in this codebase until the discrepancy is settled.
+     */
+    inline constexpr int logic_frames_per_second = ra3::core::logic_frames_per_second;
+
+    /** Convert a duration in seconds to a whole number of logic frames. */
+    [[nodiscard]] constexpr auto seconds_to_frames(float seconds) -> uint32 {
+        return static_cast<uint32>(seconds * static_cast<float>(logic_frames_per_second) + 0.5F);
+    }
+
+    // ---------------------------------------------------------------------
+    // Damage types
+    // ---------------------------------------------------------------------
+
+    /**
+     * RA3's damage types, recovered from the keys of the shipped
+     * `ArmorTemplate` tables and the `DamageType` of every `WeaponTemplate`.
+     *
+     * This is *not* the Generals/ZH set (`EXPLOSION`/`SMALL_ARMS`/...): RA3
+     * replaced it with these. `unresistable` is special - it skips the armour
+     * multiplier entirely.
+     */
+    enum class damage_type : uint8 {
+        gun,
+        melee,
+        concussive,
+        auto_cannon,
+        rocket,
+        flak,
+        cannon,
+        prism,
+        tesla,
+        explosive,
+        impact,
+        sniper,
+        grenade,
+        radiation,
+        magic,
+        crush,
+        healing,
+        unresistable,
+        count,
+    };
+
+    inline constexpr usize damage_type_count = static_cast<usize>(damage_type::count);
+
+    [[nodiscard]] constexpr auto to_string(damage_type value) -> std::string_view {
+        switch (value) {
+        case damage_type::gun: return "GUN";
+        case damage_type::melee: return "MELEE";
+        case damage_type::concussive: return "CONCUSSIVE";
+        case damage_type::auto_cannon: return "AUTO_CANNON";
+        case damage_type::rocket: return "ROCKET";
+        case damage_type::flak: return "FLAK";
+        case damage_type::cannon: return "CANNON";
+        case damage_type::prism: return "PRISM";
+        case damage_type::tesla: return "TESLA";
+        case damage_type::explosive: return "EXPLOSIVE";
+        case damage_type::impact: return "IMPACT";
+        case damage_type::sniper: return "SNIPER";
+        case damage_type::grenade: return "GRENADE";
+        case damage_type::radiation: return "RADIATION";
+        case damage_type::magic: return "MAGIC";
+        case damage_type::crush: return "CRUSH";
+        case damage_type::healing: return "HEALING";
+        case damage_type::unresistable: return "UNRESISTABLE";
+        case damage_type::count: break;
+        }
+        return "UNKNOWN";
+    }
+
+    /** Parse an asset damage-type name (e.g. `"AUTO_CANNON"`). */
+    [[nodiscard]] inline auto damage_type_from_name(std::string_view name) -> damage_type {
+        for (usize i = 0; i < damage_type_count; ++i) {
+            const auto value = static_cast<damage_type>(i);
+            if (to_string(value) == name) return value;
+        }
+        return damage_type::gun;
+    }
+
+    // ---------------------------------------------------------------------
+    // Armour
+    // ---------------------------------------------------------------------
+
+    /**
+     * A `ArmorTemplate`: a per-damage-type damage multiplier.
+     *
+     * Values are fractions (1.0 == 100%). Unlisted types default to 100%,
+     * except when the template declares a `DEFAULT` (`default_fraction`), as
+     * `InvulnerableArmor` does with 0. Matches OpenSAGE's `ArmorTemplate`.
+     */
+    struct armor_set {
+        std::string_view id;
+        std::array<float, damage_type_count> multipliers{};
+        float default_fraction = 1.0F;
+
+        /** Apply this armour. `unresistable` is never scaled. */
+        [[nodiscard]] constexpr auto adjust(damage_type type, float damage) const -> float {
+            if (type == damage_type::unresistable) return damage;
+            const auto scaled = damage * multipliers[static_cast<usize>(type)];
+            return scaled < 0.0F ? 0.0F : scaled;
+        }
+    };
+
+    /**
+     * Build an armour set. `vs` entries are the raw percentages from the
+     * shipped `ArmorTemplate` (`100.0` means normal damage).
+     */
+    constexpr auto make_armor(std::string_view id, float default_percent, std::initializer_list<std::pair<damage_type, float>> vs) -> armor_set {
+        armor_set armor{};
+        armor.id = id;
+        armor.default_fraction = default_percent / 100.0F;
+        armor.multipliers.fill(armor.default_fraction);
+        for (const auto &[type, percent]: vs) armor.multipliers[static_cast<usize>(type)] = percent / 100.0F;
+        return armor;
+    }
+
+    /**
+     * The armour templates used by the modelled units, copied verbatim from the
+     * shipped `ArmorTemplate` tables (`ra3-headless/out/armors.json`).
+     */
+    inline constexpr armor_set allied_scout_infantry_armor = make_armor(
+        "AlliedScoutInfantryArmor", 100.0F,
+        {{damage_type::gun, 1.0F}, {damage_type::melee, 50.0F}, {damage_type::concussive, 50.0F}, {damage_type::auto_cannon, 50.0F},
+         {damage_type::rocket, 50.0F}, {damage_type::flak, 50.0F}, {damage_type::cannon, 50.0F}, {damage_type::prism, 50.0F},
+         {damage_type::tesla, 50.0F}, {damage_type::explosive, 50.0F}, {damage_type::impact, 50.0F}});
+
+    inline constexpr armor_set allied_anti_infantry_infantry_armor = make_armor(
+        "AlliedAntiInfantryInfantryArmor", 100.0F,
+        {{damage_type::sniper, 100.0F}, {damage_type::cannon, 20.0F}, {damage_type::rocket, 20.0F}, {damage_type::grenade, 100.0F},
+         {damage_type::gun, 100.0F}, {damage_type::melee, 100.0F}, {damage_type::auto_cannon, 150.0F}, {damage_type::impact, 100.0F},
+         {damage_type::explosive, 100.0F}, {damage_type::flak, 10.0F}, {damage_type::prism, 100.0F}, {damage_type::tesla, 1000.0F},
+         {damage_type::radiation, 100.0F}});
+
+    inline constexpr armor_set soviet_anti_infantry_infantry_armor = make_armor(
+        "SovietAntiInfantryInfantryArmor", 100.0F,
+        {{damage_type::sniper, 100.0F}, {damage_type::cannon, 20.0F}, {damage_type::rocket, 20.0F}, {damage_type::grenade, 100.0F},
+         {damage_type::gun, 100.0F}, {damage_type::melee, 100.0F}, {damage_type::auto_cannon, 150.0F}, {damage_type::impact, 100.0F},
+         {damage_type::explosive, 100.0F}, {damage_type::flak, 10.0F}, {damage_type::prism, 100.0F}, {damage_type::tesla, 1000.0F},
+         {damage_type::radiation, 100.0F}});
+
+    inline constexpr armor_set soviet_scout_infantry_armor = make_armor(
+        "SovietScoutInfantryArmor", 100.0F,
+        {{damage_type::gun, 1.0F}, {damage_type::melee, 50.0F}, {damage_type::concussive, 50.0F}, {damage_type::auto_cannon, 50.0F},
+         {damage_type::rocket, 50.0F}, {damage_type::flak, 50.0F}, {damage_type::cannon, 50.0F}, {damage_type::prism, 50.0F},
+         {damage_type::tesla, 50.0F}, {damage_type::explosive, 50.0F}, {damage_type::impact, 50.0F}});
+
+    inline constexpr armor_set allied_miner_armor =
+        make_armor("AlliedMinerArmor", 100.0F,
+                   {{damage_type::melee, 0.0F}, {damage_type::sniper, 0.0F}, {damage_type::gun, 50.0F}, {damage_type::auto_cannon, 100.0F},
+                    {damage_type::impact, 100.0F}, {damage_type::flak, 100.0F}, {damage_type::rocket, 100.0F}, {damage_type::cannon, 150.0F},
+                    {damage_type::prism, 150.0F}, {damage_type::tesla, 150.0F}, {damage_type::explosive, 100.0F},
+                    {damage_type::concussive, 100.0F}, {damage_type::radiation, 5.0F}});
+
+    inline constexpr armor_set allied_anti_vehicle_vehicle_tech1_armor = make_armor(
+        "AlliedAntiVehicleVehicleTech1Armor", 100.0F,
+        {{damage_type::melee, 0.0F}, {damage_type::sniper, 0.0F}, {damage_type::gun, 25.0F}, {damage_type::auto_cannon, 100.0F},
+         {damage_type::impact, 75.0F}, {damage_type::rocket, 75.0F}, {damage_type::flak, 100.0F}, {damage_type::cannon, 170.0F},
+         {damage_type::prism, 170.0F}, {damage_type::tesla, 170.0F}, {damage_type::explosive, 100.0F}, {damage_type::radiation, 5.0F}});
+
+    inline constexpr armor_set soviet_anti_vehicle_vehicle_tech1_armor = make_armor(
+        "SovietAntiVehicleVehicleTech1Armor", 100.0F,
+        {{damage_type::melee, 0.0F}, {damage_type::sniper, 0.0F}, {damage_type::gun, 50.0F}, {damage_type::auto_cannon, 25.0F},
+         {damage_type::impact, 75.0F}, {damage_type::flak, 100.0F}, {damage_type::rocket, 100.0F}, {damage_type::cannon, 100.0F},
+         {damage_type::prism, 100.0F}, {damage_type::tesla, 100.0F}, {damage_type::explosive, 100.0F}, {damage_type::concussive, 100.0F},
+         {damage_type::radiation, 5.0F}});
+
+    /** The faction structure armour shared by con yard, power plant, barracks, refinery and war factory. */
+    inline constexpr armor_set allied_structure_armor = make_armor(
+        "AlliedConYardArmor", 100.0F,
+        {{damage_type::sniper, 0.0F}, {damage_type::cannon, 100.0F}, {damage_type::rocket, 100.0F}, {damage_type::grenade, 100.0F},
+         {damage_type::gun, 100.0F}, {damage_type::melee, 0.0F}, {damage_type::auto_cannon, 50.0F}, {damage_type::impact, 100.0F},
+         {damage_type::explosive, 125.0F}, {damage_type::flak, 100.0F}, {damage_type::prism, 100.0F}, {damage_type::tesla, 100.0F},
+         {damage_type::radiation, 0.0F}});
+
+    inline constexpr armor_set soviet_structure_armor = make_armor(
+        "SovietConYardArmor", 100.0F,
+        {{damage_type::sniper, 0.0F}, {damage_type::cannon, 100.0F}, {damage_type::rocket, 100.0F}, {damage_type::grenade, 100.0F},
+         {damage_type::gun, 100.0F}, {damage_type::melee, 0.0F}, {damage_type::auto_cannon, 50.0F}, {damage_type::impact, 100.0F},
+         {damage_type::explosive, 125.0F}, {damage_type::flak, 100.0F}, {damage_type::prism, 100.0F}, {damage_type::tesla, 100.0F},
+         {damage_type::radiation, 0.0F}});
+
+    /** Neutral armour: everything does normal damage. */
+    inline constexpr armor_set neutral_armor = make_armor("NoArmor", 100.0F, {});
+
+    // ---------------------------------------------------------------------
+    // Target classification and weapon anti-mask
+    // ---------------------------------------------------------------------
+
+    /** Coarse target classes, derived from a `GameObject`'s `KindOf` flags. */
+    namespace target_class {
+        inline constexpr uint32 none = 0U;
+        inline constexpr uint32 infantry = 1U << 0U;
+        inline constexpr uint32 vehicle = 1U << 1U;
+        inline constexpr uint32 structure = 1U << 2U;
+        inline constexpr uint32 aircraft = 1U << 3U;
+        inline constexpr uint32 ground = infantry | vehicle | structure;
+        inline constexpr uint32 any = 0xFFFFFFFFU;
+    }
+
+    /**
+     * A `WeaponTemplate`'s `AntiMask`. RA3's tokens are recovered from the
+     * shipped weapons (`ra3-headless/out/weapons.json`).
+     */
+    namespace anti {
+        inline constexpr uint32 ground = 1U << 0U;
+        inline constexpr uint32 water = 1U << 1U;
+        inline constexpr uint32 structure = 1U << 2U;
+        inline constexpr uint32 infantry = 1U << 3U;
+        inline constexpr uint32 vehicle = 1U << 4U;
+        inline constexpr uint32 airborne_vehicle = 1U << 5U;
+        inline constexpr uint32 airborne_infantry = 1U << 6U;
+        inline constexpr uint32 submerged = 1U << 7U;
+        inline constexpr uint32 lifted_ground_unit = 1U << 8U;
+        inline constexpr uint32 mine = 1U << 9U;
+        inline constexpr uint32 projectile = 1U << 10U;
+        inline constexpr uint32 small_missile = 1U << 11U;
+        inline constexpr uint32 ballistic_missile = 1U << 12U;
+        inline constexpr uint32 parachute = 1U << 13U;
+    }
+
+    // ---------------------------------------------------------------------
+    // Weapons
+    // ---------------------------------------------------------------------
+
+    /** Primary weapon parameters. Timings are in seconds. */
+    struct weapon_data {
+        std::string_view ra3_id;
+        float attack_range = 0.0F;
+        float damage = 0.0F;
+        damage_type type = damage_type::gun;
+        float splash_radius = 0.0F;
+        float weapon_speed = 0.0F;
+        uint32 clip_size = 1;
+        float reload_seconds = 1.0F;
+        float firing_seconds = 0.5F;
+        uint32 anti_mask = 0U;
+        /** Classes this weapon may never target (the nugget's `SpecialObjectFilter`). */
+        uint32 excluded_classes = target_class::none;
+        /** One hit kills any valid target (the maul's `InstakillNugget`). */
+        bool instakill = false;
+        bool projectile = false;
+
+        /**
+         * Can this weapon target an object of `target` class?
+         *
+         * `ANTI_GROUND` covers all ground classes; the airborne flags cover
+         * aircraft. A weapon with no anti-air flag cannot hit aircraft, which is
+         * why an attack dog can never maul a plane.
+         */
+        [[nodiscard]] constexpr auto can_target(uint32 target) const -> bool {
+            if ((target & excluded_classes) != 0U) return false;
+            if ((target & target_class::aircraft) != 0U) {
+                return (anti_mask & (anti::airborne_vehicle | anti::airborne_infantry)) != 0U;
+            }
+            if ((anti_mask & anti::ground) != 0U && (target & target_class::ground) != 0U) return true;
+            if ((anti_mask & anti::infantry) != 0U && (target & target_class::infantry) != 0U) return true;
+            if ((anti_mask & anti::vehicle) != 0U && (target & target_class::vehicle) != 0U) return true;
+            if ((anti_mask & anti::structure) != 0U && (target & target_class::structure) != 0U) return true;
+            return false;
+        }
+    };
+
+    /**
+     * The primary weapons of the modelled units, from the shipped
+     * `WeaponTemplate`s.
+     */
+    inline constexpr weapon_data maul_weapon{
+        "AlliedScoutInfantryMaul", 30.0F, 1.0F, damage_type::unresistable, 0.0F, 125.0F, 1U, 1.5F, 0.5F, anti::ground | anti::water,
+        target_class::vehicle | target_class::structure | target_class::aircraft, true, false};
+
+    inline constexpr weapon_data shotgun_weapon{"AlliedAntiInfantryInfantryShotgun",
+                                              150.0F,
+                                              40.0F,
+                                              damage_type::gun,
+                                              155.0F,
+                                              750.0F,
+                                              1U,
+                                              1.0F,
+                                              0.5F,
+                                              anti::ground | anti::structure | anti::water,
+                                              target_class::none,
+                                              false,
+                                              true};
+
+    inline constexpr weapon_data ak47_weapon{"SovietAntiInfantryInfantryAK47",
+                                            150.0F,
+                                            5.0F,
+                                            damage_type::gun,
+                                            0.0F,
+                                            750.0F,
+                                            1U,
+                                            0.5F,
+                                            0.25F,
+                                            anti::water | anti::ground | anti::structure,
+                                            target_class::none,
+                                            false,
+                                            true};
+
+    inline constexpr weapon_data guardian_cannon_weapon{"AlliedAntiVehicleVehicleTech1Cannon",
+                                                      150.0F,
+                                                      60.0F,
+                                                      damage_type::cannon,
+                                                      0.0F,
+                                                      999999.0F,
+                                                      1U,
+                                                      1.8F,
+                                                      0.2F,
+                                                      anti::water | anti::ground | anti::structure,
+                                                      target_class::none,
+                                                      false,
+                                                      true};
+
+    inline constexpr weapon_data rhino_cannon_weapon{"SovietAntiVehicleVehicleTech1CannonWeapon",
+                                                    150.0F,
+                                                    35.0F,
+                                                    damage_type::cannon,
+                                                    0.0F,
+                                                    999999.0F,
+                                                    1U,
+                                                    1.0F,
+                                                    0.2F,
+                                                    anti::water | anti::ground | anti::structure,
+                                                    target_class::none,
+                                                    false,
+                                                    true};
+
+    // ---------------------------------------------------------------------
+    // Entities
+    // ---------------------------------------------------------------------
+
+    /** Everything the skirmish simulation can place. */
+    enum class entity_kind : uint8 {
+        none = 0,
+        attack_dog,       ///< AlliedScoutInfantry
+        peacekeeper,      ///< AlliedAntiInfantryInfantry
+        conscript,        ///< SovietAntiInfantryInfantry
+        guardian_tank,    ///< AlliedAntiVehicleVehicleTech1
+        rhino_tank,       ///< SovietAntiVehicleVehicleTech1
+        miner,            ///< AlliedMiner
+        construction_yard,
+        power_plant,
+        barracks,
+        war_factory,
+        refinery,
+        count,
+    };
+
+    inline constexpr usize entity_kind_count = static_cast<usize>(entity_kind::count);
+
+    [[nodiscard]] constexpr auto to_string(entity_kind value) -> std::string_view {
+        switch (value) {
+        case entity_kind::attack_dog: return "attack_dog";
+        case entity_kind::peacekeeper: return "peacekeeper";
+        case entity_kind::conscript: return "conscript";
+        case entity_kind::guardian_tank: return "guardian_tank";
+        case entity_kind::rhino_tank: return "rhino_tank";
+        case entity_kind::miner: return "miner";
+        case entity_kind::construction_yard: return "construction_yard";
+        case entity_kind::power_plant: return "power_plant";
+        case entity_kind::barracks: return "barracks";
+        case entity_kind::war_factory: return "war_factory";
+        case entity_kind::refinery: return "refinery";
+        case entity_kind::none: break;
+        case entity_kind::count: break;
+        }
+        return "none";
+    }
+
+    [[nodiscard]] constexpr auto is_unit(entity_kind kind) -> bool {
+        switch (kind) {
+        case entity_kind::attack_dog:
+        case entity_kind::peacekeeper:
+        case entity_kind::conscript:
+        case entity_kind::guardian_tank:
+        case entity_kind::rhino_tank:
+        case entity_kind::miner: return true;
+        default: return false;
+        }
+    }
+
+    [[nodiscard]] constexpr auto is_structure(entity_kind kind) -> bool {
+        switch (kind) {
+        case entity_kind::construction_yard:
+        case entity_kind::power_plant:
+        case entity_kind::barracks:
+        case entity_kind::war_factory:
+        case entity_kind::refinery: return true;
+        default: return false;
+        }
+    }
+
+    /** Target class of an entity, from its `KindOf` (`INFANTRY`/`VEHICLE`/...). */
+    [[nodiscard]] constexpr auto class_of(entity_kind kind) -> uint32 {
+        switch (kind) {
+        case entity_kind::attack_dog:
+        case entity_kind::peacekeeper:
+        case entity_kind::conscript: return target_class::infantry;
+        case entity_kind::guardian_tank:
+        case entity_kind::rhino_tank:
+        case entity_kind::miner: return target_class::vehicle;
+        case entity_kind::construction_yard:
+        case entity_kind::power_plant:
+        case entity_kind::barracks:
+        case entity_kind::war_factory:
+        case entity_kind::refinery: return target_class::structure;
+        default: return target_class::none;
+        }
+    }
+
+    /** Mobile unit parameters. */
+    struct unit_data {
+        entity_kind kind = entity_kind::none;
+        std::string_view ra3_id;
+        int32 cost = 0;
+        float build_seconds = 0.0F;
+        float max_health = 0.0F;
+        const armor_set *armor = &neutral_armor;
+        float speed = 0.0F;          ///< LocomotorSet Speed, world units per second.
+        float vision = 0.0F;         ///< VisionInfo VisionRange.
+        float shroud_clear = 0.0F;   ///< VisionInfo ShroudClearingRange.
+        float radius = 0.0F;         ///< Geometry MajorRadius.
+        const weapon_data *weapon = nullptr;
+        entity_kind built_by = entity_kind::none; ///< Producer structure.
+    };
+
+    /** Structure parameters. */
+    struct structure_data {
+        entity_kind kind = entity_kind::none;
+        std::string_view ra3_id;
+        int32 cost = 0;
+        float build_seconds = 0.0F;
+        float max_health = 0.0F;
+        const armor_set *armor = &neutral_armor;
+        int32 energy = 0; ///< `EnergyProduction`: positive supplies, negative draws.
+        float vision = 0.0F;
+        float shroud_clear = 0.0F;
+        float radius = 0.0F;
+        int size_cells = 1;                   ///< Footprint, cells per side.
+        entity_kind prerequisite = entity_kind::none; ///< Prerequisite structure.
+        bool is_producer = false;             ///< Can build units.
+        bool is_refinery = false;             ///< Runs an ore extraction cycle.
+    };
+
+    /**
+     * Mobile units. Health, cost, build time, speed and armour are the retail
+     * `GameObject`/`LocomotorSet`/`ArmorTemplate` values.
+     */
+    inline constexpr std::array<unit_data, entity_kind_count> units{{
+        {}, // none
+        {entity_kind::attack_dog, "AlliedScoutInfantry", 200, 2.0F, 30.0F, &allied_scout_infantry_armor, 100.0F, 200.0F, 750.0F, 7.0F, &maul_weapon,
+         entity_kind::barracks},
+        {entity_kind::peacekeeper, "AlliedAntiInfantryInfantry", 200, 5.0F, 150.0F, &allied_anti_infantry_infantry_armor, 50.0F, 200.0F, 500.0F, 7.0F,
+         &shotgun_weapon, entity_kind::barracks},
+        {entity_kind::conscript, "SovietAntiInfantryInfantry", 100, 4.0F, 100.0F, &soviet_anti_infantry_infantry_armor, 50.0F, 200.0F, 500.0F, 5.0F,
+         &ak47_weapon, entity_kind::barracks},
+        {entity_kind::guardian_tank, "AlliedAntiVehicleVehicleTech1", 950, 10.0F, 480.0F, &allied_anti_vehicle_vehicle_tech1_armor, 80.0F, 200.0F, 500.0F,
+         20.0F, &guardian_cannon_weapon, entity_kind::war_factory},
+        {entity_kind::rhino_tank, "SovietAntiVehicleVehicleTech1", 1000, 10.0F, 550.0F, &soviet_anti_vehicle_vehicle_tech1_armor, 75.0F, 200.0F, 500.0F,
+         20.0F, &rhino_cannon_weapon, entity_kind::war_factory},
+        {entity_kind::miner, "AlliedMiner", 1000, 20.0F, 500.0F, &allied_miner_armor, 50.0F, 200.0F, 500.0F, 20.0F, nullptr, entity_kind::refinery},
+        {}, {}, {}, {}, {},
+    }};
+
+    /**
+     * Structures. `energy` is the `EnergyProduction` attribute; `build_seconds`
+     * is `BuildTime`. Soviet `BuildTime` is not set on the base structures (the
+     * extractor reads 0), so the Allied values are used for both sides and the
+     * discrepancy is documented rather than invented.
+     */
+    inline constexpr std::array<structure_data, entity_kind_count> structures{{
+        {}, {}, {}, {}, {}, {}, {}, // none + the six units
+        {entity_kind::construction_yard, "AlliedConstructionYard", 5000, 25.0F, 4000.0F, &allied_structure_armor, 50, 150.0F, 1000.0F, 60.0F, 3,
+         entity_kind::none, false, false},
+        {entity_kind::power_plant, "AlliedPowerPlant", 800, 10.0F, 1000.0F, &allied_structure_armor, 100, 150.0F, 300.0F, 30.0F, 2,
+         entity_kind::none, false, false},
+        {entity_kind::barracks, "AlliedBarracks", 500, 10.0F, 1000.0F, &allied_structure_armor, -25, 150.0F, 300.0F, 45.0F, 2, entity_kind::none,
+         true, false},
+        {entity_kind::war_factory, "AlliedWarFactory", 2000, 20.0F, 2500.0F, &allied_structure_armor, -50, 150.0F, 500.0F, 60.0F, 3,
+         entity_kind::none, true, false},
+        {entity_kind::refinery, "AlliedRefinery", 2000, 20.0F, 2000.0F, &allied_structure_armor, -50, 150.0F, 500.0F, 60.0F, 3,
+         entity_kind::power_plant, false, true},
+    }};
+
+    /** Look up a mobile unit. Only valid when `is_unit(kind)`. */
+    [[nodiscard]] inline auto unit_of(entity_kind kind) -> const unit_data & { return units.at(static_cast<usize>(kind)); }
+
+    /** Look up a structure. Only valid when `is_structure(kind)`. */
+    [[nodiscard]] inline auto structure_of(entity_kind kind) -> const structure_data & { return structures.at(static_cast<usize>(kind)); }
+
+    /** Cost in credits. */
+    [[nodiscard]] inline auto cost_of(entity_kind kind) -> int32 {
+        if (is_unit(kind)) return unit_of(kind).cost;
+        if (is_structure(kind)) return structure_of(kind).cost;
+        return 0;
+    }
+
+    /** Build time in logic frames. */
+    [[nodiscard]] inline auto build_frames_of(entity_kind kind) -> uint32 {
+        if (is_unit(kind)) return seconds_to_frames(unit_of(kind).build_seconds);
+        if (is_structure(kind)) return seconds_to_frames(structure_of(kind).build_seconds);
+        return 0U;
+    }
+
+    /** Maximum health. */
+    [[nodiscard]] inline auto max_health_of(entity_kind kind) -> float {
+        if (is_unit(kind)) return unit_of(kind).max_health;
+        if (is_structure(kind)) return structure_of(kind).max_health;
+        return 0.0F;
+    }
+
+    /** Armour template. */
+    [[nodiscard]] inline auto armor_of(entity_kind kind) -> const armor_set & {
+        if (is_unit(kind)) return *unit_of(kind).armor;
+        if (is_structure(kind)) return *structure_of(kind).armor;
+        return neutral_armor;
+    }
+
+    /** Vision range in world units. */
+    [[nodiscard]] inline auto vision_of(entity_kind kind) -> float {
+        if (is_unit(kind)) return unit_of(kind).vision;
+        if (is_structure(kind)) return structure_of(kind).vision;
+        return 0.0F;
+    }
+
+    /** The weapon a unit fires, or `nullptr` (structures, miners). */
+    [[nodiscard]] inline auto weapon_of(entity_kind kind) -> const weapon_data * {
+        return is_unit(kind) ? unit_of(kind).weapon : nullptr;
+    }
+
+    // ---------------------------------------------------------------------
+    // Economy and world rules
+    // ---------------------------------------------------------------------
+
+    /**
+     * Ore economy, from `OreNodeBehaviour` and `MpGameRules`.
+     *
+     * A refinery runs one extraction cycle: `MOVE_TO_EXTRACT + EXTRACT +
+     * MOVE_TO_DELIVER + DELIVERY` = 11 s for 250 credits while its node has
+     * ore. The engine actually spawns a separate miner; OpenRA3 folds the cycle
+     * into the refinery (a documented simplification, as in `ra3-sim`).
+     */
+    struct economy_data {
+        int32 starting_credits = 10000;  ///< MpGameRules SkirmishStartCash LoCash.
+        int32 credits_step = 5000;       ///< SkirmishStartCash ChoiceStepAmount.
+        int32 credits_max = 40000;       ///< SkirmishStartCash HiCash.
+        int32 ore_per_delivery = 250;    ///< OreNodeBehaviour DeliveryAmount.
+        int32 ore_per_delivery_empty = 60; ///< OreNodeBehaviour DeliveryAmountWhenEmpty.
+        int32 ore_node_capacity = 30000; ///< OreNodeBehaviour MaximumGatheredValue.
+        float extraction_seconds = 11.0F; ///< 3.5 + 2 + 3.5 + 2.
+    };
+
+    /** Miscellaneous world rules. */
+    struct world_data {
+        float standard_shroud_clear = 500.0F; ///< Define STANDARD_SHROUD_CLEAR.
+        float scout_shroud_clear = 750.0F;    ///< Define SCOUT_SHROUD_CLEAR.
+        int low_power_production_divisor = 2; ///< Low power halves production speed.
+        int low_power_mining_divisor = 2;     ///< Low power halves refinery income.
+    };
+
+    inline constexpr economy_data economy{};
+    inline constexpr world_data world_rules{};
+
+    /** Ore extracted per completed refinery cycle, given the remaining node ore. */
+    [[nodiscard]] constexpr auto ore_per_cycle(int32 node_remaining) -> int32 {
+        return node_remaining > 0 ? economy.ore_per_delivery : economy.ore_per_delivery_empty;
+    }
+}

src/display/ra3.display.cppm

@@ -0,0 +1,174 @@
+export module ra3.display;
+
+import std;
+
+export import ra3.core;
+import ra3.render;
+import ra3.terrain;
+import ra3.client;
+import ra3.ui;
+import ra3.vulkan;
+import ra3.dx;
+import ra3.wasmgl;
+import ra3.webgpu;
+
+/**
+ * Backend selection for the presentation layer.
+ *
+ * The app talks only to `ra3::client::display`; this module picks the concrete
+ * backend so no caller has to know which one is in use. The available backends
+ * are Vulkan, Direct3D 11 and Direct3D 12 (desktop), the WebGPU and SDL-free
+ * WebGL2 wasm worker backends (wasm) and the SDL software blit fallback. The
+ * caller may name a preferred backend (the in-game menu exposes this); if it
+ * does not start, the others are tried in turn. The GPU terrain path reports
+ * failure so the caller can fall back to the software renderer.
+ */
+export namespace ra3::display {
+    using ra3::client::display_options;
+    using ra3::render::camera3d;
+    using ra3::render::image;
+    using ra3::render::ui_event;
+    using ra3::render::view_camera;
+
+    using menu_frame = std::function<std::optional<image>(const ui_event &, ra3::core::uint32, ra3::core::uint32, bool &)>;
+    using camera_frame = std::function<image(const camera3d &, ra3::core::uint32, ra3::core::uint32)>;
+
+    /** A concrete presentation backend, or `none`. */
+    enum class backend { none, vulkan, d3d11, d3d12, wasmgl, webgpu, sdl };
+
+    /** The backend preferred on this host: WebGPU under Emscripten (falling back to the WebGL worker), else Vulkan. */
+    [[nodiscard]] inline constexpr auto default_backend() -> backend {
+#if defined(__EMSCRIPTEN__)
+        return backend::webgpu;
+#else
+        return backend::vulkan;
+#endif
+    }
+
+    [[nodiscard]] inline auto backend_name(backend which) -> std::string_view {
+        switch (which) {
+        case backend::vulkan: return "vulkan";
+        case backend::d3d11: return "d3d11";
+        case backend::d3d12: return "d3d12";
+        case backend::wasmgl: return "wasmgl";
+        case backend::webgpu: return "webgpu";
+        case backend::sdl: return "sdl";
+        default: return "none";
+        }
+    }
+
+    [[nodiscard]] inline auto make_backend(backend which) -> std::unique_ptr<ra3::client::display> {
+        switch (which) {
+        case backend::vulkan: return std::make_unique<ra3::vulkan::vulkan_display>();
+        case backend::d3d11: return std::make_unique<ra3::dx::d3d11_display>();
+        case backend::d3d12: return std::make_unique<ra3::dx::d3d12_display>();
+        case backend::wasmgl: return std::make_unique<ra3::wasmgl::wasmgl_display>();
+        case backend::webgpu: return std::make_unique<ra3::webgpu::webgpu_display>();
+        case backend::sdl: return std::make_unique<ra3::ui::sdl_display>();
+        default: return nullptr;
+        }
+    }
+
+    /** The order in which backends are attempted for a preferred one. */
+    [[nodiscard]] inline auto backend_order(backend preferred) -> std::array<backend, 6> {
+        switch (preferred) {
+        case backend::d3d11: return {backend::d3d11, backend::d3d12, backend::vulkan, backend::webgpu, backend::wasmgl, backend::sdl};
+        case backend::d3d12: return {backend::d3d12, backend::d3d11, backend::vulkan, backend::webgpu, backend::wasmgl, backend::sdl};
+        case backend::wasmgl: return {backend::wasmgl, backend::webgpu, backend::vulkan, backend::d3d11, backend::d3d12, backend::sdl};
+        case backend::webgpu: return {backend::webgpu, backend::wasmgl, backend::vulkan, backend::d3d11, backend::d3d12, backend::sdl};
+        case backend::sdl: return {backend::sdl, backend::d3d11, backend::d3d12, backend::vulkan, backend::webgpu, backend::wasmgl};
+        case backend::vulkan:
+        default: return {backend::vulkan, backend::d3d11, backend::d3d12, backend::webgpu, backend::wasmgl, backend::sdl};
+        }
+    }
+
+    /**
+     * Create and initialize the preferred backend, falling back to the others,
+     * or return null when none starts. The caller owns the display and may reuse
+     * it for a menu, a loading bar and a viewer in sequence.
+     */
+    [[nodiscard]] inline auto create(const display_options &options, backend preferred) -> std::unique_ptr<ra3::client::display> {
+        for (const auto which: backend_order(preferred)) {
+            auto candidate = make_backend(which);
+            if (candidate && candidate->init(options)) return candidate;
+        }
+        return nullptr;
+    }
+
+    /** Create and initialize the preferred display (Vulkan, then SDL). */
+    [[nodiscard]] inline auto create(const display_options &options, bool prefer_vulkan) -> std::unique_ptr<ra3::client::display> {
+        return create(options, prefer_vulkan ? backend::vulkan : backend::sdl);
+    }
+
+    /**
+     * Run `action` on the first backend that initializes.
+     *
+     * `action` must call one of the shared `display` loops; it returns false to
+     * mean "this backend did not start", so the next one is tried.
+     */
+    template<typename Fn>
+    [[nodiscard]] auto with_display(backend preferred, Fn &&action) -> bool {
+        for (const auto which: backend_order(preferred)) {
+            auto candidate = make_backend(which);
+            if (candidate && action(*candidate)) return true;
+        }
+        return false;
+    }
+
+    /** Run `action` on the first display that initializes: Vulkan, then SDL. */
+    template<typename Fn>
+    [[nodiscard]] auto with_display(bool prefer_vulkan, Fn &&action) -> bool {
+        return with_display(prefer_vulkan ? backend::vulkan : backend::sdl, std::forward<Fn>(action));
+    }
+
+    /** Interactive menu on the preferred (or first available) backend. */
+    [[nodiscard]] inline auto run_menu(const display_options &options, const menu_frame &frame, backend preferred = default_backend()) -> bool {
+        return with_display(preferred, [&](ra3::client::display &d) { return d.run_menu(options, frame); });
+    }
+
+    /** Pan/zoom image viewer on the preferred (or first available) backend. */
+    [[nodiscard]] inline auto run_image(const display_options &options, const image &scene, view_camera camera, backend preferred) -> bool {
+        return with_display(preferred, [&](ra3::client::display &d) { return d.run_image(options, scene, camera); });
+    }
+
+    /** Pan/zoom image viewer on the preferred (or first available) backend. */
+    [[nodiscard]] inline auto run_image(const display_options &options, const image &scene, view_camera camera, bool prefer_vulkan) -> bool {
+        return run_image(options, scene, camera, prefer_vulkan ? backend::vulkan : backend::sdl);
+    }
+
+    /** Software 3D camera viewer on the preferred (or first available) backend. */
+    [[nodiscard]] inline auto run_camera(const display_options &options, const camera_frame &provider, camera3d camera, bool prefer_vulkan) -> bool {
+        return with_display(prefer_vulkan ? backend::vulkan : backend::sdl,
+                            [&](ra3::client::display &d) { return d.run_camera(options, provider, camera); });
+    }
+
+    /**
+     * GPU terrain viewer on the preferred (or first available) backend. Returns
+     * false when no GPU backend that offers terrain starts, so the caller can
+     * render offscreen instead.
+     */
+    [[nodiscard]] inline auto run_terrain(const display_options &options, const ra3::terrain::gpu_terrain &terrain, camera3d camera,
+                                          backend preferred) -> bool {
+        return with_display(preferred, [&](ra3::client::display &d) {
+            if (!d.supports_terrain()) return false;
+            return d.run_terrain(options, terrain, camera);
+        });
+    }
+
+    /** GPU terrain viewer with a corner minimap overlay. */
+    [[nodiscard]] inline auto run_terrain(const display_options &options, const ra3::terrain::gpu_terrain &terrain, camera3d camera,
+                                          const image &minimap, backend preferred) -> bool {
+        return with_display(preferred, [&](ra3::client::display &d) {
+            if (!d.supports_terrain()) return false;
+            return d.run_terrain(options, terrain, camera, minimap);
+        });
+    }
+
+    /**
+     * GPU terrain viewer. Vulkan/D3D only: returns false when the preferred GPU
+     * backend is unavailable so the caller can render offscreen instead.
+     */
+    [[nodiscard]] inline auto run_terrain(const display_options &options, const ra3::terrain::gpu_terrain &terrain, camera3d camera) -> bool {
+        return run_terrain(options, terrain, camera, backend::vulkan);
+    }
+}

src/dx/ra3.dx.null.cppm

@@ -0,0 +1,37 @@
+export module ra3.dx;
+
+import std;
+
+export import ra3.core;
+import ra3.render;
+import ra3.client;
+
+/**
+ * Fallback Direct3D backends used when the build has no Windows/D3D (for
+ * example the Linux development build). `init` fails so the caller can select
+ * another display; the class names match the real `ra3.dx` module so the
+ * backend factory in `ra3.display` compiles unchanged.
+ */
+export namespace ra3::dx {
+    class d3d11_display final : public ra3::client::display {
+    public:
+        [[nodiscard]] auto init(const ra3::client::display_options &) -> bool override { return false; }
+        [[nodiscard]] auto present(const ra3::render::image &, const ra3::render::view_rect &, bool) -> bool override { return false; }
+        [[nodiscard]] auto poll_event(ra3::render::ui_event &) -> bool override { return false; }
+        [[nodiscard]] auto window_size() const -> std::pair<int, int> override { return {0, 0}; }
+        [[nodiscard]] auto key_down(ra3::render::ui_key) const -> bool override { return false; }
+        auto shutdown() -> void override {}
+        [[nodiscard]] auto name() const -> std::string_view override { return "d3d11(null)"; }
+    };
+
+    class d3d12_display final : public ra3::client::display {
+    public:
+        [[nodiscard]] auto init(const ra3::client::display_options &) -> bool override { return false; }
+        [[nodiscard]] auto present(const ra3::render::image &, const ra3::render::view_rect &, bool) -> bool override { return false; }
+        [[nodiscard]] auto poll_event(ra3::render::ui_event &) -> bool override { return false; }
+        [[nodiscard]] auto window_size() const -> std::pair<int, int> override { return {0, 0}; }
+        [[nodiscard]] auto key_down(ra3::render::ui_key) const -> bool override { return false; }
+        auto shutdown() -> void override {}
+        [[nodiscard]] auto name() const -> std::string_view override { return "d3d12(null)"; }
+    };
+}

src/fs/ra3.fs.cppm

@@ -1,31 +1,18 @@
-module;
-
-#include <algorithm>
-#include <array>
-#include <cstddef>
-#include <cstdint>
-#include <cstdlib>
-#include <cstring>
-#include <filesystem>
-#include <fstream>
-#include <optional>
-#include <span>
-#include <stdexcept>
-#include <string>
-#include <string_view>
-#include <unordered_map>
-#include <vector>
-
 export module ra3.fs;
 
+import std;
+
 export import ra3.core;
+import ra3.assets;
 
 /**
  * Reading of the retail game's on-disk assets.
  *
  * Red Alert 3 ships its data in `BIG4` archives under `<install>\Data`, with
- * individual payloads compressed by EA's RefPack codec. This module implements
+ * individual payloads compressed by EA's RefPack codec. The container and codec
- * the container and codec so OpenRA3 can read a user's own installation.
+ * are implemented by the vendored `libra3assets` (`ra3.assets`, a sibling of
+ * `libenderlog`); this module is the thin adapter OpenRA3's loader talks to, so
+ * the format knowledge lives in one place.
  *
  * No game data is ever written into the repository; callers point the loader at
  * their local install (`--game-dir` / `RA3_GAME_DIR`, default `C:\Red Alert 3`).
@@ -58,11 +45,21 @@ export namespace ra3::fs {
         uint32 size = 0;
     };
 
-    /** True when `data` starts with a RefPack header (`0b??010000`, `0xFB`). */
+    namespace detail {
-    [[nodiscard]] inline auto is_refpack(std::span<const uint8> data) -> bool {
+        /** View a `uint8` range as bytes, the currency of `libra3assets`. */
-        return data.size() >= 2 && (data[0] & refpack_mask) == 0x10U && data[1] == refpack_magic2;
+        [[nodiscard]] inline auto as_bytes(std::span<const uint8> data) -> std::span<const std::byte> { return std::as_bytes(data); }
+
+        /** Copy a `libra3assets` byte buffer into OpenRA3's `uint8` vector. */
+        [[nodiscard]] inline auto to_u8(std::vector<std::byte> bytes) -> std::vector<uint8> {
+            std::vector<uint8> out(bytes.size());
+            if (!bytes.empty()) std::memcpy(out.data(), bytes.data(), bytes.size());
+            return out;
+        }
     }
 
+    /** True when `data` starts with a RefPack header (`0b??010000`, `0xFB`). */
+    [[nodiscard]] inline auto is_refpack(std::span<const uint8> data) -> bool { return ra3::assets::is_refpack(detail::as_bytes(data)); }
+
     /**
      * Decompress an EA RefPack stream.
      *
@@ -71,80 +68,17 @@ export namespace ra3::fs {
      * @throws refpack_error if the stream is malformed or the length disagrees.
      */
     [[nodiscard]] inline auto refpack_decompress(std::span<const uint8> data) -> std::vector<uint8> {
-        if (!is_refpack(data)) throw refpack_error("not a RefPack stream");
+        try {
-
+            return detail::to_u8(ra3::assets::refpack_decompress(detail::as_bytes(data)));
-        usize pos = 0;
+        } catch (const ra3::assets::refpack_error &error) {
-        const auto header = data[pos++];
+            throw refpack_error(error.what());
-        const bool large_files = (header & 0x80U) != 0;
-        const bool compressed_size_present = (header & 0x01U) != 0;
-        pos++; // 0xFB
-
-        const usize size_bytes = large_files ? 4U : 3U;
-        auto read_size = [&]() -> uint32 {
-            uint32 value = 0;
-            for (usize i = 0; i < size_bytes; ++i) {
-                if (pos >= data.size()) throw refpack_error("truncated RefPack size field");
-                value = (value << 8) | data[pos++];
-            }
-            return value;
-        };
-
-        if (compressed_size_present) (void)read_size();
-        const auto out_len = read_size();
-
-        std::vector<uint8> out;
-        out.reserve(out_len);
-
-        auto copy_literals = [&](usize count) {
-            if (pos + count > data.size()) throw refpack_error("truncated RefPack literals");
-            out.insert(out.end(), data.begin() + static_cast<std::ptrdiff_t>(pos), data.begin() + static_cast<std::ptrdiff_t>(pos + count));
-            pos += count;
-        };
-
-        auto copy_reference = [&](usize length, usize distance) {
-            if (distance == 0 || distance > out.size()) throw refpack_error("RefPack back-reference out of range");
-            usize start = out.size() - distance;
-            for (usize i = 0; i < length; ++i) out.push_back(out[start + i]);
-        };
-
-        while (pos < data.size()) {
-            const auto cmd = data[pos++];
-            if ((cmd & 0x80U) == 0) { // 2-byte command
-                if (pos >= data.size()) throw refpack_error("truncated 2-byte command");
-                const auto b2 = data[pos++];
-                copy_literals(cmd & 0x03U);
-                copy_reference(((cmd & 0x1CU) >> 2) + 3, ((cmd & 0x60U) << 3) + b2 + 1);
-            } else if ((cmd & 0x40U) == 0) { // 3-byte command
-                if (pos + 1 >= data.size()) throw refpack_error("truncated 3-byte command");
-                const auto b2 = data[pos];
-                const auto b3 = data[pos + 1];
-                pos += 2;
-                copy_literals((b2 & 0xC0U) >> 6);
-                copy_reference((cmd & 0x3FU) + 4, ((b2 & 0x3FU) << 8) + b3 + 1);
-            } else if ((cmd & 0x20U) == 0) { // 4-byte command
-                if (pos + 2 >= data.size()) throw refpack_error("truncated 4-byte command");
-                const auto b2 = data[pos];
-                const auto b3 = data[pos + 1];
-                const auto b4 = data[pos + 2];
-                pos += 3;
-                copy_literals(cmd & 0x03U);
-                copy_reference(((cmd & 0x0CU) << 6) + b4 + 5, ((cmd & 0x10U) << 12) + (b2 << 8) + b3 + 1);
-            } else if (cmd < 0xFCU) { // long literal run
-                copy_literals(((cmd & 0x1FU) + 1) << 2);
-            } else { // stop
-                copy_literals(cmd & 0x03U);
-                break;
-            }
         }
-
-        if (out.size() != out_len) throw refpack_error("RefPack length mismatch");
-        return out;
     }
 
     /** Decompress `data` when it is RefPack, otherwise copy it unchanged. */
     [[nodiscard]] inline auto maybe_decompress(std::span<const uint8> data) -> std::vector<uint8> {
-        if (is_refpack(data)) return refpack_decompress(data);
+        if (!is_refpack(data)) return {data.begin(), data.end()};
-        return {data.begin(), data.end()};
+        return refpack_decompress(data);
     }
 
     /**
@@ -153,23 +87,11 @@ export namespace ra3::fs {
      * @throws refpack_error if the stream is malformed.
      */
     [[nodiscard]] inline auto refpack_output_size(std::span<const uint8> data) -> uint32 {
-        if (!is_refpack(data)) throw refpack_error("not a RefPack stream");
+        try {
-        usize pos = 0;
+            return ra3::assets::refpack_output_size(detail::as_bytes(data));
-        const auto header = data[pos++];
+        } catch (const ra3::assets::refpack_error &error) {
-        const bool large_files = (header & 0x80U) != 0;
+            throw refpack_error(error.what());
-        const bool compressed_size_present = (header & 0x01U) != 0;
+        }
-        pos++; // 0xFB
-        const usize size_bytes = large_files ? 4U : 3U;
-        auto read_size = [&]() -> uint32 {
-            uint32 value = 0;
-            for (usize i = 0; i < size_bytes; ++i) {
-                if (pos >= data.size()) throw refpack_error("truncated RefPack size field");
-                value = (value << 8) | data[pos++];
-            }
-            return value;
-        };
-        if (compressed_size_present) (void)read_size();
-        return read_size();
     }
 
     [[nodiscard]] constexpr auto read_be32(const uint8 *p) -> uint32 {
@@ -181,81 +103,32 @@ export namespace ra3::fs {
     }
 
     /**
-     * A parsed `BIG4` archive. Only the index is held in memory; payloads are
+     * A parsed `BIG4` archive.
-     * read from disk on demand so multi-hundred-megabyte archives stay cheap.
+     *
+     * The index and payloads are held by a `ra3::assets::big_archive`; this
+     * adapter exposes the OpenRA3-facing surface (`big_entry`, `uint8` buffers)
+     * over it. Payloads are RefPack-decompressed on request.
      */
     class big_archive {
     public:
         /**
-         * Parse the index of a `BIG4` archive.
+         * Parse a `BIG4` archive.
          *
          * @param path Archive path.
          * @throws archive_error if the file is missing, not `BIG4`, or truncated.
          */
         [[nodiscard]] static auto open(const std::filesystem::path &path) -> big_archive {
-            big_archive archive;
+            try {
-            archive.path_ = path;
+                return big_archive{ra3::assets::big_archive::open(path), path};
-            std::error_code ec;
+            } catch (const ra3::assets::asset_error &error) {
-            archive.file_size_ = static_cast<usize>(std::filesystem::file_size(path, ec));
+                throw archive_error(error.what());
-            if (ec) throw archive_error("cannot stat archive: " + path.string());
-
-            std::ifstream in(path, std::ios::binary);
-            if (!in) throw archive_error("cannot open archive: " + path.string());
-
-            std::array<uint8, 16> header{};
-            in.read(reinterpret_cast<char *>(header.data()), static_cast<std::streamsize>(header.size()));
-            if (!in || std::memcmp(header.data(), big_magic.data(), big_magic.size()) != 0) throw archive_error("not a BIG4 archive: " + path.string());
-
-            const auto count = read_be32(header.data() + 8);
-
-            // Read the variable-length index, growing the window until parsed.
-            usize window = std::min(archive.file_size_, std::max<usize>(1U << 20U, static_cast<usize>(count) * 256U));
-            std::vector<uint8> index;
-            for (;;) {
-                index.resize(window);
-                in.clear();
-                in.seekg(0);
-                in.read(reinterpret_cast<char *>(index.data()), static_cast<std::streamsize>(window));
-                const auto got = static_cast<usize>(in.gcount());
-                index.resize(got);
-
-                archive.entries_.clear();
-                archive.entries_.reserve(count);
-                usize pos = 16;
-                bool complete = true;
-                for (uint32 i = 0; i < count; ++i) {
-                    if (pos + 8 > index.size()) {
-                        complete = false;
-                        break;
-                    }
-                    big_entry entry;
-                    entry.offset = read_be32(index.data() + pos);
-                    entry.size = read_be32(index.data() + pos + 4);
-                    pos += 8;
-                    const auto *begin = reinterpret_cast<const char *>(index.data() + pos);
-                    const auto *end = reinterpret_cast<const char *>(std::memchr(begin, '\0', index.size() - pos));
-                    if (end == nullptr) {
-                        complete = false;
-                        break;
-                    }
-                    entry.name.assign(begin, end);
-                    pos += static_cast<usize>(end - begin) + 1U;
-                    archive.entries_.push_back(std::move(entry));
-                }
-                if (complete) break;
-                if (window >= archive.file_size_) throw archive_error("truncated BIG4 index: " + path.string());
-                window = std::min(archive.file_size_, window * 2U);
             }
-
-            archive.index_.reserve(archive.entries_.size());
-            for (usize i = 0; i < archive.entries_.size(); ++i) archive.index_.emplace(archive.entries_[i].name, i);
-            return archive;
         }
 
         [[nodiscard]] auto path() const -> const std::filesystem::path & { return path_; }
         [[nodiscard]] auto entries() const -> const std::vector<big_entry> & { return entries_; }
         [[nodiscard]] auto size() const -> usize { return entries_.size(); }
-        [[nodiscard]] auto contains(std::string_view name) const -> bool { return index_.contains(std::string{name}); }
+        [[nodiscard]] auto contains(std::string_view name) const -> bool { return archive_.contains(name); }
 
         /** Entry names whose path contains `needle`, in index order. */
         [[nodiscard]] auto find(std::string_view needle) const -> std::vector<const big_entry *> {
@@ -274,42 +147,33 @@ export namespace ra3::fs {
          * @throws archive_error if the entry is missing or unreadable.
          */
         [[nodiscard]] auto read(std::string_view name, bool decompress = true) const -> std::vector<uint8> {
-            const auto it = index_.find(std::string{name});
+            try {
-            if (it == index_.end()) throw archive_error("no such entry: " + std::string{name});
+                return detail::to_u8(archive_.read(name, decompress));
-            const auto &entry = entries_[it->second];
+            } catch (const ra3::assets::refpack_error &error) {
-
+                throw refpack_error(error.what());
-            std::ifstream in(path_, std::ios::binary);
+            } catch (const ra3::assets::asset_error &error) {
-            if (!in) throw archive_error("cannot open archive: " + path_.string());
+                throw archive_error(error.what());
-            in.seekg(static_cast<std::streamoff>(entry.offset));
+            }
-            std::vector<uint8> raw(entry.size);
-            in.read(reinterpret_cast<char *>(raw.data()), static_cast<std::streamsize>(raw.size()));
-            if (!in) throw archive_error("short read for entry: " + entry.name);
-            return decompress ? maybe_decompress(raw) : raw;
         }
 
         /** Read the first `count` stored bytes of an entry (no decompression). */
         [[nodiscard]] auto read_prefix(std::string_view name, usize count) const -> std::vector<uint8> {
-            const auto it = index_.find(std::string{name});
+            try {
-            if (it == index_.end()) throw archive_error("no such entry: " + std::string{name});
+                return detail::to_u8(archive_.read_prefix(name, count));
-            const auto &entry = entries_[it->second];
+            } catch (const ra3::assets::asset_error &error) {
-
+                throw archive_error(error.what());
-            std::ifstream in(path_, std::ios::binary);
+            }
-            if (!in) throw archive_error("cannot open archive: " + path_.string());
-            in.seekg(static_cast<std::streamoff>(entry.offset));
-            const auto want = std::min(count, static_cast<usize>(entry.size));
-            std::vector<uint8> raw(want);
-            in.read(reinterpret_cast<char *>(raw.data()), static_cast<std::streamsize>(raw.size()));
-            raw.resize(static_cast<usize>(in.gcount()));
-            return raw;
         }
 
     private:
-        big_archive() = default;
+        big_archive(ra3::assets::big_archive archive, std::filesystem::path path) : archive_(std::move(archive)), path_(std::move(path)) {
+            entries_.reserve(archive_.size());
+            for (const auto &entry: archive_.entries()) entries_.push_back({entry.name, entry.offset, entry.size});
+        }
 
+        ra3::assets::big_archive archive_;
         std::filesystem::path path_;
-        usize file_size_ = 0;
         std::vector<big_entry> entries_;
-        std::unordered_map<std::string, usize> index_;
     };
 
     /**
@@ -322,18 +186,6 @@ export namespace ra3::fs {
      * @return The install root, or `std::nullopt` when none is found.
      */
     [[nodiscard]] inline auto find_game_dir(const std::optional<std::filesystem::path> &explicit_dir = std::nullopt) -> std::optional<std::filesystem::path> {
-        auto qualifies = [](const std::filesystem::path &candidate) {
+        return ra3::assets::find_game_dir(explicit_dir);
-            std::error_code ec;
-            return !candidate.empty() && std::filesystem::is_directory(candidate / "Data", ec);
-        };
-
-        if (explicit_dir && qualifies(*explicit_dir)) return explicit_dir;
-        if (const auto *env = std::getenv("RA3_GAME_DIR"); env != nullptr && *env != '\0') {
-            const std::filesystem::path candidate{env};
-            if (qualifies(candidate)) return candidate;
-        }
-        const std::filesystem::path default_dir{"C:/Red Alert 3"};
-        if (qualifies(default_dir)) return default_dir;
-        return std::nullopt;
     }
 }

src/game/ra3.game.cppm

@@ -1,12 +1,7 @@
-module;
-
-#include <cstdint>
-#include <string>
-#include <string_view>
-#include <vector>
-
 export module ra3.game;
 
+import std;
+
 import ra3.core;
 import ra3.logic;
 

src/logic/ra3.logic.cppm

@@ -1,17 +1,7 @@
-module;
-
-#include <cstddef>
-#include <cstdint>
-#include <memory>
-#include <span>
-#include <string>
-#include <string_view>
-#include <unordered_map>
-#include <utility>
-#include <vector>
-
 export module ra3.logic;
 
+import std;
+
 import ra3.core;
 
 /**

src/map/ra3.map.cppm

@@ -1,20 +1,10 @@
-module;
-
-#include <algorithm>
-#include <cmath>
-#include <cstdint>
-#include <cstring>
-#include <optional>
-#include <span>
-#include <string>
-#include <string_view>
-#include <utility>
-#include <vector>
-
 export module ra3.map;
 
+import std;
+
 export import ra3.core;
 export import ra3.fs;
+import ra3.assets;
 
 /**
  * Red Alert 3 map discovery and loading.
@@ -30,8 +20,9 @@ export import ra3.fs;
 export namespace ra3::map {
     using ra3::core::coord3d;
     using ra3::core::real;
-    using ra3::core::uint32;
     using ra3::core::uint8;
+    using ra3::core::uint16;
+    using ra3::core::uint32;
     using ra3::core::usize;
 
     /** A player start location extracted from a map's waypoints. */
@@ -51,14 +42,18 @@ export namespace ra3::map {
         uint32 unpacked_size = 0;
     };
 
-    /** The result of loading a map: its metadata and recovered start positions. */
+    /** The result of loading a map: its metadata, recovered start positions and the raw `CkMp` tree. */
     struct loaded_map {
         map_info info;
         std::vector<start_position> starts;
         usize ckmp_size = 0;
+        std::vector<uint8> bytes; ///< The uncompressed `CkMp` payload (terrain/objects parsed from here).
     };
 
     namespace detail {
+        /** View a `uint8` range as bytes, the currency of `libra3assets`. */
+        [[nodiscard]] inline auto as_bytes(std::span<const uint8> data) -> std::span<const std::byte> { return std::as_bytes(data); }
+
         [[nodiscard]] inline auto split_path(std::string_view path) -> std::vector<std::string> {
             std::vector<std::string> parts;
             usize start = 0;
@@ -91,54 +86,6 @@ export namespace ra3::map {
             return file;
         }
 
-        [[nodiscard]] inline auto find_bytes(std::span<const uint8> haystack, std::string_view needle) -> usize {
-            if (needle.empty()) return 0;
-            const auto *needle_begin = reinterpret_cast<const uint8 *>(needle.data());
-            const auto it = std::search(haystack.begin(), haystack.end(), needle_begin, needle_begin + needle.size());
-            return it == haystack.end() ? static_cast<usize>(-1) : static_cast<usize>(it - haystack.begin());
-        }
-
-        [[nodiscard]] inline auto read_le_f32(const uint8 *p) -> real {
-            const auto bits = fs::read_le32(p);
-            real value = 0.0F;
-            std::memcpy(&value, &bits, sizeof(value));
-            return value;
-        }
-
-        /** First plausible `(x, y, 0)` float triple at or after `from`. */
-        [[nodiscard]] inline auto scan_triple(std::span<const uint8> data, usize from, usize window) -> std::optional<start_position> {
-            const auto end = std::min(data.size(), from + window);
-            for (usize p = from; p + 12U <= end; ++p) {
-                const auto x = read_le_f32(data.data() + p);
-                const auto y = read_le_f32(data.data() + p + 4U);
-                const auto z = read_le_f32(data.data() + p + 8U);
-                if (z == 0.0F && std::isfinite(x) && std::isfinite(y) && x > 0.0F && x < 20000.0F && y > 0.0F && y < 20000.0F) {
-                    return start_position{x, y, z};
-                }
-            }
-            return std::nullopt;
-        }
-
-        /** Extract `Player_1_Start` .. `Player_N_Start` waypoint coordinates. */
-        [[nodiscard]] inline auto extract_start_positions(std::span<const uint8> ckmp, int max_players = 8) -> std::vector<start_position> {
-            std::vector<start_position> result;
-            for (int n = 1; n <= max_players; ++n) {
-                const auto needle = std::string{"Player_"} + std::to_string(n) + "_Start";
-                usize cursor = 0;
-                while (cursor < ckmp.size()) {
-                    const auto at = find_bytes(ckmp.subspan(cursor), needle);
-                    if (at == static_cast<usize>(-1)) break;
-                    const auto abs = cursor + at;
-                    if (const auto triple = scan_triple(ckmp, abs + needle.size(), 128); triple) {
-                        result.push_back(*triple);
-                        break;
-                    }
-                    cursor = abs + 1;
-                }
-            }
-            return result;
-        }
-
         /** Number of distinct integer positions (used to reject degenerate sets). */
         [[nodiscard]] inline auto distinct_positions(const std::vector<start_position> &starts) -> usize {
             std::vector<std::pair<int, int>> seen;
@@ -192,6 +139,218 @@ export namespace ra3::map {
         std::vector<map_info> maps_;
     };
 
+    /**
+     * Normalise a loose `.map` payload to bare `CkMp` bytes.
+     *
+     * Accepts either the raw `.big` payload (the `EAR\0` wrapper around a
+     * RefPack stream, as `ra3tools` extracts it), a bare RefPack stream, or an
+     * already-unwrapped `CkMp` tree (as our own `extract` writes).
+     */
+    [[nodiscard]] inline auto to_ckmp(std::span<const uint8> raw) -> std::vector<uint8> {
+        std::span<const uint8> payload = raw;
+        if (raw.size() >= 8U && std::memcmp(raw.data(), "EAR\0", 4) == 0) payload = raw.subspan(8);
+        return fs::maybe_decompress(payload);
+    }
+
+    /**
+     * Recover `Player_N_Start` waypoints from raw, uncompressed `CkMp` bytes.
+     *
+     * `libra3assets` decodes the `ObjectsList` `*Waypoints/Waypoint` objects and
+     * returns the position of each `waypointName == "Player_<n>_Start"`. This
+     * replaces the previous whole-buffer heuristic, which scanned for the string
+     * and then took the first plausible float triple *after* it — off by one
+     * (the position precedes the name in each object) and prone to matching
+     * arbitrary bytes.
+     */
+    [[nodiscard]] inline auto starts_from_ckmp(std::span<const uint8> ckmp) -> std::vector<start_position> {
+        std::vector<start_position> starts;
+        try {
+            const auto document = ra3::assets::map_document::parse(detail::as_bytes(ckmp));
+            for (const auto &start: document.player_starts()) starts.push_back({start.position.x, start.position.y, start.position.z});
+        } catch (const std::exception &) {
+            return {};
+        }
+        if (detail::distinct_positions(starts) < 2U) starts.clear();
+        return starts;
+    }
+
+    /**
+     * One object the map places on the ground: a building, a prop, a lamp, a
+     * tree — anything in the `ObjectsList` chunk.
+     *
+     * `type` is the SAGE `ThingTemplate` name (e.g. `BB_GRASS02`,
+     * `AlliedBarracks`); the per-map compiled art stream resolves it to the
+     * `W3DMesh` assets that draw it. `angle` is the Z rotation in radians.
+     */
+    struct map_object {
+        std::string type;
+        real x = 0.0F;
+        real y = 0.0F;
+        real z = 0.0F;
+        real angle = 0.0F;
+        real scale = 1.0F;
+        uint32 road_type = 0U; ///< SAGE `RoadType` flags; 0 for a non-road object.
+    };
+
+    /**
+     * Every object the map places (the `ObjectsList` chunk).
+     *
+     * Decoded by `libra3assets` (`ra3.assets`): the map is parsed as a
+     * `map_document`, whose `ObjectsList` accessor walks the nested `Object`
+     * assets (a `Coord3D`, a Z `angle`, a `RoadType`, a `u16`-prefixed
+     * type-name and a property list keyed into the shared name table).
+     *
+     * @return The objects in chunk order; empty when the map is malformed or has
+     *         no object list.
+     */
+    [[nodiscard]] inline auto parse_objects(std::span<const uint8> ckmp) -> std::vector<map_object> {
+        std::vector<map_object> objects;
+        try {
+            const auto document = ra3::assets::map_document::parse(detail::as_bytes(ckmp));
+            for (const auto &object: document.objects()) {
+                map_object out;
+                out.type = object.type_name;
+                out.x = object.position.x;
+                out.y = object.position.y;
+                out.z = object.position.z;
+                out.angle = object.angle;
+                out.scale = 1.0F;
+                out.road_type = static_cast<uint32>(object.road);
+                objects.push_back(std::move(out));
+            }
+        } catch (const std::exception &) {
+            return {};
+        }
+        return objects;
+    }
+
+    /** Map id -> localized display name, keyed by lowercased id. */
+    struct map_name_table {
+        std::unordered_map<std::string, std::string> names;
+
+        [[nodiscard]] auto empty() const -> bool { return names.empty(); }
+
+        /** The display name for `id`, or `id` itself when the string table has none. */
+        [[nodiscard]] auto lookup(std::string_view id) const -> std::string {
+            auto key = std::string{id};
+            std::transform(key.begin(), key.end(), key.begin(), [](unsigned char ch) { return static_cast<char>(std::tolower(ch)); });
+            if (const auto it = names.find(key); it != names.end() && !it->second.empty()) return it->second;
+            return std::string{id};
+        }
+    };
+
+    /**
+     * Parse `MAP:<id>` display names out of a SAGE `.csf` string table.
+     *
+     * The map list UI reads its labels from the install's `data\gamestrings.csf`
+     * under the key `MAP:<UPPERCASE_ID>` (e.g. `MAP:MAP_MP_2_FEASEL4` is
+     * "Battlebase Beta"). Decoding is `libra3assets`' `csf_table` (each UTF-16
+     * code unit is bit-inverted; the table lookup is case-insensitive).
+     */
+    [[nodiscard]] inline auto parse_map_names(std::span<const uint8> csf) -> map_name_table {
+        map_name_table table;
+        try {
+            const auto strings = ra3::assets::csf_table::parse(detail::as_bytes(csf));
+            for (const auto &entry: strings.entries()) {
+                constexpr std::string_view prefix = "MAP:";
+                if (entry.label.size() <= prefix.size() || entry.label.compare(0, prefix.size(), prefix) != 0) continue;
+                auto id = entry.label.substr(prefix.size());
+                std::transform(id.begin(), id.end(), id.begin(), [](unsigned char ch) { return static_cast<char>(std::tolower(ch)); });
+                auto value = ra3::assets::utf16_to_utf8(entry.value());
+                // CSF strings are NUL-terminated; the terminator is not part of the text.
+                if (const auto nul = value.find('\0'); nul != std::string::npos) value.resize(nul);
+                if (!value.empty()) table.names.try_emplace(std::move(id), std::move(value));
+            }
+        } catch (const std::exception &) {
+            return {};
+        }
+        return table;
+    }
+
+    /** Load display names from the install's newest English string table. */
+    [[nodiscard]] inline auto load_map_names_from_data_dir(const std::filesystem::path &data_dir) -> map_name_table {
+        std::error_code ec;
+        std::filesystem::path chosen;
+        int best_version = -1;
+        for (const auto &entry: std::filesystem::directory_iterator(data_dir, ec)) {
+            if (!entry.is_regular_file()) continue;
+            const auto name = entry.path().filename().string();
+            if (name.rfind("Lang-English", 0) != 0 || !name.ends_with(".big")) continue;
+            const auto mid = name.substr(12, name.size() - 16U);
+            int version = 0;
+            try {
+                version = std::stoi(mid);
+            } catch (const std::exception &) {
+                continue;
+            }
+            if (version > best_version) {
+                best_version = version;
+                chosen = entry.path();
+            }
+        }
+        if (chosen.empty()) chosen = data_dir / "English.big";
+        if (!std::filesystem::exists(chosen, ec)) return {};
+        try {
+            const auto archive = fs::big_archive::open(chosen);
+            const auto matches = archive.find("gamestrings.csf");
+            if (matches.empty()) return {};
+            return parse_map_names(archive.read(matches.front()->name, true));
+        } catch (const std::exception &) {
+            return {};
+        }
+    }
+
+    /** Read `<assets>/maps/map_names.tsv`, or any `gamestrings.csf` under `assets`. */
+    [[nodiscard]] inline auto load_map_names(const std::filesystem::path &assets) -> map_name_table {
+        const auto read_file = [](const std::filesystem::path &path) {
+            std::ifstream in(path, std::ios::binary);
+            return std::vector<uint8>{std::istreambuf_iterator<char>(in), std::istreambuf_iterator<char>()};
+        };
+
+        std::error_code ec;
+        const auto tsv = assets / "maps" / "map_names.tsv";
+        if (std::filesystem::exists(tsv, ec)) {
+            const auto bytes = read_file(tsv);
+            map_name_table table;
+            std::string text{bytes.begin(), bytes.end()};
+            for (std::size_t start = 0; start < text.size();) {
+                const auto end = text.find('\n', start);
+                const auto line = text.substr(start, end == std::string::npos ? std::string::npos : end - start);
+                start = end == std::string::npos ? text.size() : end + 1U;
+                const auto tab = line.find('\t');
+                if (tab == std::string::npos || tab == 0U) continue;
+                auto id = line.substr(0, tab);
+                std::transform(id.begin(), id.end(), id.begin(), [](unsigned char ch) { return static_cast<char>(std::tolower(ch)); });
+                table.names.try_emplace(std::move(id), line.substr(tab + 1U));
+            }
+            if (!table.empty()) return table;
+        }
+        for (const auto &entry: std::filesystem::recursive_directory_iterator(assets, ec)) {
+            if (!entry.is_regular_file() || entry.path().filename() != "gamestrings.csf") continue;
+            return parse_map_names(read_file(entry.path()));
+        }
+        return {};
+    }
+
+    /** Serialize a name table as `id<TAB>name` lines (tabs/newlines stripped). */
+    [[nodiscard]] inline auto serialize_map_names(const map_name_table &table) -> std::string {
+        std::vector<std::string> ids;
+        ids.reserve(table.names.size());
+        for (const auto &[id, _]: table.names) ids.push_back(id);
+        std::sort(ids.begin(), ids.end());
+        std::string out;
+        for (const auto &id: ids) {
+            auto name = table.names.at(id);
+            std::replace(name.begin(), name.end(), '\t', ' ');
+            std::replace(name.begin(), name.end(), '\n', ' ');
+            out += id;
+            out += '\t';
+            out += name;
+            out += '\n';
+        }
+        return out;
+    }
+
     /**
      * Load a map: unwrap the `EAR\0` + RefPack container and recover the
      * player start waypoints.
@@ -212,7 +371,8 @@ export namespace ra3::map {
         // Layer 2: the wrapper body is RefPack again, yielding the `CkMp` tree.
         auto ckmp = fs::maybe_decompress(payload);
         result.ckmp_size = ckmp.size();
-        result.starts = detail::extract_start_positions(ckmp);
+        result.starts = starts_from_ckmp(ckmp);
+        result.bytes = std::move(ckmp);
         // Maps that keep starts in `MPPositionList` instead of `Player_N_Start`
         // waypoints yield fewer than two distinct points; signal "unknown" so
         // the caller can fall back rather than spawn everyone at the origin.

src/ra3.cppm

@@ -9,9 +9,17 @@ export module ra3;
 export import ra3.core;
 export import ra3.logic;
 export import ra3.client;
+export import ra3.data;
 export import ra3.game;
 export import ra3.fs;
 export import ra3.map;
 export import ra3.skirmish;
 export import ra3.render;
+export import ra3.terrain;
+export import ra3.models;
 export import ra3.ui;
+export import ra3.vulkan;
+export import ra3.dx;
+export import ra3.wasmgl;
+export import ra3.webgpu;
+export import ra3.display;

src/render/ra3.render.cppm

@@ -1,18 +1,7 @@
-module;
-
-#include <algorithm>
-#include <cmath>
-#include <cstddef>
-#include <cstdint>
-#include <cstring>
-#include <span>
-#include <stdexcept>
-#include <string>
-#include <utility>
-#include <vector>
-
 export module ra3.render;
 
+import std;
+
 export import ra3.core;
 
 /**
@@ -134,6 +123,274 @@ export namespace ra3::render {
         std::vector<uint32> pixels_;
     };
 
+    namespace detail {
+        // 8x12 bitmap font for ASCII 32..126 (baseline at row 9 so descenders fit);
+        // each row byte has bit 7 as the leftmost column, top row first.
+        inline constexpr std::array<std::array<uint8, 12>, 95> font8x8 = {{
+            {0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}, // ' '
+            {0x00,0x40,0x40,0x40,0x40,0x40,0x00,0x00,0x40,0x00,0x00,0x00}, // '!'
+            {0x00,0x6C,0x48,0x48,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}, // '"'
+            {0x00,0x14,0x14,0x28,0x7C,0x28,0x7C,0x28,0x50,0x50,0x00,0x00}, // '#'
+            {0x00,0x10,0x38,0x40,0x40,0x38,0x48,0x70,0x10,0x10,0x00,0x00}, // '$'
+            {0x00,0x20,0x50,0x20,0x0C,0x70,0x08,0x14,0x08,0x00,0x00,0x00}, // '%'
+            {0x00,0x00,0x00,0x18,0x20,0x20,0x54,0x48,0x34,0x00,0x00,0x00}, // '&'
+            {0x00,0x40,0x40,0x40,0x40,0x00,0x00,0x00,0x00,0x00,0x00,0x00}, // "'"
+            {0x00,0x20,0x20,0x40,0x40,0x40,0x40,0x40,0x40,0x20,0x20,0x00}, // '('
+            {0x00,0x40,0x40,0x20,0x20,0x20,0x20,0x20,0x20,0x40,0x40,0x00}, // ')'
+            {0x00,0x10,0x7C,0x10,0x28,0x08,0x00,0x00,0x00,0x00,0x00,0x00}, // '*'
+            {0x00,0x00,0x08,0x08,0x08,0x7F,0x08,0x08,0x08,0x00,0x00,0x00}, // '+'
+            {0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x30,0x20,0x60,0x40,0x00}, // ','
+            {0x00,0x00,0x00,0x00,0x00,0x7C,0x00,0x00,0x00,0x00,0x00,0x00}, // '-'
+            {0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x60,0x60,0x00,0x00,0x00}, // '.'
+            {0x00,0x04,0x04,0x08,0x08,0x10,0x10,0x20,0x20,0x40,0x00,0x00}, // '/'
+            {0x00,0x38,0x44,0x44,0x44,0x44,0x44,0x44,0x38,0x00,0x00,0x00}, // '0'
+            {0x00,0x30,0x10,0x10,0x10,0x10,0x10,0x10,0x7C,0x00,0x00,0x00}, // '1'
+            {0x00,0x38,0x44,0x04,0x08,0x10,0x20,0x44,0x7C,0x00,0x00,0x00}, // '2'
+            {0x00,0x38,0x44,0x04,0x18,0x04,0x04,0x44,0x38,0x00,0x00,0x00}, // '3'
+            {0x00,0x0C,0x14,0x14,0x24,0x44,0x7E,0x04,0x0E,0x00,0x00,0x00}, // '4'
+            {0x00,0x3C,0x20,0x20,0x38,0x04,0x04,0x44,0x38,0x00,0x00,0x00}, // '5'
+            {0x00,0x1C,0x20,0x40,0x78,0x44,0x44,0x44,0x38,0x00,0x00,0x00}, // '6'
+            {0x00,0x7C,0x44,0x04,0x08,0x08,0x08,0x10,0x10,0x00,0x00,0x00}, // '7'
+            {0x00,0x38,0x44,0x44,0x38,0x44,0x44,0x44,0x38,0x00,0x00,0x00}, // '8'
+            {0x00,0x38,0x44,0x44,0x44,0x3C,0x04,0x08,0x70,0x00,0x00,0x00}, // '9'
+            {0x00,0x00,0x00,0x60,0x60,0x00,0x00,0x60,0x60,0x00,0x00,0x00}, // ':'
+            {0x00,0x00,0x00,0x30,0x30,0x00,0x00,0x30,0x60,0x40,0x00,0x00}, // ';'
+            {0x00,0x06,0x08,0x30,0x40,0x30,0x08,0x06,0x00,0x00,0x00,0x00}, // '<'
+            {0x00,0x00,0x00,0x00,0x7C,0x00,0x7C,0x00,0x00,0x00,0x00,0x00}, // '='
+            {0x00,0x60,0x10,0x0C,0x02,0x0C,0x10,0x60,0x00,0x00,0x00,0x00}, // '>'
+            {0x00,0x00,0x38,0x44,0x04,0x08,0x10,0x00,0x30,0x00,0x00,0x00}, // '?'
+            {0x38,0x44,0x44,0x4C,0x54,0x54,0x4C,0x40,0x44,0x38,0x00,0x00}, // '@'
+            {0x00,0x18,0x08,0x14,0x14,0x14,0x3E,0x22,0x77,0x00,0x00,0x00}, // 'A'
+            {0x00,0x7C,0x22,0x22,0x3C,0x22,0x22,0x22,0x7C,0x00,0x00,0x00}, // 'B'
+            {0x00,0x3C,0x44,0x40,0x40,0x40,0x40,0x44,0x38,0x00,0x00,0x00}, // 'C'
+            {0x00,0x78,0x24,0x22,0x22,0x22,0x22,0x24,0x78,0x00,0x00,0x00}, // 'D'
+            {0x00,0x7E,0x22,0x28,0x38,0x28,0x20,0x22,0x7E,0x00,0x00,0x00}, // 'E'
+            {0x00,0x7E,0x22,0x28,0x38,0x28,0x20,0x20,0x70,0x00,0x00,0x00}, // 'F'
+            {0x00,0x3C,0x44,0x40,0x40,0x4E,0x44,0x44,0x38,0x00,0x00,0x00}, // 'G'
+            {0x00,0x77,0x22,0x22,0x3E,0x22,0x22,0x22,0x77,0x00,0x00,0x00}, // 'H'
+            {0x00,0x7C,0x10,0x10,0x10,0x10,0x10,0x10,0x7C,0x00,0x00,0x00}, // 'I'
+            {0x00,0x3C,0x08,0x08,0x08,0x48,0x48,0x48,0x30,0x00,0x00,0x00}, // 'J'
+            {0x00,0x77,0x22,0x24,0x28,0x38,0x24,0x22,0x73,0x00,0x00,0x00}, // 'K'
+            {0x00,0x70,0x20,0x20,0x20,0x20,0x24,0x24,0x7C,0x00,0x00,0x00}, // 'L'
+            {0x00,0x77,0x36,0x36,0x2A,0x2A,0x22,0x22,0x77,0x00,0x00,0x00}, // 'M'
+            {0x00,0x77,0x32,0x32,0x2A,0x2A,0x2A,0x26,0x76,0x00,0x00,0x00}, // 'N'
+            {0x00,0x38,0x44,0x44,0x44,0x44,0x44,0x44,0x38,0x00,0x00,0x00}, // 'O'
+            {0x00,0x78,0x24,0x24,0x24,0x38,0x20,0x20,0x70,0x00,0x00,0x00}, // 'P'
+            {0x00,0x38,0x44,0x44,0x44,0x44,0x44,0x44,0x38,0x1C,0x00,0x00}, // 'Q'
+            {0x00,0x7C,0x22,0x22,0x22,0x3C,0x24,0x22,0x71,0x00,0x00,0x00}, // 'R'
+            {0x00,0x34,0x4C,0x40,0x38,0x04,0x04,0x64,0x58,0x00,0x00,0x00}, // 'S'
+            {0x00,0x7F,0x49,0x08,0x08,0x08,0x08,0x08,0x1C,0x00,0x00,0x00}, // 'T'
+            {0x00,0x77,0x22,0x22,0x22,0x22,0x22,0x22,0x1C,0x00,0x00,0x00}, // 'U'
+            {0x00,0x77,0x22,0x22,0x14,0x14,0x14,0x08,0x08,0x00,0x00,0x00}, // 'V'
+            {0x00,0x77,0x22,0x22,0x2A,0x2A,0x2A,0x2A,0x14,0x00,0x00,0x00}, // 'W'
+            {0x00,0x63,0x22,0x14,0x08,0x08,0x14,0x22,0x63,0x00,0x00,0x00}, // 'X'
+            {0x00,0x77,0x22,0x14,0x14,0x08,0x08,0x08,0x1C,0x00,0x00,0x00}, // 'Y'
+            {0x00,0x7C,0x44,0x08,0x10,0x10,0x20,0x44,0x7C,0x00,0x00,0x00}, // 'Z'
+            {0x00,0x70,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x70,0x00}, // '['
+            {0x00,0x00,0x40,0x40,0x40,0x20,0x20,0x10,0x10,0x00,0x00,0x00}, // '\\'
+            {0x00,0x70,0x10,0x10,0x10,0x10,0x10,0x10,0x10,0x10,0x70,0x00}, // ']'
+            {0x00,0x10,0x10,0x28,0x44,0x00,0x00,0x00,0x00,0x00,0x00,0x00}, // '^'
+            {0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x7F}, // '_'
+            {0x00,0x40,0x20,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}, // '`'
+            {0x00,0x00,0x00,0x38,0x04,0x3C,0x44,0x44,0x3E,0x00,0x00,0x00}, // 'a'
+            {0x00,0x60,0x20,0x2C,0x32,0x22,0x22,0x22,0x7C,0x00,0x00,0x00}, // 'b'
+            {0x00,0x00,0x00,0x3C,0x44,0x40,0x40,0x44,0x38,0x00,0x00,0x00}, // 'c'
+            {0x00,0x0C,0x04,0x34,0x4C,0x44,0x44,0x44,0x3E,0x00,0x00,0x00}, // 'd'
+            {0x00,0x00,0x00,0x38,0x44,0x7C,0x40,0x40,0x3C,0x00,0x00,0x00}, // 'e'
+            {0x00,0x1C,0x20,0x7C,0x20,0x20,0x20,0x20,0x7C,0x00,0x00,0x00}, // 'f'
+            {0x00,0x00,0x00,0x36,0x4C,0x44,0x44,0x44,0x3C,0x04,0x38,0x00}, // 'g'
+            {0x00,0x60,0x20,0x2C,0x32,0x22,0x22,0x22,0x77,0x00,0x00,0x00}, // 'h'
+            {0x00,0x10,0x00,0x70,0x10,0x10,0x10,0x10,0x7C,0x00,0x00,0x00}, // 'i'
+            {0x00,0x10,0x00,0x78,0x08,0x08,0x08,0x08,0x08,0x08,0x70,0x00}, // 'j'
+            {0x00,0x60,0x20,0x2E,0x24,0x38,0x28,0x24,0x6E,0x00,0x00,0x00}, // 'k'
+            {0x00,0x30,0x10,0x10,0x10,0x10,0x10,0x10,0x7C,0x00,0x00,0x00}, // 'l'
+            {0x00,0x00,0x00,0x74,0x2A,0x2A,0x2A,0x2A,0x7F,0x00,0x00,0x00}, // 'm'
+            {0x00,0x00,0x00,0x6C,0x32,0x22,0x22,0x22,0x77,0x00,0x00,0x00}, // 'n'
+            {0x00,0x00,0x00,0x38,0x44,0x44,0x44,0x44,0x38,0x00,0x00,0x00}, // 'o'
+            {0x00,0x00,0x00,0x6C,0x32,0x22,0x22,0x22,0x3C,0x20,0x70,0x00}, // 'p'
+            {0x00,0x00,0x00,0x36,0x4C,0x44,0x44,0x44,0x3C,0x04,0x0E,0x00}, // 'q'
+            {0x00,0x00,0x00,0x6C,0x30,0x20,0x20,0x20,0x7C,0x00,0x00,0x00}, // 'r'
+            {0x00,0x00,0x00,0x3C,0x44,0x38,0x04,0x44,0x78,0x00,0x00,0x00}, // 's'
+            {0x00,0x00,0x20,0x7C,0x20,0x20,0x20,0x22,0x1C,0x00,0x00,0x00}, // 't'
+            {0x00,0x00,0x00,0x66,0x22,0x22,0x22,0x26,0x1B,0x00,0x00,0x00}, // 'u'
+            {0x00,0x00,0x00,0x77,0x22,0x22,0x14,0x14,0x08,0x00,0x00,0x00}, // 'v'
+            {0x00,0x00,0x00,0x77,0x22,0x2A,0x2A,0x2A,0x14,0x00,0x00,0x00}, // 'w'
+            {0x00,0x00,0x00,0x66,0x24,0x18,0x18,0x24,0x66,0x00,0x00,0x00}, // 'x'
+            {0x00,0x00,0x00,0x77,0x22,0x12,0x14,0x0C,0x08,0x08,0x3C,0x00}, // 'y'
+            {0x00,0x00,0x00,0x7C,0x48,0x10,0x20,0x44,0x7C,0x00,0x00,0x00}, // 'z'
+            {0x00,0x10,0x20,0x20,0x20,0x20,0x40,0x20,0x20,0x20,0x10,0x00}, // '{'
+            {0x00,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x40,0x00,0x00}, // '|'
+            {0x00,0x40,0x20,0x20,0x20,0x20,0x10,0x20,0x20,0x20,0x40,0x00}, // '}'
+            {0x00,0x00,0x00,0x00,0x00,0x24,0x58,0x00,0x00,0x00,0x00,0x00}, // '~'
+        }};
+
+        inline constexpr uint32 glyph_width = 8;
+        inline constexpr uint32 glyph_height = 12;
+    }
+
+    /** Pixel width of `text` drawn at `scale`. */
+    [[nodiscard]] inline auto text_width(std::string_view text, uint32 scale = 1U) -> uint32 {
+        return static_cast<uint32>(text.size()) * detail::glyph_width * std::max(1U, scale);
+    }
+
+    /** Draw `text` with its top-left at `(x, y)`, glyphs scaled by `scale`. */
+    inline auto draw_text(image &target, int x, int y, std::string_view text, uint32 color, uint32 scale = 1U) -> void {
+        scale = std::max(1U, scale);
+        int cursor = x;
+        for (const auto ch: text) {
+            const auto code = static_cast<unsigned char>(ch);
+            if (code >= 32U && code < 127U) {
+                const auto &glyph = detail::font8x8[code - 32U];
+                for (uint32 gy = 0; gy < detail::glyph_height; ++gy) {
+                    const auto bits = glyph[gy];
+                    if (bits == 0U) continue;
+                    for (uint32 gx = 0; gx < detail::glyph_width; ++gx) {
+                        if ((bits & (1U << (7U - gx))) == 0U) continue;
+                        for (uint32 sy = 0; sy < scale; ++sy) {
+                            for (uint32 sx = 0; sx < scale; ++sx) {
+                                target.set(cursor + static_cast<int>(gx * scale + sx), y + static_cast<int>(gy * scale + sy), color);
+                            }
+                        }
+                    }
+                }
+            }
+            cursor += static_cast<int>(detail::glyph_width * scale);
+        }
+    }
+
+    /**
+     * Backend-agnostic input for the interactive loops. The windowing backends
+     * (`ra3.vulkan` / `ra3.ui`) translate their native events into this and hand
+     * it to the shared `ra3::client::display` loops.
+     */
+    enum class ui_key : uint8 { none, up, down, left, right, page_up, page_down, confirm, cancel, tab, backspace };
+
+    enum class ui_event_type : uint8 { none, quit, key, text, mouse_move, mouse_button, wheel };
+
+    struct ui_event {
+        ui_event_type type = ui_event_type::none;
+        ui_key key = ui_key::none;
+        char character = '\0';
+        float x = 0.0F;
+        float y = 0.0F;
+        float dx = 0.0F;
+        float dy = 0.0F;
+        float wheel = 0.0F;
+        bool left = false;
+        bool middle = false;
+        bool right = false;
+        bool released = false; ///< mouse_button: true for a button-up event.
+    };
+
+    /** A warm red/gold loading screen with a progress bar (0..1). */
+    [[nodiscard]] inline auto compose_progress(uint32 width, uint32 height, float progress, std::string_view label) -> image {
+        const auto background = argb(34, 9, 8);
+        const auto panel = argb(58, 14, 12);
+        const auto edge = argb(120, 30, 22);
+        const auto gold = argb(236, 190, 80);
+        const auto cream = argb(246, 228, 192);
+        image img(width, height, background);
+        const auto k = static_cast<double>(height) / 720.0;
+        const auto S = [k](double v) { return static_cast<int>(std::lround(v * k)); };
+        const auto scale = static_cast<uint32>(std::max(1, static_cast<int>(std::lround(2.0 * k))));
+        const auto t = std::clamp(progress, 0.0F, 1.0F);
+
+        const auto title = std::string_view{"OpenRA3"};
+        draw_text(img, (static_cast<int>(width) - static_cast<int>(text_width(title, scale + 1U))) / 2, S(250), title, gold, scale + 1U);
+        draw_text(img, (static_cast<int>(width) - static_cast<int>(text_width(label, scale))) / 2, S(300), label, cream, scale);
+
+        const int bar_x = S(240);
+        const int bar_y = S(360);
+        const int bar_w = static_cast<int>(width) - 2 * bar_x;
+        const int bar_h = S(28);
+        img.draw_rect(bar_x - S(3), bar_y - S(3), bar_w + S(6), bar_h + S(6), edge);
+        img.draw_rect(bar_x, bar_y, bar_w, bar_h, panel);
+        img.draw_rect(bar_x, bar_y, static_cast<int>(static_cast<float>(bar_w) * t), bar_h, gold);
+
+        char percent[32];
+        std::snprintf(percent, sizeof(percent), "%d%%", static_cast<int>(t * 100.0F + 0.5F));
+        draw_text(img, (static_cast<int>(width) - static_cast<int>(text_width(percent, scale))) / 2, bar_y + bar_h + S(18), percent, cream, scale);
+        return img;
+    }
+
+    /**
+     * A small translucent label for the top-left corner, e.g.
+     * `FPS: 155/160 [vulkan]`. `cap == 0` means vertical sync, `cap < 0` means
+     * uncapped. `backend` is the active renderer backend name (empty omits it).
+     */
+    [[nodiscard]] inline auto compose_fps_label(uint32 fps, int cap, std::string_view backend = {}) -> image {
+        char text[64];
+        if (cap == 0) {
+            std::snprintf(text, sizeof(text), "FPS: %u/vsync", fps);
+        } else if (cap < 0) {
+            std::snprintf(text, sizeof(text), "FPS: %u", fps);
+        } else {
+            std::snprintf(text, sizeof(text), "FPS: %u/%d", fps, cap);
+        }
+        std::string label{text};
+        if (!backend.empty()) {
+            label += " [";
+            label += backend;
+            label += ']';
+        }
+        const auto w = text_width(label, 1U) + 8U;
+        const auto h = detail::glyph_height + 6U;
+        image img(w, h, argb(30, 6, 6, 200)); // warm translucent backing
+        draw_text(img, 4, 3, label, argb(240, 200, 90), 1U);
+        return img;
+    }
+
+    /**
+     * Box-downsample `source` so its width is at most `max_width` (aspect
+     * preserved). Returns a copy when it is already small enough.
+     */
+    [[nodiscard]] inline auto downscale(const image &source, uint32 max_width) -> image {
+        if (source.empty() || source.width() <= max_width) return source;
+        const auto scale = static_cast<uint32>(std::ceil(static_cast<double>(source.width()) / static_cast<double>(max_width)));
+        const auto w = std::max(1U, source.width() / scale);
+        const auto h = std::max(1U, source.height() / scale);
+        image out(w, h);
+        for (uint32 y = 0; y < h; ++y) {
+            for (uint32 x = 0; x < w; ++x) {
+                uint32 r = 0;
+                uint32 g = 0;
+                uint32 b = 0;
+                uint32 n = 0;
+                for (uint32 dy = 0; dy < scale; ++dy) {
+                    for (uint32 dx = 0; dx < scale; ++dx) {
+                        const auto sx = std::min(source.width() - 1U, x * scale + dx);
+                        const auto sy = std::min(source.height() - 1U, y * scale + dy);
+                        const auto px = source.data()[static_cast<usize>(sy) * source.width() + sx];
+                        r += (px >> 16U) & 0xFFU;
+                        g += (px >> 8U) & 0xFFU;
+                        b += px & 0xFFU;
+                        ++n;
+                    }
+                }
+                out.set(static_cast<int>(x), static_cast<int>(y), argb(static_cast<uint8>(r / n), static_cast<uint8>(g / n), static_cast<uint8>(b / n)));
+            }
+        }
+        return out;
+    }
+
+    /**
+     * Copy `full` (a whole-map overview) and mark the camera's location with a
+     * gold rectangle. `u`/`v` are the normalized map position (v is y-down).
+     */
+    [[nodiscard]] inline auto compose_minimap(const image &full, float u, float v) -> image {
+        image out = full;
+        if (full.empty()) return out;
+        const int r = std::max(4, static_cast<int>(full.width()) / 48);
+        const int x = std::clamp(static_cast<int>(u * static_cast<float>(full.width())), r, static_cast<int>(full.width()) - r - 1);
+        const int y = std::clamp(static_cast<int>(v * static_cast<float>(full.height())), r, static_cast<int>(full.height()) - r - 1);
+        const auto gold = argb(240, 200, 90);
+        out.draw_rect(x - r, y - r, 2 * r, 2, gold);
+        out.draw_rect(x - r, y + r - 2, 2 * r, 2, gold);
+        out.draw_rect(x - r, y - r, 2, 2 * r, gold);
+        out.draw_rect(x + r - 2, y - r, 2, 2 * r, gold);
+        return out;
+    }
+
     [[nodiscard]] inline auto read_u16(std::span<const uint8> data, usize at) -> uint32 {
         return static_cast<uint32>(data[at]) | (static_cast<uint32>(data[at + 1U]) << 8U);
     }
@@ -223,7 +480,7 @@ export namespace ra3::render {
             out[at + 2U] = static_cast<uint8>(value >> 16U);
             out[at + 3U] = static_cast<uint8>(value >> 24U);
         };
-        auto put16 = [&out](usize at, uint16_t value) {
+        auto put16 = [&out](usize at, std::uint16_t value) {
             out[at] = static_cast<uint8>(value);
             out[at + 1U] = static_cast<uint8>(value >> 8U);
         };
@@ -308,4 +565,129 @@ export namespace ra3::render {
         }
         return scene;
     }
+
+    /**
+     * The destination of the map image on screen, in window coordinates.
+     *
+     * `x`/`y` is the top-left corner and `w`/`h` the size, in the same units as
+     * the window. The viewer draws `image * w` into this rectangle; whatever is
+     * left of the window stays background, so the map is letterboxed instead of
+     * stretched.
+     */
+    struct view_rect {
+        float x = 0.0F;
+        float y = 0.0F;
+        float w = 0.0F;
+        float h = 0.0F;
+    };
+
+    /** Letterbox an `iw`x`ih` image into a `ww`x`wh` window, preserving aspect. */
+    [[nodiscard]] inline auto fit_rect(float iw, float ih, float ww, float wh) -> view_rect {
+        if (iw <= 0.0F || ih <= 0.0F || ww <= 0.0F || wh <= 0.0F) return {};
+        const auto scale = std::min(ww / iw, wh / ih);
+        const auto w = iw * scale;
+        const auto h = ih * scale;
+        return {(ww - w) * 0.5F, (wh - h) * 0.5F, w, h};
+    }
+
+    /**
+     * A 2D pan/zoom camera over a raster map, reproducing the Red Alert 3
+     * tactical view controls:
+     *
+     *   - the wheel zooms (zoom 1 === the whole map fits the window);
+     *   - pushing the cursor against a screen edge scrolls the view;
+     *   - the view is clamped so it never leaves the map.
+     *
+     * `center_x`/`center_y` are the normalized image position (0..1, y down)
+     * held at the centre of the viewport. The camera mirrors the retail view
+     * object (`TheTacticalView`, retail `ra3_1.12.game` `0x00cdb7b4`), whose
+     * zoom is the scalar the debug overlay prints at `0x00c0b900`; the
+     * per-map scroll scaling is `cameraScrollSpeedScalar` (map data table at
+     * `0x00c11a54`).
+     */
+    struct view_camera {
+        float zoom = 1.0F;
+        float center_x = 0.5F;
+        float center_y = 0.5F;
+        float min_zoom = 1.0F;
+        float max_zoom = 24.0F;
+        float zoom_step = 1.15F;
+        float edge_scroll_viewports_per_second = 0.55F; ///< speed of a full edge push
+        float edge_margin = 24.0F;                      ///< pixels from the border
+
+        /** Keep the visible window inside the image. */
+        auto clamp_center() -> void {
+            const float half = 0.5F / zoom;
+            center_x = std::clamp(center_x, half, 1.0F - half);
+            center_y = std::clamp(center_y, half, 1.0F - half);
+        }
+
+        /** Zoom by `factor` (wheel up > 1) about the viewport centre. */
+        auto zoom_by(float factor) -> void {
+            zoom = std::clamp(zoom * factor, min_zoom, max_zoom);
+            this->clamp_center();
+        }
+
+        /** Scroll directly by a normalized image delta. */
+        auto scroll(float dx, float dy) -> void {
+            center_x += dx;
+            center_y += dy;
+            this->clamp_center();
+        }
+
+        /**
+         * Push the camera when the cursor `(mouse_x, mouse_y)` is within
+         * `edge_margin` of a window edge. `dt` is the frame time in seconds.
+         */
+        auto edge_scroll(float mouse_x, float mouse_y, float window_w, float window_h, float dt) -> void {
+            if (zoom <= min_zoom + 1.0e-4F || window_w <= 0.0F || window_h <= 0.0F) return;
+            float dir_x = 0.0F;
+            float dir_y = 0.0F;
+            if (mouse_x <= edge_margin) {
+                dir_x = -1.0F;
+            } else if (mouse_x >= window_w - edge_margin) {
+                dir_x = 1.0F;
+            }
+            if (mouse_y <= edge_margin) {
+                dir_y = -1.0F;
+            } else if (mouse_y >= window_h - edge_margin) {
+                dir_y = 1.0F;
+            }
+            if (dir_x == 0.0F && dir_y == 0.0F) return;
+            const auto step = (1.0F / zoom) * edge_scroll_viewports_per_second * dt;
+            this->scroll(dir_x * step, dir_y * step);
+        }
+
+        /** Resolve the image destination rectangle for a window of `window_w` x `window_h`. */
+        [[nodiscard]] auto rect(float image_w, float image_h, float window_w, float window_h) const -> view_rect {
+            if (image_w <= 0.0F || image_h <= 0.0F) return {};
+            const auto fit = std::min(window_w / image_w, window_h / image_h);
+            const auto scale = fit * zoom;
+            const auto w = image_w * scale;
+            const auto h = image_h * scale;
+            auto x = window_w * 0.5F - w * center_x;
+            auto y = window_h * 0.5F - h * center_y;
+            x = w <= window_w ? (window_w - w) * 0.5F : std::clamp(x, window_w - w, 0.0F);
+            y = h <= window_h ? (window_h - h) * 0.5F : std::clamp(y, window_h - h, 0.0F);
+            return {x, y, w, h};
+        }
+    };
+
+    /**
+     * A perspective camera aimed at a ground target, like the retail tactical
+     * view. The wheel changes `height` (moving the camera closer/farther), not
+     * an image scale; `yaw`/`pitch` orbit it.
+     */
+    struct camera3d {
+        float target_x = 0.0F; ///< World position the camera looks at.
+        float target_y = 0.0F;
+        float yaw = 0.0F;      ///< Radians; 0 looks toward +Y.
+        float pitch = 1.02F;   ///< Radians above the horizon (~58 degrees down).
+        float height = 420.0F; ///< Camera height above the target's ground.
+        float fov = 0.85F;     ///< Vertical field of view, radians.
+        // Zoom range mirrors the retail TacticalView (zoom 0.2..1.3 around the
+        // default height): closer/farther than that is clamped.
+        float min_height = 320.0F;
+        float max_height = 2100.0F;
+    };
 }

src/skirmish/ra3.skirmish.cppm

@@ -1,29 +1,33 @@
-module;
-
-#include <algorithm>
-#include <cmath>
-#include <cstdint>
-#include <span>
-#include <string>
-#include <string_view>
-#include <utility>
-#include <vector>
-
 export module ra3.skirmish;
 
+import std;
+
 export import ra3.core;
 export import ra3.map;
 export import ra3.game;
+export import ra3.data;
 import ra3.logic;
 
 /**
- * A minimal, headless skirmish simulation.
+ * A headless skirmish simulation driven by the real Red Alert 3 balance.
  *
- * Two sides start on a real map's waypoint positions, earn credits, train
+ * Two sides start on a real map's waypoints, build a base, extract ore and
- * units and fight until one side's base is destroyed. The simulation is fully
+ * fight. The mechanics mirror SAGE where it matters and use the retail numbers
- * deterministic: fixed 30 Hz steps, no wall-clock, and a seeded logic random
+ * from `ra3.data`:
- * stream. There is no networking, no online service and no EA account - this is
+ *
- * offline skirmish only.
+ *   - damage is resolved through the target's `ArmorTemplate` for the weapon's
+ *     damage type (`UNRESISTABLE` bypasses it);
+ *   - a weapon may only target what its `AntiMask` allows (an attack dog's maul
+ *     can never touch a structure or vehicle);
+ *   - structures and units are built through a pay-as-you-go queue gated on
+ *     power, cost and the tech prerequisite;
+ *   - refineries run the ore extraction cycle against a finite node;
+ *   - a side is defeated when it has no structures left, and the last side
+ *     standing wins (the engine's team-wipe victory).
+ *
+ * The simulation is fully deterministic: fixed 30 Hz steps, no wall-clock and a
+ * seeded logic random stream. There is no networking, no online service and no
+ * EA account - this is offline skirmish only.
  */
 export namespace ra3::skirmish {
     using ra3::core::coord3d;
@@ -32,75 +36,29 @@ export namespace ra3::skirmish {
     using ra3::core::uint32;
     using ra3::core::uint8;
     using ra3::core::usize;
+    using ra3::data::entity_kind;
 
-    /** Broad unit role. */
+    /** A live entity instance. */
-    enum class unit_class : uint8 { harvester, infantry, tank, base };
-
-    [[nodiscard]] constexpr auto to_string(unit_class value) -> std::string_view {
-        switch (value) {
-        case unit_class::harvester:
-            return "Harvester";
-        case unit_class::infantry:
-            return "Infantry";
-        case unit_class::tank:
-            return "Tank";
-        case unit_class::base:
-            return "Base";
-        }
-        return "Unknown";
-    }
-
-    /**
-     * Static combat/economy stats for a unit class.
-     *
-     * These are OpenRA3's own balance values (the retail numbers live in
-     * compiled assets that are not parsed yet), chosen so a skirmish resolves.
-     */
-    struct unit_type {
-        unit_class cls = unit_class::infantry;
-        std::string_view name;
-        real max_health = 1.0F;
-        real speed = 0.0F;
-        real weapon_damage = 0.0F;
-        real weapon_range = 0.0F;
-        real weapon_cooldown = 1.0F;
-        int32 cost = 0;
-        real build_time = 1.0F;
-        bool mobile = false;
-        bool produces = false;
-    };
-
-    inline constexpr unit_type harvester_type{unit_class::harvester, "Harvester", 300.0F, 10.0F, 0.0F, 0.0F, 0.0F, 1400, 8.0F, true, false};
-    inline constexpr unit_type infantry_type{unit_class::infantry, "Infantry", 120.0F, 12.0F, 8.0F, 55.0F, 1.0F, 150, 3.0F, true, false};
-    inline constexpr unit_type tank_type{unit_class::tank, "Tank", 480.0F, 9.0F, 30.0F, 70.0F, 1.6F, 900, 8.0F, true, false};
-    inline constexpr unit_type base_type{unit_class::base, "Base", 2500.0F, 0.0F, 20.0F, 90.0F, 2.0F, 0, 0.0F, false, true};
-
-    [[nodiscard]] constexpr auto unit_stats(unit_class value) -> const unit_type & {
-        switch (value) {
-        case unit_class::harvester:
-            return harvester_type;
-        case unit_class::infantry:
-            return infantry_type;
-        case unit_class::tank:
-            return tank_type;
-        case unit_class::base:
-            return base_type;
-        }
-        return infantry_type;
-    }
-
-    /** A live unit instance. */
     struct unit {
         uint32 id = 0;
         uint32 owner = 0;
-        unit_class cls = unit_class::infantry;
+        entity_kind kind = entity_kind::none;
         coord3d position{};
         real health = 0.0F;
         real max_health = 0.0F;
-        real cooldown = 0.0F;
+        real cooldown = 0.0F;     ///< Seconds until the weapon may fire again.
+        real cycle_timer = 0.0F;  ///< Refinery ore-extraction progress, seconds.
         bool alive = true;
     };
 
+    /** One entry in a player's production queue. */
+    struct build_job {
+        entity_kind kind = entity_kind::none;
+        uint32 progress = 0; ///< Frames completed.
+        uint32 total = 0;    ///< Frames required.
+        int32 paid = 0;      ///< Credits paid so far (pay-as-you-go).
+    };
+
     /** Per-player state for the match. */
     struct player_state {
         uint32 index = 0;
@@ -111,19 +69,22 @@ export namespace ra3::skirmish {
         real money_accumulator = 0.0F;
         coord3d start{};
         uint32 base_unit = 0;
-        real build_timer = 0.0F;
+        real think_timer = 0.0F;
         int32 kills = 0;
         int32 losses = 0;
+        int32 power_produced = 0;
+        int32 power_consumed = 0;
+        int32 ore_remaining = 0; ///< Credits left in this side's ore node(s).
+        std::vector<build_job> queue;
     };
 
     /** Skirmish parameters. */
     struct match_config {
         std::string map_id = "builtin";
-        int32 starting_money = 10000;
+        int32 starting_money = ra3::data::economy.starting_credits;
         uint32 seed = 1;
         uint32 max_frames = 30U * 60U * 15U;
-        real income_per_second = 25.0F;
+        uint32 max_units_per_player = 30U;
-        real harvester_income_per_second = 15.0F;
     };
 
     /** Outcome of a completed (or capped) match. */
@@ -165,16 +126,19 @@ export namespace ra3::skirmish {
             return match;
         }
 
-        /** Run until a base falls or the frame cap is reached. */
+        /** Run until a side is wiped out or the frame cap is reached. */
         auto run() -> match_result {
             while (!this->decided() && frame_ < config_.max_frames) this->step();
+            if (!decided_) this->decide_on_timeout();
             return this->result();
         }
 
         /** Advance exactly one 30 Hz frame. */
         auto step() -> void {
             constexpr real dt = 1.0F / 30.0F;
-            this->apply_income(dt);
+            this->update_power();
+            this->update_economy(dt);
+            this->update_production();
             this->run_ai(dt);
             this->update_units(dt);
             this->check_victory();
@@ -211,7 +175,7 @@ export namespace ra3::skirmish {
         }
 
     private:
-        static constexpr real build_interval_seconds = 4.0F;
+        static constexpr real ai_think_seconds = 2.0F;
 
         auto spawn_player(uint32 index, std::string name, game::faction side, bool human, const coord3d &start) -> void {
             player_state player;
@@ -221,66 +185,168 @@ export namespace ra3::skirmish {
             player.human = human;
             player.money = config_.starting_money;
             player.start = start;
-            player.base_unit = this->spawn_unit(index, unit_class::base, start);
+            player.ore_remaining = ra3::data::economy.ore_node_capacity;
-            this->spawn_unit(index, unit_class::harvester, {start.x + 60.0F, start.y + 20.0F, 0.0F});
+            player.base_unit = this->spawn_unit(index, entity_kind::construction_yard, start);
-            this->spawn_unit(index, unit_class::tank, {start.x + 40.0F, start.y + 50.0F, 0.0F});
-            this->spawn_unit(index, unit_class::tank, {start.x + 70.0F, start.y - 30.0F, 0.0F});
-            this->spawn_unit(index, unit_class::infantry, {start.x + 30.0F, start.y - 60.0F, 0.0F});
-            this->spawn_unit(index, unit_class::infantry, {start.x + 90.0F, start.y - 60.0F, 0.0F});
             players_.push_back(std::move(player));
         }
 
-        auto spawn_unit(uint32 owner, unit_class cls, const coord3d &position) -> uint32 {
+        auto spawn_unit(uint32 owner, entity_kind kind, const coord3d &position) -> uint32 {
-            const auto &stats = unit_stats(cls);
             unit created;
             created.id = next_unit_id_++;
             created.owner = owner;
-            created.cls = cls;
+            created.kind = kind;
             created.position = position;
-            created.health = stats.max_health;
+            created.health = ra3::data::max_health_of(kind);
-            created.max_health = stats.max_health;
+            created.max_health = created.health;
             units_.push_back(created);
             return created.id;
         }
 
-        auto apply_income(real dt) -> void {
+        /** Sum structure energy; a side is low on power when it draws more than it makes. */
+        auto update_power() -> void {
             for (auto &player: players_) {
-                real rate = config_.income_per_second;
+                player.power_produced = 0;
+                player.power_consumed = 0;
                 for (const auto &entry: units_) {
-                    if (entry.alive && entry.owner == player.index && entry.cls == unit_class::harvester) rate += config_.harvester_income_per_second;
+                    if (!entry.alive || entry.owner != player.index || !ra3::data::is_structure(entry.kind)) continue;
-                }
+                    const auto energy = ra3::data::structure_of(entry.kind).energy;
-                player.money_accumulator += rate * dt;
+                    if (energy >= 0) {
-                const auto whole = static_cast<int32>(player.money_accumulator);
+                        player.power_produced += energy;
-                if (whole > 0) {
+                    } else {
-                    player.money += whole;
+                        player.power_consumed += -energy;
-                    player.money_accumulator -= static_cast<real>(whole);
+                    }
                 }
             }
         }
 
+        [[nodiscard]] auto low_power(uint32 owner) const -> bool {
+            const auto &player = players_.at(owner);
+            return player.power_consumed > player.power_produced;
+        }
+
+        /**
+         * Ore extraction: every refinery runs the RA3 cycle (11 s for 250
+         * credits) against the side's finite node. Under low power the cycle is
+         * half speed.
+         */
+        auto update_economy(real dt) -> void {
+            for (auto &player: players_) {
+                const auto rate = low_power(player.index) ? (1.0F / static_cast<real>(ra3::data::world_rules.low_power_mining_divisor)) : 1.0F;
+                for (auto &entry: units_) {
+                    if (!entry.alive || entry.owner != player.index || !ra3::data::is_structure(entry.kind)) continue;
+                    if (!ra3::data::structure_of(entry.kind).is_refinery) continue;
+
+                    entry.cycle_timer += dt * rate;
+                    if (entry.cycle_timer < ra3::data::economy.extraction_seconds) continue;
+                    entry.cycle_timer -= ra3::data::economy.extraction_seconds;
+
+                    const auto yield = ra3::data::ore_per_cycle(player.ore_remaining);
+                    player.ore_remaining = player.ore_remaining > yield ? player.ore_remaining - yield : 0;
+                    player.money += yield;
+                }
+            }
+        }
+
+        /**
+         * Work each player's production queue. Cost is paid as the job
+         * progresses, a job stalls while unaffordable, and low power halves the
+         * production rate.
+         */
+        auto update_production() -> void {
+            for (auto &player: players_) {
+                if (player.queue.empty()) continue;
+                auto &job = player.queue.front();
+
+                const auto cost = ra3::data::cost_of(job.kind);
+                const auto advance = low_power(player.index) ? (frame_ % static_cast<uint32>(ra3::data::world_rules.low_power_production_divisor) == 0U) : true;
+                if (advance && job.total > 0U) {
+                    const auto next_progress = job.progress + 1U;
+                    const auto target_paid = static_cast<int32>((static_cast<std::int64_t>(cost) * next_progress) / job.total);
+                    const auto delta = target_paid - job.paid;
+                    if (delta <= player.money) {
+                        player.money -= delta;
+                        job.paid = target_paid;
+                        job.progress = next_progress;
+                    }
+                }
+
+                if (job.progress < job.total) continue;
+
+                if (ra3::data::is_structure(job.kind)) {
+                    const auto &base = this->find_unit(player.base_unit);
+                    const coord3d at = base != nullptr && base->alive ? base->position : player.start;
+                    const auto offset = static_cast<real>(ra3::data::structure_of(job.kind).size_cells) * ra3::data::cell_size + 40.0F;
+                    this->spawn_unit(player.index, job.kind, {at.x + offset, at.y + offset * static_cast<real>(player.queue.size()), 0.0F});
+                } else {
+                    const auto *producer = this->find_producer(player.index, ra3::data::unit_of(job.kind).built_by);
+                    if (producer == nullptr) continue; // wait for the producer
+                    this->spawn_unit(player.index, job.kind, {producer->position.x + 40.0F, producer->position.y + 40.0F, 0.0F});
+                }
+                player.queue.erase(player.queue.begin());
+            }
+        }
+
+        /** A simple scripted opponent: build a base, then train an army. */
         auto run_ai(real dt) -> void {
             for (auto &player: players_) {
-                player.build_timer += dt;
+                player.think_timer += dt;
-                if (player.build_timer < build_interval_seconds) continue;
+                if (player.think_timer < ai_think_seconds) continue;
-                player.build_timer = 0.0F;
+                player.think_timer = 0.0F;
+                if (!player.queue.empty()) continue;
+                if (this->unit_count(player.index) >= config_.max_units_per_player) continue;
 
-                const auto *base = this->find_unit(player.base_unit);
+                if (this->enqueue_if_missing(player, entity_kind::power_plant)) continue;
-                if (base == nullptr || !base->alive) continue;
+                if (this->enqueue_if_missing(player, entity_kind::refinery)) continue;
-                if (player.money < tank_type.cost) continue;
+                if (this->enqueue_if_missing(player, entity_kind::barracks)) continue;
+                if (this->enqueue_if_missing(player, entity_kind::war_factory)) continue;
 
-                player.money -= tank_type.cost;
+                // Army composition: roughly half infantry, half tanks.
-                this->spawn_unit(player.index, unit_class::tank, {base->position.x + 50.0F, base->position.y - 50.0F, 0.0F});
+                const bool want_infantry = (frame_ / 30U) % 2U == 0U;
+                const auto choice = want_infantry ? entity_kind::peacekeeper : entity_kind::guardian_tank;
+                if (player.money >= ra3::data::cost_of(choice) * 2) this->enqueue(player, choice);
             }
         }
 
+        /** Queue `kind` when the side has none and can afford it. */
+        auto enqueue_if_missing(player_state &player, entity_kind kind) -> bool {
+            for (const auto &entry: units_) {
+                if (entry.alive && entry.owner == player.index && entry.kind == kind) return false;
+            }
+            const auto &data = ra3::data::structure_of(kind);
+            if (data.prerequisite != entity_kind::none) {
+                bool have_prereq = false;
+                for (const auto &entry: units_) {
+                    if (entry.alive && entry.owner == player.index && entry.kind == data.prerequisite) have_prereq = true;
+                }
+                if (!have_prereq) return false;
+            }
+            if (player.money < ra3::data::cost_of(kind)) return false;
+            return this->enqueue(player, kind);
+        }
+
+        auto enqueue(player_state &player, entity_kind kind) -> bool {
+            if (player.queue.size() >= 9U) return false;
+            build_job job;
+            job.kind = kind;
+            job.total = ra3::data::build_frames_of(kind);
+            player.queue.push_back(job);
+            return true;
+        }
+
+        /**
+         * Move and fight. A unit seeks the nearest enemy its weapon can legally
+         * target; with no such target it advances on the enemy base so a match
+         * always converges.
+         */
         auto update_units(real dt) -> void {
             for (auto &entry: units_) {
                 if (!entry.alive) continue;
                 if (entry.cooldown > 0.0F) entry.cooldown -= dt;
-                if (entry.cls == unit_class::harvester) continue; // economy only, no combat
 
-                const auto &stats = unit_stats(entry.cls);
+                const auto *weapon = ra3::data::weapon_of(entry.kind);
-                auto *target = this->nearest_enemy(entry);
+                if (weapon == nullptr) continue;
+
+                auto *target = this->nearest_target(entry, *weapon);
                 if (target == nullptr) continue;
 
                 const auto dx = target->position.x - entry.position.x;
@@ -288,50 +354,52 @@ export namespace ra3::skirmish {
                 const auto dz = target->position.z - entry.position.z;
                 const auto distance = std::sqrt(dx * dx + dy * dy + dz * dz);
 
-                if (distance > stats.weapon_range && stats.mobile && stats.speed > 0.0F) {
+                if (distance > weapon->attack_range) {
-                    if (distance > 1.0e-3F) {
+                    const auto speed = ra3::data::unit_of(entry.kind).speed;
-                        const auto travel = stats.speed * dt;
+                    if (speed > 0.0F && distance > 1.0e-3F) {
+                        const auto travel = speed * dt;
                         entry.position.x += dx / distance * travel;
                         entry.position.y += dy / distance * travel;
                     }
-                } else if (stats.weapon_damage > 0.0F && distance <= stats.weapon_range && entry.cooldown <= 0.0F) {
+                    continue;
-                    entry.cooldown = stats.weapon_cooldown;
+                }
-                    target->health -= stats.weapon_damage;
+
-                    if (target->health <= 0.0F) {
+                if (entry.cooldown > 0.0F) continue;
-                        target->health = 0.0F;
+                entry.cooldown = weapon->reload_seconds + weapon->firing_seconds;
-                        target->alive = false;
+                this->apply_damage(entry, *target, *weapon);
-                        this->player_ref(entry.owner).kills += 1;
+
-                        this->player_ref(target->owner).losses += 1;
+                if (weapon->splash_radius > 0.0F) {
+                    for (auto &other: units_) {
+                        if (!other.alive || other.owner == entry.owner || &other == target) continue;
+                        if (!weapon->can_target(ra3::data::class_of(other.kind))) continue;
+                        const auto ox = other.position.x - target->position.x;
+                        const auto oy = other.position.y - target->position.y;
+                        if (ox * ox + oy * oy <= weapon->splash_radius * weapon->splash_radius) this->apply_damage(entry, other, *weapon);
                     }
                 }
             }
         }
 
-        auto check_victory() -> void {
+        /** Resolve one hit through the target's armour. */
-            const bool first_alive = this->base_alive(0U);
+        auto apply_damage(const unit &attacker, unit &target, const ra3::data::weapon_data &weapon) -> void {
-            const bool second_alive = this->base_alive(1U);
+            if (!target.alive) return;
-            if (first_alive && second_alive) return;
+            const auto damage = weapon.instakill ? target.max_health : ra3::data::armor_of(target.kind).adjust(weapon.type, weapon.damage);
-            decided_ = true;
+            target.health -= damage;
-            if (first_alive) {
+            if (target.health > 0.0F) return;
-                winner_ = 0;
+
-            } else if (second_alive) {
+            target.health = 0.0F;
-                winner_ = 1;
+            target.alive = false;
-            } else {
+            this->player_ref(attacker.owner).kills += 1;
-                winner_ = -1;
+            this->player_ref(target.owner).losses += 1;
-            }
         }
 
-        [[nodiscard]] auto base_alive(uint32 owner) const -> bool {
+        /** Nearest enemy this weapon may target, or `nullptr`. */
-            const auto &player = players_.at(owner);
+        [[nodiscard]] auto nearest_target(const unit &self, const ra3::data::weapon_data &weapon) -> unit * {
-            const auto *base = this->find_unit(player.base_unit);
-            return base != nullptr && base->alive;
-        }
-
-        [[nodiscard]] auto nearest_enemy(const unit &self) -> unit * {
             unit *best = nullptr;
             real best_distance = 1.0e30F;
             for (auto &candidate: units_) {
                 if (!candidate.alive || candidate.owner == self.owner) continue;
+                if (!weapon.can_target(ra3::data::class_of(candidate.kind))) continue;
                 const auto dx = candidate.position.x - self.position.x;
                 const auto dy = candidate.position.y - self.position.y;
                 const auto squared = dx * dx + dy * dy;
@@ -343,6 +411,43 @@ export namespace ra3::skirmish {
             return best;
         }
 
+        /** Defeat is losing every structure; the last side standing wins. */
+        auto check_victory() -> void {
+            const bool first_alive = this->has_structures(0U);
+            const bool second_alive = this->has_structures(1U);
+            if (first_alive && second_alive) return;
+            decided_ = true;
+            winner_ = first_alive ? 0 : (second_alive ? 1 : -1);
+        }
+
+        /** Frame cap: the higher-scoring side wins, with a deterministic tie-break. */
+        auto decide_on_timeout() -> void {
+            decided_ = true;
+            const auto first = this->score_tuple(0U);
+            const auto second = this->score_tuple(1U);
+            winner_ = first == second ? -1 : (first > second ? 0 : 1);
+        }
+
+        [[nodiscard]] auto score_tuple(uint32 owner) const -> std::tuple<int32, int32, int32> {
+            const auto &player = players_.at(owner);
+            return {this->score(owner), player.kills, static_cast<int32>(this->unit_count(owner))};
+        }
+
+        [[nodiscard]] auto score(uint32 owner) const -> int32 {
+            int32 total = players_.at(owner).money;
+            for (const auto &entry: units_) {
+                if (entry.alive && entry.owner == owner) total += ra3::data::cost_of(entry.kind);
+            }
+            return total;
+        }
+
+        [[nodiscard]] auto has_structures(uint32 owner) const -> bool {
+            for (const auto &entry: units_) {
+                if (entry.alive && entry.owner == owner && ra3::data::is_structure(entry.kind)) return true;
+            }
+            return false;
+        }
+
         [[nodiscard]] auto find_unit(uint32 id) -> unit * {
             for (auto &entry: units_) {
                 if (entry.id == id) return &entry;
@@ -357,6 +462,13 @@ export namespace ra3::skirmish {
             return nullptr;
         }
 
+        [[nodiscard]] auto find_producer(uint32 owner, entity_kind kind) -> unit * {
+            for (auto &entry: units_) {
+                if (entry.alive && entry.owner == owner && entry.kind == kind) return &entry;
+            }
+            return nullptr;
+        }
+
         [[nodiscard]] auto player_ref(uint32 index) -> player_state & { return players_.at(index); }
 
         match_config config_;

src/ui/ra3.ui.null.cppm

@@ -1,24 +1,23 @@
-module;
-
-#include <string>
-
 export module ra3.ui;
 
+import std;
 export import ra3.core;
 import ra3.render;
+import ra3.client;
 
 /**
- * Fallback viewer used when the build has no SDL3. It never opens a window;
+ * Fallback SDL backend used when the build has no SDL3. It never opens a window;
- * the caller should write an offscreen image instead.
+ * `init` fails so the caller can fall back to an offscreen image.
  */
 export namespace ra3::ui {
-    /** Window parameters (mirrors the SDL backend). */
+    class sdl_display final : public ra3::client::display {
-    struct viewer_options {
+    public:
-        std::string title = "OpenRA3";
+        [[nodiscard]] auto init(const ra3::client::display_options &) -> bool override { return false; }
-        int width = 1024;
+        [[nodiscard]] auto present(const ra3::render::image &, const ra3::render::view_rect &, bool) -> bool override { return false; }
-        int height = 768;
+        [[nodiscard]] auto poll_event(ra3::render::ui_event &) -> bool override { return false; }
+        [[nodiscard]] auto window_size() const -> std::pair<int, int> override { return {0, 0}; }
+        [[nodiscard]] auto key_down(ra3::render::ui_key) const -> bool override { return false; }
+        auto shutdown() -> void override {}
+        [[nodiscard]] auto name() const -> std::string_view override { return "sdl(null)"; }
     };
-
-    /** Always returns false: this build has no windowing backend. */
-    [[nodiscard]] inline auto run_viewer(const ra3::render::image &, const viewer_options &) -> bool { return false; }
 }

src/ui/ra3.ui.sdl.cppm

@@ -2,92 +2,196 @@ module;
 
 #include <SDL3/SDL.h>
 
-#include <algorithm>
-#include <string>
-
 export module ra3.ui;
 
+import std;
 export import ra3.core;
 import ra3.render;
+import ra3.client;
 
 /**
- * A minimal SDL3 window for viewing a rendered scene.
+ * The SDL3 presentation backend.
  *
- * Controls: drag with the left mouse button to pan, wheel to zoom, Esc/close
+ * SDL3 is the platform layer: it owns the window, the input, and (here) a
- * to quit. When no display is available `run_viewer` returns false so the
+ * low-end `SDL_Renderer` blit path. Only the low-level display primitives live
- * caller can fall back to an offscreen image.
+ * in this module; the interactive loops are shared in `ra3::client::display`.
+ * The Vulkan backend implements the same interface.
  */
 export namespace ra3::ui {
-    /** Window parameters. */
-    struct viewer_options {
-        std::string title = "OpenRA3";
-        int width = 1024;
-        int height = 768;
-    };
-
     /**
-     * Show `scene` in a window until the user quits.
+     * An SDL_Renderer-backed display: cheap, dependency-light, and used as the
-     *
+     * fallback when Vulkan is unavailable.
-     * @return true if the window ran; false if video init or window creation
-     *         failed (typically no display).
      */
-    [[nodiscard]] inline auto run_viewer(const ra3::render::image &scene, const viewer_options &options) -> bool {
+    class sdl_display final : public ra3::client::display {
-        if (scene.empty()) return false;
+    public:
-        if (!SDL_Init(SDL_INIT_VIDEO)) return false;
+        sdl_display() = default;
+        sdl_display(const sdl_display &) = delete;
+        auto operator=(const sdl_display &) -> sdl_display & = delete;
+        ~sdl_display() override { this->shutdown(); }
 
-        SDL_Window *window = SDL_CreateWindow(options.title.c_str(), options.width, options.height, SDL_WINDOW_RESIZABLE);
+        [[nodiscard]] auto init(const ra3::client::display_options &options) -> bool override {
-        if (window == nullptr) {
+            if (!SDL_Init(SDL_INIT_VIDEO)) return false;
-            SDL_Quit();
+            this->fps_limit_ = options.fps_limit;
-            return false;
+            window_ = SDL_CreateWindow(options.title.c_str(), options.width, options.height,
+                                       SDL_WINDOW_RESIZABLE | (options.fullscreen ? SDL_WINDOW_FULLSCREEN : 0));
+            if (window_ == nullptr) {
+                SDL_Quit();
+                return false;
+            }
+            SDL_RaiseWindow(window_);
+            renderer_ = SDL_CreateRenderer(window_, nullptr);
+            if (renderer_ == nullptr) {
+                this->shutdown();
+                return false;
+            }
+            SDL_SetRenderVSync(renderer_, options.fps_limit == 0 ? 1 : 0);
+            SDL_StartTextInput(window_);
+            return true;
         }
-        SDL_Renderer *renderer = SDL_CreateRenderer(window, nullptr);
-        if (renderer == nullptr) {
-            SDL_DestroyWindow(window);
-            SDL_Quit();
-            return false;
-        }
-        SDL_Texture *texture = SDL_CreateTexture(renderer, SDL_PIXELFORMAT_ARGB8888, SDL_TEXTUREACCESS_STREAMING, static_cast<int>(scene.width()),
-                                                 static_cast<int>(scene.height()));
-        if (texture == nullptr) {
-            SDL_DestroyRenderer(renderer);
-            SDL_DestroyWindow(window);
-            SDL_Quit();
-            return false;
-        }
-        SDL_UpdateTexture(texture, nullptr, scene.data(), static_cast<int>(scene.width()) * 4);
-        SDL_SetTextureScaleMode(texture, SDL_SCALEMODE_NEAREST);
 
-        float zoom = 1.0F;
+        [[nodiscard]] auto present(const ra3::render::image &frame, const ra3::render::view_rect &dest, bool changed) -> bool override {
-        float pan_x = 0.0F;
+            if (frame.empty() || renderer_ == nullptr) return false;
-        float pan_y = 0.0F;
+            if (changed || texture_ == nullptr || frame.width() != texture_w_ || frame.height() != texture_h_) {
-        bool running = true;
+                if (texture_ != nullptr) SDL_DestroyTexture(texture_);
-        SDL_Event event;
+                texture_ = SDL_CreateTexture(renderer_, SDL_PIXELFORMAT_ARGB8888, SDL_TEXTUREACCESS_STREAMING, static_cast<int>(frame.width()),
-        while (running) {
+                                             static_cast<int>(frame.height()));
+                if (texture_ == nullptr) return false;
+                texture_w_ = frame.width();
+                texture_h_ = frame.height();
+                SDL_SetTextureScaleMode(texture_, SDL_SCALEMODE_LINEAR);
+                SDL_UpdateTexture(texture_, nullptr, frame.data(), static_cast<int>(frame.width()) * 4);
+            }
+            SDL_SetRenderDrawColor(renderer_, 0, 0, 0, 255);
+            SDL_RenderClear(renderer_);
+            const SDL_FRect dst{dest.x, dest.y, dest.w, dest.h};
+            SDL_RenderTexture(renderer_, texture_, nullptr, &dst);
+            SDL_RenderPresent(renderer_);
+            return true;
+        }
+
+        [[nodiscard]] auto poll_event(ra3::render::ui_event &out) -> bool override {
+            SDL_Event event;
             while (SDL_PollEvent(&event)) {
-                if (event.type == SDL_EVENT_QUIT) {
+                switch (event.type) {
-                    running = false;
+                case SDL_EVENT_QUIT:
-                } else if (event.type == SDL_EVENT_KEY_DOWN && event.key.key == SDLK_ESCAPE) {
+                    out = {};
-                    running = false;
+                    out.type = ra3::render::ui_event_type::quit;
-                } else if (event.type == SDL_EVENT_MOUSE_WHEEL) {
+                    return true;
-                    zoom *= event.wheel.y > 0.0F ? 1.1F : (1.0F / 1.1F);
+                case SDL_EVENT_KEY_DOWN:
-                    zoom = std::clamp(zoom, 0.1F, 20.0F);
+                    if (const auto key = map_key(event.key.key); key != ra3::render::ui_key::none) {
-                } else if (event.type == SDL_EVENT_MOUSE_MOTION && (event.motion.state & SDL_BUTTON_LMASK) != 0U) {
+                        out = {};
-                    pan_x += event.motion.xrel;
+                        out.type = ra3::render::ui_event_type::key;
-                    pan_y += event.motion.yrel;
+                        out.key = key;
+                        return true;
+                    }
+                    break;
+                case SDL_EVENT_TEXT_INPUT:
+                    if (event.text.text[0] != '\0') {
+                        out = {};
+                        out.type = ra3::render::ui_event_type::text;
+                        out.character = event.text.text[0];
+                        return true;
+                    }
+                    break;
+                case SDL_EVENT_MOUSE_MOTION:
+                    out = {};
+                    out.type = ra3::render::ui_event_type::mouse_move;
+                    out.x = event.motion.x;
+                    out.y = event.motion.y;
+                    out.dx = event.motion.xrel;
+                    out.dy = event.motion.yrel;
+                    out.left = (event.motion.state & SDL_BUTTON_LMASK) != 0U;
+                    out.middle = (event.motion.state & SDL_BUTTON_MMASK) != 0U;
+                    out.right = (event.motion.state & SDL_BUTTON_RMASK) != 0U;
+                    return true;
+                case SDL_EVENT_MOUSE_BUTTON_DOWN:
+                    out = {};
+                    out.type = ra3::render::ui_event_type::mouse_button;
+                    out.x = event.button.x;
+                    out.y = event.button.y;
+                    out.left = event.button.button == SDL_BUTTON_LEFT;
+                    out.middle = event.button.button == SDL_BUTTON_MIDDLE;
+                    out.right = event.button.button == SDL_BUTTON_RIGHT;
+                    return true;
+                case SDL_EVENT_MOUSE_BUTTON_UP:
+                    out = {};
+                    out.type = ra3::render::ui_event_type::mouse_button;
+                    out.x = event.button.x;
+                    out.y = event.button.y;
+                    out.released = true;
+                    out.left = event.button.button == SDL_BUTTON_LEFT;
+                    out.middle = event.button.button == SDL_BUTTON_MIDDLE;
+                    out.right = event.button.button == SDL_BUTTON_RIGHT;
+                    return true;
+                case SDL_EVENT_MOUSE_WHEEL:
+                    out = {};
+                    out.type = ra3::render::ui_event_type::wheel;
+                    out.wheel = event.wheel.y;
+                    return true;
+                default:
+                    break;
                 }
             }
-
+            return false;
-            SDL_SetRenderDrawColor(renderer, 0, 0, 0, 255);
-            SDL_RenderClear(renderer);
-            const SDL_FRect dst{pan_x, pan_y, static_cast<float>(scene.width()) * zoom, static_cast<float>(scene.height()) * zoom};
-            SDL_RenderTexture(renderer, texture, nullptr, &dst);
-            SDL_RenderPresent(renderer);
         }
 
-        SDL_DestroyTexture(texture);
+        [[nodiscard]] auto window_size() const -> std::pair<int, int> override {
-        SDL_DestroyRenderer(renderer);
+            int w = 0;
-        SDL_DestroyWindow(window);
+            int h = 0;
-        SDL_Quit();
+            SDL_GetWindowSizeInPixels(window_, &w, &h);
-        return true;
+            return {w, h};
-    }
+        }
+
+        [[nodiscard]] auto key_down(ra3::render::ui_key key) const -> bool override {
+            const bool *keys = SDL_GetKeyboardState(nullptr);
+            if (keys == nullptr) return false;
+            switch (key) {
+            case ra3::render::ui_key::up: return keys[SDL_SCANCODE_UP];
+            case ra3::render::ui_key::down: return keys[SDL_SCANCODE_DOWN];
+            case ra3::render::ui_key::left: return keys[SDL_SCANCODE_LEFT];
+            case ra3::render::ui_key::right: return keys[SDL_SCANCODE_RIGHT];
+            default: return false;
+            }
+        }
+
+        auto shutdown() -> void override {
+            if (window_ != nullptr) SDL_StopTextInput(window_);
+            if (texture_ != nullptr) SDL_DestroyTexture(texture_);
+            if (renderer_ != nullptr) SDL_DestroyRenderer(renderer_);
+            if (window_ != nullptr) SDL_DestroyWindow(window_);
+            SDL_Quit();
+            texture_ = nullptr;
+            renderer_ = nullptr;
+            window_ = nullptr;
+            texture_w_ = 0;
+            texture_h_ = 0;
+        }
+
+        [[nodiscard]] auto name() const -> std::string_view override { return "sdl"; }
+
+    private:
+        [[nodiscard]] static auto map_key(SDL_Keycode key) -> ra3::render::ui_key {
+            using ra3::render::ui_key;
+            switch (key) {
+            case SDLK_UP: return ui_key::up;
+            case SDLK_DOWN: return ui_key::down;
+            case SDLK_LEFT: return ui_key::left;
+            case SDLK_RIGHT: return ui_key::right;
+            case SDLK_PAGEUP: return ui_key::page_up;
+            case SDLK_PAGEDOWN: return ui_key::page_down;
+            case SDLK_RETURN:
+            case SDLK_KP_ENTER: return ui_key::confirm;
+            case SDLK_ESCAPE: return ui_key::cancel;
+            case SDLK_TAB: return ui_key::tab;
+            case SDLK_BACKSPACE: return ui_key::backspace;
+            default: return ui_key::none;
+            }
+        }
+
+        SDL_Window *window_ = nullptr;
+        SDL_Renderer *renderer_ = nullptr;
+        SDL_Texture *texture_ = nullptr;
+        ra3::core::uint32 texture_w_ = 0;
+        ra3::core::uint32 texture_h_ = 0;
+    };
 }

src/vulkan/ra3.vulkan.null.cppm

@@ -0,0 +1,25 @@
+export module ra3.vulkan;
+
+import std;
+
+export import ra3.core;
+import ra3.render;
+import ra3.client;
+
+/**
+ * Fallback Vulkan backend used when the build has no Vulkan loader (for example
+ * the Windows cross-build without a Vulkan SDK). `init` fails so the caller can
+ * select another display.
+ */
+export namespace ra3::vulkan {
+    class vulkan_display final : public ra3::client::display {
+    public:
+        [[nodiscard]] auto init(const ra3::client::display_options &) -> bool override { return false; }
+        [[nodiscard]] auto present(const ra3::render::image &, const ra3::render::view_rect &, bool) -> bool override { return false; }
+        [[nodiscard]] auto poll_event(ra3::render::ui_event &) -> bool override { return false; }
+        [[nodiscard]] auto window_size() const -> std::pair<int, int> override { return {0, 0}; }
+        [[nodiscard]] auto key_down(ra3::render::ui_key) const -> bool override { return false; }
+        auto shutdown() -> void override {}
+        [[nodiscard]] auto name() const -> std::string_view override { return "vulkan(null)"; }
+    };
+}

src/wasmgl/ra3.wasmgl.cppm

@@ -0,0 +1,661 @@
+module;
+
+// Emscripten/GLES3 headers in the global module fragment (C headers). No SDL:
+// this backend runs the engine on a Web Worker and renders into an
+// OffscreenCanvas transferred from the page, so it must not touch the
+// main-thread-only SDL Emscripten port.
+#include <GLES3/gl3.h>
+
+#include <emscripten/em_asm.h>
+#include <emscripten/emscripten.h>
+#include <emscripten/html5.h>
+
+// Sized normalized texture formats used by the terrain textures; core in
+// WebGL2/GLES3 but missing from some GLES3 headers.
+#ifndef GL_R16
+#define GL_R16 0x822A
+#endif
+#ifndef GL_RGBA16
+#define GL_RGBA16 0x805B
+#endif
+
+#include "wasmgl_glsl_embedded.hpp"
+
+export module ra3.wasmgl;
+
+import std;
+
+export import ra3.core;
+export import ra3.render;
+export import ra3.terrain;
+export import ra3.client;
+import ender.log;
+
+/**
+ * An SDL-free WebGL 2 presentation backend for the wasm build.
+ *
+ * The whole runtime runs on a plain Web Worker (started by
+ * `apps/web/openra3.worker.js`), so `main()` lives there and its virtual
+ * filesystem is local to the worker: `FS.createLazyFile` (synchronous XHR) is
+ * legal and the browser fetches each asset only when the engine opens it.
+ * Note that Emscripten's `PROXY_TO_PTHREAD` cannot be used for this: in a
+ * pthread every filesystem syscall is proxied to the main browser thread, so
+ * the engine would read the main thread's FS, not the worker's lazy one.
+ *
+ * The page transfers its `#canvas` to the worker as an OffscreenCanvas; this
+ * module creates the WebGL2 context on it with `emscripten_webgl_create_context`
+ * and draws the same 2D menu / GPU terrain as the other backends. Input arrives
+ * over the worker message channel (the page owns the DOM listeners) into the
+ * `openra3_*` C functions below, which queue `ra3::render::ui_event`s.
+ *
+ * It reuses the same GL pipeline/texture code as the desktop GPU backends; only
+ * the windowing/context/event layer differs.
+ */
+export namespace ra3::wasmgl {
+    class wasmgl_display;
+
+    /**
+     * Receives the input events the worker forwards from the page. Each wasm
+     * backend (WebGL here, WebGPU in `ra3.webgpu`) implements it and registers
+     * itself on init, so the `openra3_*` C exports live in exactly one module.
+     */
+    class event_sink {
+    public:
+        virtual ~event_sink() = default;
+        virtual void on_key(std::string_view code, bool down) = 0;
+        virtual void on_text(int codepoint) = 0;
+        virtual void on_mouse_button(double x, double y, bool left) = 0;
+        virtual void on_mouse_move(double x, double y, double dx, double dy, bool left) = 0;
+        virtual void on_wheel(double delta_y) = 0;
+        virtual void on_resize(int width, int height) = 0;
+        virtual void on_quit() = 0;
+    };
+
+    namespace detail {
+        /** The backend that currently receives worker input. */
+        [[nodiscard]] inline auto sink_slot() -> event_sink *& {
+            static event_sink *sink = nullptr;
+            return sink;
+        }
+    } // namespace detail
+
+    /** Register (or, with null, clear) the backend that receives input events. */
+    inline auto set_event_sink(event_sink *sink) -> void { detail::sink_slot() = sink; }
+
+    namespace detail {
+        /** Movement keys tracked as "held" for panning (physical codes). */
+        enum class move_key : std::uint8_t { w, s, a, d, arrow_up, arrow_down, arrow_left, arrow_right, count };
+
+        [[nodiscard]] inline auto move_key_index(std::string_view code) -> int {
+            if (code == "KeyW") return static_cast<int>(move_key::w);
+            if (code == "KeyS") return static_cast<int>(move_key::s);
+            if (code == "KeyA") return static_cast<int>(move_key::a);
+            if (code == "KeyD") return static_cast<int>(move_key::d);
+            if (code == "ArrowUp") return static_cast<int>(move_key::arrow_up);
+            if (code == "ArrowDown") return static_cast<int>(move_key::arrow_down);
+            if (code == "ArrowLeft") return static_cast<int>(move_key::arrow_left);
+            if (code == "ArrowRight") return static_cast<int>(move_key::arrow_right);
+            return -1;
+        }
+
+        /** The `ui_key` for an action key, or `none`. */
+        [[nodiscard]] inline auto key_from_code(std::string_view code) -> ra3::render::ui_key {
+            using ra3::render::ui_key;
+            if (code == "ArrowUp") return ui_key::up;
+            if (code == "ArrowDown") return ui_key::down;
+            if (code == "ArrowLeft") return ui_key::left;
+            if (code == "ArrowRight") return ui_key::right;
+            if (code == "PageUp") return ui_key::page_up;
+            if (code == "PageDown") return ui_key::page_down;
+            if (code == "Enter" || code == "NumpadEnter") return ui_key::confirm;
+            if (code == "Escape") return ui_key::cancel;
+            if (code == "Tab") return ui_key::tab;
+            if (code == "Backspace") return ui_key::backspace;
+            return ui_key::none;
+        }
+
+        /** The single live display (there is only ever one). */
+        [[nodiscard]] inline auto active_slot() -> wasmgl_display *& {
+            static wasmgl_display *instance = nullptr;
+            return instance;
+        }
+
+        /** Camera + terrain uniforms (5 x vec4), matching the other backends. */
+        [[nodiscard]] inline auto terrain_uniforms(const ra3::terrain::gpu_terrain &terrain, const ra3::render::camera3d &camera, float time_s,
+                                                   float aspect) -> std::array<float, 20> {
+            return {camera.target_x,
+                    camera.target_y,
+                    camera.yaw,
+                    camera.height,
+                    camera.pitch,
+                    camera.fov,
+                    terrain.water_z,
+                    terrain.has_water ? 1.0F : 0.0F,
+                    0.45F,
+                    0.35F,
+                    0.82F,
+                    0.38F,
+                    static_cast<float>(terrain.width),
+                    static_cast<float>(terrain.height),
+                    0.0F,
+                    terrain.z_scale,
+                    time_s,
+                    0.0F,
+                    terrain.cell_span,
+                    aspect};
+        }
+
+        /**
+         * Read `assets.manifest.json` and register every listed file as an
+         * Emscripten lazy file, so the browser fetches a file only when the
+         * engine first opens it. Runs on the worker, where synchronous XHR
+         * (used by `FS.createLazyFile`) is allowed. Returns the number of files
+         * registered, or -1 on failure. A missing manifest is not an error (the
+         * caller may have preloaded a full asset tree instead).
+         */
+        [[nodiscard]] inline auto mount_lazy_assets(const std::string &manifest_path, const std::string &assets_root, const std::string &url_prefix)
+            -> int {
+            std::ifstream in(manifest_path, std::ios::binary);
+            if (!in) return 0;
+            const std::string json{std::istreambuf_iterator<char>(in), std::istreambuf_iterator<char>()};
+            if (json.empty()) return 0;
+            return EM_ASM_INT(
+                {
+                    try {
+                        var manifest = JSON.parse(UTF8ToString($0));
+                        var root = UTF8ToString($1);
+                        var prefix = UTF8ToString($2);
+                        var files = manifest.files || [];
+                        var n = 0;
+                        for (var i = 0; i < files.length; ++i) {
+                            var rel = files[i];
+                            var full = root + '/' + rel;
+                            var slash = full.lastIndexOf('/');
+                            var dir = full.substring(0, slash);
+                            var name = full.substring(slash + 1);
+                            FS.mkdirTree(dir);
+                            FS.createLazyFile(dir, name, prefix + rel, true, false);
+                            ++n;
+                        }
+                        console.log('ra3.wasmgl: mounted ' + n + ' lazy assets under ' + root);
+                        return n;
+                    } catch (e) {
+                        console.error('ra3.wasmgl: lazy asset mount failed: ' + e);
+                        return -1;
+                    }
+                },
+                json.c_str(), assets_root.c_str(), url_prefix.c_str());
+        }
+    } // namespace detail
+
+    /**
+     * Mount the wasm asset tree lazily (call once, before any asset access).
+     * On non-wasm builds this does nothing.
+     */
+    inline auto mount_assets(const std::string &manifest_path = "/assets.manifest.json", const std::string &assets_root = "/assets",
+                             const std::string &url_prefix = "assets/") -> int {
+#if defined(__EMSCRIPTEN__)
+        return detail::mount_lazy_assets(manifest_path, assets_root, url_prefix);
+#else
+        (void) manifest_path;
+        (void) assets_root;
+        (void) url_prefix;
+        return 0;
+#endif
+    }
+
+    class wasmgl_display final : public ra3::client::display, public event_sink {
+    public:
+        wasmgl_display() = default;
+        wasmgl_display(const wasmgl_display &) = delete;
+        auto operator=(const wasmgl_display &) -> wasmgl_display & = delete;
+        ~wasmgl_display() override { this->shutdown(); }
+
+        [[nodiscard]] auto init(const ra3::client::display_options &options) -> bool override {
+            this->fps_limit_ = options.fps_limit;
+
+            // There is no DOM in the worker, so Emscripten's canvas lookup
+            // (`findEventTarget`, a CSS selector) cannot find #canvas. Register
+            // the transferred OffscreenCanvas (Module.canvas) as a special target
+            // so `emscripten_webgl_create_context`/`..._element_size` resolve it.
+            EM_ASM({
+                if (typeof specialHTMLTargets !== 'undefined' && Module['canvas']) {
+                    specialHTMLTargets['#canvas'] = Module['canvas'];
+                }
+            });
+
+            EmscriptenWebGLContextAttributes attributes;
+            emscripten_webgl_init_context_attributes(&attributes);
+            attributes.majorVersion = 2;
+            attributes.minorVersion = 0;
+            attributes.alpha = false;
+            attributes.depth = true;
+            attributes.stencil = false;
+            attributes.antialias = false;
+            attributes.premultipliedAlpha = false;
+            attributes.preserveDrawingBuffer = false;
+            attributes.powerPreference = EM_WEBGL_POWER_PREFERENCE_HIGH_PERFORMANCE;
+            attributes.proxyContextToMainThread = EMSCRIPTEN_WEBGL_CONTEXT_PROXY_DISALLOW;
+            context_ = emscripten_webgl_create_context("#canvas", &attributes);
+            if (context_ == 0) {
+                ender::log::error("ra3.wasmgl: emscripten_webgl_create_context failed (is #canvas an OffscreenCanvas in this worker?)");
+                return false;
+            }
+            if (emscripten_webgl_make_context_current(context_) != EMSCRIPTEN_RESULT_SUCCESS) {
+                ender::log::error("ra3.wasmgl: emscripten_webgl_make_context_current failed");
+                this->shutdown();
+                return false;
+            }
+            // The page sized the canvas before transfer; fall back to the
+            // requested size if it is missing.
+            const auto [width, height] = this->window_size();
+            if (width <= 0 || height <= 0) {
+                emscripten_set_canvas_element_size("#canvas", options.width, options.height);
+            }
+            if (!this->create_scene_pipeline()) {
+                this->shutdown();
+                return false;
+            }
+            glGenVertexArrays(1, &vao_);
+            glBindVertexArray(vao_);
+            detail::active_slot() = this;
+            detail::sink_slot() = this;
+            ender::log::info(std::format("ra3.wasmgl: WebGL worker backend initialized ({})",
+                                         reinterpret_cast<const char *>(glGetString(GL_VERSION))));
+            return true;
+        }
+
+        [[nodiscard]] auto present(const ra3::render::image &frame, const ra3::render::view_rect &dest, bool changed) -> bool override {
+            if (frame.empty()) return false;
+            if (changed || scene_tex_ == 0U || frame.width() != scene_w_ || frame.height() != scene_h_) {
+                this->upload_scene(frame);
+            }
+            const auto [window_w, window_h] = this->window_size();
+            if (window_w <= 0 || window_h <= 0) return true;
+
+            glViewport(0, 0, window_w, window_h);
+            glDisable(GL_DEPTH_TEST);
+            glEnable(GL_BLEND);
+            glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
+            glClearColor(0.05F, 0.06F, 0.08F, 1.0F);
+            glClear(GL_COLOR_BUFFER_BIT);
+            this->draw_fullscreen(scene_program_, scene_rect_loc_, scene_tex_, dest, window_w, window_h);
+            this->mark_frame();
+            return true;
+        }
+
+        [[nodiscard]] auto poll_event(ra3::render::ui_event &out) -> bool override {
+            if (events_.empty()) return false;
+            out = events_.front();
+            events_.pop_front();
+            return true;
+        }
+
+        [[nodiscard]] auto window_size() const -> std::pair<int, int> override {
+            int w = 0;
+            int h = 0;
+            if (emscripten_get_canvas_element_size("#canvas", &w, &h) != EMSCRIPTEN_RESULT_SUCCESS) return {0, 0};
+            return {w, h};
+        }
+
+        [[nodiscard]] auto key_down(ra3::render::ui_key key) const -> bool override {
+            const auto held = [this](detail::move_key which) { return held_[static_cast<std::size_t>(which)]; };
+            switch (key) {
+            case ra3::render::ui_key::up: return held(detail::move_key::w) || held(detail::move_key::arrow_up);
+            case ra3::render::ui_key::down: return held(detail::move_key::s) || held(detail::move_key::arrow_down);
+            case ra3::render::ui_key::left: return held(detail::move_key::a) || held(detail::move_key::arrow_left);
+            case ra3::render::ui_key::right: return held(detail::move_key::d) || held(detail::move_key::arrow_right);
+            default: return false;
+            }
+        }
+
+        [[nodiscard]] auto supports_terrain() const -> bool override { return true; }
+
+        [[nodiscard]] auto present_terrain(const ra3::terrain::gpu_terrain &terrain, const ra3::render::camera3d &camera, float time_s,
+                                           const ra3::client::terrain_overlay &overlay) -> bool override {
+            if (!terrain_ready_) {
+                if (!this->create_terrain_pipeline()) return false;
+                if (!this->create_terrain_textures(terrain)) return false;
+                terrain_ready_ = true;
+                ender::log::info(std::format("ra3.wasmgl: terrain ready ({}x{}, {} layers)", terrain.width, terrain.height, terrain.layer_count));
+            }
+            if (overlay.label_changed) this->upload_overlay(label_tex_, overlay.label);
+            if (overlay.minimap_changed) this->upload_overlay(minimap_tex_, overlay.minimap);
+
+            const auto [window_w, window_h] = this->window_size();
+            if (window_w <= 0 || window_h <= 0) return true;
+            const auto aspect = static_cast<float>(window_w) / static_cast<float>(std::max(1, window_h));
+
+            glViewport(0, 0, window_w, window_h);
+            glDisable(GL_DEPTH_TEST);
+            glEnable(GL_BLEND);
+            glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
+            glClearColor(0.45F, 0.55F, 0.70F, 1.0F);
+            glClear(GL_COLOR_BUFFER_BIT);
+            glBindVertexArray(vao_);
+
+            glUseProgram(terrain_program_);
+            const auto uniforms = detail::terrain_uniforms(terrain, camera, time_s, aspect);
+            glUniform4fv(terrain_cam_loc_, 5, uniforms.data());
+            glActiveTexture(GL_TEXTURE0);
+            glBindTexture(GL_TEXTURE_2D, height_tex_);
+            glActiveTexture(GL_TEXTURE1);
+            glBindTexture(GL_TEXTURE_2D, cell_tex_);
+            glActiveTexture(GL_TEXTURE2);
+            glBindTexture(GL_TEXTURE_2D_ARRAY, atlas_tex_);
+            glUniform1i(terrain_height_loc_, 0);
+            glUniform1i(terrain_cell_loc_, 1);
+            glUniform1i(terrain_atlas_loc_, 2);
+            glDrawArrays(GL_TRIANGLES, 0, 3);
+
+            // Overlays (FPS label, corner minimap) use the image program.
+            const float margin = 12.0F;
+            this->draw_overlay(label_tex_, overlay.label.width(), overlay.label.height(), margin, margin, window_w, window_h);
+            this->draw_overlay(minimap_tex_, overlay.minimap.width(), overlay.minimap.height(),
+                               static_cast<float>(window_w) - static_cast<float>(overlay.minimap.width()) - margin, margin, window_w, window_h);
+            this->mark_frame();
+            return true;
+        }
+
+        auto shutdown() -> void override {
+            if (detail::active_slot() == this) detail::active_slot() = nullptr;
+            if (detail::sink_slot() == this) detail::sink_slot() = nullptr;
+            if (context_ != 0) {
+                this->destroy_textures();
+                if (scene_program_ != 0U) glDeleteProgram(scene_program_);
+                if (terrain_program_ != 0U) glDeleteProgram(terrain_program_);
+                if (vao_ != 0U) glDeleteVertexArrays(1, &vao_);
+                emscripten_webgl_destroy_context(context_);
+            }
+            context_ = 0;
+            vao_ = 0U;
+            scene_program_ = terrain_program_ = 0U;
+            scene_rect_loc_ = terrain_cam_loc_ = terrain_height_loc_ = terrain_cell_loc_ = terrain_atlas_loc_ = -1;
+            terrain_ready_ = false;
+            scene_w_ = scene_h_ = 0U;
+            events_.clear();
+            held_.fill(false);
+        }
+
+        [[nodiscard]] auto name() const -> std::string_view override { return "wasmgl"; }
+
+        // ---- worker message entry points (see apps/web/openra3.worker.js) ----
+
+        /** A key down/up; `code` is a DOM `KeyboardEvent.code`. */
+        auto on_key(std::string_view code, bool down) -> void override {
+            if (const int index = detail::move_key_index(code); index >= 0) {
+                held_[static_cast<std::size_t>(index)] = down;
+            }
+            if (!down) return;
+            if (const auto key = detail::key_from_code(code); key != ra3::render::ui_key::none) {
+                ra3::render::ui_event out;
+                out.type = ra3::render::ui_event_type::key;
+                out.key = key;
+                events_.push_back(out);
+            }
+        }
+
+        /** A printable character (DOM `KeyboardEvent.charCode`). */
+        auto on_text(int codepoint) -> void override {
+            if (codepoint <= 0 || codepoint > 0x7F) return;
+            ra3::render::ui_event out;
+            out.type = ra3::render::ui_event_type::text;
+            out.character = static_cast<char>(codepoint);
+            events_.push_back(out);
+        }
+
+        auto on_mouse_button(double x, double y, bool left) -> void override {
+            ra3::render::ui_event out;
+            out.type = ra3::render::ui_event_type::mouse_button;
+            out.x = static_cast<float>(x);
+            out.y = static_cast<float>(y);
+            out.left = left;
+            events_.push_back(out);
+        }
+
+        auto on_mouse_move(double x, double y, double dx, double dy, bool left) -> void override {
+            ra3::render::ui_event out;
+            out.type = ra3::render::ui_event_type::mouse_move;
+            out.x = static_cast<float>(x);
+            out.y = static_cast<float>(y);
+            out.dx = static_cast<float>(dx);
+            out.dy = static_cast<float>(dy);
+            out.left = left;
+            events_.push_back(out);
+        }
+
+        auto on_wheel(double delta_y) -> void override {
+            ra3::render::ui_event out;
+            out.type = ra3::render::ui_event_type::wheel;
+            out.wheel = static_cast<float>(-delta_y); // browser +Y is scroll-down; SDL +Y is scroll-up.
+            events_.push_back(out);
+        }
+
+        auto on_quit() -> void override {
+            ra3::render::ui_event out;
+            out.type = ra3::render::ui_event_type::quit;
+            events_.push_back(out);
+        }
+
+        /** Resize the drawing buffer (backing pixels, already DPR-scaled). */
+        auto on_resize(int width, int height) -> void override {
+            if (width > 0 && height > 0) emscripten_set_canvas_element_size("#canvas", width, height);
+        }
+
+    private:
+        // ---- GL helpers ------------------------------------------------------
+
+        [[nodiscard]] auto compile(unsigned type, const char *source, std::string_view what) -> GLuint {
+            const GLuint shader = glCreateShader(type);
+            glShaderSource(shader, 1, &source, nullptr);
+            glCompileShader(shader);
+            GLint ok = GL_FALSE;
+            glGetShaderiv(shader, GL_COMPILE_STATUS, &ok);
+            if (ok == GL_FALSE) {
+                std::array<char, 1024> log{};
+                glGetShaderInfoLog(shader, static_cast<GLsizei>(log.size()), nullptr, log.data());
+                ender::log::error(std::format("ra3.wasmgl: {} shader compile failed: {}", what, log.data()));
+                glDeleteShader(shader);
+                return 0U;
+            }
+            return shader;
+        }
+
+        [[nodiscard]] auto link(const char *vertex, const char *fragment, std::string_view what) -> GLuint {
+            const GLuint vs = this->compile(GL_VERTEX_SHADER, vertex, what);
+            const GLuint fs = this->compile(GL_FRAGMENT_SHADER, fragment, what);
+            if (vs == 0U || fs == 0U) {
+                if (vs != 0U) glDeleteShader(vs);
+                if (fs != 0U) glDeleteShader(fs);
+                return 0U;
+            }
+            const GLuint program = glCreateProgram();
+            glAttachShader(program, vs);
+            glAttachShader(program, fs);
+            glLinkProgram(program);
+            glDeleteShader(vs);
+            glDeleteShader(fs);
+            GLint ok = GL_FALSE;
+            glGetProgramiv(program, GL_LINK_STATUS, &ok);
+            if (ok == GL_FALSE) {
+                std::array<char, 1024> log{};
+                glGetProgramInfoLog(program, static_cast<GLsizei>(log.size()), nullptr, log.data());
+                ender::log::error(std::format("ra3.wasmgl: {} program link failed: {}", what, log.data()));
+                glDeleteProgram(program);
+                return 0U;
+            }
+            return program;
+        }
+
+        [[nodiscard]] auto create_scene_pipeline() -> bool {
+            scene_program_ = this->link(ra3_shaders::webgl_scene_vert_glsl, ra3_shaders::webgl_scene_frag_glsl, "scene");
+            if (scene_program_ == 0U) return false;
+            scene_rect_loc_ = glGetUniformLocation(scene_program_, "u_rect");
+            glUseProgram(scene_program_);
+            glUniform1i(glGetUniformLocation(scene_program_, "u_scene"), 0);
+            return true;
+        }
+
+        [[nodiscard]] auto create_terrain_pipeline() -> bool {
+            terrain_program_ = this->link(ra3_shaders::webgl_terrain_vert_glsl, ra3_shaders::webgl_terrain_frag_glsl, "terrain");
+            if (terrain_program_ == 0U) return false;
+            terrain_cam_loc_ = glGetUniformLocation(terrain_program_, "u_data");
+            terrain_height_loc_ = glGetUniformLocation(terrain_program_, "u_heightmap");
+            terrain_cell_loc_ = glGetUniformLocation(terrain_program_, "u_celldata");
+            terrain_atlas_loc_ = glGetUniformLocation(terrain_program_, "u_atlas");
+            return true;
+        }
+
+        /** (Re)create the 2D texture used by the scene/overlay path. */
+        auto make_texture2d(GLuint &texture, GLint internal, GLenum format, GLenum type, int w, int h, const void *data, bool linear,
+                            bool wrap) -> void {
+            if (texture == 0U) glGenTextures(1, &texture);
+            glBindTexture(GL_TEXTURE_2D, texture);
+            glPixelStorei(GL_UNPACK_ALIGNMENT, 1);
+            glTexImage2D(GL_TEXTURE_2D, 0, internal, w, h, 0, format, type, data);
+            if (const GLenum error = glGetError(); error != GL_NO_ERROR) {
+                ender::log::error(std::format("ra3.wasmgl: texImage2D failed: internal=0x{:X} format=0x{:X} type=0x{:X} size={}x{} err=0x{:X}",
+                                              static_cast<unsigned>(internal), static_cast<unsigned>(format), static_cast<unsigned>(type), w, h,
+                                              static_cast<unsigned>(error)));
+            }
+            glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, linear ? GL_LINEAR : GL_NEAREST);
+            glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, linear ? GL_LINEAR : GL_NEAREST);
+            glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, wrap ? GL_REPEAT : GL_CLAMP_TO_EDGE);
+            glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, wrap ? GL_REPEAT : GL_CLAMP_TO_EDGE);
+        }
+
+        auto upload_scene(const ra3::render::image &frame) -> void {
+            // The image is 0xAARRGGBB (BGRA in memory); store it as RGBA and let
+            // the shader swizzle `.bgra`.
+            this->make_texture2d(scene_tex_, GL_RGBA8, GL_RGBA, GL_UNSIGNED_BYTE, static_cast<int>(frame.width()),
+                                 static_cast<int>(frame.height()), frame.data(), true, false);
+            scene_w_ = frame.width();
+            scene_h_ = frame.height();
+        }
+
+        auto upload_overlay(GLuint &texture, const ra3::render::image &source) -> void {
+            if (source.empty()) return;
+            this->make_texture2d(texture, GL_RGBA8, GL_RGBA, GL_UNSIGNED_BYTE, static_cast<int>(source.width()),
+                                 static_cast<int>(source.height()), source.data(), true, false);
+        }
+
+        [[nodiscard]] auto create_terrain_textures(const ra3::terrain::gpu_terrain &terrain) -> bool {
+            this->make_texture2d(height_tex_, GL_R16, GL_RED, GL_UNSIGNED_SHORT, static_cast<int>(terrain.width),
+                                 static_cast<int>(terrain.height), terrain.heights.data(), false, false);
+            this->make_texture2d(cell_tex_, GL_RGBA16, GL_RGBA, GL_UNSIGNED_SHORT, static_cast<int>(terrain.width),
+                                 static_cast<int>(terrain.height), terrain.cell_data.data(), false, false);
+            if (atlas_tex_ == 0U) glGenTextures(1, &atlas_tex_);
+            glBindTexture(GL_TEXTURE_2D_ARRAY, atlas_tex_);
+            glPixelStorei(GL_UNPACK_ALIGNMENT, 1);
+            glTexImage3D(GL_TEXTURE_2D_ARRAY, 0, GL_RGBA8, static_cast<GLsizei>(terrain.layer_size), static_cast<GLsizei>(terrain.layer_size),
+                         static_cast<GLsizei>(terrain.layer_count), 0, GL_RGBA, GL_UNSIGNED_BYTE, terrain.layers.data());
+            glTexParameteri(GL_TEXTURE_2D_ARRAY, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
+            glTexParameteri(GL_TEXTURE_2D_ARRAY, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
+            glTexParameteri(GL_TEXTURE_2D_ARRAY, GL_TEXTURE_WRAP_S, GL_REPEAT);
+            glTexParameteri(GL_TEXTURE_2D_ARRAY, GL_TEXTURE_WRAP_T, GL_REPEAT);
+            return true;
+        }
+
+        auto destroy_textures() -> void {
+            for (GLuint *texture: {&scene_tex_, &height_tex_, &cell_tex_, &atlas_tex_, &label_tex_, &minimap_tex_}) {
+                if (*texture != 0U) glDeleteTextures(1, texture);
+                *texture = 0U;
+            }
+        }
+
+        /** Publish a coarse frame counter to the page for the fps probe. */
+        auto mark_frame() const -> void {
+            ++frames_;
+            if (frames_ % 15U == 0U) {
+                EM_ASM({ self.postMessage({ openra3Frames: $0 }); }, static_cast<int>(frames_));
+            }
+        }
+
+        auto draw_fullscreen(GLuint program, GLint rect_location, GLuint texture, const ra3::render::view_rect &dest, int window_w, int window_h)
+            -> void {
+            glUseProgram(program);
+            glBindVertexArray(vao_);
+            const float rect[4] = {dest.x / static_cast<float>(window_w), dest.y / static_cast<float>(window_h),
+                                   dest.w / static_cast<float>(window_w), dest.h / static_cast<float>(window_h)};
+            glUniform4fv(rect_location, 1, rect);
+            glActiveTexture(GL_TEXTURE0);
+            glBindTexture(GL_TEXTURE_2D, texture);
+            glDrawArrays(GL_TRIANGLES, 0, 3);
+        }
+
+        auto draw_overlay(GLuint texture, core::uint32 w, core::uint32 h, float x, float y, int window_w, int window_h) -> void {
+            if (texture == 0U || w == 0U || h == 0U) return;
+            const ra3::render::view_rect rect{x, y, static_cast<float>(w), static_cast<float>(h)};
+            this->draw_fullscreen(scene_program_, scene_rect_loc_, texture, rect, window_w, window_h);
+        }
+
+        EMSCRIPTEN_WEBGL_CONTEXT_HANDLE context_ = 0;
+        GLuint vao_ = 0U;
+
+        GLuint scene_program_ = 0U;
+        GLint scene_rect_loc_ = -1;
+        GLuint terrain_program_ = 0U;
+        GLint terrain_cam_loc_ = -1;
+        GLint terrain_height_loc_ = -1;
+        GLint terrain_cell_loc_ = -1;
+        GLint terrain_atlas_loc_ = -1;
+
+        GLuint scene_tex_ = 0U;
+        core::uint32 scene_w_ = 0U;
+        core::uint32 scene_h_ = 0U;
+        bool terrain_ready_ = false;
+        GLuint height_tex_ = 0U;
+        GLuint cell_tex_ = 0U;
+        GLuint atlas_tex_ = 0U;
+        GLuint label_tex_ = 0U;
+        GLuint minimap_tex_ = 0U;
+
+        std::deque<ra3::render::ui_event> events_;
+        std::array<bool, static_cast<std::size_t>(detail::move_key::count)> held_{};
+        mutable unsigned frames_ = 0U;
+    };
+
+    // ---- C API called by apps/web/openra3.worker.js --------------------------
+
+    /** Key down/up: `code` is a DOM KeyboardEvent.code. */
+    inline auto post_key(const char *code, int down) -> void {
+        if (auto *sink = detail::sink_slot(); sink != nullptr) sink->on_key(code != nullptr ? code : "", down != 0);
+    }
+
+    /** Printable character (DOM charCode). */
+    inline auto post_text(int codepoint) -> void {
+        if (auto *sink = detail::sink_slot(); sink != nullptr) sink->on_text(codepoint);
+    }
+
+    inline auto post_mouse_button(double x, double y, int left) -> void {
+        if (auto *sink = detail::sink_slot(); sink != nullptr) sink->on_mouse_button(x, y, left != 0);
+    }
+
+    inline auto post_mouse_move(double x, double y, double dx, double dy, int left) -> void {
+        if (auto *sink = detail::sink_slot(); sink != nullptr) sink->on_mouse_move(x, y, dx, dy, left != 0);
+    }
+
+    inline auto post_wheel(double delta_y) -> void {
+        if (auto *sink = detail::sink_slot(); sink != nullptr) sink->on_wheel(delta_y);
+    }
+
+    inline auto post_resize(int width, int height) -> void {
+        if (auto *sink = detail::sink_slot(); sink != nullptr) sink->on_resize(width, height);
+    }
+
+    inline auto post_quit() -> void {
+        if (auto *sink = detail::sink_slot(); sink != nullptr) sink->on_quit();
+    }
+} // namespace ra3::wasmgl
+
+extern "C" {
+EMSCRIPTEN_KEEPALIVE inline auto openra3_key(const char *code, int down) -> void { ra3::wasmgl::post_key(code, down); }
+EMSCRIPTEN_KEEPALIVE inline auto openra3_text(int codepoint) -> void { ra3::wasmgl::post_text(codepoint); }
+EMSCRIPTEN_KEEPALIVE inline auto openra3_mouse_button(double x, double y, int left) -> void { ra3::wasmgl::post_mouse_button(x, y, left); }
+EMSCRIPTEN_KEEPALIVE inline auto openra3_mouse_move(double x, double y, double dx, double dy, int left) -> void {
+    ra3::wasmgl::post_mouse_move(x, y, dx, dy, left);
+}
+EMSCRIPTEN_KEEPALIVE inline auto openra3_wheel(double delta_y) -> void { ra3::wasmgl::post_wheel(delta_y); }
+EMSCRIPTEN_KEEPALIVE inline auto openra3_resize(int width, int height) -> void { ra3::wasmgl::post_resize(width, height); }
+EMSCRIPTEN_KEEPALIVE inline auto openra3_quit() -> void { ra3::wasmgl::post_quit(); }
+}

src/wasmgl/ra3.wasmgl.null.cppm

@@ -0,0 +1,32 @@
+export module ra3.wasmgl;
+
+import std;
+
+export import ra3.core;
+import ra3.render;
+import ra3.client;
+
+/**
+ * Fallback wasm-worker WebGL backend for builds without Emscripten. `init` fails
+ * so the caller can select another display; the class name matches the real
+ * `ra3.wasmgl` module so the backend factory in `ra3.display` compiles
+ * unchanged.
+ */
+export namespace ra3::wasmgl {
+    /** No-op off Emscripten (there is no Emscripten virtual filesystem). */
+    inline auto mount_assets(const std::string & = "/assets.manifest.json", const std::string & = "/assets",
+                             const std::string & = "assets/") -> int {
+        return 0;
+    }
+
+    class wasmgl_display final : public ra3::client::display {
+    public:
+        [[nodiscard]] auto init(const ra3::client::display_options &) -> bool override { return false; }
+        [[nodiscard]] auto present(const ra3::render::image &, const ra3::render::view_rect &, bool) -> bool override { return false; }
+        [[nodiscard]] auto poll_event(ra3::render::ui_event &) -> bool override { return false; }
+        [[nodiscard]] auto window_size() const -> std::pair<int, int> override { return {0, 0}; }
+        [[nodiscard]] auto key_down(ra3::render::ui_key) const -> bool override { return false; }
+        auto shutdown() -> void override {}
+        [[nodiscard]] auto name() const -> std::string_view override { return "wasmgl(null)"; }
+    };
+}

src/webgpu/ra3.webgpu.cppm

@@ -0,0 +1,610 @@
+module;
+
+// Dawn's header-only C++ wrapper for the WebGPU C API, provided by Emscripten's
+// emdawnwebgpu port (`--use-port=emdawnwebgpu`). This backend is wasm-only: on
+// the web WebGPU accepts WGSL only (SPIR-V is not available), so the shaders are
+// WGSL ports of the Vulkan/WebGL ones rather than a reuse of the SPIR-V blobs.
+#include <webgpu/webgpu_cpp.h>
+
+#include <emscripten/em_asm.h>
+#include <emscripten/emscripten.h>
+#include <emscripten/html5.h>
+
+#include "webgpu_wgsl_embedded.hpp"
+
+export module ra3.webgpu;
+
+import std;
+
+export import ra3.core;
+export import ra3.render;
+export import ra3.terrain;
+export import ra3.client;
+import ra3.wasmgl;
+import ender.log;
+
+/**
+ * A WebGPU presentation backend for the wasm build, a peer of `ra3.wasmgl`.
+ *
+ * It runs in the same plain Web Worker and draws into the same transferred
+ * OffscreenCanvas, but through WebGPU: a surface is created on `#canvas`, a
+ * swapchain image is acquired each frame and presented. The uniform layout and
+ * the terrain data plumbing are shared with the Vulkan/WebGL backends
+ * (`terrain_uniforms`); only the API calls and the WGSL shaders differ.
+ *
+ * It reuses `ra3.wasmgl`'s `event_sink` so the page/worker input protocol is the
+ * same for both wasm backends.
+ */
+export namespace ra3::webgpu {
+    class webgpu_display final : public ra3::client::display, public ra3::wasmgl::event_sink {
+    public:
+        webgpu_display() = default;
+        webgpu_display(const webgpu_display &) = delete;
+        auto operator=(const webgpu_display &) -> webgpu_display & = delete;
+        ~webgpu_display() override { this->shutdown(); }
+
+        [[nodiscard]] auto init(const ra3::client::display_options &options) -> bool override {
+            this->fps_limit_ = options.fps_limit;
+            wgpu::Device device(emscripten_webgpu_get_device());
+            if (device == nullptr) {
+                ender::log::warn("ra3.webgpu: no preinitialized WebGPU device");
+                return false;
+            }
+            device_ = std::move(device);
+            queue_ = device_.GetQueue();
+            instance_ = wgpu::CreateInstance();
+            if (instance_ == nullptr) {
+                ender::log::warn("ra3.webgpu: wgpuCreateInstance failed");
+                return false;
+            }
+
+            wgpu::EmscriptenSurfaceSourceCanvasHTMLSelector selector;
+            selector.selector = "#canvas";
+            // There is no DOM in the worker, so Emscripten's canvas lookup cannot
+            // find #canvas by CSS selector; register the transferred OffscreenCanvas
+            // (Module.canvas) as a special target for `wgpuInstanceCreateSurface`.
+            EM_ASM({
+                if (typeof specialHTMLTargets !== 'undefined' && Module['canvas']) {
+                    specialHTMLTargets['#canvas'] = Module['canvas'];
+                }
+            });
+            wgpu::SurfaceDescriptor surface_descriptor;
+            surface_descriptor.nextInChain = &selector;
+            surface_ = instance_.CreateSurface(&surface_descriptor);
+            if (surface_ == nullptr) {
+                ender::log::warn("ra3.webgpu: CreateSurface failed (is #canvas an OffscreenCanvas?)");
+                return false;
+            }
+
+            if (!this->create_pipelines()) {
+                ender::log::warn("ra3.webgpu: pipeline creation failed");
+                this->shutdown();
+                return false;
+            }
+            const auto [width, height] = this->window_size();
+            this->configure(width > 0 ? width : options.width, height > 0 ? height : options.height);
+            ra3::wasmgl::set_event_sink(this);
+            ender::log::info("ra3.webgpu: WebGPU backend initialized");
+            return true;
+        }
+
+        [[nodiscard]] auto present(const ra3::render::image &frame, const ra3::render::view_rect &dest, bool changed) -> bool override {
+            if (frame.empty()) return false;
+            if (changed || !scene_.texture || static_cast<int>(frame.width()) != scene_.width || static_cast<int>(frame.height()) != scene_.height) {
+                this->upload_image(scene_, frame);
+            }
+            const auto [window_w, window_h] = this->window_size();
+            if (window_w <= 0 || window_h <= 0) return true;
+            return this->draw({0.05F, 0.06F, 0.08F, 1.0F}, [&](wgpu::RenderPassEncoder &pass, int w, int h) {
+                this->draw_image(pass, scene_, dest, w, h);
+            });
+        }
+
+        [[nodiscard]] auto poll_event(ra3::render::ui_event &out) -> bool override {
+            if (events_.empty()) return false;
+            out = events_.front();
+            events_.pop_front();
+            return true;
+        }
+
+        [[nodiscard]] auto window_size() const -> std::pair<int, int> override {
+            int w = 0;
+            int h = 0;
+            if (emscripten_get_canvas_element_size("#canvas", &w, &h) != EMSCRIPTEN_RESULT_SUCCESS) return {0, 0};
+            return {w, h};
+        }
+
+        [[nodiscard]] auto key_down(ra3::render::ui_key key) const -> bool override {
+            const auto held = [this](ra3::wasmgl::detail::move_key which) { return held_[static_cast<std::size_t>(which)]; };
+            switch (key) {
+            case ra3::render::ui_key::up: return held(ra3::wasmgl::detail::move_key::w) || held(ra3::wasmgl::detail::move_key::arrow_up);
+            case ra3::render::ui_key::down: return held(ra3::wasmgl::detail::move_key::s) || held(ra3::wasmgl::detail::move_key::arrow_down);
+            case ra3::render::ui_key::left: return held(ra3::wasmgl::detail::move_key::a) || held(ra3::wasmgl::detail::move_key::arrow_left);
+            case ra3::render::ui_key::right: return held(ra3::wasmgl::detail::move_key::d) || held(ra3::wasmgl::detail::move_key::arrow_right);
+            default: return false;
+            }
+        }
+
+        [[nodiscard]] auto supports_terrain() const -> bool override { return true; }
+
+        [[nodiscard]] auto present_terrain(const ra3::terrain::gpu_terrain &terrain, const ra3::render::camera3d &camera, float time_s,
+                                           const ra3::client::terrain_overlay &overlay) -> bool override {
+            if (!terrain_ready_) {
+                if (!this->create_terrain(terrain)) return false;
+                terrain_ready_ = true;
+                ender::log::info(std::format("ra3.webgpu: terrain ready ({}x{}, {} layers)", terrain.width, terrain.height, terrain.layer_count));
+            }
+            if (overlay.label_changed) this->upload_image(label_, overlay.label);
+            if (overlay.minimap_changed) this->upload_image(minimap_, overlay.minimap);
+
+            const auto [window_w, window_h] = this->window_size();
+            if (window_w <= 0 || window_h <= 0) return true;
+            const auto aspect = static_cast<float>(window_w) / static_cast<float>(std::max(1, window_h));
+            const auto uniforms = detail_uniforms(terrain, camera, time_s, aspect);
+            queue_.WriteBuffer(terrain_.ubo, 0, uniforms.data(), uniforms.size() * sizeof(float));
+
+            const float margin = 12.0F;
+            return this->draw({0.45F, 0.55F, 0.70F, 1.0F}, [&](wgpu::RenderPassEncoder &pass, int w, int h) {
+                pass.SetPipeline(terrain_.pipeline);
+                pass.SetBindGroup(0, terrain_.bind_group);
+                pass.Draw(3);
+                this->draw_image(pass, label_, {margin, margin, static_cast<float>(label_.width), static_cast<float>(label_.height)}, w, h);
+                this->draw_image(pass, minimap_, {static_cast<float>(w) - static_cast<float>(minimap_.width) - margin, margin,
+                                                  static_cast<float>(minimap_.width), static_cast<float>(minimap_.height)},
+                                 w, h);
+            });
+        }
+
+        auto shutdown() -> void override {
+            if (ra3::wasmgl::detail::sink_slot() == this) ra3::wasmgl::set_event_sink(nullptr);
+            terrain_ready_ = false;
+            scene_ = {};
+            label_ = {};
+            minimap_ = {};
+            terrain_ = {};
+            surface_ = nullptr;
+            queue_ = nullptr;
+            device_ = nullptr;
+            instance_ = nullptr;
+            events_.clear();
+            held_.fill(false);
+        }
+
+        [[nodiscard]] auto name() const -> std::string_view override { return "webgpu"; }
+
+        // ---- worker input (ra3.wasmgl::event_sink) ---------------------------
+
+        auto on_key(std::string_view code, bool down) -> void override {
+            if (const int index = ra3::wasmgl::detail::move_key_index(code); index >= 0) {
+                held_[static_cast<std::size_t>(index)] = down;
+            }
+            if (!down) return;
+            if (const auto key = ra3::wasmgl::detail::key_from_code(code); key != ra3::render::ui_key::none) {
+                push_key(key);
+            }
+        }
+
+        auto on_text(int codepoint) -> void override {
+            if (codepoint <= 0 || codepoint > 0x7F) return;
+            ra3::render::ui_event out;
+            out.type = ra3::render::ui_event_type::text;
+            out.character = static_cast<char>(codepoint);
+            events_.push_back(out);
+        }
+
+        auto on_mouse_button(double x, double y, bool left) -> void override {
+            ra3::render::ui_event out;
+            out.type = ra3::render::ui_event_type::mouse_button;
+            out.x = static_cast<float>(x);
+            out.y = static_cast<float>(y);
+            out.left = left;
+            events_.push_back(out);
+        }
+
+        auto on_mouse_move(double x, double y, double dx, double dy, bool left) -> void override {
+            ra3::render::ui_event out;
+            out.type = ra3::render::ui_event_type::mouse_move;
+            out.x = static_cast<float>(x);
+            out.y = static_cast<float>(y);
+            out.dx = static_cast<float>(dx);
+            out.dy = static_cast<float>(dy);
+            out.left = left;
+            events_.push_back(out);
+        }
+
+        auto on_wheel(double delta_y) -> void override {
+            ra3::render::ui_event out;
+            out.type = ra3::render::ui_event_type::wheel;
+            out.wheel = static_cast<float>(-delta_y);
+            events_.push_back(out);
+        }
+
+        auto on_quit() -> void override {
+            ra3::render::ui_event out;
+            out.type = ra3::render::ui_event_type::quit;
+            events_.push_back(out);
+        }
+
+        auto on_resize(int width, int height) -> void override {
+            if (width > 0 && height > 0) emscripten_set_canvas_element_size("#canvas", width, height);
+        }
+
+    private:
+        /** A drawn image: its texture, uniform rect buffer and bind group. */
+        struct image_target {
+            wgpu::Texture texture;
+            wgpu::TextureView view;
+            wgpu::Buffer ubo;
+            wgpu::BindGroup bind_group;
+            int width = 0;
+            int height = 0;
+            int tex_width = 0;
+            int tex_height = 0;
+        };
+
+        struct terrain_target {
+            wgpu::RenderPipeline pipeline;
+            wgpu::Buffer ubo;
+            wgpu::Texture height;
+            wgpu::Texture cell;
+            wgpu::Texture atlas;
+            wgpu::TextureView height_view;
+            wgpu::TextureView cell_view;
+            wgpu::TextureView atlas_view;
+            wgpu::BindGroup bind_group;
+        };
+
+        static auto detail_uniforms(const ra3::terrain::gpu_terrain &terrain, const ra3::render::camera3d &camera, float time_s, float aspect)
+            -> std::array<float, 20> {
+            return {camera.target_x,
+                    camera.target_y,
+                    camera.yaw,
+                    camera.height,
+                    camera.pitch,
+                    camera.fov,
+                    terrain.water_z,
+                    terrain.has_water ? 1.0F : 0.0F,
+                    0.45F,
+                    0.35F,
+                    0.82F,
+                    0.38F,
+                    static_cast<float>(terrain.width),
+                    static_cast<float>(terrain.height),
+                    0.0F,
+                    terrain.z_scale,
+                    time_s,
+                    0.0F,
+                    terrain.cell_span,
+                    aspect};
+        }
+
+        auto push_key(ra3::render::ui_key key) -> void {
+            ra3::render::ui_event out;
+            out.type = ra3::render::ui_event_type::key;
+            out.key = key;
+            events_.push_back(out);
+        }
+
+        [[nodiscard]] auto make_shader(const char *wgsl) -> wgpu::ShaderModule {
+            wgpu::ShaderSourceWGSL source;
+            source.code = wgsl;
+            wgpu::ShaderModuleDescriptor descriptor;
+            descriptor.nextInChain = &source;
+            return device_.CreateShaderModule(&descriptor);
+        }
+
+        [[nodiscard]] auto create_pipelines() -> bool {
+            scene_shader_ = this->make_shader(ra3_shaders::webgpu_scene_wgsl);
+            terrain_shader_ = this->make_shader(ra3_shaders::webgpu_terrain_wgsl);
+            if (scene_shader_ == nullptr || terrain_shader_ == nullptr) {
+                ender::log::warn(std::format("ra3.webgpu: shader module creation failed (scene={} terrain={})",
+                                             scene_shader_ != nullptr, terrain_shader_ != nullptr));
+                return false;
+            }
+
+            wgpu::SamplerDescriptor clamp_desc;
+            clamp_desc.addressModeU = wgpu::AddressMode::ClampToEdge;
+            clamp_desc.addressModeV = wgpu::AddressMode::ClampToEdge;
+            clamp_desc.magFilter = wgpu::FilterMode::Linear;
+            clamp_desc.minFilter = wgpu::FilterMode::Linear;
+            clamp_desc.lodMaxClamp = 32.0F;
+            clamp_sampler_ = device_.CreateSampler(&clamp_desc);
+
+            wgpu::SamplerDescriptor repeat_desc = clamp_desc;
+            repeat_desc.addressModeU = wgpu::AddressMode::Repeat;
+            repeat_desc.addressModeV = wgpu::AddressMode::Repeat;
+            repeat_sampler_ = device_.CreateSampler(&repeat_desc);
+
+            // Scene: uniform(rect) + texture + sampler.
+            wgpu::BindGroupLayoutEntry scene_entries[3] = {};
+            scene_entries[0].binding = 0;
+            scene_entries[0].visibility = wgpu::ShaderStage::Vertex | wgpu::ShaderStage::Fragment;
+            scene_entries[0].buffer.type = wgpu::BufferBindingType::Uniform;
+            scene_entries[0].buffer.minBindingSize = 16;
+            scene_entries[1].binding = 1;
+            scene_entries[1].visibility = wgpu::ShaderStage::Fragment;
+            scene_entries[1].texture.sampleType = wgpu::TextureSampleType::Float;
+            scene_entries[1].texture.viewDimension = wgpu::TextureViewDimension::e2D;
+            scene_entries[2].binding = 2;
+            scene_entries[2].visibility = wgpu::ShaderStage::Fragment;
+            scene_entries[2].sampler.type = wgpu::SamplerBindingType::Filtering;
+            wgpu::BindGroupLayoutDescriptor scene_layout_desc;
+            scene_layout_desc.entryCount = 3;
+            scene_layout_desc.entries = scene_entries;
+            scene_bind_group_layout_ = device_.CreateBindGroupLayout(&scene_layout_desc);
+
+            wgpu::PipelineLayoutDescriptor scene_pipeline_layout_desc;
+            scene_pipeline_layout_desc.bindGroupLayoutCount = 1;
+            scene_pipeline_layout_desc.bindGroupLayouts = &scene_bind_group_layout_;
+            scene_pipeline_layout_ = device_.CreatePipelineLayout(&scene_pipeline_layout_desc);
+            scene_pipeline_ = this->create_pipeline(scene_pipeline_layout_, scene_shader_, ra3_shaders::webgpu_scene_wgsl);
+            if (scene_pipeline_ == nullptr) {
+                ender::log::warn("ra3.webgpu: scene render pipeline creation failed");
+            }
+
+            // Terrain: uniform(data[5]) + R16Uint + RGBA16Uint + RGBA8 array + sampler.
+            wgpu::BindGroupLayoutEntry terrain_entries[5] = {};
+            terrain_entries[0].binding = 0;
+            terrain_entries[0].visibility = wgpu::ShaderStage::Fragment;
+            terrain_entries[0].buffer.type = wgpu::BufferBindingType::Uniform;
+            terrain_entries[0].buffer.minBindingSize = 80;
+            terrain_entries[1].binding = 1;
+            terrain_entries[1].visibility = wgpu::ShaderStage::Fragment;
+            terrain_entries[1].texture.sampleType = wgpu::TextureSampleType::Uint;
+            terrain_entries[1].texture.viewDimension = wgpu::TextureViewDimension::e2D;
+            terrain_entries[2].binding = 2;
+            terrain_entries[2].visibility = wgpu::ShaderStage::Fragment;
+            terrain_entries[2].texture.sampleType = wgpu::TextureSampleType::Uint;
+            terrain_entries[2].texture.viewDimension = wgpu::TextureViewDimension::e2D;
+            terrain_entries[3].binding = 3;
+            terrain_entries[3].visibility = wgpu::ShaderStage::Fragment;
+            terrain_entries[3].texture.sampleType = wgpu::TextureSampleType::Float;
+            terrain_entries[3].texture.viewDimension = wgpu::TextureViewDimension::e2DArray;
+            terrain_entries[4].binding = 4;
+            terrain_entries[4].visibility = wgpu::ShaderStage::Fragment;
+            terrain_entries[4].sampler.type = wgpu::SamplerBindingType::Filtering;
+            wgpu::BindGroupLayoutDescriptor terrain_layout_desc;
+            terrain_layout_desc.entryCount = 5;
+            terrain_layout_desc.entries = terrain_entries;
+            terrain_bind_group_layout_ = device_.CreateBindGroupLayout(&terrain_layout_desc);
+            return scene_pipeline_ != nullptr;
+        }
+
+        [[nodiscard]] auto create_pipeline(const wgpu::PipelineLayout &layout, const wgpu::ShaderModule &shader, const char *wgsl) -> wgpu::RenderPipeline {
+            (void) wgsl;
+            wgpu::ColorTargetState target;
+            target.format = surface_format_;
+            target.writeMask = wgpu::ColorWriteMask::All;
+            wgpu::FragmentState fragment;
+            fragment.module = shader;
+            fragment.entryPoint = "fs_main";
+            fragment.targetCount = 1;
+            fragment.targets = &target;
+            wgpu::RenderPipelineDescriptor descriptor;
+            descriptor.layout = layout;
+            descriptor.vertex.module = shader;
+            descriptor.vertex.entryPoint = "vs_main";
+            descriptor.primitive.topology = wgpu::PrimitiveTopology::TriangleList;
+            descriptor.fragment = &fragment;
+            descriptor.multisample.count = 1;
+            return device_.CreateRenderPipeline(&descriptor);
+        }
+
+        auto configure(int width, int height) -> void {
+            if (surface_ == nullptr || width <= 0 || height <= 0) return;
+            if (width == surface_w_ && height == surface_h_) return;
+            wgpu::SurfaceConfiguration config;
+            config.device = device_;
+            config.format = surface_format_;
+            config.usage = wgpu::TextureUsage::RenderAttachment;
+            config.width = static_cast<uint32_t>(width);
+            config.height = static_cast<uint32_t>(height);
+            config.presentMode = wgpu::PresentMode::Fifo;
+            surface_.Configure(&config);
+            surface_w_ = width;
+            surface_h_ = height;
+        }
+
+        auto make_target(image_target &target) -> void {
+            wgpu::BufferDescriptor ubo_desc;
+            ubo_desc.size = 16;
+            ubo_desc.usage = wgpu::BufferUsage::Uniform | wgpu::BufferUsage::CopyDst;
+            target.ubo = device_.CreateBuffer(&ubo_desc);
+        }
+
+        auto upload_image(image_target &target, const ra3::render::image &frame) -> void {
+            if (frame.empty()) return;
+            target.width = static_cast<int>(frame.width());
+            target.height = static_cast<int>(frame.height());
+            if (target.texture == nullptr || target.tex_width != target.width || target.tex_height != target.height) {
+                wgpu::TextureDescriptor descriptor;
+                descriptor.size = {frame.width(), frame.height(), 1};
+                descriptor.format = wgpu::TextureFormat::RGBA8Unorm;
+                descriptor.usage = wgpu::TextureUsage::TextureBinding | wgpu::TextureUsage::CopyDst;
+                descriptor.dimension = wgpu::TextureDimension::e2D;
+                descriptor.mipLevelCount = 1;
+                descriptor.sampleCount = 1;
+                target.texture = device_.CreateTexture(&descriptor);
+                target.view = target.texture.CreateView();
+                target.tex_width = target.width;
+                target.tex_height = target.height;
+                if (!target.ubo) this->make_target(target);
+                target.bind_group = this->make_image_bind_group(target);
+            }
+            wgpu::TexelCopyTextureInfo destination;
+            destination.texture = target.texture;
+            wgpu::TexelCopyBufferLayout layout;
+            layout.bytesPerRow = frame.width() * 4;
+            layout.rowsPerImage = frame.height();
+            wgpu::Extent3D size = {frame.width(), frame.height(), 1};
+            queue_.WriteTexture(&destination, frame.data(), static_cast<size_t>(frame.width()) * frame.height() * 4, &layout, &size);
+        }
+
+        [[nodiscard]] auto make_image_bind_group(image_target &target) -> wgpu::BindGroup {
+            wgpu::BindGroupEntry entries[3] = {};
+            entries[0].binding = 0;
+            entries[0].buffer = target.ubo;
+            entries[0].size = 16;
+            entries[1].binding = 1;
+            entries[1].textureView = target.view;
+            entries[2].binding = 2;
+            entries[2].sampler = clamp_sampler_;
+            wgpu::BindGroupDescriptor descriptor;
+            descriptor.layout = scene_bind_group_layout_;
+            descriptor.entryCount = 3;
+            descriptor.entries = entries;
+            return device_.CreateBindGroup(&descriptor);
+        }
+
+        auto draw_image(wgpu::RenderPassEncoder &pass, image_target &target, const ra3::render::view_rect &dest, int window_w, int window_h) -> void {
+            if (target.bind_group == nullptr || window_w <= 0 || window_h <= 0) return;
+            const float rect[4] = {dest.x / static_cast<float>(window_w), dest.y / static_cast<float>(window_h),
+                                   dest.w / static_cast<float>(window_w), dest.h / static_cast<float>(window_h)};
+            queue_.WriteBuffer(target.ubo, 0, rect, sizeof(rect));
+            pass.SetPipeline(scene_pipeline_);
+            pass.SetBindGroup(0, target.bind_group);
+            pass.Draw(3);
+        }
+
+        [[nodiscard]] auto create_terrain(const ra3::terrain::gpu_terrain &terrain) -> bool {
+            {
+                wgpu::BufferDescriptor descriptor;
+                descriptor.size = 80;
+                descriptor.usage = wgpu::BufferUsage::Uniform | wgpu::BufferUsage::CopyDst;
+                terrain_.ubo = device_.CreateBuffer(&descriptor);
+            }
+            terrain_.height = this->make_texture(wgpu::TextureFormat::R16Uint, terrain.width, terrain.height, 1);
+            terrain_.cell = this->make_texture(wgpu::TextureFormat::RGBA16Uint, terrain.width, terrain.height, 1);
+            terrain_.atlas = this->make_texture(wgpu::TextureFormat::RGBA8Unorm, terrain.layer_size, terrain.layer_size, terrain.layer_count);
+            terrain_.height_view = terrain_.height.CreateView();
+            terrain_.cell_view = terrain_.cell.CreateView();
+            terrain_.atlas_view = terrain_.atlas.CreateView();
+
+            this->write_texture(terrain_.height, terrain.heights.data(), terrain.width, terrain.height, 1, 2);
+            this->write_texture(terrain_.cell, terrain.cell_data.data(), terrain.width, terrain.height, 1, 8);
+            this->write_texture(terrain_.atlas, terrain.layers.data(), terrain.layer_size, terrain.layer_size, terrain.layer_count, 4);
+
+            wgpu::BindGroupEntry entries[5] = {};
+            entries[0].binding = 0;
+            entries[0].buffer = terrain_.ubo;
+            entries[0].size = 80;
+            entries[1].binding = 1;
+            entries[1].textureView = terrain_.height_view;
+            entries[2].binding = 2;
+            entries[2].textureView = terrain_.cell_view;
+            entries[3].binding = 3;
+            entries[3].textureView = terrain_.atlas_view;
+            entries[4].binding = 4;
+            entries[4].sampler = repeat_sampler_;
+            wgpu::BindGroupDescriptor bind_desc;
+            bind_desc.layout = terrain_bind_group_layout_;
+            bind_desc.entryCount = 5;
+            bind_desc.entries = entries;
+            terrain_.bind_group = device_.CreateBindGroup(&bind_desc);
+
+            terrain_.pipeline = this->create_pipeline(terrain_pipeline_layout(), terrain_shader_, ra3_shaders::webgpu_terrain_wgsl);
+            return terrain_.pipeline != nullptr && terrain_.bind_group != nullptr;
+        }
+
+        [[nodiscard]] auto terrain_pipeline_layout() -> wgpu::PipelineLayout {
+            if (terrain_pipeline_layout_ == nullptr) {
+                wgpu::PipelineLayoutDescriptor descriptor;
+                descriptor.bindGroupLayoutCount = 1;
+                descriptor.bindGroupLayouts = &terrain_bind_group_layout_;
+                terrain_pipeline_layout_ = device_.CreatePipelineLayout(&descriptor);
+            }
+            return terrain_pipeline_layout_;
+        }
+
+        [[nodiscard]] auto make_texture(wgpu::TextureFormat format, uint32_t width, uint32_t height, uint32_t layers) -> wgpu::Texture {
+            wgpu::TextureDescriptor descriptor;
+            descriptor.size = {width, height, layers};
+            descriptor.format = format;
+            descriptor.usage = wgpu::TextureUsage::TextureBinding | wgpu::TextureUsage::CopyDst;
+            descriptor.dimension = wgpu::TextureDimension::e2D;
+            descriptor.mipLevelCount = 1;
+            descriptor.sampleCount = 1;
+            return device_.CreateTexture(&descriptor);
+        }
+
+        auto write_texture(const wgpu::Texture &texture, const void *data, uint32_t width, uint32_t height, uint32_t layers, uint32_t bytes_per_pixel)
+            -> void {
+            wgpu::TexelCopyTextureInfo destination;
+            destination.texture = texture;
+            wgpu::TexelCopyBufferLayout layout;
+            layout.bytesPerRow = width * bytes_per_pixel;
+            layout.rowsPerImage = height;
+            wgpu::Extent3D size = {width, height, layers};
+            queue_.WriteTexture(&destination, data, static_cast<size_t>(width) * height * layers * bytes_per_pixel, &layout, &size);
+        }
+
+        /** Clear, run `record`, submit and present. */
+        template<typename Record>
+        [[nodiscard]] auto draw(std::array<float, 4> clear, Record &&record) -> bool {
+            const auto [window_w, window_h] = this->window_size();
+            this->configure(window_w, window_h);
+            wgpu::SurfaceTexture surface_texture;
+            surface_.GetCurrentTexture(&surface_texture);
+            if (surface_texture.status != wgpu::SurfaceGetCurrentTextureStatus::SuccessOptimal &&
+                surface_texture.status != wgpu::SurfaceGetCurrentTextureStatus::SuccessSuboptimal) {
+                return false;
+            }
+            wgpu::TextureView view = surface_texture.texture.CreateView();
+            wgpu::RenderPassColorAttachment color;
+            color.view = view;
+            color.depthSlice = 0xFFFFFFFFu; // kWGPU_DEPTH_SLICE_UNDEFINED
+            color.loadOp = wgpu::LoadOp::Clear;
+            color.storeOp = wgpu::StoreOp::Store;
+            color.clearValue = {clear[0], clear[1], clear[2], clear[3]};
+            wgpu::RenderPassDescriptor pass_desc;
+            pass_desc.colorAttachmentCount = 1;
+            pass_desc.colorAttachments = &color;
+            wgpu::CommandEncoder encoder = device_.CreateCommandEncoder();
+            wgpu::RenderPassEncoder pass = encoder.BeginRenderPass(&pass_desc);
+            record(pass, window_w, window_h);
+            pass.End();
+            wgpu::CommandBuffer commands = encoder.Finish();
+            queue_.Submit(1, &commands);
+            // WebGPU presents implicitly at the end of the frame; the port's
+            // wgpuSurfacePresent is intentionally unsupported.
+            this->mark_frame();
+            return true;
+        }
+
+        /** Publish a coarse frame counter to the page for the fps probe. */
+        auto mark_frame() const -> void {
+            ++frames_;
+            if (frames_ % 15U == 0U) {
+                EM_ASM({ self.postMessage({ openra3Frames: $0 }); }, static_cast<int>(frames_));
+            }
+        }
+
+        wgpu::Instance instance_;
+        wgpu::Device device_;
+        wgpu::Queue queue_;
+        wgpu::Surface surface_;
+        wgpu::TextureFormat surface_format_ = wgpu::TextureFormat::BGRA8Unorm;
+        int surface_w_ = 0;
+        int surface_h_ = 0;
+
+        wgpu::ShaderModule scene_shader_;
+        wgpu::ShaderModule terrain_shader_;
+        wgpu::BindGroupLayout scene_bind_group_layout_;
+        wgpu::BindGroupLayout terrain_bind_group_layout_;
+        wgpu::PipelineLayout scene_pipeline_layout_;
+        wgpu::PipelineLayout terrain_pipeline_layout_;
+        wgpu::RenderPipeline scene_pipeline_;
+        wgpu::Sampler clamp_sampler_;
+        wgpu::Sampler repeat_sampler_;
+
+        image_target scene_;
+        image_target label_;
+        image_target minimap_;
+        terrain_target terrain_;
+        bool terrain_ready_ = false;
+
+        std::deque<ra3::render::ui_event> events_;
+        std::array<bool, static_cast<std::size_t>(ra3::wasmgl::detail::move_key::count)> held_{};
+        mutable unsigned frames_ = 0U;
+    };
+}

src/webgpu/ra3.webgpu.null.cppm

@@ -0,0 +1,26 @@
+export module ra3.webgpu;
+
+import std;
+
+export import ra3.core;
+export import ra3.render;
+export import ra3.client;
+
+/**
+ * Fallback WebGPU backend for builds without Emscripten. `init` fails so the
+ * caller can select another display; the class name matches the real
+ * `ra3.webgpu` module so the backend factory in `ra3.display` compiles
+ * unchanged.
+ */
+export namespace ra3::webgpu {
+    class webgpu_display final : public ra3::client::display {
+    public:
+        [[nodiscard]] auto init(const ra3::client::display_options &) -> bool override { return false; }
+        [[nodiscard]] auto present(const ra3::render::image &, const ra3::render::view_rect &, bool) -> bool override { return false; }
+        [[nodiscard]] auto poll_event(ra3::render::ui_event &) -> bool override { return false; }
+        [[nodiscard]] auto window_size() const -> std::pair<int, int> override { return {0, 0}; }
+        [[nodiscard]] auto key_down(ra3::render::ui_key) const -> bool override { return false; }
+        auto shutdown() -> void override {}
+        [[nodiscard]] auto name() const -> std::string_view override { return "webgpu(null)"; }
+    };
+}

tests/ra3_tests.cpp

@@ -1,13 +1,6 @@
-#include <cstdint>
+import std;
-#include <cstdio>
-#include <filesystem>
-#include <fstream>
-#include <memory>
-#include <string>
-#include <string_view>
-#include <vector>
-
 import ra3;
+import ra3.assets;
 
 namespace {
     int failures = 0;
@@ -89,6 +82,25 @@ auto main() -> int {
 
     check(game::to_string(game::faction::soviet) == "Soviet", "faction names round-trip");
 
+    // RA3 data: damage types, armour resolution and weapon target masks.
+    check(data::to_string(data::damage_type::auto_cannon) == "AUTO_CANNON", "damage type names round-trip");
+    check(data::damage_type_from_name("PRISM") == data::damage_type::prism, "damage type parses from asset name");
+    check(data::allied_scout_infantry_armor.adjust(data::damage_type::gun, 100.0F) == 1.0F, "scout armour takes 1% from GUN");
+    check(data::allied_scout_infantry_armor.adjust(data::damage_type::tesla, 100.0F) == 50.0F, "scout armour takes 50% from TESLA");
+    check(data::allied_anti_infantry_infantry_armor.adjust(data::damage_type::tesla, 100.0F) == 1000.0F, "peacekeeper armour takes 10x from TESLA");
+    check(data::allied_anti_infantry_infantry_armor.adjust(data::damage_type::unresistable, 100.0F) == 100.0F, "UNRESISTABLE bypasses armour");
+    check(data::maul_weapon.can_target(data::target_class::infantry), "the maul can target infantry");
+    check(!data::maul_weapon.can_target(data::target_class::vehicle), "the maul cannot target vehicles");
+    check(!data::maul_weapon.can_target(data::target_class::structure), "the maul cannot target structures");
+    check(!data::maul_weapon.can_target(data::target_class::aircraft), "the maul cannot target aircraft");
+    check(data::shotgun_weapon.can_target(data::target_class::infantry) && data::shotgun_weapon.can_target(data::target_class::structure),
+          "the shotgun hits infantry and structures");
+    check(!data::shotgun_weapon.can_target(data::target_class::aircraft), "the shotgun cannot hit aircraft");
+    check(data::cost_of(data::entity_kind::guardian_tank) == 950, "guardian tank costs 950");
+    check(data::max_health_of(data::entity_kind::power_plant) == 1000.0F, "power plant has 1000 health");
+    check(data::structure_of(data::entity_kind::power_plant).energy == 100, "power plant supplies 100 energy");
+    check(data::seconds_to_frames(1.0F) == 30U, "one second is 30 logic frames");
+
     // RefPack: a literal-only stream decodes to its payload.
     const std::vector<core::uint8> refpack{0x10, 0xFB, 0x00, 0x00, 0x03, 0xFF, 'A', 'B', 'C'};
     check(fs::is_refpack(refpack), "literal RefPack stream is recognised");
@@ -128,11 +140,36 @@ auto main() -> int {
     const auto composed = render::compose(decoded_tga, markers, scene);
     check(composed.width() == 2U && composed.height() == 2U, "compose preserves size");
 
+    // Camera: wheel zoom, clamped pan and RA3-style edge scrolling.
+    render::view_camera camera;
+    camera.zoom = 2.0F;
+    camera.center_x = 0.5F;
+    camera.center_y = 0.5F;
+    camera.scroll(10.0F, 10.0F);
+    check(camera.center_x == 0.75F && camera.center_y == 0.75F, "camera clamps the centre to the map");
+    camera.zoom_by(100.0F);
+    check(camera.zoom == camera.max_zoom, "camera clamps the maximum zoom");
+    camera.zoom_by(0.001F);
+    check(camera.zoom == camera.min_zoom, "camera clamps the minimum zoom");
+    const auto fit_rect = camera.rect(512.0F, 512.0F, 1024.0F, 768.0F);
+    check(fit_rect.w == 768.0F && fit_rect.h == 768.0F && fit_rect.x == 128.0F && fit_rect.y == 0.0F, "camera letterboxes a square map into a wide window");
+
+    render::view_camera edge;
+    edge.zoom = 2.0F;
+    edge.center_x = 0.5F;
+    edge.center_y = 0.5F;
+    edge.edge_scroll(0.0F, 0.0F, 1024.0F, 768.0F, 1.0F);
+    check(edge.center_x < 0.5F && edge.center_y < 0.5F, "the cursor at the top-left edge scrolls up-left");
+    render::view_camera whole;
+    whole.edge_scroll(0.0F, 0.0F, 1024.0F, 768.0F, 1.0F);
+    check(whole.center_x == 0.5F && whole.center_y == 0.5F, "no edge scroll while the whole map fits");
+
     // Skirmish: deterministic, resolves within the frame cap.
     skirmish::match_config config;
     config.seed = 42U;
     const auto starts = skirmish::builtin_start_positions();
     auto first = skirmish::skirmish_match::create(config, starts);
+    check(first.unit_count(0U) == 1U && first.unit_count(1U) == 1U, "each side starts with a construction yard");
     const auto first_result = first.run();
     auto second = skirmish::skirmish_match::create(config, starts);
     const auto second_result = second.run();
@@ -140,6 +177,230 @@ auto main() -> int {
     check(first_result.winner == 0 || first_result.winner == 1, "skirmish has a winner");
     check(first_result.frames == second_result.frames && first_result.winner == second_result.winner, "skirmish is deterministic");
 
+    // Text/font: glyphs paint, spaces are blank and widths scale.
+    check(render::text_width("ABC", 2U) == 48U, "text width scales with glyph size");
+    render::image text_image(64U, 16U, render::black);
+    render::draw_text(text_image, 0, 0, "A", render::white, 2U);
+    int lit = 0;
+    for (std::size_t i = 0; i < 64U * 16U; ++i) {
+        if (text_image.data()[i] != render::black) ++lit;
+    }
+    check(lit > 0, "draw_text paints glyph pixels");
+    render::image space_image(64U, 16U, render::black);
+    render::draw_text(space_image, 0, 0, " ", render::white, 2U);
+    bool space_lit = false;
+    for (std::size_t i = 0; i < 64U * 16U; ++i) {
+        if (space_image.data()[i] != render::black) space_lit = true;
+    }
+    check(!space_lit, "a space paints nothing");
+
+    // FPS label: the active backend name is appended (e.g. `[vulkan]`).
+    const auto fps_label = render::compose_fps_label(155U, 0, "vulkan");
+    const auto fps_plain = render::compose_fps_label(155U, 0);
+    check(fps_label.width() > fps_plain.width(), "FPS label grows when the backend is shown");
+    check(fps_label.width() == render::text_width("FPS: 155/vsync [vulkan]") + 8U, "FPS label includes the backend name");
+
+    const auto box = render::fit_rect(1280.0F, 720.0F, 1920.0F, 1080.0F);
+    check(box.x == 0.0F && box.y == 0.0F && box.w == 1920.0F && box.h == 1080.0F, "fit_rect fills a same-aspect window");
+
+    // Map display names: decode a synthetic `gamestrings.csf` `MAP:` label.
+    std::vector<core::uint8> csf;
+    const auto put_le32 = [&csf](std::uint32_t v) {
+        for (int i = 0; i < 4; ++i) csf.push_back(static_cast<core::uint8>(v >> (8 * i)));
+    };
+    csf.insert(csf.end(), {' ', 'F', 'S', 'C'});
+    put_le32(3U);
+    put_le32(1U);
+    put_le32(1U);
+    for (int i = 0; i < 8; ++i) csf.push_back(0U);
+    csf.insert(csf.end(), {' ', 'L', 'B', 'L'});
+    put_le32(1U);
+    const std::string csf_label = "MAP:MAP_MP_2_FEASEL4";
+    put_le32(static_cast<std::uint32_t>(csf_label.size()));
+    csf.insert(csf.end(), csf_label.begin(), csf_label.end());
+    csf.insert(csf.end(), {' ', 'R', 'T', 'S'});
+    const std::string csf_value = "Battlebase Beta";
+    put_le32(static_cast<std::uint32_t>(csf_value.size()));
+    for (const auto ch: csf_value) {
+        csf.push_back(static_cast<core::uint8>(ch ^ 0xFF));
+        csf.push_back(0xFFU);
+    }
+    const auto names = map::parse_map_names(csf);
+    check(names.lookup("map_mp_2_feasel4") == "Battlebase Beta", "CSF map names decode (byte-XOR 0xFF)");
+    check(names.lookup("unknown_map") == "unknown_map", "an unknown id falls back to itself");
+
+    // Map objects (`ObjectsList`): decode a synthetic one-object chunk.
+    const auto put16 = [](std::vector<core::uint8> &out, std::uint16_t v) {
+        out.push_back(static_cast<core::uint8>(v));
+        out.push_back(static_cast<core::uint8>(v >> 8U));
+    };
+    const auto put32 = [](std::vector<core::uint8> &out, std::uint32_t v) {
+        for (int i = 0; i < 4; ++i) out.push_back(static_cast<core::uint8>(v >> (8 * i)));
+    };
+    const auto putf = [&put32](std::vector<core::uint8> &out, float f) {
+        std::uint32_t bits = 0;
+        std::memcpy(&bits, &f, sizeof(bits));
+        put32(out, bits);
+    };
+
+    std::vector<core::uint8> object_data;
+    putf(object_data, 100.0F);
+    putf(object_data, 200.0F);
+    putf(object_data, 0.0F);
+    putf(object_data, 0.5F);
+    put32(object_data, 0U); // road type
+    const std::string object_type = "BB_TEST";
+    put16(object_data, static_cast<std::uint16_t>(object_type.size()));
+    object_data.insert(object_data.end(), object_type.begin(), object_type.end());
+    put16(object_data, 0U); // no properties
+    std::vector<core::uint8> object_asset;
+    put32(object_asset, 1U); // asset index
+    put16(object_asset, 1U); // version
+    put32(object_asset, static_cast<std::uint32_t>(object_data.size()));
+    object_asset.insert(object_asset.end(), object_data.begin(), object_data.end());
+
+    std::vector<core::uint8> ckmp;
+    ckmp.insert(ckmp.end(), {'C', 'k', 'M', 'p'});
+    put32(ckmp, 1U); // one asset name
+    const std::string chunk_name = "ObjectsList";
+    ckmp.push_back(static_cast<core::uint8>(chunk_name.size()));
+    ckmp.insert(ckmp.end(), chunk_name.begin(), chunk_name.end());
+    put32(ckmp, 1U); // name index
+    put32(ckmp, 1U); // chunk index
+    put16(ckmp, 3U); // chunk version
+    put32(ckmp, static_cast<std::uint32_t>(object_asset.size()));
+    ckmp.insert(ckmp.end(), object_asset.begin(), object_asset.end());
+
+    const auto objects = map::parse_objects(ckmp);
+    check(objects.size() == 1U, "ObjectsList parses one object");
+    check(!objects.empty() && objects[0].type == "BB_TEST", "object type-name decodes");
+    check(!objects.empty() && objects[0].x == 100.0F && objects[0].y == 200.0F && objects[0].angle == 0.5F, "object position/angle decode");
+
+    // DDS: a 1x1 uncompressed RGB32 image decodes with correct channels.
+    std::vector<core::uint8> dds(128U, 0U);
+    dds[0] = 'D';
+    dds[1] = 'D';
+    dds[2] = 'S';
+    dds[3] = ' ';
+    const auto put_dds = [&dds](std::size_t off, std::uint32_t v) {
+        for (int i = 0; i < 4; ++i) dds[off + static_cast<std::size_t>(i)] = static_cast<core::uint8>(v >> (8 * i));
+    };
+    put_dds(4U, 124U);
+    put_dds(8U, 0x1U);       // flags: DDSD_CAPS|... (unused)
+    put_dds(12U, 1U);        // height
+    put_dds(16U, 1U);        // width
+    put_dds(76U, 32U);       // pixel format size
+    put_dds(80U, 0x40U);     // DDPF_RGB
+    put_dds(84U, 0U);        // no fourcc
+    put_dds(88U, 32U);       // bits per pixel
+    put_dds(92U, 0x00FF0000U);
+    put_dds(96U, 0x0000FF00U);
+    put_dds(100U, 0x000000FFU);
+    put_dds(104U, 0xFF000000U);
+    dds.push_back(0x00U); // B
+    dds.push_back(0x00U); // G
+    dds.push_back(0xFFU); // R
+    dds.push_back(0xFFU); // A
+    const auto decoded_dds = models::decode_dds(dds);
+    check(decoded_dds.width() == 1U && decoded_dds.height() == 1U, "DDS dimensions decode");
+    check(!decoded_dds.empty() && decoded_dds.data()[0] == render::argb(255, 0, 0), "DDS RGB32 channels map to ARGB");
+
+    check(models::decode_dds(std::vector<core::uint8>{1U, 2U, 3U}).empty(), "a non-DDS payload yields no image");
+
+    // Real-asset checks (opt-in): set OPENRA3_TEST_ASSETS to an extracted assets
+    // directory. They run the libra3assets-backed readers over the retail data and
+    // compare the map names against the golden `maps/map_names.tsv` written by the
+    // previous hand-rolled parser.
+    if (const char *assets_env = std::getenv("OPENRA3_TEST_ASSETS"); assets_env != nullptr && *assets_env != '\0') {
+        const std::filesystem::path assets{assets_env};
+        const auto read_all = [](const std::filesystem::path &path) {
+            std::ifstream in(path, std::ios::binary);
+            return std::vector<core::uint8>{std::istreambuf_iterator<char>(in), std::istreambuf_iterator<char>()};
+        };
+
+        const auto golden = assets / "maps" / "map_names.tsv";
+        // The golden table came from the newest `Lang-English<N>.big`; mirror that.
+        const auto pick_english_csf = [](const std::filesystem::path &raw) -> std::filesystem::path {
+            std::filesystem::path best;
+            int best_version = -1;
+            std::error_code ec;
+            for (const auto &entry: std::filesystem::directory_iterator(raw, ec)) {
+                if (!entry.is_directory()) continue;
+                const auto name = entry.path().filename().string();
+                if (name.rfind("Lang-English", 0) != 0) continue;
+                int version = 0;
+                try {
+                    version = std::stoi(name.substr(12));
+                } catch (const std::exception &) {
+                    continue;
+                }
+                if (version > best_version) {
+                    best_version = version;
+                    best = entry.path() / "data" / "gamestrings.csf";
+                }
+            }
+            if (!best.empty() && std::filesystem::exists(best)) return best;
+            return raw / "English" / "data" / "gamestrings.csf";
+        };
+        const auto csf_path = pick_english_csf(assets / "raw");
+        if (std::filesystem::exists(golden) && std::filesystem::exists(csf_path)) {
+            const auto table = map::parse_map_names(read_all(csf_path));
+            std::ifstream in(golden, std::ios::binary);
+            std::string line;
+            std::size_t matched = 0;
+            std::size_t mismatched = 0;
+            while (std::getline(in, line)) {
+                const auto tab = line.find('\t');
+                if (tab == std::string::npos) continue;
+                const auto id = line.substr(0, tab);
+                const auto expected = line.substr(tab + 1U);
+                if (table.lookup(id) == expected) {
+                    ++matched;
+                } else {
+                    ++mismatched;
+                    if (mismatched <= 5U) std::printf("  name mismatch %s: golden '%s' new '%s'\n", id.c_str(), expected.c_str(), table.lookup(id).c_str());
+                }
+            }
+            std::printf("  real CSF: %zu names, golden %zu matched, %zu mismatched\n", table.names.size(), matched, mismatched);
+            check(mismatched == 0U, "map names reproduce the golden map_names.tsv");
+        }
+
+        std::size_t maps_ok = 0;
+        std::size_t maps_bad = 0;
+        std::size_t library_starts = 0;
+        std::size_t no_starts = 0;
+        std::size_t roundtrip_bad = 0;
+        const auto to_bytes = [](std::span<const core::uint8> data) {
+            return std::span<const std::byte>{reinterpret_cast<const std::byte *>(data.data()), data.size()};
+        };
+        for (const auto &entry: std::filesystem::directory_iterator(assets / "maps")) {
+            if (!entry.is_regular_file() || entry.path().extension() != ".map") continue;
+            try {
+                const auto ckmp = map::to_ckmp(read_all(entry.path()));
+                const auto parsed = terrain::parse_map(ckmp);
+                const auto starts = map::starts_from_ckmp(ckmp);
+                const auto document = ra3::assets::map_document::parse(to_bytes(ckmp));
+                if (document.player_starts().size() >= 2U) ++library_starts; else ++no_starts;
+                if (!std::ranges::equal(document.to_ckmp(), to_bytes(ckmp))) ++roundtrip_bad;
+                if (parsed.width > 0U && parsed.height > 0U && parsed.elevations.size() == static_cast<std::size_t>(parsed.width) * parsed.height && starts.size() >= 2U) {
+                    ++maps_ok;
+                } else {
+                    ++maps_bad;
+                    if (maps_bad <= 5U)
+                        std::printf("  map oddity %s: %ux%u starts %zu\n", entry.path().filename().string().c_str(), parsed.width, parsed.height, starts.size());
+                }
+            } catch (const std::exception &error) {
+                ++maps_bad;
+                if (maps_bad <= 5U) std::printf("  map FAIL %s: %s\n", entry.path().filename().string().c_str(), error.what());
+            }
+        }
+        std::printf("  real maps: %zu ok, %zu bad; player_starts resolved %zu, unresolved %zu; round-trip mismatched %zu\n", maps_ok, maps_bad, library_starts,
+                    no_starts, roundtrip_bad);
+        check(maps_bad == 0U, "every extracted map parses terrain + starts through libra3assets");
+        check(no_starts == 0U, "libra3assets player_starts() resolves every retail map's start waypoints");
+        check(roundtrip_bad == 0U, "libra3assets re-serialises every retail map byte-for-byte");
+    }
+
     if (failures == 0) {
         std::puts("ra3_tests: OK");
     }

third_party/libenderlog/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EnderTheCoder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

third_party/libenderlog/README.md

@@ -0,0 +1,177 @@
+# libenderlog
+
+A standalone C++26 logging library, built as a C++20/26 **module** (`import ender.log;`)
+with **`std::stacktrace`** call-stack capture on severe records.
+
+It was extracted from the `ender-physics` engine, where it started life as
+`ender.log`, and turned into a library that has no other dependency — not on the
+engine, not on a logging framework.
+
+## Features
+
+- **Leveled records.** `trace`, `debug`, `info`, `warn`, `error`, `critical`,
+  filtered by an atomic `minimum` check that is cheap enough to guard expensive
+  message construction: `if (log::enabled(log::level::debug)) { ... }`.
+- **Source location.** Every record carries the file, line and function of the
+  caller, taken from `std::source_location` at the call site — exact even in a
+  stripped release binary, because it is a compile-time constant.
+- **Call stacks.** Records at or above `options::stacktrace_from` carry a
+  formatted `std::stacktrace`. The frames belonging to the library itself are
+  stripped by symbol, so the first reported frame is the caller regardless of
+  the optimisation level (the level wrappers get inlined away under `-O`).
+- **Pluggable sinks.** A `console_sink` (stderr by default) and a `memory_sink`
+  (for tests and in-game consoles) ship; `sink` is a small interface.
+- **File output with archiving.** `file_sink` writes to a file and, on open,
+  moves an existing log aside to a timestamped archive, so a run never appends
+  onto a previous run's log. It can also rotate by size, bound how many archives
+  are kept, and format both the record timestamp and the archive names.
+- **No stacktrace? No problem.** Where `<stacktrace>` is missing (libc++, and
+  therefore every cross target), the module still compiles and records still
+  carry their call site — they simply have no stack.
+
+## Requirements
+
+C++26 modules and `import std;` need a recent toolchain:
+
+| Requirement | Version |
+|---|---|
+| Compiler | **GCC 15+** (or Clang with a standard library that provides the `std` module) |
+| CMake | **3.30+** (for `CMAKE_EXPERIMENTAL_CXX_IMPORT_STD`) |
+| Standard library | libstdc++ for `std::stacktrace` |
+
+Ubuntu 26.04's default `g++` (GCC 15) and CMake 4 satisfy this, and that is the
+release the CI targets and the `.deb` is built for. Ubuntu 24.04 ships GCC 13 and
+CMake 3.28 and cannot build `import std;` without extra toolchains, so it is not
+supported.
+
+## Building
+
+```sh
+cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j
+ctest --test-dir build --output-on-failure
+```
+
+Options:
+
+| Option | Default | Description |
+|---|---|---|
+| `ENDERLOG_WERROR` | `OFF` | Treat warnings as errors |
+| `ENDERLOG_BACKTRACE_SYMBOLS` | `ON` | Link executables with `-rdynamic` so traces can name frames |
+| `ENDERLOG_BUILD_TESTS` | `ON` | Build the test suite |
+| `ENDERLOG_BUILD_EXAMPLES` | `ON` | Build the example program |
+
+Build Debug or RelWithDebInfo when you need to read a trace: frame names come
+from debug information, and a release build often reports application frames as
+`<unknown>`.
+
+## Using the library
+
+### `add_subdirectory`
+
+```cmake
+add_subdirectory(libenderlog)
+target_link_libraries(my_app PRIVATE enderlog::enderlog)
+```
+
+### Installed package
+
+```cmake
+find_package(enderlog REQUIRED)
+target_link_libraries(my_app PRIVATE enderlog::enderlog)
+```
+
+The static archive is installed together with the module interface source
+(`ender.log.cppm`) because a module's BMI is compiler-version-specific — the
+consumer rebuilds it from the source.
+
+### In code
+
+```cpp
+import std;
+import ender.log;
+
+namespace log = ender::log;
+
+auto main() -> int {
+    log::configure({.minimum = log::level::debug, .stacktrace_from = log::level::warn});
+
+    log::info(std::format("body {} moved to {:.2f}", 7, 12.35)); // formatted by the caller
+    log::error("a body left the world");                          // carries a stack trace
+}
+```
+
+Example output:
+
+```
+[2026-10-01 11:32:18] ERROR    example: a body left the world  (examples/main.cpp:8)
+    #0  simulate_one_step (examples/main.cpp:8)
+    #1  main (examples/main.cpp:20)
+    #2  <unknown>
+    #3  __libc_start_main
+    #4  _start
+```
+
+### Configuration
+
+```cpp
+log::configure({
+    .minimum = log::level::debug,          // drop everything below this
+    .stacktrace_from = log::level::error,  // capture a stack at/above this
+    .stacktrace_depth = 16,                // max frames kept
+    .stacktrace_skip = 2,                  // frames dropped before the caller is found
+});
+```
+
+`log::current_options()` reads it back, `log::add_sink(...)` adds a destination,
+and `log::set_sinks({...})` replaces them.
+
+### Writing to a file
+
+```cpp
+namespace log = ender::log;
+
+// Archive any existing enderlog.log to enderlog.<timestamp>.log, then start a
+// fresh file for this run. Rotate at 64 KiB and keep the last 5 archives.
+auto sink = log::add_file_sink("enderlog.log", {.max_file_size = 64 * 1024, .max_archives = 5});
+```
+
+- **No appending onto a previous run.** On open, an existing non-empty
+  `enderlog.log` is renamed to `enderlog.<timestamp>.log` before the new file is
+  created, so every run gets its own file and the previous run's log is
+  preserved. The timestamp is inserted before the extension, which stays last
+  (`.log` when the active file has none). A leftover empty file is simply
+  replaced.
+- `file_options::max_file_size` (0 disables) rotates the active file mid-run the
+  same way, and never archives an empty file. `file_options::max_archives`
+  (0 keeps all) deletes the oldest archives beyond the limit.
+- `file_options::flush_each_record` (on by default) flushes after every record so
+  a crash keeps the tail.
+- `file_options::timestamp_format` (chrono syntax, default `%Y-%m-%d %H:%M:%S`)
+  controls the timestamp on each record's header line;
+  `file_options::archive_time_format` (chrono syntax, default `%Y%m%d-%H%M%S`)
+  controls the timestamp inserted into archive names. A chrono format string must
+  begin with `%` (e.g. `%Y-%m-%d_%H%M%S`).
+- `add_file_sink` adds the sink to the global logger and returns it; `path()` and
+  `archives()` expose what it wrote. The `file_sink` class can also be used
+  directly and installed with `set_sinks`.
+
+## Packaging
+
+`cpack` produces a Debian package:
+
+```sh
+cmake -S . -B build -DENDERLOG_DISTRO=ubuntu26.04
+cmake --build build -j
+cd build
+cpack
+# -> libenderlog-dev_0.0.1_amd64_ubuntu26.04.deb
+```
+
+The package installs the static archive, the module interface source and the
+CMake package config. CI builds it for Ubuntu 26.04 and publishes it as a job
+artifact.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

third_party/libenderlog/src/ender.log.cppm

@@ -0,0 +1,573 @@
+/**
+ * Logging with call-stack capture.
+ *
+ * Records carry a level, message, source location and — for severe enough
+ * levels — a formatted `std::stacktrace`. Capturing a trace walks the stack and
+ * reads debug information, so it is only done when the record's level is at or
+ * above `options::stacktrace_from`, and the whole call is skipped when the
+ * level is disabled.
+ *
+ * `std::stacktrace` is implemented by libstdc++ only. With GCC the module has
+ * to link `stdc++exp` (the static library that implements it); the CMake target
+ * takes care of that. File and line numbers in the trace come from debug
+ * information, so build with `-g` (Debug or RelWithDebInfo) to see them; symbol
+ * names work in any build.
+ */
+module;
+
+// libc++ (the OpenRA3 toolchain) has no <stacktrace>, so this vendored copy adds
+// a native fallback for the frames: Windows CaptureStackBackTrace and POSIX
+// execinfo. These live in the global module fragment because they are C headers.
+#if defined(_WIN32)
+#define WIN32_LEAN_AND_MEAN
+#define NOMINMAX
+#include <windows.h>
+#elif (defined(__unix__) || defined(__APPLE__)) && !defined(__EMSCRIPTEN__)
+#include <execinfo.h>
+#endif
+
+export module ender.log;
+
+import std;
+
+export namespace ender::log {
+    /** Severity of a record, ordered from most to least verbose. */
+    enum class level: std::uint8_t {
+        trace = 0,
+        debug,
+        info,
+        warn,
+        error,
+        critical,
+    };
+
+    /** Short upper-case name of a level, for output. */
+    [[nodiscard]] inline auto to_string(const level severity) -> std::string_view {
+        switch (severity) {
+            case level::trace: return "TRACE";
+            case level::debug: return "DEBUG";
+            case level::info: return "INFO";
+            case level::warn: return "WARN";
+            case level::error: return "ERROR";
+            case level::critical: return "CRITICAL";
+        }
+        return "?";
+    }
+
+    /** Default timestamp rendered on a record, chrono format syntax. */
+    inline constexpr std::string_view default_time_format{"%Y-%m-%d %H:%M:%S"};
+
+    /** Logger configuration. */
+    struct options {
+        /** Records below this level are dropped before anything is built. */
+        level minimum{level::info};
+        /** Capture a stack trace for records at this level and above. */
+        level stacktrace_from{level::error};
+        /** Maximum number of frames kept in a captured trace. */
+        std::size_t stacktrace_depth{16};
+        /**
+         * Frames to drop from the top of a captured trace.
+         *
+         * The default drops `capture_stacktrace` and `emit`, which always exist
+         * as frames. The level wrappers are inlined away in optimised builds, so
+         * a fixed count cannot cover them; any leading frame that belongs to
+         * this module is therefore stripped by name instead, which keeps the
+         * caller visible whether or not the wrappers were inlined.
+         */
+        std::size_t stacktrace_skip{2};
+    };
+
+    /** One log record. */
+    struct record {
+        level severity{level::info};
+        std::string message{};
+        std::string file{};
+        std::uint32_t line{0};
+        std::string function{};
+        /** Formatted call stack; empty when it was not captured. */
+        std::string stacktrace{};
+        std::chrono::system_clock::time_point time{};
+        std::thread::id thread{};
+
+        [[nodiscard]] auto has_stacktrace() const -> bool { return !stacktrace.empty(); }
+    };
+
+    namespace detail {
+        /**
+         * Render a time point with a runtime chrono format string.
+         *
+         * `std::format`'s format string is compile-time only, so the spec is
+         * wrapped in a replacement field and fed to `std::vformat`; a bare spec
+         * would be read as literal text rather than a chrono conversion.
+         */
+        [[nodiscard]] inline auto format_time(const std::chrono::system_clock::time_point time,
+                                              const std::string_view time_format) -> std::string {
+            const auto moment = std::chrono::floor<std::chrono::seconds>(time);
+            const auto pattern = std::string{"{:"}.append(time_format).append("}");
+            return std::vformat(pattern, std::make_format_args(moment));
+        }
+
+        /**
+         * Render one record as a human-readable block: a header line and, when
+         * present, the indented stack frames. Shared by the stream sinks.
+         *
+         * @param time_format A chrono format string applied to the record's
+         *        timestamp; defaults to the date and time of day.
+         */
+        [[nodiscard]] inline auto format_record(const record &entry,
+                                                const std::string_view time_format = default_time_format)
+            -> std::string {
+            const auto stamp = format_time(entry.time, time_format);
+            auto text = std::format("[{}] {:<8} {}", stamp, to_string(entry.severity), entry.message);
+            if (!entry.file.empty()) {
+                text += std::format("  ({}:{})", entry.file, entry.line);
+            }
+            text += '\n';
+            if (entry.has_stacktrace()) {
+                text += entry.stacktrace;
+            }
+            return text;
+        }
+    }
+
+    /** Where records go. */
+    class sink {
+    public:
+        virtual ~sink() = default;
+
+        /** Receive one record; called with the logger's mutex held. */
+        virtual auto write(const record &entry) -> void = 0;
+
+        /** Flush any buffering. */
+        virtual auto flush() -> void {}
+    };
+
+    /** Writes a human-readable line per record to a stream (stderr by default). */
+    class console_sink final: public sink {
+    public:
+        explicit console_sink(std::ostream &stream = std::cerr,
+                              std::string time_format = std::string{default_time_format})
+            : stream_(&stream), time_format_(std::move(time_format)) {}
+
+        auto write(const record &entry) -> void override {
+            *stream_ << detail::format_record(entry, time_format_);
+            stream_->flush();
+        }
+
+    private:
+        std::ostream *stream_;
+        std::string time_format_;
+    };
+
+    /** Keeps every record in memory; useful for tests and in-game consoles. */
+    class memory_sink final: public sink {
+    public:
+        auto write(const record &entry) -> void override {
+            const auto lock = std::scoped_lock{mutex_};
+            records_.push_back(entry);
+        }
+
+        [[nodiscard]] auto records() const -> std::vector<record> {
+            const auto lock = std::scoped_lock{mutex_};
+            return records_;
+        }
+
+        [[nodiscard]] auto size() const -> std::size_t {
+            const auto lock = std::scoped_lock{mutex_};
+            return records_.size();
+        }
+
+        auto clear() -> void {
+            const auto lock = std::scoped_lock{mutex_};
+            records_.clear();
+        }
+
+    private:
+        mutable std::mutex mutex_;
+        std::vector<record> records_;
+    };
+
+    /** Configuration for `file_sink`. */
+    struct file_options {
+        /** Move an existing log file aside to an archive when the sink opens it. */
+        bool archive_on_open{true};
+        /** Flush after every record, so the tail survives a crash. */
+        bool flush_each_record{true};
+        /** Rotate once the active file would grow past this many bytes; 0 disables. */
+        std::size_t max_file_size{0};
+        /** Keep at most this many archives, dropping the oldest first; 0 keeps them all. */
+        std::size_t max_archives{0};
+        /** Timestamp format used on each record's header line (chrono syntax). */
+        std::string timestamp_format{std::string{default_time_format}};
+        /** Chrono format for the timestamp inserted into archive names. */
+        std::string archive_time_format{"%Y%m%d-%H%M%S"};
+    };
+
+    /**
+     * Writes records to a file, archiving the previous one on open.
+     *
+     * `path` is the active file. When the sink opens it and the file already
+     * holds data, that file is renamed to a timestamped archive first, so a run
+     * never appends onto a previous run's log: every start begins a fresh file
+     * and the old one is preserved as `<stem>.<timestamp><extension>` (`.log`
+     * when the active file has no extension), where the timestamp is rendered by
+     * `file_options::archive_time_format` (default `<YYYYmmdd-HHMMSS>`). The same
+     * happens mid-run once the active file passes `file_options::max_file_size`.
+     * `file_options::max_archives` bounds how many archives are kept.
+     *
+     * As with every sink, `write` is called with the logger's mutex held, so one
+     * sink is safe to share; it is not safe for two processes to point at the
+     * same file.
+     */
+    class file_sink final: public sink {
+    public:
+        explicit file_sink(std::filesystem::path path, const file_options options = {})
+            : path_(std::move(path)), options_(options) {
+            if (options_.archive_on_open && std::filesystem::exists(path_)) {
+                if (std::filesystem::file_size(path_) > 0) {
+                    archive_current();
+                } else {
+                    std::filesystem::remove(path_);
+                }
+            }
+            open();
+        }
+
+        auto write(const record &entry) -> void override {
+            const auto block = detail::format_record(entry, options_.timestamp_format);
+            // Rotate before writing, but never rotate an empty file: that would
+            // archive nothing and lose the record that is about to be written.
+            if (options_.max_file_size > 0 && size_ > 0 && size_ + block.size() > options_.max_file_size) {
+                archive_current();
+                open();
+            }
+            stream_ << block;
+            size_ += block.size();
+            if (options_.flush_each_record) stream_.flush();
+        }
+
+        auto flush() -> void override {
+            if (stream_.is_open()) stream_.flush();
+        }
+
+        /** The active log file. */
+        [[nodiscard]] auto path() const -> const std::filesystem::path & { return path_; }
+
+        /** Archives this sink created, oldest first. */
+        [[nodiscard]] auto archives() const -> const std::vector<std::filesystem::path> & { return archives_; }
+
+    private:
+        auto open() -> void {
+            stream_.clear();
+            stream_.open(path_, std::ios::out | std::ios::trunc | std::ios::binary);
+            size_ = 0;
+        }
+
+        auto archive_current() -> void {
+            if (stream_.is_open()) stream_.close();
+            const auto stamp = detail::format_time(std::chrono::system_clock::now(), options_.archive_time_format);
+            // Keep the extension last: `<stem>.<timestamp><extension>`, falling
+            // back to `.log` when the active file has none.
+            const auto stem = path_.stem().string();
+            const auto extension = path_.has_extension() ? path_.extension().string() : std::string{".log"};
+            auto archive = path_.parent_path() / (stem + "." + stamp + extension);
+            // Two rotations can land in the same second; disambiguate with a
+            // counter rather than overwrite the earlier archive.
+            for (auto counter = 1; std::filesystem::exists(archive); ++counter) {
+                archive = path_.parent_path() /
+                          (stem + "." + stamp + "." + std::to_string(counter) + extension);
+            }
+            std::filesystem::rename(path_, archive);
+            archives_.push_back(archive);
+            prune_archives();
+        }
+
+        auto prune_archives() -> void {
+            if (options_.max_archives == 0) return;
+            while (archives_.size() > options_.max_archives) {
+                auto ignored = std::error_code{};
+                std::filesystem::remove(archives_.front(), ignored);
+                archives_.erase(archives_.begin());
+            }
+        }
+
+        std::filesystem::path path_;
+        file_options options_;
+        std::ofstream stream_;
+        std::size_t size_{0};
+        std::vector<std::filesystem::path> archives_;
+    };
+
+    /*
+     * <stacktrace> is not portable: libc++ has never implemented it, and only
+     * libstdc++ provides it here. Where it is missing, records still carry their
+     * call site through std::source_location - they simply carry no stack, and
+     * everything below degrades to an empty string rather than the module
+     * refusing to compile.
+     *
+     * CMake decides this and passes it in, rather than the module testing
+     * `__cpp_lib_stacktrace` itself: feature-test macros come from the standard
+     * library's headers, and `import std;` does not export them, so probing for
+     * one here silently reports "absent" even on libstdc++, which has it.
+     */
+#ifndef ENDERLOG_HAS_STACKTRACE
+#define ENDERLOG_HAS_STACKTRACE 0
+#endif
+
+#if ENDERLOG_HAS_STACKTRACE
+    /** True when a frame belongs to the logging module itself. */
+    [[nodiscard]] inline auto is_logger_frame(const std::stacktrace_entry &entry) -> bool {
+        if (entry.description().find("ender::log") != std::string::npos) return true;
+        return entry.source_file().find("ender.log.cppm") != std::string::npos;
+    }
+
+    /**
+     * Render a trace as one indented line per frame.
+     *
+     * @param skip_logger_frames Drop leading frames belonging to this module, so
+     *        the first reported frame is the caller. This is what makes the
+     *        output stable across optimisation levels: in a release build the
+     *        level wrappers are inlined into the caller, so counting frames
+     *        alone would either over- or under-skip.
+     */
+    [[nodiscard]] inline auto format_stacktrace(const std::stacktrace &trace,
+                                                const bool skip_logger_frames = true) -> std::string {
+        if (trace.empty()) return "    <empty stacktrace>\n";
+
+        auto first = std::size_t{0};
+        if (skip_logger_frames) {
+            while (first < trace.size() && is_logger_frame(trace.at(first))) ++first;
+            if (first >= trace.size()) first = 0; // never hide the whole trace
+        }
+
+        auto text = std::string{};
+        for (auto index = first; index < trace.size(); ++index) {
+            const auto &entry = trace.at(index);
+            auto description = entry.description();
+            if (description.empty()) description = "<unknown>";
+
+            auto location = std::string{};
+            if (!entry.source_file().empty()) {
+                location = std::format(" ({}:{})", entry.source_file(), entry.source_line());
+            }
+            text += std::format("    #{:<3}{}{}\n", index - first, description, location);
+        }
+        return text;
+    }
+
+    /** Capture and render the current call stack, innermost frame first. */
+    [[nodiscard]] inline auto capture_stacktrace(const std::size_t skip = 2, const std::size_t depth = 16)
+        -> std::string {
+        return format_stacktrace(std::stacktrace::current(skip, depth));
+    }
+#else
+    /**
+     * libc++ fallback: capture the current call stack with the platform's own
+     * backtrace API and render one indented line per frame.
+     *
+     * On Windows a frame is reported as `module.dll+0xRVA` (a MinGW release build
+     * has DWARF, not the PDB symbols dbghelp resolves, so a module+offset is the
+     * practical answer). On POSIX `backtrace_symbols` is used, which names a
+     * frame when the executable was linked with `-rdynamic`.
+     */
+#if defined(_WIN32)
+    [[nodiscard]] inline auto symbolicate_frame(void *address) -> std::string {
+        const auto value = reinterpret_cast<std::uintptr_t>(address);
+        HMODULE module = nullptr;
+        if (GetModuleHandleExW(GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS | GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT,
+                               reinterpret_cast<LPCWSTR>(address), &module)) {
+            wchar_t wide[260] = L"?";
+            GetModuleFileNameW(module, wide, 260U);
+            char narrow[260] = "?";
+            WideCharToMultiByte(CP_UTF8, 0, wide, -1, narrow, sizeof(narrow), nullptr, nullptr);
+            const char *base = std::strrchr(narrow, '\\');
+            return std::format("{}+0x{:X}", base != nullptr ? base + 1 : narrow, value - reinterpret_cast<std::uintptr_t>(module));
+        }
+        return std::format("0x{:X}", value);
+    }
+#endif
+
+    [[nodiscard]] inline auto capture_stacktrace(const std::size_t skip = 2, const std::size_t depth = 16) -> std::string {
+        constexpr std::size_t max_frames = 64;
+#if defined(_WIN32)
+        void *frames[max_frames] = {};
+        const auto want = static_cast<DWORD>(std::min(max_frames, skip + std::max<std::size_t>(depth, 1U)));
+        const USHORT count = CaptureStackBackTrace(static_cast<DWORD>(skip), want, frames, nullptr);
+        auto text = std::string{};
+        for (USHORT index = 0; index < count; ++index) {
+            text += std::format("    #{:<3}{}\n", index, symbolicate_frame(frames[index]));
+        }
+        return text;
+#elif (defined(__unix__) || defined(__APPLE__)) && !defined(__EMSCRIPTEN__)
+        void *frames[max_frames] = {};
+        const int count = ::backtrace(frames, static_cast<int>(std::min(max_frames, skip + std::max<std::size_t>(depth, 1U))));
+        char **symbols = ::backtrace_symbols(frames, count);
+        auto text = std::string{};
+        for (int index = static_cast<int>(std::min<std::size_t>(skip, static_cast<std::size_t>(count))); index < count; ++index) {
+            text += std::format("    #{:<3}{}\n", index - static_cast<int>(skip),
+                                symbols != nullptr ? symbols[index] : std::format("0x{:X}", reinterpret_cast<std::uintptr_t>(frames[index])));
+        }
+        if (symbols != nullptr) std::free(symbols);
+        return text;
+#else
+        (void) skip;
+        (void) depth;
+        return {};
+#endif
+    }
+#endif
+
+    /**
+     * The process-wide logger.
+     *
+     * `enabled` is an atomic read so hot paths can guard expensive message
+     * construction; everything else takes the mutex.
+     */
+    class logger {
+    public:
+        [[nodiscard]] static auto instance() -> logger & {
+            static logger shared;
+            return shared;
+        }
+
+        auto configure(const options &config) -> void {
+            const auto lock = std::scoped_lock{mutex_};
+            options_ = config;
+            minimum_.store(static_cast<std::uint8_t>(config.minimum), std::memory_order_relaxed);
+        }
+
+        [[nodiscard]] auto configuration() const -> options {
+            const auto lock = std::scoped_lock{mutex_};
+            return options_;
+        }
+
+        [[nodiscard]] auto enabled(const level severity) const -> bool {
+            return static_cast<std::uint8_t>(severity) >= minimum_.load(std::memory_order_relaxed);
+        }
+
+        auto add_sink(std::shared_ptr<sink> destination) -> void {
+            const auto lock = std::scoped_lock{mutex_};
+            sinks_.push_back(std::move(destination));
+        }
+
+        auto set_sinks(std::vector<std::shared_ptr<sink>> destinations) -> void {
+            const auto lock = std::scoped_lock{mutex_};
+            sinks_ = std::move(destinations);
+        }
+
+        auto dispatch(const record &entry) -> void {
+            const auto lock = std::scoped_lock{mutex_};
+            for (const auto &destination: sinks_) {
+                destination->write(entry);
+            }
+        }
+
+    private:
+        logger() { sinks_.push_back(std::make_shared<console_sink>()); }
+
+        mutable std::mutex mutex_;
+        options options_{};
+        std::atomic<std::uint8_t> minimum_{static_cast<std::uint8_t>(options{}.minimum)};
+        std::vector<std::shared_ptr<sink>> sinks_;
+    };
+
+    /** Apply a configuration to the process-wide logger. */
+    inline auto configure(const options &config) -> void { logger::instance().configure(config); }
+
+    /** Current configuration of the process-wide logger. */
+    [[nodiscard]] inline auto current_options() -> options { return logger::instance().configuration(); }
+
+    /** Route records to an additional sink. */
+    inline auto add_sink(std::shared_ptr<sink> destination) -> void {
+        logger::instance().add_sink(std::move(destination));
+    }
+
+    /**
+     * Create a file sink, route records to it, and hand it back.
+     *
+     * The previous log at `path` is archived on open, so this never appends onto
+     * an earlier run.
+     *
+     * @return The sink, so the caller can inspect the archives it creates.
+     */
+    inline auto add_file_sink(std::filesystem::path path, const file_options &options = {})
+        -> std::shared_ptr<file_sink> {
+        auto destination = std::make_shared<file_sink>(std::move(path), options);
+        logger::instance().add_sink(destination);
+        return destination;
+    }
+
+    /** Replace every sink. */
+    inline auto set_sinks(std::vector<std::shared_ptr<sink>> destinations) -> void {
+        logger::instance().set_sinks(std::move(destinations));
+    }
+
+    /** True when a record at this level would be emitted. */
+    [[nodiscard]] inline auto enabled(const level severity) -> bool { return logger::instance().enabled(severity); }
+
+    namespace detail {
+        /** Build and dispatch one record. Not for direct use. */
+        inline auto emit(const level severity, std::string message, const std::source_location location) -> void {
+            auto &target = logger::instance();
+            if (!target.enabled(severity)) return;
+
+            const auto config = target.configuration();
+            auto entry = record{
+                .severity = severity,
+                .message = std::move(message),
+                .file = location.file_name(),
+                .line = static_cast<std::uint32_t>(location.line()),
+                .function = location.function_name(),
+                .time = std::chrono::system_clock::now(),
+                .thread = std::this_thread::get_id(),
+            };
+            if (severity >= config.stacktrace_from) {
+                entry.stacktrace = capture_stacktrace(config.stacktrace_skip, config.stacktrace_depth);
+            }
+            target.dispatch(entry);
+        }
+    }
+
+    /**
+     * Emit a record.
+     *
+     * The source location defaults to the call site, so this reports exactly
+     * where it was called from.
+     */
+    inline auto log(const level severity,
+                    std::string message,
+                    const std::source_location location = std::source_location::current()) -> void {
+        detail::emit(severity, std::move(message), location);
+    }
+
+    inline auto trace(std::string message, const std::source_location location = std::source_location::current())
+        -> void {
+        detail::emit(level::trace, std::move(message), location);
+    }
+
+    inline auto debug(std::string message, const std::source_location location = std::source_location::current())
+        -> void {
+        detail::emit(level::debug, std::move(message), location);
+    }
+
+    inline auto info(std::string message, const std::source_location location = std::source_location::current())
+        -> void {
+        detail::emit(level::info, std::move(message), location);
+    }
+
+    inline auto warn(std::string message, const std::source_location location = std::source_location::current())
+        -> void {
+        detail::emit(level::warn, std::move(message), location);
+    }
+
+    /** Emits at `error`, which captures a call stack by default. */
+    inline auto error(std::string message, const std::source_location location = std::source_location::current())
+        -> void {
+        detail::emit(level::error, std::move(message), location);
+    }
+
+    inline auto critical(std::string message, const std::source_location location = std::source_location::current())
+        -> void {
+        detail::emit(level::critical, std::move(message), location);
+    }
+}

third_party/libra3assets/README.md

@@ -0,0 +1,134 @@
+# libra3assets
+
+A dependency-free C++26 library that reads **and writes** the resource files
+Red Alert 3 ships, so tooling (map editors in particular) can work with the
+retail assets directly. No engine, no game install required to build - only to
+feed it data.
+
+It is a sub-project of this repository, a sibling of
+[`libra3replay`](../libra3replay/README.md), and follows the same build
+conventions (C++26 modules, `import std;`, GCC 16, CMake 4 + Ninja).
+
+## What it handles
+
+| Module             | Format                                                              | Read | Write |
+| ------------------ | ------------------------------------------------------------------- | :--: | :---: |
+| `ra3.assets:big`      | `BIG4` archives (`Data\*.big`)                                   | yes  | yes   |
+| `ra3.assets:refpack`  | EA RefPack codec (`10 FB`)                                       | yes  | yes   |
+| `ra3.assets:binary`   | compiled `BinaryAsset` streams (`.bin` + `.manifest`, `cdata`)   | yes  | -     |
+| `ra3.assets:csf`      | SAGE `.csf` string tables (`gamestrings.csf`)                    | yes  | yes   |
+| `ra3.assets:map`      | SAGE `.map` containers (`CkMp`) incl. `HeightMapData`/objects    | yes  | yes   |
+| `ra3.assets:bytes`    | bounds-checked little-/big-endian readers and writers            | yes  | yes   |
+
+The **map** module is the centrepiece for a map editor. A `.map` is modelled as
+an ordered list of named, versioned `CkMp` chunks; chunks the library does not
+type (e.g. `BlendTileData`, `SidesList`) are preserved byte-for-byte and the
+asset-name table keeps its original indices, so an edit/ serialise cycle is
+lossless. Typed accessors cover the terrain grid (`HeightMapData`), every placed
+object (`ObjectsList`, including the `*Waypoints/Waypoint` objects that carry
+`Player_N_Start`), `MPPositionList`, `WorldInfo` and `WaypointsList`.
+
+The **binary** module parses the compiled `BinaryAsset` streams that
+BinaryAssetBuilder produces (`data\static.bin`, `data\global.bin`, ...): the
+manifest index, each asset's instance slice, its relocation/import sidecars and
+its `cdata` blob, plus the hash used to name assets.
+
+## Build
+
+```bash
+cmake -S libra3assets -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=g++-16
+cmake --build build
+ctest --test-dir build --output-on-failure
+```
+
+The library is a set of C++20/26 modules (`ra3.assets` plus the `:error`,
+`:bytes`, `:refpack`, `:big`, `:binary`, `:csf` and `:map` partitions) that
+imports the standard library (`import std;`). That needs **CMake 4.0+ with the
+Ninja generator** and a compiler whose standard library ships a `std` module -
+**GCC 16** in practice. The tests need nothing but the library itself.
+
+> Building with the distro GCC 16: pass `-DCMAKE_CXX_COMPILER=g++-16`.
+
+## Use
+
+```cpp
+import std;
+import ra3.assets;
+
+using namespace ra3::assets;
+
+// --- a map, for a map editor -------------------------------------------------
+auto document = map_document::open("map_mp_2_black1b.map");
+
+if (const auto height = document.height_map()) {
+    std::println("terrain {}x{}", height->width, height->height);
+    auto grid = *height;                       // copy, then edit
+    grid.set(10, 10, grid.at(10, 10) + 1);     // raise a cell
+    document.set_height_map(std::move(grid));  // re-encode the chunk
+}
+
+for (const auto &start: document.player_starts())
+    std::println("Player {} at ({}, {})", start.index, start.position.x, start.position.y);
+
+for (const auto &object: document.objects())
+    if (object.type_name == "*Waypoints/Waypoint")
+        std::println("{} -> {}", object.property("waypointName")->as_ascii(), object.position.y);
+
+// Lossless: unknown chunks and the name table survive the round-trip.
+write_file("edited.map", document.serialize(/* compress = */ true));
+
+// --- a BIG4 archive ----------------------------------------------------------
+const auto archive = big_archive::open("Data/GlobalStream.big");
+std::println("{} entries", archive.size());
+for (const auto *entry: archive.find("audio"))
+    std::println("{} ({} bytes)", entry->name, entry->size);
+
+// --- a compiled BinaryAsset stream ------------------------------------------
+const auto stream = binary_stream_from_big(archive, binary_stream::global, /* need_data = */ false);
+for (const auto &[type, count]: stream.type_counts())
+    std::println("{:6}  {}", count, type);
+```
+
+The API deliberately avoids integer IDs for anything selectable: chunk kinds are
+`chunk_kind` (e.g. `chunk_kind::height_map_data`), streams are `binary_stream`
+(`binary_stream::global`), property types are `property_type`, and an
+`asset_property` carries a `std::variant<bool, std::int32_t, float, std::string,
+std::u16string>`.
+
+## Command-line tool
+
+`ra3assets-cli` is built alongside the library:
+
+```
+ra3assets-cli big    list    <archive.big> [match]
+ra3assets-cli big    extract <archive.big> <out-dir> [match]
+ra3assets-cli binary list    <path> [type]
+ra3assets-cli binary types   <path> [static|global|locale|static_l|static_m]
+ra3assets-cli binary cat     <path> <Type:Instance|#index> <out-file>
+ra3assets-cli map    info    <map-file>
+ra3assets-cli map    starts  <map-file>
+ra3assets-cli map    repack  <map-file> <out-file> [--compress]
+ra3assets-cli csf    <csf-or-game-dir-or-big> [label]
+ra3assets-cli hash   <text>...
+```
+
+## Notes and limits
+
+- A `BIG4` archive opened from disk keeps only its index in memory and reads
+  payloads on demand, so enumerating the ~700 MB retail `StaticStream.big` costs
+  a few megabytes; pass `need_data = false` to `binary_stream_from_big` when you
+  only need the manifest. A parsed `.map` document is held in full - that is what
+  its typed accessors edit.
+- `set_height_map` keeps the on-disk `HeightMapData` version (RA3 uses 6, i.e.
+  16-bit elevations). Older 8-bit maps serialise back as 8-bit.
+- RefPack compression is a plain greedy LZ77 matcher. It is lossless against the
+  bundled decoder and produces streams the game's decoder accepts, but it is
+  slightly less dense than the retail compressor (≈3% on a typical map).
+- `BlendTileData` (terrain texture blending) is preserved but not yet
+  type-modelled; a map editor should treat the chunk as opaque for now. The
+  planned follow-up covers `BlendTileData` and `SidesList`.
+- Only `BIG4` is supported (RA3's format); older `BIGF` archives are not.
+
+The on-disk layouts were reverse engineered from the shipped files and
+cross-checked against [`ra3tools`](../ra3tools/), OpenRA3's `ra3.fs`/`ra3.map`
+modules and the OpenSAGE re-implementation (`reference/OpenSAGE`).

third_party/libra3assets/src/assets.cppm

@@ -0,0 +1,65 @@
+/**
+ * libra3assets - read (and write) Red Alert 3's built-in resource files.
+ *
+ * The primary module interface re-exports every partition:
+ *
+ * - `:error`   - the `asset_error` exception family
+ * - `:bytes`   - bounds-checked little-/big-endian readers and writers
+ * - `:refpack` - EA's RefPack codec (decompress and compress)
+ * - `:big`     - `BIG4` archives (`Data\*.big`), read and write
+ * - `:binary`  - compiled `BinaryAsset` streams (`*.bin` + `.manifest`)
+ * - `:csf`     - SAGE `.csf` string tables
+ * - `:map`     - SAGE `.map` containers (`CkMp`), read and write
+ *
+ * Nothing here reads game data on its own: callers point the library at their
+ * own installation (`RA3_GAME_DIR` / `C:\Red Alert 3`).
+ */
+export module ra3.assets;
+
+export import :error;
+export import :bytes;
+export import :refpack;
+export import :big;
+export import :binary;
+export import :csf;
+export import :map;
+
+import std;
+
+export namespace ra3::assets {
+
+    /**
+     * Locate a Red Alert 3 installation.
+     *
+     * Resolution order: the explicit argument, then `$RA3_GAME_DIR`, then the
+     * default `C:\Red Alert 3`. A directory qualifies only if it has a `Data`
+     * subdirectory.
+     */
+    [[nodiscard]] inline auto find_game_dir(const std::optional<std::filesystem::path> &explicit_dir = std::nullopt) -> std::optional<std::filesystem::path> {
+        const auto qualifies = [](const std::filesystem::path &candidate) {
+            std::error_code ec;
+            return !candidate.empty() && std::filesystem::is_directory(candidate / "Data", ec);
+        };
+
+        if (explicit_dir && qualifies(*explicit_dir)) return explicit_dir;
+        if (const auto *env = std::getenv("RA3_GAME_DIR"); env != nullptr && *env != '\0') {
+            const std::filesystem::path candidate{env};
+            if (qualifies(candidate)) return candidate;
+        }
+        const std::filesystem::path default_dir{"C:/Red Alert 3"};
+        if (qualifies(default_dir)) return default_dir;
+        return std::nullopt;
+    }
+
+    /** Every `Data\*.big` archive in an installation, sorted by name. */
+    [[nodiscard]] inline auto list_archives(const std::filesystem::path &game_dir) -> std::vector<std::filesystem::path> {
+        std::vector<std::filesystem::path> archives;
+        std::error_code ec;
+        for (const auto &entry: std::filesystem::directory_iterator(game_dir / "Data", ec)) {
+            if (entry.is_regular_file() && entry.path().extension() == ".big") archives.push_back(entry.path());
+        }
+        std::ranges::sort(archives);
+        return archives;
+    }
+
+} // namespace ra3::assets

third_party/libra3assets/src/big.cppm

@@ -0,0 +1,274 @@
+/**
+ * `BIG4` archives - Red Alert 3's on-disk asset container.
+ *
+ * Retail RA3 ships its data as `Data\*.big`: a 16-byte header, a variable-
+ * length entry index and the 64-byte-aligned payloads. The count and the entry
+ * offsets/sizes are **big-endian** (the header size is little-endian, matching
+ * the retail files); each payload may itself be RefPack-compressed, which is
+ * detected from its own magic rather than flagged in the index.
+ *
+ * Both directions are implemented so a map editor can repack an archive.
+ */
+export module ra3.assets:big;
+
+import std;
+
+import :bytes;
+import :error;
+import :refpack;
+
+export namespace ra3::assets {
+
+    /** One file inside a `BIG4` archive. */
+    struct big_entry {
+        std::string name;
+        std::uint32_t offset = 0;
+        std::uint32_t size = 0;
+    };
+
+    namespace detail {
+        [[nodiscard]] inline auto align_up(std::uint64_t value, std::uint64_t alignment) -> std::uint64_t {
+            return (value + alignment - 1U) / alignment * alignment;
+        }
+
+        [[nodiscard]] inline constexpr auto bswap32(std::uint32_t value) -> std::uint32_t {
+            return ((value & 0x000000FFU) << 24U) | ((value & 0x0000FF00U) << 8U) | ((value & 0x00FF0000U) >> 8U) | ((value & 0xFF000000U) >> 24U);
+        }
+    }
+
+    /**
+     * A parsed `BIG4` archive.
+     *
+     * Opening from disk parses only the index; payloads are read (and
+     * RefPack-decompressed) on demand, so a multi-hundred-megabyte archive costs
+     * a few megabytes to enumerate. An archive built from an in-memory image
+     * (`from_bytes`) slices its payloads out of that buffer instead.
+     */
+    class big_archive {
+    public:
+        /** Read and parse an archive from disk, keeping only the index in memory. */
+        [[nodiscard]] static auto open(const std::filesystem::path &path) -> big_archive {
+            big_archive archive;
+            archive.path_ = path;
+
+            std::error_code ec;
+            archive.file_size_ = static_cast<std::uint64_t>(std::filesystem::file_size(path, ec));
+            if (ec) throw big_error("cannot stat archive: " + path.string());
+
+            std::ifstream in(path, std::ios::binary);
+            if (!in) throw big_error("cannot open archive: " + path.string());
+
+            std::array<std::byte, 16> header{};
+            in.read(reinterpret_cast<char *>(header.data()), static_cast<std::streamsize>(header.size()));
+            if (!in || std::string_view{reinterpret_cast<const char *>(header.data()), 4} != "BIG4") throw big_error("not a BIG4 archive: " + path.string());
+
+            // The index is a dense variable-length table from offset 16; read a
+            // window and grow it until every entry parses. Payloads are never
+            // touched, so the memory cost stays at the index size.
+            const auto size = archive.file_size_;
+            std::uint64_t window = std::min<std::uint64_t>(size, 1U << 20U);
+            std::vector<std::byte> buffer;
+            for (;;) {
+                buffer.resize(static_cast<std::size_t>(window));
+                in.clear();
+                in.seekg(0);
+                in.read(reinterpret_cast<char *>(buffer.data()), static_cast<std::streamsize>(window));
+                const auto got = in.gcount();
+                buffer.resize(got > 0 ? static_cast<std::size_t>(got) : 0U);
+
+                std::vector<big_entry> entries;
+                if (big_archive::parse_index(buffer, entries)) {
+                    archive.entries_ = std::move(entries);
+                    break;
+                }
+                if (window >= size) throw big_error("truncated BIG4 index: " + path.string());
+                window = std::min<std::uint64_t>(size, window * 2U);
+            }
+            archive.reindex();
+            return archive;
+        }
+
+        /** Parse an in-memory archive image; payloads are sliced from it. */
+        [[nodiscard]] static auto from_bytes(std::vector<std::byte> bytes) -> big_archive {
+            big_archive archive;
+            archive.bytes_ = std::move(bytes);
+            archive.in_memory_ = true;
+            if (!big_archive::parse_index(archive.bytes_, archive.entries_)) throw big_error("not a BIG4 archive");
+            archive.reindex();
+            return archive;
+        }
+
+        [[nodiscard]] auto path() const -> const std::filesystem::path & { return this->path_; }
+        [[nodiscard]] auto entries() const -> const std::vector<big_entry> & { return this->entries_; }
+        [[nodiscard]] auto size() const -> std::size_t { return this->entries_.size(); }
+        [[nodiscard]] auto contains(std::string_view name) const -> bool { return this->index_.contains(std::string{name}); }
+
+        /** The entry with exactly this name, or `nullptr`. */
+        [[nodiscard]] auto find_exact(std::string_view name) const -> const big_entry * {
+            const auto it = this->index_.find(std::string{name});
+            return it == this->index_.end() ? nullptr : &this->entries_[it->second];
+        }
+
+        /** Every entry whose name contains `needle`, in index order. */
+        [[nodiscard]] auto find(std::string_view needle) const -> std::vector<const big_entry *> {
+            std::vector<const big_entry *> matches;
+            for (const auto &entry: this->entries_) {
+                if (entry.name.find(needle) != std::string::npos) matches.push_back(&entry);
+            }
+            return matches;
+        }
+
+        /** Read an entry's payload; RefPack-decompress it when `decompress`. */
+        [[nodiscard]] auto read(std::string_view name, bool decompress = true) const -> std::vector<std::byte> {
+            const auto *entry = this->find_exact(name);
+            if (entry == nullptr) throw big_error("no such entry: " + std::string{name});
+            return this->read(*entry, decompress);
+        }
+
+        [[nodiscard]] auto read(const big_entry &entry, bool decompress = true) const -> std::vector<std::byte> {
+            const auto raw = this->stored(entry.offset, entry.size);
+            return decompress ? maybe_decompress(raw) : raw;
+        }
+
+        /** The first `count` stored bytes of an entry (no decompression). */
+        [[nodiscard]] auto read_prefix(std::string_view name, std::size_t count) const -> std::vector<std::byte> {
+            const auto *entry = this->find_exact(name);
+            if (entry == nullptr) throw big_error("no such entry: " + std::string{name});
+            return this->stored(entry->offset, static_cast<std::uint32_t>(std::min<std::size_t>(count, entry->size)));
+        }
+
+    private:
+        big_archive() = default;
+
+        /** Parse a `BIG4` index from `data`; false when it is not fully present. */
+        [[nodiscard]] static auto parse_index(std::span<const std::byte> data, std::vector<big_entry> &out) -> bool {
+            if (data.size() < 16U) return false;
+            byte_reader reader{data};
+            if (reader.read_ascii(4) != "BIG4") return false;
+            (void) reader.read_u32();    // total file size (little-endian); implied by the buffer
+            const auto count = reader.read_be_u32();
+            (void) reader.read_be_u32(); // index size
+            // Each entry is at least `u32 offset + u32 size + NUL name` (9 bytes),
+            // so a count that cannot fit bounds both the reserve and the window.
+            if (count > (data.size() - 16U) / 9U) return false;
+            out.clear();
+            out.reserve(count);
+            for (std::uint32_t i = 0; i < count; ++i) {
+                if (reader.remaining() < 8U) return false;
+                big_entry entry;
+                entry.offset = reader.read_be_u32();
+                entry.size = reader.read_be_u32();
+                // The NUL-terminated name may run past the current window.
+                std::string name;
+                bool terminated = false;
+                while (reader.remaining() > 0U) {
+                    const auto ch = reader.read_u8();
+                    if (ch == 0U) {
+                        terminated = true;
+                        break;
+                    }
+                    name.push_back(static_cast<char>(ch));
+                }
+                if (!terminated) return false;
+                entry.name = std::move(name);
+                out.push_back(std::move(entry));
+            }
+            return true;
+        }
+
+        /** Read `count` stored bytes at `offset`, from memory or from disk. */
+        [[nodiscard]] auto stored(std::uint32_t offset, std::uint32_t count) const -> std::vector<std::byte> {
+            if (this->in_memory_) {
+                if (static_cast<std::uint64_t>(offset) + count > this->bytes_.size()) throw big_error("entry extends past end of archive");
+                const auto *begin = this->bytes_.data() + offset;
+                return std::vector<std::byte>{begin, begin + count};
+            }
+            if (static_cast<std::uint64_t>(offset) + count > this->file_size_) throw big_error("entry extends past end of archive");
+            std::ifstream in(this->path_, std::ios::binary);
+            if (!in) throw big_error("cannot open archive: " + this->path_.string());
+            in.seekg(static_cast<std::streamoff>(offset));
+            std::vector<std::byte> raw(count);
+            if (count > 0U) in.read(reinterpret_cast<char *>(raw.data()), static_cast<std::streamsize>(count));
+            if (!in) throw big_error("short read from archive: " + this->path_.string());
+            return raw;
+        }
+
+        auto reindex() -> void {
+            this->index_.clear();
+            for (std::size_t i = 0; i < this->entries_.size(); ++i) this->index_.emplace(this->entries_[i].name, i);
+        }
+
+        std::filesystem::path path_;
+        std::vector<std::byte> bytes_; ///< In-memory image (from_bytes); empty when opened from disk.
+        bool in_memory_ = false;
+        std::uint64_t file_size_ = 0;
+        std::vector<big_entry> entries_;
+        std::unordered_map<std::string, std::size_t> index_;
+    };
+
+    /**
+     * Builds a `BIG4` archive.
+     *
+     * Entry payloads are written 64-byte aligned (as the retail archives are),
+     * and the header's index size reproduces the retail convention
+     * (`last-entry end + 8`). `add(..., compress = true)` RefPack-encodes the
+     * payload when that is smaller, otherwise stores it verbatim.
+     */
+    class big_writer {
+    public:
+        auto add(std::string name, std::vector<std::byte> payload, bool compress = false) -> void {
+            if (compress) {
+                auto packed = refpack_compress(payload);
+                if (packed.size() < payload.size()) payload = std::move(packed);
+            }
+            this->items_.push_back({std::move(name), std::move(payload)});
+        }
+
+        /** Serialise the archive into a fresh byte image. */
+        [[nodiscard]] auto write() const -> std::vector<std::byte> {
+            std::uint64_t table_end = 16U;
+            for (const auto &item: this->items_) table_end += 8U + item.name.size() + 1U;
+            const auto index_size = table_end + 8U;
+            const auto data_start = detail::align_up(index_size, 64U);
+
+            std::vector<std::uint64_t> offsets;
+            offsets.reserve(this->items_.size());
+            std::uint64_t cursor = data_start;
+            for (const auto &item: this->items_) {
+                offsets.push_back(cursor);
+                cursor = detail::align_up(cursor + item.payload.size(), 64U);
+            }
+
+            byte_writer writer;
+            writer.write_ascii("BIG4");
+            writer.write_u32(static_cast<std::uint32_t>(cursor)); // total file size (little-endian)
+            writer.write_u32(detail::bswap32(static_cast<std::uint32_t>(this->items_.size())));
+            writer.write_u32(detail::bswap32(static_cast<std::uint32_t>(index_size)));
+            for (std::size_t i = 0; i < this->items_.size(); ++i) {
+                writer.write_u32(detail::bswap32(static_cast<std::uint32_t>(offsets[i])));
+                writer.write_u32(detail::bswap32(static_cast<std::uint32_t>(this->items_[i].payload.size())));
+                writer.write_ascii(this->items_[i].name);
+                writer.write_u8(0);
+            }
+            while (writer.size() < data_start) writer.write_u8(0);
+            for (std::size_t i = 0; i < this->items_.size(); ++i) {
+                writer.write_bytes(this->items_[i].payload);
+                if (i + 1U < this->items_.size()) {
+                    while (writer.size() < offsets[i + 1U]) writer.write_u8(0);
+                }
+            }
+            return writer.take();
+        }
+
+    private:
+        struct pending_item {
+            std::string name;
+            std::vector<std::byte> payload;
+        };
+
+        std::vector<pending_item> items_;
+    };
+
+} // namespace ra3::assets
+
+

third_party/libra3assets/src/binary.cppm

@@ -0,0 +1,396 @@
+/**
+ * Compiled `BinaryAsset` streams (`Data\*.bin` + `.manifest`).
+ *
+ * Retail RA3 does not ship its gameplay/art assets as source files: the
+ * BinaryAssetBuilder compiles every XML/`.w3x` into a `.bin` *instance stream*
+ * plus a `.manifest` index (`data\static.bin`, `data\global.bin`, ...). This
+ * partition parses that index, exposes each asset's instance slice, its
+ * relocation/import sidecars and its custom-data (`cdata`) blob, and implements
+ * the Bob-Jenkins-style hash the builder names assets with.
+ *
+ * Asset names are `"Type:Instance"` (e.g. `W3DMesh:ABAIRFIELD`); `Type` is
+ * case-sensitive and `Instance` is lowercased before hashing.
+ */
+export module ra3.assets:binary;
+
+import std;
+
+import :big;
+import :bytes;
+import :error;
+import :refpack;
+
+export namespace ra3::assets {
+
+    /** The compiled instance streams a retail install ships. */
+    enum class binary_stream {
+        static_data, ///< `data\static.bin` - the main art/gameplay stream
+        global,      ///< `data\global.bin` - sounds, AI, UI
+        locale,      ///< `data\locale.bin` - localized on-demand textures
+        static_low,  ///< `data\static_l.bin` - low-detail model LODs
+        static_medium, ///< `data\static_m.bin` - medium-detail model LODs
+    };
+
+    /** The `data\<name>.manifest` stem for a stream. */
+    [[nodiscard]] inline auto to_string(binary_stream stream) -> std::string_view {
+        switch (stream) {
+        case binary_stream::static_data: return "static";
+        case binary_stream::global: return "global";
+        case binary_stream::locale: return "locale";
+        case binary_stream::static_low: return "static_l";
+        case binary_stream::static_medium: return "static_m";
+        }
+        return "static";
+    }
+
+    /** Resolve a stream name (e.g. `"global"`), or `std::nullopt`. */
+    [[nodiscard]] inline auto binary_stream_from_name(std::string_view name) -> std::optional<binary_stream> {
+        for (const auto candidate: {binary_stream::static_data, binary_stream::global, binary_stream::locale, binary_stream::static_low, binary_stream::static_medium}) {
+            if (to_string(candidate) == name) return candidate;
+        }
+        return std::nullopt;
+    }
+
+    /** Streams in the order `binary_stream_from_big` prefers when none is given. */
+    inline constexpr std::array<binary_stream, 5> binary_stream_order{binary_stream::static_data, binary_stream::global, binary_stream::locale, binary_stream::static_low,
+                                                                      binary_stream::static_medium};
+
+    /** Types compiled from a `.w3x` model source. */
+    inline constexpr std::array<std::string_view, 5> w3d_types{"W3DMesh", "W3DHierarchy", "W3DAnimation", "W3DContainer", "W3DCollisionBox"};
+
+    /**
+     * The hash BinaryAssetBuilder names assets with.
+     *
+     * A Bob-Jenkins `lookup3`-style mix. `seed` is the running value; the public
+     * overloads seed it with the length (`hash_string`).
+     */
+    [[nodiscard]] inline auto fast_hash(std::span<const std::byte> data, std::uint32_t seed = 0) -> std::uint32_t {
+        const auto length = data.size();
+        if (length == 0U) return 0x1337C0DEU;
+        const auto at16 = [&](std::size_t pos) -> std::uint32_t {
+            return static_cast<std::uint32_t>(std::to_integer<std::uint8_t>(data[pos])) |
+                   (static_cast<std::uint32_t>(std::to_integer<std::uint8_t>(data[pos + 1U])) << 8U);
+        };
+        std::uint32_t h = seed;
+        std::size_t pos = 0;
+        const auto extra = length & 3U;
+        for (std::size_t i = 0; i < (length >> 2U); ++i) {
+            h += at16(pos);
+            h ^= (at16(pos + 2U) ^ (h << 5U)) << 11U;
+            h += h >> 11U;
+            pos += 4U;
+        }
+        if (extra == 1U) {
+            h += std::to_integer<std::uint8_t>(data[pos]);
+            h ^= h << 10U;
+            h += h >> 1U;
+        } else if (extra == 2U) {
+            h += at16(pos);
+            h ^= h << 11U;
+            h += h >> 17U;
+        } else if (extra == 3U) {
+            h += at16(pos);
+            h ^= h << 16U;
+            h ^= static_cast<std::uint32_t>(std::to_integer<std::uint8_t>(data[pos + 2U])) << 18U;
+            h += h >> 11U;
+        }
+        h ^= h << 3U;
+        h += h >> 5U;
+        h ^= h << 2U;
+        h += h >> 15U;
+        h ^= h << 10U;
+        return h;
+    }
+
+    /**
+     * Hash an asset type (case-sensitive, the `TypeId`) or an instance name
+     * (`case_sensitive = false`, the `InstanceId`).
+     */
+    [[nodiscard]] inline auto hash_string(std::string_view text, bool case_sensitive = true) -> std::uint32_t {
+        std::string buffer{text};
+        if (!case_sensitive) {
+            std::ranges::transform(buffer, buffer.begin(), [](unsigned char ch) { return static_cast<char>(std::tolower(ch)); });
+        }
+        const auto *bytes = reinterpret_cast<const std::byte *>(buffer.data());
+        return fast_hash(std::span<const std::byte>{bytes, buffer.size()}, static_cast<std::uint32_t>(buffer.size()));
+    }
+
+    /** One asset in a compiled stream. */
+    struct binary_asset {
+        std::uint32_t index = 0;
+        std::uint32_t type_id = 0;
+        std::uint32_t instance_id = 0;
+        std::uint32_t type_hash = 0;
+        std::uint32_t instance_hash = 0;
+        std::vector<std::pair<std::uint32_t, std::uint32_t>> references; ///< (typeId, instanceId) pairs
+        std::string name;   ///< "Type:Instance"
+        std::string source; ///< the `.w3x`/XML it was compiled from
+        std::uint32_t instance_size = 0;
+        std::uint32_t relocation_size = 0;
+        std::uint32_t imports_size = 0;
+        bool tokenized = false;
+        std::uint32_t instance_offset = 4;   ///< into the decompressed `.bin` (after its 4-byte checksum)
+        std::uint32_t relocation_offset = 4; ///< into the `.relo`
+        std::uint32_t imports_offset = 4;    ///< into the `.imp`
+
+        [[nodiscard]] auto type_name() const -> std::string_view {
+            const auto colon = this->name.find(':');
+            return std::string_view{this->name}.substr(0, colon);
+        }
+
+        [[nodiscard]] auto instance_name() const -> std::string_view {
+            const auto colon = this->name.find(':');
+            return colon == std::string::npos ? std::string_view{this->name} : std::string_view{this->name}.substr(colon + 1U);
+        }
+
+        /**
+         * The `cdata` blob name for a custom-data asset (`AudioFile`,
+         * `OnDemandTexture`, ...):
+         * `data\<stream>\cdata\<typeId>.<typeHash>.<instanceId>.<instanceHash>.cdata`.
+         */
+        [[nodiscard]] auto cdata_name(std::string_view stream) const -> std::string {
+            return std::format("data\\{}\\cdata\\{:08x}.{:08x}.{:08x}.{:08x}.cdata", stream, this->type_id, this->type_hash, this->instance_id,
+                               this->instance_hash);
+        }
+    };
+
+    /** A callback that resolves a `cdata` blob name to its decompressed bytes. */
+    using cdata_source = std::function<std::optional<std::vector<std::byte>>(const std::string &name)>;
+
+    /**
+     * A parsed `.manifest` (+ optional `.bin`/`.relo`/`.imp`).
+     *
+     * Only the manifest is mandatory; `need_data = false` when constructing
+     * skips the (up to hundreds of megabytes) instance stream, which is all
+     * listing the assets requires.
+     */
+    class binary_container {
+    public:
+        /** Parse a manifest, its instance stream and its optional fixup streams. */
+        [[nodiscard]] static auto from_bytes(std::vector<std::byte> manifest, std::vector<std::byte> data = {}, std::vector<std::byte> relocation = {},
+                                             std::vector<std::byte> imports = {}, std::string stream = "static") -> binary_container {
+            binary_container container;
+            container.stream_ = std::move(stream);
+            container.manifest_ = std::move(manifest);
+            container.data_ = std::move(data);
+            container.relocation_ = std::move(relocation);
+            container.imports_ = std::move(imports);
+            container.parse();
+            return container;
+        }
+
+        [[nodiscard]] auto stream() const -> const std::string & { return this->stream_; }
+        [[nodiscard]] auto version() const -> std::uint16_t { return this->version_; }
+        [[nodiscard]] auto is_linked() const -> bool { return this->is_linked_; }
+        [[nodiscard]] auto assets() const -> const std::vector<binary_asset> & { return this->assets_; }
+        [[nodiscard]] auto size() const -> std::size_t { return this->assets_.size(); }
+
+        /** Count of assets per `Type` (the part before `:`). */
+        [[nodiscard]] auto type_counts() const -> std::map<std::string, std::size_t> {
+            std::map<std::string, std::size_t> counts;
+            for (const auto &asset: this->assets_) ++counts[std::string{asset.type_name()}];
+            return counts;
+        }
+
+        /** Map `(typeId << 32 | instanceId)` to the owning asset. */
+        [[nodiscard]] auto asset_index() const -> const std::unordered_map<std::uint64_t, std::size_t> & { return this->asset_index_; }
+
+        /** Every asset, in manifest order, whose `Type` matches (case-insensitive). */
+        [[nodiscard]] auto of_type(std::string_view type) const -> std::vector<const binary_asset *> {
+            std::vector<const binary_asset *> matches;
+            for (const auto &asset: this->assets_) {
+                if (std::ranges::equal(asset.type_name(), type, [](char a, char b) { return std::tolower(static_cast<unsigned char>(a)) == std::tolower(static_cast<unsigned char>(b)); }))
+                    matches.push_back(&asset);
+            }
+            return matches;
+        }
+
+        /** Resolve `"Type:Instance"` (case-sensitive, then insensitive) or `"#index"`. */
+        [[nodiscard]] auto find(std::string_view selector) const -> const binary_asset & {
+            if (selector.starts_with('#')) {
+                const auto index = static_cast<std::size_t>(std::stoul(std::string{selector.substr(1)}));
+                if (index >= this->assets_.size()) throw binary_error("asset index out of range: " + std::string{selector});
+                return this->assets_[index];
+            }
+            for (const auto &asset: this->assets_) {
+                if (asset.name == selector) return asset;
+            }
+            for (const auto &asset: this->assets_) {
+                if (std::ranges::equal(asset.name, selector, [](char a, char b) { return std::tolower(static_cast<unsigned char>(a)) == std::tolower(static_cast<unsigned char>(b)); }))
+                    return asset;
+            }
+            throw binary_error("no such asset: " + std::string{selector});
+        }
+
+        auto set_cdata_source(cdata_source source) -> void { this->cdata_ = std::move(source); }
+
+        [[nodiscard]] auto read_instance(const binary_asset &asset) const -> std::span<const std::byte> {
+            if (asset.instance_size == 0U) return {};
+            if (static_cast<std::uint64_t>(asset.instance_offset) + asset.instance_size > this->data_.size()) throw binary_error("instance extends past stream: " + asset.name);
+            return std::span<const std::byte>{this->data_}.subspan(asset.instance_offset, asset.instance_size);
+        }
+
+        [[nodiscard]] auto read_relocation(const binary_asset &asset) const -> std::span<const std::byte> {
+            if (asset.relocation_size == 0U) return {};
+            if (static_cast<std::uint64_t>(asset.relocation_offset) + asset.relocation_size > this->relocation_.size()) throw binary_error("relocation extends past stream: " + asset.name);
+            return std::span<const std::byte>{this->relocation_}.subspan(asset.relocation_offset, asset.relocation_size);
+        }
+
+        [[nodiscard]] auto read_imports(const binary_asset &asset) const -> std::span<const std::byte> {
+            if (asset.imports_size == 0U) return {};
+            if (static_cast<std::uint64_t>(asset.imports_offset) + asset.imports_size > this->imports_.size()) throw binary_error("imports extend past stream: " + asset.name);
+            return std::span<const std::byte>{this->imports_}.subspan(asset.imports_offset, asset.imports_size);
+        }
+
+        /** The asset's `cdata` blob, or `std::nullopt` when it has none. */
+        [[nodiscard]] auto read_cdata(const binary_asset &asset) const -> std::optional<std::vector<std::byte>> {
+            if (!this->cdata_) return std::nullopt;
+            return this->cdata_(asset.cdata_name(this->stream_));
+        }
+
+        /** The asset's real payload: its `cdata` blob when present, else its instance. */
+        [[nodiscard]] auto read_payload(const binary_asset &asset) const -> std::vector<std::byte> {
+            if (auto cdata = this->read_cdata(asset)) return *cdata;
+            const auto instance = this->read_instance(asset);
+            return {instance.begin(), instance.end()};
+        }
+
+    private:
+        binary_container() = default;
+
+        auto parse() -> void {
+            byte_reader reader{this->manifest_};
+            const auto is_big_endian = reader.read_u8();
+            this->is_linked_ = reader.read_bool();
+            this->version_ = reader.read_u16();
+            if (is_big_endian != 0U) throw binary_error("big-endian manifests are not supported");
+            if (this->version_ != 5U && this->version_ != 6U) throw binary_error("unsupported manifest version " + std::to_string(this->version_));
+            (void) reader.read_u32(); // stream checksum
+            (void) reader.read_u32(); // all-types hash
+            const auto count = reader.read_u32();
+            (void) reader.read_u32(); // total instance data size
+            (void) reader.read_u32(); // max instance chunk size
+            (void) reader.read_u32(); // max relocation chunk size
+            (void) reader.read_u32(); // max imports chunk size
+            const auto reference_buffer_size = reader.read_u32();
+            const auto reference_name_buffer_size = reader.read_u32();
+            const auto name_buffer_size = reader.read_u32();
+            const auto source_buffer_size = reader.read_u32();
+
+            constexpr std::size_t header_size = 48U;
+            constexpr std::size_t entry_size = 48U;
+            if (this->manifest_.size() < header_size + static_cast<std::size_t>(count) * entry_size) throw binary_error("manifest entry table is truncated");
+
+            const auto entries_off = header_size;
+            const auto references_off = entries_off + static_cast<std::size_t>(count) * entry_size;
+            const auto reference_names_off = references_off + reference_buffer_size;
+            const auto names_off = reference_names_off + reference_name_buffer_size;
+            const auto sources_off = names_off + name_buffer_size;
+            if (sources_off + source_buffer_size > this->manifest_.size()) throw binary_error("manifest string buffers are truncated");
+
+            const auto cstr = [&](std::size_t base, std::int32_t offset) -> std::string {
+                if (offset < 0) return {};
+                const auto start = base + static_cast<std::size_t>(offset);
+                if (start >= this->manifest_.size()) return {};
+                std::size_t end = start;
+                while (end < this->manifest_.size() && std::to_integer<std::uint8_t>(this->manifest_[end]) != 0U) ++end;
+                return std::string{reinterpret_cast<const char *>(this->manifest_.data() + start), end - start};
+            };
+
+            this->assets_.reserve(count);
+            std::uint32_t instance_offset = 4;
+            std::uint32_t relocation_offset = 4;
+            std::uint32_t imports_offset = 4;
+            for (std::uint32_t i = 0; i < count; ++i) {
+                byte_reader entry{std::span<const std::byte>{this->manifest_}.subspan(entries_off + static_cast<std::size_t>(i) * entry_size, entry_size)};
+                binary_asset asset;
+                asset.index = i;
+                asset.type_id = entry.read_u32();
+                asset.instance_id = entry.read_u32();
+                asset.type_hash = entry.read_u32();
+                asset.instance_hash = entry.read_u32();
+                const auto reference_offset = entry.read_i32();
+                const auto reference_count = entry.read_i32();
+                const auto name_offset = entry.read_i32();
+                const auto source_offset = entry.read_i32();
+                asset.instance_size = entry.read_u32();
+                asset.relocation_size = entry.read_u32();
+                asset.imports_size = entry.read_u32();
+                asset.tokenized = entry.read_u32() != 0U;
+                asset.name = cstr(names_off, name_offset);
+                asset.source = cstr(sources_off, source_offset);
+                asset.instance_offset = instance_offset;
+                asset.relocation_offset = relocation_offset;
+                asset.imports_offset = imports_offset;
+                instance_offset += asset.instance_size;
+                relocation_offset += asset.relocation_size;
+                imports_offset += asset.imports_size;
+
+                for (std::int32_t j = 0; j < reference_count; ++j) {
+                    byte_reader ref{std::span<const std::byte>{this->manifest_}.subspan(references_off + static_cast<std::size_t>(reference_offset) +
+                                                                                          static_cast<std::size_t>(j) * 8U,
+                                                                                      8U)};
+                    asset.references.emplace_back(ref.read_u32(), ref.read_u32());
+                }
+                this->asset_index_.emplace((static_cast<std::uint64_t>(asset.type_id) << 32U) | asset.instance_id, this->assets_.size());
+                this->assets_.push_back(std::move(asset));
+            }
+        }
+
+        std::string stream_ = "static";
+        std::vector<std::byte> manifest_;
+        std::vector<std::byte> data_;
+        std::vector<std::byte> relocation_;
+        std::vector<std::byte> imports_;
+        std::uint16_t version_ = 0;
+        bool is_linked_ = false;
+        std::vector<binary_asset> assets_;
+        std::unordered_map<std::uint64_t, std::size_t> asset_index_;
+        cdata_source cdata_;
+    };
+
+    namespace detail {
+        [[nodiscard]] inline auto pick_manifest(std::string_view stream) -> std::string { return std::format("data\\{}.manifest", stream); }
+    }
+
+    /**
+     * Load one BinaryAsset stream out of a `BIG4` archive.
+     *
+     * `stream` selects the `.manifest` (default: the first of
+     * `binary_stream_order` found). When `need_data` is false only the manifest
+     * is read, which is enough to enumerate assets without decompressing the
+     * multi-hundred-megabyte instance stream.
+     *
+     * The returned container keeps a `cdata` reader that borrows `archive`; keep
+     * the archive alive for as long as the container is used.
+     */
+    [[nodiscard]] inline auto binary_stream_from_big(const big_archive &archive, std::optional<binary_stream> stream = std::nullopt, bool need_data = true) -> binary_container {
+        std::optional<binary_stream> chosen = stream;
+        if (!chosen) {
+            for (const auto candidate: binary_stream_order) {
+                if (archive.contains(detail::pick_manifest(to_string(candidate)))) {
+                    chosen = candidate;
+                    break;
+                }
+            }
+        }
+        if (!chosen) throw binary_error("archive has no known .manifest entry");
+
+        const auto manifest_name = detail::pick_manifest(to_string(*chosen));
+        const auto base = manifest_name.substr(0, manifest_name.size() - std::string_view{".manifest"}.size());
+        const auto manifest = maybe_decompress(archive.read(manifest_name, false));
+        std::vector<std::byte> data;
+        if (need_data) data = maybe_decompress(archive.read(base + ".bin", false));
+        const auto relocation = maybe_decompress(archive.read(base + ".relo", false));
+        const auto imports = maybe_decompress(archive.read(base + ".imp", false));
+
+        auto container = binary_container::from_bytes(std::move(manifest), std::move(data), std::move(relocation), std::move(imports), std::string{to_string(*chosen)});
+        container.set_cdata_source([&archive](const std::string &name) -> std::optional<std::vector<std::byte>> {
+            const auto *entry = archive.find_exact(name);
+            if (entry == nullptr) return std::nullopt;
+            return maybe_decompress(archive.read(*entry, false));
+        });
+        return container;
+    }
+
+} // namespace ra3::assets

third_party/libra3assets/src/bytes.cppm

@@ -0,0 +1,220 @@
+/**
+ * Bounds-checked little-/big-endian byte readers and writers.
+ *
+ * Red Alert 3's asset formats are little-endian, with one notable exception:
+ * the `BIG4` index stores its counts, offsets and sizes big-endian. Both byte
+ * orders are provided here. Every read is bounds-checked and throws
+ * `format_error` rather than reading past the end of the buffer.
+ */
+export module ra3.assets:bytes;
+
+import std;
+
+import :error;
+
+export namespace ra3::assets {
+
+    /** A cursor over a read-only byte range with checked accessors. */
+    class byte_reader {
+    public:
+        explicit byte_reader(std::span<const std::byte> data)
+            : data_(data) {
+        }
+
+        [[nodiscard]] auto size() const -> std::size_t { return this->data_.size(); }
+        [[nodiscard]] auto position() const -> std::size_t { return this->pos_; }
+        [[nodiscard]] auto remaining() const -> std::size_t { return this->data_.size() - this->pos_; }
+        [[nodiscard]] auto empty() const -> bool { return this->pos_ >= this->data_.size(); }
+
+        auto seek(std::size_t at) -> void {
+            if (at > this->data_.size()) throw format_error("seek past end of buffer");
+            this->pos_ = at;
+        }
+
+        auto skip(std::size_t count) -> void {
+            this->require(count);
+            this->pos_ += count;
+        }
+
+        [[nodiscard]] auto read_u8() -> std::uint8_t {
+            this->require(1);
+            return std::to_integer<std::uint8_t>(this->data_[this->pos_++]);
+        }
+
+        [[nodiscard]] auto read_bool() -> bool { return this->read_u8() != 0U; }
+
+        [[nodiscard]] auto read_u16() -> std::uint16_t {
+            return static_cast<std::uint16_t>(this->read_le(2));
+        }
+
+        [[nodiscard]] auto read_u24() -> std::uint32_t { return this->read_le(3); }
+
+        [[nodiscard]] auto read_u32() -> std::uint32_t { return this->read_le(4); }
+
+        [[nodiscard]] auto read_u64() -> std::uint64_t { return this->read_le(8); }
+
+        [[nodiscard]] auto read_i16() -> std::int16_t { return static_cast<std::int16_t>(this->read_u16()); }
+
+        [[nodiscard]] auto read_i32() -> std::int32_t { return static_cast<std::int32_t>(this->read_u32()); }
+
+        [[nodiscard]] auto read_f32() -> float { return std::bit_cast<float>(this->read_u32()); }
+
+        [[nodiscard]] auto read_be_u16() -> std::uint16_t { return static_cast<std::uint16_t>(this->read_be(2)); }
+        [[nodiscard]] auto read_be_u32() -> std::uint32_t { return this->read_be(4); }
+
+        /** A view of the next `count` bytes; the cursor advances past them. */
+        [[nodiscard]] auto read_bytes(std::size_t count) -> std::span<const std::byte> {
+            this->require(count);
+            const auto view = this->data_.subspan(this->pos_, count);
+            this->pos_ += count;
+            return view;
+        }
+
+        /** `count` bytes decoded as Latin-1 (one byte per character). */
+        [[nodiscard]] auto read_ascii(std::size_t count) -> std::string {
+            const auto view = this->read_bytes(count);
+            return std::string{reinterpret_cast<const char *>(view.data()), view.size()};
+        }
+
+        /** A `u16`-length-prefixed ASCII string. */
+        [[nodiscard]] auto read_u16_prefixed_ascii() -> std::string { return this->read_ascii(this->read_u16()); }
+
+        /** A `u16`-length-prefixed string, decoded as UTF-8 (ASCII-compatible). */
+        [[nodiscard]] auto read_u16_prefixed_ascii_as_utf8() -> std::string { return this->read_u16_prefixed_ascii(); }
+
+        /** A `u16`-length-prefixed UTF-16LE string (length counted in code units). */
+        [[nodiscard]] auto read_u16_prefixed_utf16() -> std::u16string {
+            const auto count = this->read_u16();
+            this->require(static_cast<std::size_t>(count) * 2U);
+            std::u16string text(count, u'\0');
+            for (std::uint16_t i = 0; i < count; ++i) text[i] = static_cast<char16_t>(this->read_u16());
+            return text;
+        }
+
+        /** A NUL-terminated ASCII string; the cursor stops just past the NUL. */
+        [[nodiscard]] auto read_cstring() -> std::string {
+            std::string text;
+            while (this->pos_ < this->data_.size()) {
+                const auto ch = static_cast<char>(this->read_u8());
+                if (ch == '\0') break;
+                text.push_back(ch);
+            }
+            return text;
+        }
+
+    private:
+        auto require(std::size_t count) const -> void {
+            if (this->pos_ + count > this->data_.size()) throw format_error("unexpected end of buffer");
+        }
+
+        [[nodiscard]] auto read_le(std::size_t width) -> std::uint64_t {
+            this->require(width);
+            std::uint64_t value = 0;
+            for (std::size_t i = 0; i < width; ++i) value |= static_cast<std::uint64_t>(std::to_integer<std::uint8_t>(this->data_[this->pos_ + i])) << (8U * i);
+            this->pos_ += width;
+            return value;
+        }
+
+        [[nodiscard]] auto read_be(std::size_t width) -> std::uint64_t {
+            this->require(width);
+            std::uint64_t value = 0;
+            for (std::size_t i = 0; i < width; ++i) value = (value << 8U) | static_cast<std::uint64_t>(std::to_integer<std::uint8_t>(this->data_[this->pos_ + i]));
+            this->pos_ += width;
+            return value;
+        }
+
+        std::span<const std::byte> data_;
+        std::size_t pos_ = 0;
+    };
+
+    /** An append-only little-endian byte buffer. */
+    class byte_writer {
+    public:
+        [[nodiscard]] auto size() const -> std::size_t { return this->buffer_.size(); }
+        [[nodiscard]] auto data() const -> std::span<const std::byte> { return this->buffer_; }
+        [[nodiscard]] auto take() -> std::vector<std::byte> { return std::move(this->buffer_); }
+
+        auto write_u8(std::uint8_t value) -> void { this->buffer_.push_back(static_cast<std::byte>(value)); }
+
+        auto write_bool(bool value) -> void { this->write_u8(value ? 1U : 0U); }
+
+        auto write_u16(std::uint16_t value) -> void { this->write_le(value, 2); }
+        auto write_u24(std::uint32_t value) -> void { this->write_le(value, 3); }
+        auto write_u32(std::uint32_t value) -> void { this->write_le(value, 4); }
+        auto write_u64(std::uint64_t value) -> void { this->write_le(value, 8); }
+        auto write_i16(std::int16_t value) -> void { this->write_u16(static_cast<std::uint16_t>(value)); }
+        auto write_i32(std::int32_t value) -> void { this->write_u32(static_cast<std::uint32_t>(value)); }
+        auto write_f32(float value) -> void { this->write_u32(std::bit_cast<std::uint32_t>(value)); }
+
+        auto write_bytes(std::span<const std::byte> bytes) -> void { this->buffer_.insert(this->buffer_.end(), bytes.begin(), bytes.end()); }
+
+        auto write_ascii(std::string_view text) -> void {
+            for (const auto ch: text) this->buffer_.push_back(static_cast<std::byte>(static_cast<unsigned char>(ch)));
+        }
+
+        auto write_u16_prefixed_ascii(std::string_view text) -> void {
+            this->write_u16(static_cast<std::uint16_t>(text.size()));
+            this->write_ascii(text);
+        }
+
+        auto write_u16_prefixed_utf16(std::u16string_view text) -> void {
+            this->write_u16(static_cast<std::uint16_t>(text.size()));
+            for (const auto unit: text) {
+                this->write_u16(static_cast<std::uint16_t>(unit));
+            }
+        }
+
+        /** Overwrite a previously written `u32` (used to backpatch sizes). */
+        auto patch_u32(std::size_t offset, std::uint32_t value) -> void {
+            if (offset + 4U > this->buffer_.size()) throw format_error("patch offset past end of buffer");
+            for (std::size_t i = 0; i < 4U; ++i) this->buffer_[offset + i] = static_cast<std::byte>((value >> (8U * i)) & 0xFFU);
+        }
+
+    private:
+        auto write_le(std::uint64_t value, std::size_t width) -> void {
+            for (std::size_t i = 0; i < width; ++i) this->buffer_.push_back(static_cast<std::byte>((value >> (8U * i)) & 0xFFU));
+        }
+
+        std::vector<std::byte> buffer_;
+    };
+
+    /** Convenience: encode a UTF-8 string (ASCII subset) as UTF-16LE code units. */
+    [[nodiscard]] inline auto to_utf16(std::string_view text) -> std::u16string {
+        std::u16string out;
+        out.reserve(text.size());
+        for (const auto ch: text) out.push_back(static_cast<char16_t>(static_cast<unsigned char>(ch)));
+        return out;
+    }
+
+    /** Convenience: narrow a UTF-16 string that is known to be within Latin-1. */
+    [[nodiscard]] inline auto to_ascii(std::u16string_view text) -> std::string {
+        std::string out;
+        out.reserve(text.size());
+        for (const auto unit: text) out.push_back(static_cast<char>(unit & 0xFFU));
+        return out;
+    }
+
+    /** Read a whole file as bytes. */
+    [[nodiscard]] inline auto read_file(const std::filesystem::path &path) -> std::vector<std::byte> {
+        std::ifstream in(path, std::ios::binary);
+        if (!in) throw format_error("cannot open file: " + path.string());
+        in.seekg(0, std::ios::end);
+        const auto end = in.tellg();
+        if (end < 0) throw format_error("cannot size file: " + path.string());
+        std::vector<std::byte> bytes(static_cast<std::size_t>(end));
+        in.seekg(0, std::ios::beg);
+        if (!bytes.empty()) in.read(reinterpret_cast<char *>(bytes.data()), static_cast<std::streamsize>(bytes.size()));
+        return bytes;
+    }
+
+    /** Write bytes to a file, creating parent directories as needed. */
+    inline auto write_file(const std::filesystem::path &path, std::span<const std::byte> bytes) -> void {
+        std::error_code ec;
+        if (!path.parent_path().empty()) std::filesystem::create_directories(path.parent_path(), ec);
+        std::ofstream out(path, std::ios::binary);
+        if (!out) throw format_error("cannot write file: " + path.string());
+        out.write(reinterpret_cast<const char *>(bytes.data()), static_cast<std::streamsize>(bytes.size()));
+        if (!out) throw format_error("cannot write file: " + path.string());
+    }
+
+} // namespace ra3::assets

third_party/libra3assets/src/csf.cppm

@@ -0,0 +1,180 @@
+/**
+ * SAGE `.csf` string tables (`data\gamestrings.csf`).
+ *
+ * The compressed unit/label localization table Red Alert 3 ships per language
+ * in `Lang-*.big` / `English.big`. Each value is a UTF-16 string whose every
+ * code unit is bit-inverted (`code ^ 0xFFFF`); labels are plain ASCII and are
+ * matched case-insensitively.
+ */
+export module ra3.assets:csf;
+
+import std;
+
+import :big;
+import :bytes;
+import :error;
+import :refpack;
+
+export namespace ra3::assets {
+
+    /** Magic of the label block (`" LBL"` little-endian). */
+    inline constexpr std::uint32_t csf_label_flag = 0x4C424C20U;
+
+    /** Magic of a value block (`" RTS"` little-endian). */
+    inline constexpr std::uint32_t csf_value_flag = 0x53545220U;
+
+    /** One label and its (usually single) string value. */
+    struct csf_entry {
+        std::string label;
+        std::vector<std::u16string> values;
+
+        /** The concatenation of every value block, the way the game renders it. */
+        [[nodiscard]] auto value() const -> std::u16string {
+            std::u16string joined;
+            for (const auto &chunk: this->values) joined += chunk;
+            return joined;
+        }
+    };
+
+    /** Decode a UTF-16 string (with surrogate pairs) to UTF-8. */
+    [[nodiscard]] inline auto utf16_to_utf8(std::u16string_view text) -> std::string {
+        std::string out;
+        for (std::size_t i = 0; i < text.size(); ++i) {
+            auto code = static_cast<std::uint32_t>(text[i]);
+            if (code >= 0xD800U && code <= 0xDBFFU && i + 1U < text.size()) {
+                const auto low = static_cast<std::uint32_t>(text[i + 1U]);
+                if (low >= 0xDC00U && low <= 0xDFFFU) {
+                    code = 0x10000U + ((code - 0xD800U) << 10U) + (low - 0xDC00U);
+                    ++i;
+                }
+            }
+            if (code < 0x80U) {
+                out.push_back(static_cast<char>(code));
+            } else if (code < 0x800U) {
+                out.push_back(static_cast<char>(0xC0U | (code >> 6U)));
+                out.push_back(static_cast<char>(0x80U | (code & 0x3FU)));
+            } else if (code < 0x10000U) {
+                out.push_back(static_cast<char>(0xE0U | (code >> 12U)));
+                out.push_back(static_cast<char>(0x80U | ((code >> 6U) & 0x3FU)));
+                out.push_back(static_cast<char>(0x80U | (code & 0x3FU)));
+            } else {
+                out.push_back(static_cast<char>(0xF0U | (code >> 18U)));
+                out.push_back(static_cast<char>(0x80U | ((code >> 12U) & 0x3FU)));
+                out.push_back(static_cast<char>(0x80U | ((code >> 6U) & 0x3FU)));
+                out.push_back(static_cast<char>(0x80U | (code & 0x3FU)));
+            }
+        }
+        return out;
+    }
+
+    /**
+     * A parsed `.csf` table.
+     *
+     * Labels are stored verbatim; lookup upper-cases the key because the engine
+     * treats them case-insensitively.
+     */
+    class csf_table {
+    public:
+        /** Parse a `.csf` image. */
+        [[nodiscard]] static auto parse(std::span<const std::byte> bytes) -> csf_table {
+            byte_reader reader{bytes};
+            const auto magic = reader.read_ascii(4);
+            if (magic != "CSF " && magic != " FSC") throw csf_error("not a CSF file");
+            csf_table table;
+            table.version_ = reader.read_u32();
+            const auto num_labels = reader.read_u32();
+            (void) reader.read_u32(); // number of value blocks
+            (void) reader.read_u32(); // reserved
+            (void) reader.read_u32(); // reserved
+            table.entries_.reserve(num_labels);
+            for (std::uint32_t i = 0; i < num_labels; ++i) {
+                (void) reader.read_u32(); // label flag (" LBL")
+                const auto value_count = reader.read_u32();
+                const auto label_length = reader.read_u32();
+                csf_entry entry;
+                entry.label = reader.read_ascii(label_length);
+                entry.values.reserve(value_count);
+                for (std::uint32_t j = 0; j < value_count; ++j) {
+                    (void) reader.read_u32(); // value flag (" RTS")
+                    const auto char_count = reader.read_u32();
+                    std::u16string value(char_count, u'\0');
+                    for (std::uint32_t k = 0; k < char_count; ++k) value[k] = static_cast<char16_t>(reader.read_u16() ^ 0xFFFFU);
+                    entry.values.push_back(std::move(value));
+                }
+                table.entries_.push_back(std::move(entry));
+            }
+            table.reindex();
+            return table;
+        }
+
+        /** Read and parse a `.csf` file from disk. */
+        [[nodiscard]] static auto open(const std::filesystem::path &path) -> csf_table {
+            return csf_table::parse(read_file(path));
+        }
+
+        /** Load `data\gamestrings.csf` out of an archive. */
+        [[nodiscard]] static auto from_big(const big_archive &archive, std::string_view entry = "data\\gamestrings.csf") -> csf_table {
+            return csf_table::parse(maybe_decompress(archive.read(entry, false)));
+        }
+
+        /** Serialise the table back to a `.csf` image. */
+        [[nodiscard]] auto write() const -> std::vector<std::byte> {
+            byte_writer writer;
+            writer.write_ascii(" FSC");
+            writer.write_u32(this->version_);
+            writer.write_u32(static_cast<std::uint32_t>(this->entries_.size()));
+            std::uint32_t value_count = 0;
+            for (const auto &entry: this->entries_) value_count += static_cast<std::uint32_t>(entry.values.size());
+            writer.write_u32(value_count);
+            writer.write_u32(0);
+            writer.write_u32(0);
+            for (const auto &entry: this->entries_) {
+                writer.write_u32(csf_label_flag);
+                writer.write_u32(static_cast<std::uint32_t>(entry.values.size()));
+                writer.write_u32(static_cast<std::uint32_t>(entry.label.size()));
+                writer.write_ascii(entry.label);
+                for (const auto &value: entry.values) {
+                    writer.write_u32(csf_value_flag);
+                    writer.write_u32(static_cast<std::uint32_t>(value.size()));
+                    for (const auto unit: value) writer.write_u16(static_cast<std::uint16_t>(unit) ^ 0xFFFFU);
+                }
+            }
+            return writer.take();
+        }
+
+        [[nodiscard]] auto version() const -> std::uint32_t { return this->version_; }
+        [[nodiscard]] auto entries() const -> const std::vector<csf_entry> & { return this->entries_; }
+        [[nodiscard]] auto size() const -> std::size_t { return this->entries_.size(); }
+
+        /** The entry for `label`, or `nullptr`; the match is case-insensitive. */
+        [[nodiscard]] auto find(std::string_view label) const -> const csf_entry * {
+            auto key = std::string{label};
+            std::ranges::transform(key, key.begin(), [](unsigned char ch) { return static_cast<char>(std::toupper(ch)); });
+            const auto it = this->index_.find(key);
+            return it == this->index_.end() ? nullptr : &this->entries_[it->second];
+        }
+
+        /** The UTF-8 value for `label`, or `fallback` when absent. */
+        [[nodiscard]] auto lookup(std::string_view label, std::string fallback = {}) const -> std::string {
+            const auto *entry = this->find(label);
+            if (entry == nullptr) return fallback;
+            auto text = utf16_to_utf8(entry->value());
+            return text.empty() ? std::move(fallback) : text;
+        }
+
+    private:
+        auto reindex() -> void {
+            this->index_.clear();
+            for (std::size_t i = 0; i < this->entries_.size(); ++i) {
+                auto key = this->entries_[i].label;
+                std::ranges::transform(key, key.begin(), [](unsigned char ch) { return static_cast<char>(std::toupper(ch)); });
+                this->index_.try_emplace(std::move(key), i);
+            }
+        }
+
+        std::uint32_t version_ = 3;
+        std::vector<csf_entry> entries_;
+        std::unordered_map<std::string, std::size_t> index_;
+    };
+
+} // namespace ra3::assets

third_party/libra3assets/src/error.cppm

@@ -0,0 +1,56 @@
+/**
+ * Exception hierarchy of libra3assets.
+ *
+ * Every failure the library reports derives from `asset_error` (itself a
+ * `std::runtime_error`), so a caller can catch the whole family with one
+ * handler and still discriminate by the concrete type when it matters.
+ */
+export module ra3.assets:error;
+
+import std;
+
+export namespace ra3::assets {
+
+    /** Base class of every failure libra3assets reports. */
+    class asset_error: public std::runtime_error {
+    public:
+        using std::runtime_error::runtime_error;
+    };
+
+    /** A byte range is not a well-formed Red Alert 3 asset. */
+    class format_error: public asset_error {
+    public:
+        using asset_error::asset_error;
+    };
+
+    /** An EA RefPack stream is malformed or its length disagrees. */
+    class refpack_error: public asset_error {
+    public:
+        using asset_error::asset_error;
+    };
+
+    /** A `BIG4` archive is malformed, truncated or missing an entry. */
+    class big_error: public asset_error {
+    public:
+        using asset_error::asset_error;
+    };
+
+    /** A compiled `BinaryAsset` manifest/stream is malformed. */
+    class binary_error: public asset_error {
+    public:
+        using asset_error::asset_error;
+    };
+
+    /** A SAGE `.csf` string table is malformed. */
+    class csf_error: public asset_error {
+    public:
+        using asset_error::asset_error;
+    };
+
+    /** A SAGE `.map` container or one of its chunks is malformed. */
+    class map_error: public asset_error {
+    public:
+        using asset_error::asset_error;
+    };
+
+} // namespace ra3::assets

third_party/libra3assets/src/map.cppm

@@ -0,0 +1,778 @@
+/**
+ * SAGE `.map` containers - the core of the map editor.
+ *
+ * A `.map` is a `CkMp` chunk tree. On disk it may be wrapped twice: inside a
+ * `BIG4` the payload is one RefPack stream; the `.map` file it yields is either
+ * a bare `CkMp` tree or an `EAR\0`-wrapped RefPack stream around one. This
+ * partition unwraps all three shapes and models the tree as an ordered list of
+ * named, versioned chunks.
+ *
+ * The container round-trips losslessly: chunks this library does not model are
+ * preserved byte-for-byte, and the asset-name table keeps its original indices
+ * so unparsed chunks (which embed name indices) stay valid. On top of the
+ * container sit typed accessors for the chunks a map editor needs:
+ * `HeightMapData` (the terrain grid), `ObjectsList` (every placed prop, building
+ * and `*Waypoints/Waypoint`), `MPPositionList`, `WorldInfo` and `WaypointsList`.
+ */
+export module ra3.assets:map;
+
+import std;
+
+import :big;
+import :bytes;
+import :error;
+import :refpack;
+
+export namespace ra3::assets {
+
+    /** A world-space coordinate. */
+    struct coord3d {
+        float x = 0.0F;
+        float y = 0.0F;
+        float z = 0.0F;
+    };
+
+    /**
+     * A map object's `RoadType` bit flags.
+     *
+     * Zero for most objects; set on objects the terrain road system connects
+     * (`Start`/`End`/`BridgeStart`/`BridgeEnd`/`Angled`/`TightCurve`/`EndCap`).
+     */
+    enum class road_type : std::uint32_t {
+        none = 0,
+        start = 2,
+        end = 4,
+        angled = 8,
+        bridge_start = 16,
+        bridge_end = 32,
+        tight_curve = 64,
+        end_cap = 128,
+        unknown3 = 256,
+        unknown4 = 512,
+    };
+
+    [[nodiscard]] constexpr auto operator|(road_type a, road_type b) -> road_type {
+        return static_cast<road_type>(static_cast<std::uint32_t>(a) | static_cast<std::uint32_t>(b));
+    }
+    [[nodiscard]] constexpr auto operator&(road_type a, road_type b) -> road_type {
+        return static_cast<road_type>(static_cast<std::uint32_t>(a) & static_cast<std::uint32_t>(b));
+    }
+
+    /** True when `value` has every bit of `flag` set. */
+    [[nodiscard]] constexpr auto has_flag(road_type value, road_type flag) -> bool {
+        return (static_cast<std::uint32_t>(value) & static_cast<std::uint32_t>(flag)) != 0U;
+    }
+
+    /** The `CkMp` chunk types SAGE defines, plus `unknown` for anything else. */
+    enum class chunk_kind {
+        asset_list,
+        global_version,
+        height_map_data,
+        blend_tile_data,
+        world_info,
+        mp_position_list,
+        sides_list,
+        library_map_lists,
+        teams,
+        player_scripts_list,
+        build_lists,
+        objects_list,
+        polygon_triggers,
+        trigger_areas,
+        global_water_settings,
+        fog_settings,
+        mission_hot_spots,
+        mission_objectives,
+        standing_water_areas,
+        river_areas,
+        standing_wave_areas,
+        global_lighting,
+        post_effects_chunk,
+        environment_data,
+        named_cameras,
+        camera_animation_list,
+        castle_templates,
+        waypoints_list,
+        skybox_settings,
+        unknown,
+    };
+
+    /** The canonical chunk name (the `unknown` kind has no name). */
+    [[nodiscard]] inline auto to_string(chunk_kind kind) -> std::string_view {
+        switch (kind) {
+        case chunk_kind::asset_list: return "AssetList";
+        case chunk_kind::global_version: return "GlobalVersion";
+        case chunk_kind::height_map_data: return "HeightMapData";
+        case chunk_kind::blend_tile_data: return "BlendTileData";
+        case chunk_kind::world_info: return "WorldInfo";
+        case chunk_kind::mp_position_list: return "MPPositionList";
+        case chunk_kind::sides_list: return "SidesList";
+        case chunk_kind::library_map_lists: return "LibraryMapLists";
+        case chunk_kind::teams: return "Teams";
+        case chunk_kind::player_scripts_list: return "PlayerScriptsList";
+        case chunk_kind::build_lists: return "BuildLists";
+        case chunk_kind::objects_list: return "ObjectsList";
+        case chunk_kind::polygon_triggers: return "PolygonTriggers";
+        case chunk_kind::trigger_areas: return "TriggerAreas";
+        case chunk_kind::global_water_settings: return "GlobalWaterSettings";
+        case chunk_kind::fog_settings: return "FogSettings";
+        case chunk_kind::mission_hot_spots: return "MissionHotSpots";
+        case chunk_kind::mission_objectives: return "MissionObjectives";
+        case chunk_kind::standing_water_areas: return "StandingWaterAreas";
+        case chunk_kind::river_areas: return "RiverAreas";
+        case chunk_kind::standing_wave_areas: return "StandingWaveAreas";
+        case chunk_kind::global_lighting: return "GlobalLighting";
+        case chunk_kind::post_effects_chunk: return "PostEffectsChunk";
+        case chunk_kind::environment_data: return "EnvironmentData";
+        case chunk_kind::named_cameras: return "NamedCameras";
+        case chunk_kind::camera_animation_list: return "CameraAnimationList";
+        case chunk_kind::castle_templates: return "CastleTemplates";
+        case chunk_kind::waypoints_list: return "WaypointsList";
+        case chunk_kind::skybox_settings: return "SkyboxSettings";
+        case chunk_kind::unknown: break;
+        }
+        return {};
+    }
+
+    /** Classify a chunk name. */
+    [[nodiscard]] inline auto chunk_kind_of(std::string_view name) -> chunk_kind {
+        for (int i = 0; i < static_cast<int>(chunk_kind::unknown); ++i) {
+            const auto kind = static_cast<chunk_kind>(i);
+            if (to_string(kind) == name) return kind;
+        }
+        return chunk_kind::unknown;
+    }
+
+    /** The map's asset-name table: `index -> name`, indices preserved on write. */
+    class name_table {
+    public:
+        [[nodiscard]] auto name(std::uint32_t index) const -> std::string_view {
+            if (index >= this->names_.size()) throw map_error("asset name index out of range: " + std::to_string(index));
+            return this->names_[index];
+        }
+
+        /** The existing index of `name`, or a freshly appended one. */
+        [[nodiscard]] auto get_or_create(std::string_view name) -> std::uint32_t {
+            for (std::uint32_t i = 1; i < this->names_.size(); ++i) {
+                if (this->names_[i] == name) return i;
+            }
+            this->names_.emplace_back(name);
+            return static_cast<std::uint32_t>(this->names_.size() - 1U);
+        }
+
+        [[nodiscard]] auto entries() const -> const std::vector<std::string> & { return this->names_; }
+        [[nodiscard]] auto size() const -> std::size_t { return this->names_.empty() ? 0U : this->names_.size() - 1U; }
+
+        /** Resize the table (used while parsing); index 0 stays the unused slot. */
+        auto resize(std::size_t count) -> void { this->names_.resize(count); }
+
+        /** Assign the name at `index` (used while parsing). */
+        auto set_name(std::uint32_t index, std::string name) -> void { this->names_.at(index) = std::move(name); }
+
+    private:
+        std::vector<std::string> names_{std::string{}}; // index 0 is unused
+    };
+
+    /** One `CkMp` chunk: a named, versioned, opaque payload. */
+    struct map_chunk {
+        std::string name;
+        chunk_kind kind = chunk_kind::unknown;
+        std::uint32_t asset_index = 0;
+        std::uint16_t version = 0;
+        std::vector<std::byte> payload;
+    };
+
+    /** A `HeightMapData` border rectangle. */
+    struct height_map_border {
+        std::uint32_t corner1_x = 0;
+        std::uint32_t corner1_y = 0;
+        std::uint32_t x = 0;
+        std::uint32_t y = 0;
+    };
+
+    /** The parsed `HeightMapData` chunk: the terrain elevation grid. */
+    struct height_map_data {
+        std::uint32_t width = 0;
+        std::uint32_t height = 0;
+        std::uint32_t border_width = 0;
+        std::vector<height_map_border> borders;
+        std::vector<std::uint16_t> elevations; ///< `width * height`, row-major (y outer, x inner)
+        std::uint16_t version = 6;
+
+        /** Metres per elevation unit (uint16 grids scale by 0.0390625). */
+        [[nodiscard]] auto vertical_scale() const -> float { return this->version >= 5U ? 0.0390625F : 0.625F; }
+
+        [[nodiscard]] auto at(std::uint32_t x, std::uint32_t y) const -> std::uint16_t { return this->elevations.at(static_cast<std::size_t>(y) * this->width + x); }
+        auto set(std::uint32_t x, std::uint32_t y, std::uint16_t value) -> void { this->elevations.at(static_cast<std::size_t>(y) * this->width + x) = value; }
+
+        /** Parse a `HeightMapData` chunk payload. */
+        [[nodiscard]] static auto parse(std::uint16_t version, std::span<const std::byte> payload) -> height_map_data {
+            byte_reader reader{payload};
+            height_map_data data;
+            data.version = version;
+            data.width = reader.read_u32();
+            data.height = reader.read_u32();
+            data.border_width = reader.read_u32();
+            const auto border_count = reader.read_u32();
+            data.borders.reserve(border_count);
+            for (std::uint32_t i = 0; i < border_count; ++i) {
+                height_map_border border;
+                if (version >= 6U) {
+                    border.corner1_x = reader.read_u32();
+                    border.corner1_y = reader.read_u32();
+                }
+                border.x = reader.read_u32();
+                border.y = reader.read_u32();
+                data.borders.push_back(border);
+            }
+            const auto area = reader.read_u32();
+            const auto expected = static_cast<std::uint64_t>(data.width) * data.height;
+            if (area != expected) throw map_error("HeightMapData area does not match width * height");
+            data.elevations.resize(static_cast<std::size_t>(expected));
+            for (std::uint32_t y = 0; y < data.height; ++y) {
+                for (std::uint32_t x = 0; x < data.width; ++x) {
+                    data.elevations[static_cast<std::size_t>(y) * data.width + x] = version >= 5U ? reader.read_u16() : reader.read_u8();
+                }
+            }
+            return data;
+        }
+
+        /** Serialise the chunk payload (without the 10-byte chunk header). */
+        [[nodiscard]] auto serialize() const -> std::vector<std::byte> {
+            byte_writer writer;
+            writer.write_u32(this->width);
+            writer.write_u32(this->height);
+            writer.write_u32(this->border_width);
+            writer.write_u32(static_cast<std::uint32_t>(this->borders.size()));
+            for (const auto &border: this->borders) {
+                if (this->version >= 6U) {
+                    writer.write_u32(border.corner1_x);
+                    writer.write_u32(border.corner1_y);
+                }
+                writer.write_u32(border.x);
+                writer.write_u32(border.y);
+            }
+            writer.write_u32(this->width * this->height);
+            for (const auto elevation: this->elevations) {
+                if (this->version >= 5U) {
+                    writer.write_u16(elevation);
+                } else {
+                    writer.write_u8(static_cast<std::uint8_t>(elevation));
+                }
+            }
+            return writer.take();
+        }
+    };
+
+    /** The value type of an asset property. */
+    enum class property_type : std::uint8_t {
+        boolean = 0,
+        integer = 1,
+        real_number = 2,
+        ascii_string = 3,
+        unicode_string = 4,
+        unknown = 5,
+    };
+
+    /** The payload of an `asset_property`; the active alternative tracks `property_type`. */
+    using property_value = std::variant<bool, std::int32_t, float, std::string, std::u16string>;
+
+    /** One key/value pair carried by a map object or the world info. */
+    struct asset_property {
+        std::string name;
+        property_type type = property_type::integer;
+        property_value value{}; ///< bool, int32, float, ASCII/UTF-8 string, or UTF-16 string
+
+        [[nodiscard]] static auto boolean(std::string name, bool value) -> asset_property {
+            return {std::move(name), property_type::boolean, value};
+        }
+        [[nodiscard]] static auto integer(std::string name, std::int32_t value) -> asset_property {
+            return {std::move(name), property_type::integer, value};
+        }
+        [[nodiscard]] static auto real(std::string name, float value) -> asset_property {
+            return {std::move(name), property_type::real_number, value};
+        }
+        [[nodiscard]] static auto text(std::string name, std::string value) -> asset_property {
+            return {std::move(name), property_type::ascii_string, std::move(value)};
+        }
+        [[nodiscard]] static auto wide_text(std::string name, std::u16string value) -> asset_property {
+            return {std::move(name), property_type::unicode_string, std::move(value)};
+        }
+
+        [[nodiscard]] auto as_bool() const -> bool {
+            const auto *held = std::get_if<bool>(&this->value);
+            return held != nullptr && *held;
+        }
+        [[nodiscard]] auto as_int() const -> std::int32_t {
+            const auto *held = std::get_if<std::int32_t>(&this->value);
+            return held != nullptr ? *held : 0;
+        }
+        [[nodiscard]] auto as_real() const -> float {
+            const auto *held = std::get_if<float>(&this->value);
+            return held != nullptr ? *held : 0.0F;
+        }
+        [[nodiscard]] auto as_ascii() const -> std::string_view {
+            const auto *held = std::get_if<std::string>(&this->value);
+            return held != nullptr ? std::string_view{*held} : std::string_view{};
+        }
+        [[nodiscard]] auto as_unicode() const -> const std::u16string * { return std::get_if<std::u16string>(&this->value); }
+    };
+
+    /** One object placed on the map (building, prop, waypoint, ...). */
+    struct map_object {
+        std::string type_name; ///< the SAGE `ThingTemplate` name, e.g. `*Waypoints/Waypoint`
+        coord3d position;
+        float angle = 0.0F;
+        road_type road = road_type::none; ///< road connectivity flags (0 for most objects)
+        std::uint16_t version = 1;
+        std::vector<asset_property> properties;
+
+        [[nodiscard]] auto property(std::string_view key) const -> const asset_property * {
+            for (const auto &entry: this->properties) {
+                if (entry.name == key) return &entry;
+            }
+            return nullptr;
+        }
+    };
+
+    /** A player start position recovered from a `Player_N_Start` waypoint. */
+    struct player_start {
+        int index = 0; ///< the `N` in `Player_N_Start` (1-based)
+        coord3d position;
+    };
+
+    /** One `MPPositionInfo` entry. */
+    struct mp_position {
+        bool is_human = false;
+        bool is_computer = false;
+        bool load_ai_script = false;
+        std::uint32_t team = 0;
+        std::vector<std::string> side_restrictions;
+        std::uint16_t version = 1;
+    };
+
+    /** One `WaypointPath` (a link between two waypoints by id). */
+    struct waypoint_path {
+        std::int32_t start_id = 0;
+        std::int32_t end_id = 0;
+    };
+
+    namespace detail {
+        /** True when `data` begins with the ASCII tag (avoids `memcmp` with a literal). */
+        [[nodiscard]] inline auto starts_with(std::span<const std::byte> data, std::string_view tag) -> bool {
+            if (data.size() < tag.size()) return false;
+            for (std::size_t i = 0; i < tag.size(); ++i) {
+                if (std::to_integer<std::uint8_t>(data[i]) != static_cast<std::uint8_t>(tag[i])) return false;
+            }
+            return true;
+        }
+
+        [[nodiscard]] inline auto read_property(byte_reader &reader, const name_table &names) -> asset_property {
+            asset_property property;
+            property.type = static_cast<property_type>(reader.read_u8());
+            property.name = names.name(reader.read_u24());
+            switch (property.type) {
+            case property_type::boolean: property.value = reader.read_bool(); break;
+            case property_type::integer: property.value = reader.read_i32(); break;
+            case property_type::real_number: property.value = reader.read_f32(); break;
+            case property_type::ascii_string:
+            case property_type::unknown: property.value = reader.read_u16_prefixed_ascii(); break;
+            case property_type::unicode_string: property.value = reader.read_u16_prefixed_utf16(); break;
+            }
+            return property;
+        }
+
+        inline auto write_property(byte_writer &writer, const asset_property &property, name_table &names) -> void {
+            writer.write_u8(static_cast<std::uint8_t>(property.type));
+            writer.write_u24(names.get_or_create(property.name));
+            switch (property.type) {
+            case property_type::boolean: writer.write_bool(property.as_bool()); break;
+            case property_type::integer: writer.write_i32(property.as_int()); break;
+            case property_type::real_number: writer.write_f32(property.as_real()); break;
+            case property_type::ascii_string:
+            case property_type::unknown: writer.write_u16_prefixed_ascii(property.as_ascii()); break;
+            case property_type::unicode_string: {
+                const auto *text = property.as_unicode();
+                writer.write_u16_prefixed_utf16(text != nullptr ? *text : std::u16string{});
+                break;
+            }
+            }
+        }
+
+        [[nodiscard]] inline auto parse_property_list(byte_reader &reader, const name_table &names) -> std::vector<asset_property> {
+            const auto count = reader.read_u16();
+            std::vector<asset_property> properties;
+            properties.reserve(count);
+            for (std::uint16_t i = 0; i < count; ++i) properties.push_back(read_property(reader, names));
+            return properties;
+        }
+
+        inline auto write_property_list(byte_writer &writer, const std::vector<asset_property> &properties, name_table &names) -> void {
+            writer.write_u16(static_cast<std::uint16_t>(properties.size()));
+            for (const auto &property: properties) write_property(writer, property, names);
+        }
+
+        /** Split `Player_<n>_Start` into `n`, or 0 when the name does not match. */
+        [[nodiscard]] inline auto parse_player_start_name(std::string_view name) -> int {
+            constexpr std::string_view prefix = "Player_";
+            constexpr std::string_view suffix = "_Start";
+            if (!name.starts_with(prefix) || !name.ends_with(suffix)) return 0;
+            const auto digits = name.substr(prefix.size(), name.size() - prefix.size() - suffix.size());
+            if (digits.empty() || !std::ranges::all_of(digits, [](char ch) { return ch >= '0' && ch <= '9'; })) return 0;
+            return std::stoi(std::string{digits});
+        }
+    }
+
+    /**
+     * A parsed `.map`: the asset-name table plus the ordered chunk list.
+     */
+    class map_document {
+    public:
+        /** Unwrap (BIG payload / `EAR\0` / bare RefPack / bare `CkMp`) and parse. */
+        [[nodiscard]] static auto parse(std::span<const std::byte> file) -> map_document {
+            auto data = std::vector<std::byte>{file.begin(), file.end()};
+            if (is_refpack(data)) data = refpack_decompress(data); // a BIG payload
+            if (detail::starts_with(data, std::string_view{"EAR\0", 4})) {
+                const auto *body = reinterpret_cast<const std::byte *>(data.data()) + 8;
+                std::span<const std::byte> payload{body, data.size() - 8U};
+                data = maybe_decompress(payload);
+            } else if (is_refpack(data)) {
+                data = refpack_decompress(data);
+            }
+            return map_document::from_ckmp(data);
+        }
+
+        [[nodiscard]] static auto open(const std::filesystem::path &path) -> map_document {
+            return map_document::parse(read_file(path));
+        }
+
+        [[nodiscard]] auto names() const -> const name_table & { return this->names_; }
+        [[nodiscard]] auto names() -> name_table & { return this->names_; }
+        [[nodiscard]] auto chunks() const -> const std::vector<map_chunk> & { return this->chunks_; }
+        [[nodiscard]] auto chunks() -> std::vector<map_chunk> & { return this->chunks_; }
+
+        [[nodiscard]] auto find_chunk(std::string_view name) const -> const map_chunk * {
+            for (const auto &chunk: this->chunks_) {
+                if (chunk.name == name) return &chunk;
+            }
+            return nullptr;
+        }
+
+        [[nodiscard]] auto find_chunk(std::string_view name) -> map_chunk * {
+            for (auto &chunk: this->chunks_) {
+                if (chunk.name == name) return &chunk;
+            }
+            return nullptr;
+        }
+
+        [[nodiscard]] auto has_chunk(std::string_view name) const -> bool { return this->find_chunk(name) != nullptr; }
+
+        /** The chunk of a known kind, or `nullptr`. */
+        [[nodiscard]] auto find_chunk(chunk_kind kind) const -> const map_chunk * {
+            for (const auto &chunk: this->chunks_) {
+                if (chunk.kind == kind) return &chunk;
+            }
+            return nullptr;
+        }
+
+        [[nodiscard]] auto find_chunk(chunk_kind kind) -> map_chunk * {
+            for (auto &chunk: this->chunks_) {
+                if (chunk.kind == kind) return &chunk;
+            }
+            return nullptr;
+        }
+
+        [[nodiscard]] auto has_chunk(chunk_kind kind) const -> bool { return this->find_chunk(kind) != nullptr; }
+
+        // -- typed chunks ---------------------------------------------------
+
+        /** The terrain grid, or `std::nullopt` when the map has no `HeightMapData`. */
+        [[nodiscard]] auto height_map() const -> std::optional<height_map_data> {
+            const auto *chunk = this->find_chunk("HeightMapData");
+            if (chunk == nullptr) return std::nullopt;
+            return height_map_data::parse(chunk->version, chunk->payload);
+        }
+
+        /** Replace (or create) the `HeightMapData` chunk from a grid. */
+        auto set_height_map(height_map_data data) -> void {
+            auto *chunk = this->find_chunk("HeightMapData");
+            if (chunk == nullptr) {
+                chunk = &this->chunks_.emplace_back();
+                chunk->name = "HeightMapData";
+                chunk->kind = chunk_kind::height_map_data;
+                chunk->asset_index = this->names_.get_or_create("HeightMapData");
+                chunk->version = data.version;
+            } else {
+                data.version = chunk->version; // keep the file's on-disk version
+            }
+            chunk->payload = data.serialize();
+        }
+
+        /** Every object the map places. */
+        [[nodiscard]] auto objects() const -> std::vector<map_object> {
+            const auto *chunk = this->find_chunk("ObjectsList");
+            if (chunk == nullptr) return {};
+            return map_document::decode_objects(this->names_, chunk->payload);
+        }
+
+        /** Replace (or create) the `ObjectsList` chunk. */
+        auto set_objects(const std::vector<map_object> &objects) -> void {
+            auto *chunk = this->find_chunk("ObjectsList");
+            if (chunk == nullptr) {
+                chunk = &this->chunks_.emplace_back();
+                chunk->name = "ObjectsList";
+                chunk->kind = chunk_kind::objects_list;
+                chunk->asset_index = this->names_.get_or_create("ObjectsList");
+                chunk->version = 1;
+            }
+            chunk->payload = map_document::encode_objects(this->names_, objects);
+        }
+
+        /** The `Player_N_Start` waypoints, ordered by index. */
+        [[nodiscard]] auto player_starts() const -> std::vector<player_start> {
+            std::vector<player_start> starts;
+            for (const auto &object: this->objects()) {
+                if (object.type_name != "*Waypoints/Waypoint") continue;
+                const auto *name_property = object.property("waypointName");
+                if (name_property == nullptr) continue;
+                const auto index = detail::parse_player_start_name(name_property->as_ascii());
+                if (index == 0) continue;
+                starts.push_back({index, object.position});
+            }
+            std::ranges::sort(starts, {}, &player_start::index);
+            return starts;
+        }
+
+        [[nodiscard]] auto mp_positions() const -> std::vector<mp_position> {
+            const auto *chunk = this->find_chunk("MPPositionList");
+            if (chunk == nullptr) return {};
+            return map_document::decode_mp_positions(chunk->payload);
+        }
+
+        auto set_mp_positions(const std::vector<mp_position> &positions) -> void {
+            auto *chunk = this->find_chunk("MPPositionList");
+            if (chunk == nullptr) {
+                chunk = &this->chunks_.emplace_back();
+                chunk->name = "MPPositionList";
+                chunk->kind = chunk_kind::mp_position_list;
+                chunk->asset_index = this->names_.get_or_create("MPPositionList");
+                chunk->version = 1;
+            }
+            chunk->payload = map_document::encode_mp_positions(this->names_, positions);
+        }
+
+        /** The `WorldInfo` property list. */
+        [[nodiscard]] auto world_info() const -> std::vector<asset_property> {
+            const auto *chunk = this->find_chunk("WorldInfo");
+            if (chunk == nullptr) return {};
+            byte_reader reader{chunk->payload};
+            return detail::parse_property_list(reader, this->names_);
+        }
+
+        auto set_world_info(const std::vector<asset_property> &properties) -> void {
+            auto *chunk = this->find_chunk("WorldInfo");
+            if (chunk == nullptr) {
+                chunk = &this->chunks_.emplace_back();
+                chunk->name = "WorldInfo";
+                chunk->kind = chunk_kind::world_info;
+                chunk->asset_index = this->names_.get_or_create("WorldInfo");
+                chunk->version = 1;
+            }
+            byte_writer writer;
+            detail::write_property_list(writer, properties, this->names_);
+            chunk->payload = writer.take();
+        }
+
+        /** The waypoint paths (`WaypointsList`). */
+        [[nodiscard]] auto waypoint_paths() const -> std::vector<waypoint_path> {
+            const auto *chunk = this->find_chunk("WaypointsList");
+            if (chunk == nullptr) return {};
+            byte_reader reader{chunk->payload};
+            const auto count = reader.read_u32();
+            std::vector<waypoint_path> paths;
+            paths.reserve(count);
+            for (std::uint32_t i = 0; i < count; ++i) paths.push_back({reader.read_i32(), reader.read_i32()});
+            return paths;
+        }
+
+        // -- serialisation --------------------------------------------------
+
+        /** The bare `CkMp` byte image. */
+        [[nodiscard]] auto to_ckmp() const -> std::vector<std::byte> {
+            byte_writer writer;
+            writer.write_ascii("CkMp");
+            const auto count = static_cast<std::uint32_t>(this->names_.size());
+            writer.write_u32(count);
+            for (std::uint32_t i = count; i >= 1U; --i) {
+                const auto &name = this->names_.entries()[i];
+                writer.write_u8(static_cast<std::uint8_t>(name.size()));
+                writer.write_ascii(name);
+                writer.write_u32(i);
+            }
+            for (const auto &chunk: this->chunks_) {
+                writer.write_u32(chunk.asset_index);
+                writer.write_u16(chunk.version);
+                writer.write_u32(static_cast<std::uint32_t>(chunk.payload.size()));
+                writer.write_bytes(chunk.payload);
+            }
+            return writer.take();
+        }
+
+        /**
+         * A standalone `.map` image.
+         *
+         * When `compress` is true the result is `EAR\0` + `u32` decompressed size
+         * + a RefPack stream (the retail compression). When false it is a bare
+         * `CkMp` tree. To store a map inside a `BIG4`, pass the *uncompressed*
+         * image and let `big_writer::add(..., compress = true)` wrap it once.
+         */
+        [[nodiscard]] auto serialize(bool compress = false) const -> std::vector<std::byte> {
+            auto ckmp = this->to_ckmp();
+            if (!compress) return ckmp;
+            byte_writer writer;
+            writer.write_ascii(std::string_view{"EAR\0", 4});
+            writer.write_u32(static_cast<std::uint32_t>(ckmp.size()));
+            const auto packed = refpack_compress(ckmp);
+            writer.write_bytes(packed);
+            return writer.take();
+        }
+
+        /** True when the name table carries `name` (top-level chunk, property, ...). */
+        [[nodiscard]] auto has_name(std::string_view name) const -> bool {
+            for (std::uint32_t i = 1; i < this->names_.entries().size(); ++i) {
+                if (this->names_.entries()[i] == name) return true;
+            }
+            return false;
+        }
+
+    private:
+        map_document() = default;
+
+        [[nodiscard]] static auto from_ckmp(std::span<const std::byte> data) -> map_document {
+            if (data.size() < 8U || !detail::starts_with(data, "CkMp")) throw map_error("not a CkMp map");
+            byte_reader reader{data};
+            (void) reader.read_ascii(4);
+            const auto count = reader.read_u32();
+            map_document document;
+            document.names_.resize(count + 1U);
+            for (std::uint32_t i = count; i >= 1U; --i) {
+                const auto length = reader.read_u8();
+                auto name = reader.read_ascii(length);
+                const auto index = reader.read_u32();
+                if (index != i) throw map_error("asset name table index mismatch");
+                document.names_.set_name(i, std::move(name));
+            }
+            while (reader.remaining() >= 10U) {
+                const auto index = reader.read_u32();
+                const auto version = reader.read_u16();
+                const auto size = reader.read_u32();
+                if (index >= document.names_.entries().size() || reader.remaining() < size) throw map_error("truncated CkMp chunk");
+                map_chunk chunk;
+                chunk.asset_index = index;
+                chunk.name = std::string{document.names_.entries()[index]};
+                chunk.kind = chunk_kind_of(chunk.name);
+                chunk.version = version;
+                const auto payload = reader.read_bytes(size);
+                chunk.payload.assign(payload.begin(), payload.end());
+                document.chunks_.push_back(std::move(chunk));
+            }
+            return document;
+        }
+
+        [[nodiscard]] static auto decode_objects(const name_table &names, std::span<const std::byte> payload) -> std::vector<map_object> {
+            byte_reader reader{payload};
+            std::vector<map_object> objects;
+            while (reader.remaining() >= 10U) {
+                (void) reader.read_u32(); // nested asset index (always "Object")
+                const auto version = reader.read_u16();
+                const auto size = reader.read_u32();
+                if (reader.remaining() < size) throw map_error("truncated Object asset");
+                const auto body = reader.read_bytes(size);
+                byte_reader body_reader{body};
+                map_object object;
+                object.version = version;
+                object.position.x = body_reader.read_f32();
+                object.position.y = body_reader.read_f32();
+                object.position.z = body_reader.read_f32();
+                object.angle = body_reader.read_f32();
+                object.road = static_cast<road_type>(body_reader.read_u32());
+                object.type_name = body_reader.read_ascii(body_reader.read_u16());
+                object.properties = detail::parse_property_list(body_reader, names);
+                objects.push_back(std::move(object));
+            }
+            return objects;
+        }
+
+        [[nodiscard]] static auto encode_objects(name_table &names, const std::vector<map_object> &objects) -> std::vector<std::byte> {
+            const auto object_index = names.get_or_create("Object");
+            byte_writer writer;
+            for (const auto &object: objects) {
+                byte_writer body;
+                body.write_f32(object.position.x);
+                body.write_f32(object.position.y);
+                body.write_f32(object.position.z);
+                body.write_f32(object.angle);
+                body.write_u32(static_cast<std::uint32_t>(object.road));
+                body.write_u16(static_cast<std::uint16_t>(object.type_name.size()));
+                body.write_ascii(object.type_name);
+                detail::write_property_list(body, object.properties, names);
+                writer.write_u32(object_index);
+                writer.write_u16(object.version);
+                writer.write_u32(static_cast<std::uint32_t>(body.size()));
+                writer.write_bytes(body.data());
+            }
+            return writer.take();
+        }
+
+        [[nodiscard]] static auto decode_mp_positions(std::span<const std::byte> payload) -> std::vector<mp_position> {
+            byte_reader reader{payload};
+            std::vector<mp_position> positions;
+            while (reader.remaining() >= 10U) {
+                (void) reader.read_u32(); // nested asset index (always "MPPositionInfo")
+                const auto version = reader.read_u16();
+                const auto size = reader.read_u32();
+                if (reader.remaining() < size) throw map_error("truncated MPPositionInfo asset");
+                const auto body = reader.read_bytes(size);
+                byte_reader body_reader{body};
+                mp_position position;
+                position.version = version;
+                position.is_human = body_reader.read_bool();
+                position.is_computer = body_reader.read_bool();
+                if (version > 0U) position.load_ai_script = body_reader.read_bool();
+                position.team = body_reader.read_u32();
+                if (version > 0U) {
+                    const auto count = body_reader.read_u32();
+                    position.side_restrictions.reserve(count);
+                    for (std::uint32_t i = 0; i < count; ++i) position.side_restrictions.push_back(body_reader.read_u16_prefixed_ascii());
+                }
+                positions.push_back(std::move(position));
+            }
+            return positions;
+        }
+
+        [[nodiscard]] static auto encode_mp_positions(name_table &names, const std::vector<mp_position> &positions) -> std::vector<std::byte> {
+            const auto info_index = names.get_or_create("MPPositionInfo");
+            byte_writer writer;
+            for (const auto &position: positions) {
+                byte_writer body;
+                body.write_bool(position.is_human);
+                body.write_bool(position.is_computer);
+                if (position.version > 0U) body.write_bool(position.load_ai_script);
+                body.write_u32(position.team);
+                if (position.version > 0U) {
+                    body.write_u32(static_cast<std::uint32_t>(position.side_restrictions.size()));
+                    for (const auto &side: position.side_restrictions) body.write_u16_prefixed_ascii(side);
+                }
+                writer.write_u32(info_index);
+                writer.write_u16(position.version);
+                writer.write_u32(static_cast<std::uint32_t>(body.size()));
+                writer.write_bytes(body.data());
+            }
+            return writer.take();
+        }
+
+        name_table names_;
+        std::vector<map_chunk> chunks_;
+    };
+
+} // namespace ra3::assets

third_party/libra3assets/src/refpack.cppm

@@ -0,0 +1,284 @@
+/**
+ * EA's RefPack compression codec.
+ *
+ * Red Alert 3 compresses individual `BIG4` payloads and every SAGE `.map` with
+ * RefPack (the `10 FB` stream shared across EA titles). This partition decodes
+ * and encodes that stream. The decoder is a port of the reference used across
+ * the project (`ra3tools/ra3_big.py`, `OpenRA3`'s `ra3.fs`); the encoder is a
+ * greedy LZ77 matcher that emits only canonical tokens, so anything it produces
+ * is readable by the same decoder (and by the game).
+ */
+export module ra3.assets:refpack;
+
+import std;
+
+import :bytes;
+import :error;
+
+export namespace ra3::assets {
+
+    /** Max back-reference distance (the 17-bit RefPack window). */
+    inline constexpr std::size_t refpack_window = 1U << 17U;
+
+    /** True when `data` starts with a RefPack header (`0b??010000`, `0xFB`). */
+    [[nodiscard]] inline auto is_refpack(std::span<const std::byte> data) -> bool {
+        return data.size() >= 2U && (std::to_integer<std::uint8_t>(data[0]) & 0x3EU) == 0x10U && std::to_integer<std::uint8_t>(data[1]) == 0xFBU;
+    }
+
+    /** Read the declared output size from a RefPack header without decompressing. */
+    [[nodiscard]] inline auto refpack_output_size(std::span<const std::byte> data) -> std::uint32_t {
+        if (!is_refpack(data)) throw refpack_error("not a RefPack stream");
+        std::size_t pos = 0;
+        const auto header = std::to_integer<std::uint8_t>(data[pos++]);
+        const bool large_files = (header & 0x80U) != 0U;
+        const bool compressed_size_present = (header & 0x01U) != 0U;
+        pos++; // 0xFB
+        const std::size_t size_bytes = large_files ? 4U : 3U;
+        const auto read_size = [&]() -> std::uint32_t {
+            std::uint32_t value = 0;
+            for (std::size_t i = 0; i < size_bytes; ++i) {
+                if (pos >= data.size()) throw refpack_error("truncated RefPack size field");
+                value = (value << 8U) | std::to_integer<std::uint8_t>(data[pos++]);
+            }
+            return value;
+        };
+        if (compressed_size_present) (void) read_size();
+        return read_size();
+    }
+
+    /**
+     * Decompress an EA RefPack stream.
+     *
+     * @throws refpack_error if the stream is malformed or the length disagrees.
+     */
+    [[nodiscard]] inline auto refpack_decompress(std::span<const std::byte> data) -> std::vector<std::byte> {
+        if (!is_refpack(data)) throw refpack_error("not a RefPack stream");
+
+        std::size_t pos = 0;
+        const auto header = std::to_integer<std::uint8_t>(data[pos++]);
+        const bool large_files = (header & 0x80U) != 0U;
+        const bool compressed_size_present = (header & 0x01U) != 0U;
+        pos++; // 0xFB
+
+        const std::size_t size_bytes = large_files ? 4U : 3U;
+        const auto read_size = [&]() -> std::uint32_t {
+            std::uint32_t value = 0;
+            for (std::size_t i = 0; i < size_bytes; ++i) {
+                if (pos >= data.size()) throw refpack_error("truncated RefPack size field");
+                value = (value << 8U) | std::to_integer<std::uint8_t>(data[pos++]);
+            }
+            return value;
+        };
+
+        if (compressed_size_present) (void) read_size();
+        const auto out_len = read_size();
+
+        std::vector<std::byte> out;
+        out.reserve(out_len); // guarantees no reallocation, so overlapping reads stay valid
+
+        const auto copy_literals = [&](std::size_t count) {
+            if (pos + count > data.size()) throw refpack_error("truncated RefPack literals");
+            out.insert(out.end(), data.begin() + static_cast<std::ptrdiff_t>(pos), data.begin() + static_cast<std::ptrdiff_t>(pos + count));
+            pos += count;
+        };
+
+        // A back-reference may overlap its own output (an RLE run): out[start + i]
+        // is read one byte at a time, so the pattern repeats correctly.
+        const auto copy_reference = [&](std::size_t length, std::size_t distance) {
+            if (distance == 0U || distance > out.size()) throw refpack_error("RefPack back-reference out of range");
+            const auto start = out.size() - distance;
+            if (out.size() + length > out_len) throw refpack_error("RefPack output overrun");
+            for (std::size_t i = 0; i < length; ++i) out.push_back(out[start + i]);
+        };
+
+        while (pos < data.size()) {
+            const auto cmd = std::to_integer<std::uint8_t>(data[pos++]);
+            if ((cmd & 0x80U) == 0U) { // 2-byte command
+                if (pos >= data.size()) throw refpack_error("truncated 2-byte command");
+                const auto b2 = std::to_integer<std::uint8_t>(data[pos++]);
+                copy_literals(cmd & 0x03U);
+                copy_reference(((cmd & 0x1CU) >> 2U) + 3U, ((cmd & 0x60U) << 3U) + b2 + 1U);
+            } else if ((cmd & 0x40U) == 0U) { // 3-byte command
+                if (pos + 1U >= data.size()) throw refpack_error("truncated 3-byte command");
+                const auto b2 = std::to_integer<std::uint8_t>(data[pos]);
+                const auto b3 = std::to_integer<std::uint8_t>(data[pos + 1U]);
+                pos += 2U;
+                copy_literals((b2 & 0xC0U) >> 6U);
+                copy_reference((cmd & 0x3FU) + 4U, ((b2 & 0x3FU) << 8U) + b3 + 1U);
+            } else if ((cmd & 0x20U) == 0U) { // 4-byte command
+                if (pos + 2U >= data.size()) throw refpack_error("truncated 4-byte command");
+                const auto b2 = std::to_integer<std::uint8_t>(data[pos]);
+                const auto b3 = std::to_integer<std::uint8_t>(data[pos + 1U]);
+                const auto b4 = std::to_integer<std::uint8_t>(data[pos + 2U]);
+                pos += 3U;
+                copy_literals(cmd & 0x03U);
+                copy_reference(((cmd & 0x0CU) << 6U) + b4 + 5U, ((cmd & 0x10U) << 12U) + (static_cast<std::size_t>(b2) << 8U) + b3 + 1U);
+            } else if (cmd < 0xFCU) { // long literal run
+                copy_literals((static_cast<std::size_t>(cmd & 0x1FU) + 1U) << 2U);
+            } else { // stop
+                copy_literals(cmd & 0x03U);
+                break;
+            }
+        }
+
+        if (out.size() != out_len) throw refpack_error("RefPack length mismatch");
+        return out;
+    }
+
+    /** Decompress `data` when it is RefPack, otherwise copy it unchanged. */
+    [[nodiscard]] inline auto maybe_decompress(std::span<const std::byte> data) -> std::vector<std::byte> {
+        if (is_refpack(data)) return refpack_decompress(data);
+        return {data.begin(), data.end()};
+    }
+
+    namespace detail {
+        /** True when `(length, distance)` maps to one of the three canonical tokens. */
+        [[nodiscard]] inline constexpr auto refpack_match_encodable(std::size_t length, std::size_t distance) -> bool {
+            if (length >= 3U && length <= 10U && distance >= 1U && distance <= 1024U) return true;
+            if (length >= 4U && length <= 67U && distance >= 1U && distance <= 16384U) return true;
+            if (length >= 5U && length <= 1028U && distance >= 1U && distance <= 131072U) return true;
+            return false;
+        }
+
+        /** Greedy RefPack encoder state. */
+        class refpack_encoder {
+        public:
+            explicit refpack_encoder(std::span<const std::byte> input)
+                : input_(input), chain_(input.size(), -1) {
+            }
+
+            [[nodiscard]] auto run() -> std::vector<std::byte> {
+                const auto n = this->input_.size();
+                const bool large = n >= (1U << 24U);
+                this->out_.write_u8(static_cast<std::uint8_t>(0x10U | (large ? 0x80U : 0x00U)));
+                this->out_.write_u8(0xFBU);
+                const std::size_t size_bytes = large ? 4U : 3U;
+                for (std::size_t i = size_bytes; i-- > 0U;) this->out_.write_u8(static_cast<std::uint8_t>((n >> (8U * i)) & 0xFFU));
+
+                std::size_t pos = 0;
+                std::size_t literals_start = 0;
+                while (pos < n) {
+                    std::size_t best_len = 0;
+                    std::size_t best_dist = 0;
+                    if (pos + 2U < n) this->find_match(pos, best_len, best_dist);
+                    if (best_len >= 3U) {
+                        const auto pending = pos - literals_start;
+                        const auto carry = pending % 4U;      // 0..3 literals ride with the token
+                        const auto run = pending - carry;     // always a multiple of 4
+                        this->emit_literal_run(literals_start, run);
+                        this->emit_match(literals_start + run, carry, best_len, best_dist);
+                        for (std::size_t i = pos; i < pos + best_len; ++i) this->insert(i);
+                        pos += best_len;
+                        literals_start = pos;
+                    } else {
+                        this->insert(pos);
+                        ++pos;
+                    }
+                }
+
+                const auto pending = n - literals_start;
+                const auto carry = pending % 4U;
+                this->emit_literal_run(literals_start, pending - carry);
+                this->out_.write_u8(static_cast<std::uint8_t>(0xFCU | carry));
+                this->write_literals(literals_start + (pending - carry), carry);
+                return this->out_.take();
+            }
+
+        private:
+            void insert(std::size_t pos) {
+                if (pos + 2U >= this->input_.size()) return;
+                const auto bucket = this->hash3(pos);
+                this->chain_[pos] = this->head_[bucket];
+                this->head_[bucket] = static_cast<std::int32_t>(pos);
+            }
+
+            void find_match(std::size_t pos, std::size_t &best_len, std::size_t &best_dist) const {
+                const auto n = this->input_.size();
+                const auto max_len = std::min<std::size_t>(1028U, n - pos);
+                auto candidate = this->head_[this->hash3(pos)];
+                int depth = 0;
+                while (candidate >= 0 && depth < 64) {
+                    const auto c = static_cast<std::size_t>(candidate);
+                    const auto distance = pos - c;
+                    if (distance > refpack_window) break; // the chain only walks backwards
+                    std::size_t length = 0;
+                    while (length < max_len && this->input_[c + length] == this->input_[pos + length]) ++length;
+                    if (length > best_len && refpack_match_encodable(length, distance)) {
+                        best_len = length;
+                        best_dist = distance;
+                        if (length == max_len) break;
+                    }
+                    candidate = this->chain_[c];
+                    ++depth;
+                }
+            }
+
+            void emit_literal_run(std::size_t offset, std::size_t count) {
+                std::size_t remaining = count;
+                std::size_t at = offset;
+                while (remaining >= 4U) {
+                    std::size_t step = std::min<std::size_t>(112U, remaining);
+                    step -= step % 4U;
+                    if (step < 4U) step = 4U;
+                    this->out_.write_u8(static_cast<std::uint8_t>(0xE0U | ((step / 4U) - 1U)));
+                    this->write_literals(at, step);
+                    at += step;
+                    remaining -= step;
+                }
+            }
+
+            void emit_match(std::size_t literal_offset, std::size_t literal_count, std::size_t length, std::size_t distance) {
+                const auto d = static_cast<std::uint32_t>(distance - 1U);
+                if (length >= 3U && length <= 10U && distance <= 1024U) { // 2-byte token
+                    const auto cmd = static_cast<std::uint8_t>((((d >> 8U) & 0x03U) << 5U) | (static_cast<std::uint32_t>(length - 3U) << 2U) |
+                                                               static_cast<std::uint32_t>(literal_count));
+                    this->out_.write_u8(cmd);
+                    this->out_.write_u8(static_cast<std::uint8_t>(d & 0xFFU));
+                } else if (length >= 4U && length <= 67U && distance <= 16384U) { // 3-byte token
+                    this->out_.write_u8(static_cast<std::uint8_t>(0x80U | (length - 4U)));
+                    this->out_.write_u8(static_cast<std::uint8_t>((literal_count << 6U) | ((d >> 8U) & 0x3FU)));
+                    this->out_.write_u8(static_cast<std::uint8_t>(d & 0xFFU));
+                } else if (length >= 5U && length <= 1028U && distance <= 131072U) { // 4-byte token
+                    const auto l = static_cast<std::uint32_t>(length - 5U);
+                    const auto cmd = static_cast<std::uint8_t>(0xC0U | (((l >> 8U) & 0x03U) << 2U) | ((d >> 12U) & 0x10U) |
+                                                                       static_cast<std::uint32_t>(literal_count));
+                    this->out_.write_u8(cmd);
+                    this->out_.write_u8(static_cast<std::uint8_t>((d >> 8U) & 0xFFU));
+                    this->out_.write_u8(static_cast<std::uint8_t>(d & 0xFFU));
+                    this->out_.write_u8(static_cast<std::uint8_t>(l & 0xFFU));
+                } else {
+                    throw refpack_error("internal error: unencodable RefPack match");
+                }
+                this->write_literals(literal_offset, literal_count);
+            }
+
+            void write_literals(std::size_t offset, std::size_t count) {
+                for (std::size_t i = 0; i < count; ++i) this->out_.write_u8(std::to_integer<std::uint8_t>(this->input_[offset + i]));
+            }
+
+            [[nodiscard]] auto hash3(std::size_t pos) const -> std::size_t {
+                const auto a = static_cast<std::uint32_t>(std::to_integer<std::uint8_t>(this->input_[pos]));
+                const auto b = static_cast<std::uint32_t>(std::to_integer<std::uint8_t>(this->input_[pos + 1U]));
+                const auto c = static_cast<std::uint32_t>(std::to_integer<std::uint8_t>(this->input_[pos + 2U]));
+                return ((a | (b << 8U) | (c << 16U)) * 2654435761U) >> (32U - 16U);
+            }
+
+            std::span<const std::byte> input_;
+            std::vector<std::int32_t> chain_;
+            std::vector<std::int32_t> head_ = std::vector<std::int32_t>(1U << 16U, -1);
+            byte_writer out_;
+        };
+    }
+
+    /**
+     * Compress a byte range into a canonical RefPack stream.
+     *
+     * The encoder is a plain greedy LZ77: it never emits a token form the
+     * decoder above cannot read, so `refpack_decompress(refpack_compress(x))`
+     * is lossless for every input.
+     */
+    [[nodiscard]] inline auto refpack_compress(std::span<const std::byte> input) -> std::vector<std::byte> {
+        return detail::refpack_encoder{input}.run();
+    }
+
+} // namespace ra3::assets

third_party/libra3assets/tests/test_assets.cpp

@@ -0,0 +1,310 @@
+#include "test_main.hpp"
+
+import std;
+import ra3.assets;
+
+using namespace ra3::assets;
+
+namespace {
+
+    auto bytes_of(std::string_view text) -> std::vector<std::byte> {
+        std::vector<std::byte> out;
+        out.reserve(text.size());
+        for (const auto ch: text) out.push_back(static_cast<std::byte>(static_cast<unsigned char>(ch)));
+        return out;
+    }
+
+    auto text_of(std::span<const std::byte> bytes) -> std::string {
+        return std::string{reinterpret_cast<const char *>(bytes.data()), bytes.size()};
+    }
+
+    /** A deterministic pseudo-random buffer (no external RNG needed). */
+    auto pseudo_random(std::size_t size, std::uint32_t seed) -> std::vector<std::byte> {
+        std::vector<std::byte> out;
+        out.reserve(size);
+        std::uint32_t state = seed;
+        for (std::size_t i = 0; i < size; ++i) {
+            state = state * 1664525U + 1013904223U;
+            out.push_back(static_cast<std::byte>((state >> 16U) & 0xFFU));
+        }
+        return out;
+    }
+
+    auto make_empty_ckmp(const std::vector<std::string> &names) -> std::vector<std::byte> {
+        byte_writer writer;
+        writer.write_ascii("CkMp");
+        writer.write_u32(static_cast<std::uint32_t>(names.size()));
+        for (std::uint32_t i = static_cast<std::uint32_t>(names.size()); i >= 1U; --i) {
+            writer.write_u8(static_cast<std::uint8_t>(names[i - 1].size()));
+            writer.write_ascii(names[i - 1]);
+            writer.write_u32(i);
+        }
+        return writer.take();
+    }
+
+    auto make_csf() -> std::vector<std::byte> {
+        byte_writer writer;
+        writer.write_ascii(" FSC");
+        writer.write_u32(3);
+        writer.write_u32(2); // labels
+        writer.write_u32(2); // value blocks
+        writer.write_u32(0);
+        writer.write_u32(0);
+        writer.write_u32(csf_label_flag);
+        writer.write_u32(1);
+        writer.write_u32(3);
+        writer.write_ascii("ABC");
+        writer.write_u32(csf_value_flag);
+        writer.write_u32(5);
+        for (const auto ch: std::string_view{"Hello"}) writer.write_u16(static_cast<std::uint16_t>(ch) ^ 0xFFFFU);
+        writer.write_u32(csf_label_flag);
+        writer.write_u32(1);
+        writer.write_u32(3);
+        writer.write_ascii("UNI");
+        writer.write_u32(csf_value_flag);
+        writer.write_u32(1);
+        writer.write_u16(0x4E2DU ^ 0xFFFFU); // U+4E2D (CJK)
+        return writer.take();
+    }
+
+} // namespace
+
+TEST(refpack_roundtrip_small) {
+    const std::vector<std::string> samples{"", "A", "AB", "ABC", "ABCD", "abcabcabc", std::string(300, 'z')};
+    for (const auto &sample: samples) {
+        const auto input = bytes_of(sample);
+        const auto packed = refpack_compress(input);
+        const auto restored = refpack_decompress(packed);
+        CHECK_EQ(restored.size(), input.size());
+        CHECK(std::ranges::equal(restored, input));
+    }
+}
+
+TEST(refpack_roundtrip_large_and_repetitive) {
+    std::vector<std::byte> input;
+    for (int i = 0; i < 2000; ++i) {
+        for (const auto ch: std::string_view{"lorem ipsum dolor sit amet "}) input.push_back(static_cast<std::byte>(ch));
+    }
+    const auto random = pseudo_random(50000, 0x1234ABCDU);
+    input.insert(input.end(), random.begin(), random.end());
+    const auto packed = refpack_compress(input);
+    CHECK(packed.size() < input.size()); // the repeated prefix must compress
+    CHECK(std::ranges::equal(refpack_decompress(packed), input));
+}
+
+TEST(refpack_decode_known_stream) {
+    // "abcd" literals, then a back-reference (distance 4, length 3) -> "abcdabc".
+    const std::vector<std::byte> stream{
+        std::byte{0x10}, std::byte{0xFB}, std::byte{0x00}, std::byte{0x00}, std::byte{0x07}, std::byte{0xE0},
+        std::byte{'a'},  std::byte{'b'},  std::byte{'c'},  std::byte{'d'},  std::byte{0x00}, std::byte{0x03},
+        std::byte{0xFC},
+    };
+    CHECK(is_refpack(stream));
+    CHECK_EQ(text_of(refpack_decompress(stream)), "abcdabc");
+    CHECK_EQ(refpack_output_size(stream), 7U);
+}
+
+TEST(big_roundtrip) {
+    big_writer writer;
+    writer.add("data\\a.txt", bytes_of("hello world"));
+    writer.add("data\\b.bin", bytes_of(std::string(1000, 'x')), true);
+    const auto image = writer.write();
+
+    CHECK(image.size() >= 16U);
+    const std::string magic{reinterpret_cast<const char *>(image.data()), 4};
+    CHECK_EQ(magic, "BIG4");
+
+    const auto archive = big_archive::from_bytes(image);
+    CHECK_EQ(archive.size(), 2U);
+    CHECK(archive.contains("data\\a.txt"));
+    CHECK_EQ(text_of(archive.read("data\\a.txt")), "hello world");
+    CHECK_EQ(archive.read("data\\b.bin").size(), 1000U);
+    CHECK_EQ(archive.find("data\\").size(), 2U);
+    // The first payload starts 64-byte aligned, as the retail archives do.
+    CHECK_EQ(archive.entries()[0].offset % 64U, 0U);
+}
+
+TEST(big_open_from_disk_is_lazy) {
+    big_writer writer;
+    writer.add("data\\a.txt", bytes_of("hello disk"));
+    writer.add("data\\b.bin", bytes_of(std::string(4096, 'q')), true);
+    const auto image = writer.write();
+
+    const auto path = std::filesystem::temp_directory_path() / "libra3assets_big_lazy.big";
+    write_file(path, image);
+
+    const auto archive = big_archive::open(path);
+    CHECK_EQ(archive.size(), 2U);
+    CHECK(archive.path() == path);
+    CHECK(archive.contains("data\\a.txt"));
+    CHECK_EQ(archive.entries()[0].offset % 64U, 0U);
+    CHECK_EQ(text_of(archive.read("data\\a.txt")), "hello disk");
+    CHECK_EQ(archive.read("data\\b.bin").size(), 4096U);
+    CHECK_EQ(text_of(archive.read_prefix("data\\a.txt", 5)), "hello");
+    CHECK(archive.read_prefix("data\\b.bin", 8U).size() == 8U);
+    std::error_code ec;
+    std::filesystem::remove(path, ec);
+}
+
+TEST(binary_manifest_and_hash) {
+    CHECK_EQ(hash_string("W3DMesh"), 0xC2B1A262U);
+    CHECK_EQ(hash_string("ABAIRFIELD", false), 0x2B479BD3U);
+    CHECK(hash_string("Texture") != hash_string("Texture", false));
+
+    const std::string name = "W3DMesh:TEST";
+    const std::string source = "art:test.w3x";
+    byte_writer manifest;
+    manifest.write_u8(0);  // not big-endian
+    manifest.write_u8(0);  // not linked
+    manifest.write_u16(5); // version
+    manifest.write_u32(0); // checksum
+    manifest.write_u32(0); // all-types hash
+    manifest.write_u32(1); // count
+    manifest.write_u32(12);
+    manifest.write_u32(0);
+    manifest.write_u32(0);
+    manifest.write_u32(0);
+    manifest.write_u32(0); // reference buffer
+    manifest.write_u32(0); // reference-name buffer
+    manifest.write_u32(static_cast<std::uint32_t>(name.size() + 1));
+    manifest.write_u32(static_cast<std::uint32_t>(source.size() + 1));
+    manifest.write_u32(hash_string("W3DMesh"));
+    manifest.write_u32(hash_string("TEST", false));
+    manifest.write_u32(hash_string("W3DMesh"));
+    manifest.write_u32(hash_string("TEST", false));
+    manifest.write_i32(0); // reference offset
+    manifest.write_i32(0); // reference count
+    manifest.write_i32(0); // name offset
+    manifest.write_i32(0); // source offset
+    manifest.write_u32(8); // instance size
+    manifest.write_u32(0); // relocation size
+    manifest.write_u32(0); // imports size
+    manifest.write_u32(0); // tokenized
+    manifest.write_ascii(name);
+    manifest.write_u8(0);
+    manifest.write_ascii(source);
+    manifest.write_u8(0);
+
+    byte_writer data;
+    data.write_u32(0); // stream checksum
+    data.write_ascii("PAYLOAD!");
+
+    auto container = binary_container::from_bytes(manifest.take(), data.take());
+    CHECK_EQ(container.size(), 1U);
+    const auto &asset = container.assets()[0];
+    CHECK_EQ(asset.name, "W3DMesh:TEST");
+    CHECK_EQ(asset.type_name(), "W3DMesh");
+    CHECK_EQ(asset.instance_name(), "TEST");
+    CHECK_EQ(asset.source, "art:test.w3x");
+    CHECK_EQ(text_of(container.read_instance(asset)), "PAYLOAD!");
+    CHECK_EQ(container.find("#0").name, "W3DMesh:TEST");
+    CHECK_EQ(container.of_type("w3dmesh").size(), 1U);
+    CHECK_EQ(container.type_counts().at("W3DMesh"), 1U);
+    CHECK(container.read_relocation(asset).empty());
+
+    container.set_cdata_source([&asset](const std::string &cdata_name) -> std::optional<std::vector<std::byte>> {
+        if (cdata_name == asset.cdata_name("static")) return bytes_of("CDATA");
+        return std::nullopt;
+    });
+    CHECK(container.read_cdata(asset).has_value());
+    CHECK_EQ(text_of(container.read_payload(asset)), "CDATA");
+}
+
+TEST(csf_roundtrip) {
+    auto table = csf_table::parse(make_csf());
+    CHECK_EQ(table.size(), 2U);
+    CHECK_EQ(table.version(), 3U);
+    CHECK_EQ(table.lookup("abc"), "Hello");      // lookup is case-insensitive
+    CHECK_EQ(table.lookup("ABC"), "Hello");
+    CHECK_EQ(table.lookup("uni"), "\xE4\xB8\xAD");
+    CHECK(table.find("missing") == nullptr);
+
+    const auto rewritten = table.write();
+    const auto reparsed = csf_table::parse(rewritten);
+    CHECK_EQ(reparsed.size(), 2U);
+    CHECK_EQ(reparsed.lookup("abc"), "Hello");
+    CHECK_EQ(reparsed.lookup("uni"), "\xE4\xB8\xAD");
+}
+
+TEST(csf_decode_utf16_surrogate) {
+    const std::u16string emoji = u"\U0001F600";
+    CHECK_EQ(utf16_to_utf8(emoji), "\xF0\x9F\x98\x80");
+}
+
+TEST(map_roundtrip) {
+    const std::vector<std::string> names{"HeightMapData", "ObjectsList", "Object", "waypointName", "MPPositionList", "MPPositionInfo", "WorldInfo", "waypointID"};
+    auto document = map_document::parse(make_empty_ckmp(names));
+    CHECK_EQ(document.names().size(), names.size());
+
+    height_map_data height;
+    height.width = 2;
+    height.height = 2;
+    height.version = 6;
+    height.elevations = {1, 2, 3, 4};
+    document.set_height_map(height);
+
+    map_object waypoint;
+    waypoint.type_name = "*Waypoints/Waypoint";
+    waypoint.position = {100.0F, 200.0F, 0.0F};
+    waypoint.properties.push_back(asset_property::text("waypointName", "Player_1_Start"));
+    waypoint.properties.push_back(asset_property::integer("waypointID", 0));
+    document.set_objects({waypoint});
+
+    mp_position position;
+    position.is_human = true;
+    position.team = 1;
+    document.set_mp_positions({position});
+
+    const auto ckmp = document.to_ckmp();
+    const auto reparsed = map_document::parse(ckmp);
+
+    CHECK(reparsed.has_chunk(chunk_kind::height_map_data));
+    CHECK(reparsed.has_chunk(chunk_kind::objects_list));
+    CHECK(reparsed.has_chunk(chunk_kind::mp_position_list));
+    CHECK_EQ(reparsed.find_chunk("HeightMapData")->kind, chunk_kind::height_map_data);
+    CHECK_EQ(chunk_kind_of("BlendTileData"), chunk_kind::blend_tile_data);
+    CHECK_EQ(chunk_kind_of("NotAChunk"), chunk_kind::unknown);
+
+    const auto restored = reparsed.height_map();
+    CHECK(restored.has_value());
+    CHECK_EQ(restored->width, 2U);
+    CHECK_EQ(restored->at(1, 1), 4U);
+    CHECK_EQ(restored->vertical_scale(), 0.0390625F);
+
+    const auto objects = reparsed.objects();
+    CHECK_EQ(objects.size(), 1U);
+    CHECK_EQ(objects[0].type_name, "*Waypoints/Waypoint");
+    CHECK_EQ(objects[0].property("waypointID")->as_int(), 0);
+
+    const auto starts = reparsed.player_starts();
+    CHECK_EQ(starts.size(), 1U);
+    CHECK_EQ(starts[0].index, 1);
+    CHECK_EQ(starts[0].position.x, 100.0F);
+
+    const auto positions = reparsed.mp_positions();
+    CHECK_EQ(positions.size(), 1U);
+    CHECK(positions[0].is_human);
+    CHECK_EQ(positions[0].team, 1U);
+}
+
+TEST(map_compressed_and_big_payload) {
+    const std::vector<std::string> names{"HeightMapData"};
+    auto document = map_document::parse(make_empty_ckmp(names));
+    height_map_data height;
+    height.width = 1;
+    height.height = 1;
+    height.version = 6;
+    height.elevations = {7};
+    document.set_height_map(height);
+
+    // EAR\0 + RefPack round-trip.
+    const auto compressed = document.serialize(true);
+    const auto from_compressed = map_document::parse(compressed);
+    CHECK(from_compressed.height_map().has_value());
+    CHECK_EQ(from_compressed.height_map()->at(0, 0), 7U);
+
+    // A BIG payload is one more RefPack layer over the map file.
+    const auto big_payload = refpack_compress(document.to_ckmp());
+    const auto from_big = map_document::parse(big_payload);
+    CHECK_EQ(from_big.height_map()->at(0, 0), 7U);
+}

third_party/libra3assets/tests/test_main.cpp

@@ -0,0 +1,5 @@
+#include "test_main.hpp"
+
+int main() {
+    return ra3test::run_all();
+}

third_party/libra3assets/tests/test_main.hpp

@@ -0,0 +1,83 @@
+#ifndef RA3TEST_HPP
+#define RA3TEST_HPP
+
+// A tiny dependency-free test harness (registry + CHECK macros). Each unit-test
+// executable compiles test_main.cpp and links the sources under test.
+
+#include <functional>
+#include <iostream>
+#include <sstream>
+#include <string>
+#include <vector>
+
+namespace ra3test {
+
+    struct test_case {
+        std::string name;
+        std::function<void()> fn;
+    };
+
+    inline auto registry() -> std::vector<test_case> & {
+        static std::vector<test_case> tests;
+        return tests;
+    }
+
+    inline auto failure_count() -> int & {
+        static int count = 0;
+        return count;
+    }
+
+    struct registrar {
+        registrar(std::string name, std::function<void()> fn) { registry().push_back({std::move(name), std::move(fn)}); }
+    };
+
+    inline auto report_failure(const std::string &expr, const std::string &file, int line) -> void {
+        ++failure_count();
+        std::cerr << "  FAIL " << file << ':' << line << "  " << expr << '\n';
+    }
+
+    inline auto check(bool condition, const std::string &expr, const std::string &file, int line) -> void {
+        if (!condition) report_failure(expr, file, line);
+    }
+
+    inline auto run_all() -> int {
+        int passed = 0;
+        for (auto &test: registry()) {
+            const int before = failure_count();
+            std::cout << "[ RUN  ] " << test.name << '\n';
+            try {
+                test.fn();
+            } catch (const std::exception &exc) {
+                report_failure(std::string("uncaught exception: ") + exc.what(), __FILE__, __LINE__);
+            }
+            if (failure_count() == before) {
+                ++passed;
+                std::cout << "[  OK  ] " << test.name << '\n';
+            }
+        }
+        std::cout << "\n" << passed << '/' << registry().size() << " tests passed, " << failure_count() << " failure(s)\n";
+        return failure_count() == 0 ? 0 : 1;
+    }
+
+} // namespace ra3test
+
+#define TEST(name)                                                                                                     \
+    static void name();                                                                                                \
+    static ::ra3test::registrar ra3test_reg_##name(#name, name);                                                       \
+    static void name()
+
+#define CHECK(cond) ::ra3test::check((cond), #cond, __FILE__, __LINE__)
+#define CHECK_EQ(a, b) ::ra3test::check_eq((a), (b), #a, #b, __FILE__, __LINE__)
+
+namespace ra3test {
+    template<typename A, typename B>
+    auto check_eq(const A &a, const B &b, const std::string &ea, const std::string &eb, const std::string &file, int line) -> void {
+        if (!(a == b)) {
+            std::ostringstream os;
+            os << ea << " == " << eb;
+            report_failure(os.str(), file, line);
+        }
+    }
+}
+
+#endif // RA3TEST_HPP

third_party/volk/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2018-2024 Arseny Kapoulkine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

third_party/vulkan/include/vk_video/vulkan_video_codec_av1std.h

@@ -0,0 +1,394 @@
+#ifndef VULKAN_VIDEO_CODEC_AV1STD_H_
+#define VULKAN_VIDEO_CODEC_AV1STD_H_ 1
+
+/*
+** Copyright 2015-2024 The Khronos Group Inc.
+**
+** SPDX-License-Identifier: Apache-2.0
+*/
+
+/*
+** This header is generated from the Khronos Vulkan XML API Registry.
+**
+*/
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+
+// vulkan_video_codec_av1std is a preprocessor guard. Do not pass it to API calls.
+#define vulkan_video_codec_av1std 1
+#include "vulkan_video_codecs_common.h"
+#define STD_VIDEO_AV1_NUM_REF_FRAMES      8
+#define STD_VIDEO_AV1_REFS_PER_FRAME      7
+#define STD_VIDEO_AV1_TOTAL_REFS_PER_FRAME 8
+#define STD_VIDEO_AV1_MAX_TILE_COLS       64
+#define STD_VIDEO_AV1_MAX_TILE_ROWS       64
+#define STD_VIDEO_AV1_MAX_SEGMENTS        8
+#define STD_VIDEO_AV1_SEG_LVL_MAX         8
+#define STD_VIDEO_AV1_PRIMARY_REF_NONE    7
+#define STD_VIDEO_AV1_SELECT_INTEGER_MV   2
+#define STD_VIDEO_AV1_SELECT_SCREEN_CONTENT_TOOLS 2
+#define STD_VIDEO_AV1_SKIP_MODE_FRAMES    2
+#define STD_VIDEO_AV1_MAX_LOOP_FILTER_STRENGTHS 4
+#define STD_VIDEO_AV1_LOOP_FILTER_ADJUSTMENTS 2
+#define STD_VIDEO_AV1_MAX_CDEF_FILTER_STRENGTHS 8
+#define STD_VIDEO_AV1_MAX_NUM_PLANES      3
+#define STD_VIDEO_AV1_GLOBAL_MOTION_PARAMS 6
+#define STD_VIDEO_AV1_MAX_NUM_Y_POINTS    14
+#define STD_VIDEO_AV1_MAX_NUM_CB_POINTS   10
+#define STD_VIDEO_AV1_MAX_NUM_CR_POINTS   10
+#define STD_VIDEO_AV1_MAX_NUM_POS_LUMA    24
+#define STD_VIDEO_AV1_MAX_NUM_POS_CHROMA  25
+
+typedef enum StdVideoAV1Profile {
+    STD_VIDEO_AV1_PROFILE_MAIN = 0,
+    STD_VIDEO_AV1_PROFILE_HIGH = 1,
+    STD_VIDEO_AV1_PROFILE_PROFESSIONAL = 2,
+    STD_VIDEO_AV1_PROFILE_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_AV1_PROFILE_MAX_ENUM = 0x7FFFFFFF
+} StdVideoAV1Profile;
+
+typedef enum StdVideoAV1Level {
+    STD_VIDEO_AV1_LEVEL_2_0 = 0,
+    STD_VIDEO_AV1_LEVEL_2_1 = 1,
+    STD_VIDEO_AV1_LEVEL_2_2 = 2,
+    STD_VIDEO_AV1_LEVEL_2_3 = 3,
+    STD_VIDEO_AV1_LEVEL_3_0 = 4,
+    STD_VIDEO_AV1_LEVEL_3_1 = 5,
+    STD_VIDEO_AV1_LEVEL_3_2 = 6,
+    STD_VIDEO_AV1_LEVEL_3_3 = 7,
+    STD_VIDEO_AV1_LEVEL_4_0 = 8,
+    STD_VIDEO_AV1_LEVEL_4_1 = 9,
+    STD_VIDEO_AV1_LEVEL_4_2 = 10,
+    STD_VIDEO_AV1_LEVEL_4_3 = 11,
+    STD_VIDEO_AV1_LEVEL_5_0 = 12,
+    STD_VIDEO_AV1_LEVEL_5_1 = 13,
+    STD_VIDEO_AV1_LEVEL_5_2 = 14,
+    STD_VIDEO_AV1_LEVEL_5_3 = 15,
+    STD_VIDEO_AV1_LEVEL_6_0 = 16,
+    STD_VIDEO_AV1_LEVEL_6_1 = 17,
+    STD_VIDEO_AV1_LEVEL_6_2 = 18,
+    STD_VIDEO_AV1_LEVEL_6_3 = 19,
+    STD_VIDEO_AV1_LEVEL_7_0 = 20,
+    STD_VIDEO_AV1_LEVEL_7_1 = 21,
+    STD_VIDEO_AV1_LEVEL_7_2 = 22,
+    STD_VIDEO_AV1_LEVEL_7_3 = 23,
+    STD_VIDEO_AV1_LEVEL_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_AV1_LEVEL_MAX_ENUM = 0x7FFFFFFF
+} StdVideoAV1Level;
+
+typedef enum StdVideoAV1FrameType {
+    STD_VIDEO_AV1_FRAME_TYPE_KEY = 0,
+    STD_VIDEO_AV1_FRAME_TYPE_INTER = 1,
+    STD_VIDEO_AV1_FRAME_TYPE_INTRA_ONLY = 2,
+    STD_VIDEO_AV1_FRAME_TYPE_SWITCH = 3,
+    STD_VIDEO_AV1_FRAME_TYPE_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_AV1_FRAME_TYPE_MAX_ENUM = 0x7FFFFFFF
+} StdVideoAV1FrameType;
+
+typedef enum StdVideoAV1ReferenceName {
+    STD_VIDEO_AV1_REFERENCE_NAME_INTRA_FRAME = 0,
+    STD_VIDEO_AV1_REFERENCE_NAME_LAST_FRAME = 1,
+    STD_VIDEO_AV1_REFERENCE_NAME_LAST2_FRAME = 2,
+    STD_VIDEO_AV1_REFERENCE_NAME_LAST3_FRAME = 3,
+    STD_VIDEO_AV1_REFERENCE_NAME_GOLDEN_FRAME = 4,
+    STD_VIDEO_AV1_REFERENCE_NAME_BWDREF_FRAME = 5,
+    STD_VIDEO_AV1_REFERENCE_NAME_ALTREF2_FRAME = 6,
+    STD_VIDEO_AV1_REFERENCE_NAME_ALTREF_FRAME = 7,
+    STD_VIDEO_AV1_REFERENCE_NAME_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_AV1_REFERENCE_NAME_MAX_ENUM = 0x7FFFFFFF
+} StdVideoAV1ReferenceName;
+
+typedef enum StdVideoAV1InterpolationFilter {
+    STD_VIDEO_AV1_INTERPOLATION_FILTER_EIGHTTAP = 0,
+    STD_VIDEO_AV1_INTERPOLATION_FILTER_EIGHTTAP_SMOOTH = 1,
+    STD_VIDEO_AV1_INTERPOLATION_FILTER_EIGHTTAP_SHARP = 2,
+    STD_VIDEO_AV1_INTERPOLATION_FILTER_BILINEAR = 3,
+    STD_VIDEO_AV1_INTERPOLATION_FILTER_SWITCHABLE = 4,
+    STD_VIDEO_AV1_INTERPOLATION_FILTER_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_AV1_INTERPOLATION_FILTER_MAX_ENUM = 0x7FFFFFFF
+} StdVideoAV1InterpolationFilter;
+
+typedef enum StdVideoAV1TxMode {
+    STD_VIDEO_AV1_TX_MODE_ONLY_4X4 = 0,
+    STD_VIDEO_AV1_TX_MODE_LARGEST = 1,
+    STD_VIDEO_AV1_TX_MODE_SELECT = 2,
+    STD_VIDEO_AV1_TX_MODE_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_AV1_TX_MODE_MAX_ENUM = 0x7FFFFFFF
+} StdVideoAV1TxMode;
+
+typedef enum StdVideoAV1FrameRestorationType {
+    STD_VIDEO_AV1_FRAME_RESTORATION_TYPE_NONE = 0,
+    STD_VIDEO_AV1_FRAME_RESTORATION_TYPE_WIENER = 1,
+    STD_VIDEO_AV1_FRAME_RESTORATION_TYPE_SGRPROJ = 2,
+    STD_VIDEO_AV1_FRAME_RESTORATION_TYPE_SWITCHABLE = 3,
+    STD_VIDEO_AV1_FRAME_RESTORATION_TYPE_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_AV1_FRAME_RESTORATION_TYPE_MAX_ENUM = 0x7FFFFFFF
+} StdVideoAV1FrameRestorationType;
+
+typedef enum StdVideoAV1ColorPrimaries {
+    STD_VIDEO_AV1_COLOR_PRIMARIES_BT_709 = 1,
+    STD_VIDEO_AV1_COLOR_PRIMARIES_UNSPECIFIED = 2,
+    STD_VIDEO_AV1_COLOR_PRIMARIES_BT_470_M = 4,
+    STD_VIDEO_AV1_COLOR_PRIMARIES_BT_470_B_G = 5,
+    STD_VIDEO_AV1_COLOR_PRIMARIES_BT_601 = 6,
+    STD_VIDEO_AV1_COLOR_PRIMARIES_SMPTE_240 = 7,
+    STD_VIDEO_AV1_COLOR_PRIMARIES_GENERIC_FILM = 8,
+    STD_VIDEO_AV1_COLOR_PRIMARIES_BT_2020 = 9,
+    STD_VIDEO_AV1_COLOR_PRIMARIES_XYZ = 10,
+    STD_VIDEO_AV1_COLOR_PRIMARIES_SMPTE_431 = 11,
+    STD_VIDEO_AV1_COLOR_PRIMARIES_SMPTE_432 = 12,
+    STD_VIDEO_AV1_COLOR_PRIMARIES_EBU_3213 = 22,
+    STD_VIDEO_AV1_COLOR_PRIMARIES_INVALID = 0x7FFFFFFF,
+  // STD_VIDEO_AV1_COLOR_PRIMARIES_BT_UNSPECIFIED is a deprecated alias
+    STD_VIDEO_AV1_COLOR_PRIMARIES_BT_UNSPECIFIED = STD_VIDEO_AV1_COLOR_PRIMARIES_UNSPECIFIED,
+    STD_VIDEO_AV1_COLOR_PRIMARIES_MAX_ENUM = 0x7FFFFFFF
+} StdVideoAV1ColorPrimaries;
+
+typedef enum StdVideoAV1TransferCharacteristics {
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_RESERVED_0 = 0,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_BT_709 = 1,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_UNSPECIFIED = 2,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_RESERVED_3 = 3,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_BT_470_M = 4,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_BT_470_B_G = 5,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_BT_601 = 6,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_SMPTE_240 = 7,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_LINEAR = 8,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_LOG_100 = 9,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_LOG_100_SQRT10 = 10,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_IEC_61966 = 11,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_BT_1361 = 12,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_SRGB = 13,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_BT_2020_10_BIT = 14,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_BT_2020_12_BIT = 15,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_SMPTE_2084 = 16,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_SMPTE_428 = 17,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_HLG = 18,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_AV1_TRANSFER_CHARACTERISTICS_MAX_ENUM = 0x7FFFFFFF
+} StdVideoAV1TransferCharacteristics;
+
+typedef enum StdVideoAV1MatrixCoefficients {
+    STD_VIDEO_AV1_MATRIX_COEFFICIENTS_IDENTITY = 0,
+    STD_VIDEO_AV1_MATRIX_COEFFICIENTS_BT_709 = 1,
+    STD_VIDEO_AV1_MATRIX_COEFFICIENTS_UNSPECIFIED = 2,
+    STD_VIDEO_AV1_MATRIX_COEFFICIENTS_RESERVED_3 = 3,
+    STD_VIDEO_AV1_MATRIX_COEFFICIENTS_FCC = 4,
+    STD_VIDEO_AV1_MATRIX_COEFFICIENTS_BT_470_B_G = 5,
+    STD_VIDEO_AV1_MATRIX_COEFFICIENTS_BT_601 = 6,
+    STD_VIDEO_AV1_MATRIX_COEFFICIENTS_SMPTE_240 = 7,
+    STD_VIDEO_AV1_MATRIX_COEFFICIENTS_SMPTE_YCGCO = 8,
+    STD_VIDEO_AV1_MATRIX_COEFFICIENTS_BT_2020_NCL = 9,
+    STD_VIDEO_AV1_MATRIX_COEFFICIENTS_BT_2020_CL = 10,
+    STD_VIDEO_AV1_MATRIX_COEFFICIENTS_SMPTE_2085 = 11,
+    STD_VIDEO_AV1_MATRIX_COEFFICIENTS_CHROMAT_NCL = 12,
+    STD_VIDEO_AV1_MATRIX_COEFFICIENTS_CHROMAT_CL = 13,
+    STD_VIDEO_AV1_MATRIX_COEFFICIENTS_ICTCP = 14,
+    STD_VIDEO_AV1_MATRIX_COEFFICIENTS_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_AV1_MATRIX_COEFFICIENTS_MAX_ENUM = 0x7FFFFFFF
+} StdVideoAV1MatrixCoefficients;
+
+typedef enum StdVideoAV1ChromaSamplePosition {
+    STD_VIDEO_AV1_CHROMA_SAMPLE_POSITION_UNKNOWN = 0,
+    STD_VIDEO_AV1_CHROMA_SAMPLE_POSITION_VERTICAL = 1,
+    STD_VIDEO_AV1_CHROMA_SAMPLE_POSITION_COLOCATED = 2,
+    STD_VIDEO_AV1_CHROMA_SAMPLE_POSITION_RESERVED = 3,
+    STD_VIDEO_AV1_CHROMA_SAMPLE_POSITION_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_AV1_CHROMA_SAMPLE_POSITION_MAX_ENUM = 0x7FFFFFFF
+} StdVideoAV1ChromaSamplePosition;
+typedef struct StdVideoAV1ColorConfigFlags {
+    uint32_t    mono_chrome : 1;
+    uint32_t    color_range : 1;
+    uint32_t    separate_uv_delta_q : 1;
+    uint32_t    color_description_present_flag : 1;
+    uint32_t    reserved : 28;
+} StdVideoAV1ColorConfigFlags;
+
+typedef struct StdVideoAV1ColorConfig {
+    StdVideoAV1ColorConfigFlags           flags;
+    uint8_t                               BitDepth;
+    uint8_t                               subsampling_x;
+    uint8_t                               subsampling_y;
+    uint8_t                               reserved1;
+    StdVideoAV1ColorPrimaries             color_primaries;
+    StdVideoAV1TransferCharacteristics    transfer_characteristics;
+    StdVideoAV1MatrixCoefficients         matrix_coefficients;
+    StdVideoAV1ChromaSamplePosition       chroma_sample_position;
+} StdVideoAV1ColorConfig;
+
+typedef struct StdVideoAV1TimingInfoFlags {
+    uint32_t    equal_picture_interval : 1;
+    uint32_t    reserved : 31;
+} StdVideoAV1TimingInfoFlags;
+
+typedef struct StdVideoAV1TimingInfo {
+    StdVideoAV1TimingInfoFlags    flags;
+    uint32_t                      num_units_in_display_tick;
+    uint32_t                      time_scale;
+    uint32_t                      num_ticks_per_picture_minus_1;
+} StdVideoAV1TimingInfo;
+
+typedef struct StdVideoAV1LoopFilterFlags {
+    uint32_t    loop_filter_delta_enabled : 1;
+    uint32_t    loop_filter_delta_update : 1;
+    uint32_t    reserved : 30;
+} StdVideoAV1LoopFilterFlags;
+
+typedef struct StdVideoAV1LoopFilter {
+    StdVideoAV1LoopFilterFlags    flags;
+    uint8_t                       loop_filter_level[STD_VIDEO_AV1_MAX_LOOP_FILTER_STRENGTHS];
+    uint8_t                       loop_filter_sharpness;
+    uint8_t                       update_ref_delta;
+    int8_t                        loop_filter_ref_deltas[STD_VIDEO_AV1_TOTAL_REFS_PER_FRAME];
+    uint8_t                       update_mode_delta;
+    int8_t                        loop_filter_mode_deltas[STD_VIDEO_AV1_LOOP_FILTER_ADJUSTMENTS];
+} StdVideoAV1LoopFilter;
+
+typedef struct StdVideoAV1QuantizationFlags {
+    uint32_t    using_qmatrix : 1;
+    uint32_t    diff_uv_delta : 1;
+    uint32_t    reserved : 30;
+} StdVideoAV1QuantizationFlags;
+
+typedef struct StdVideoAV1Quantization {
+    StdVideoAV1QuantizationFlags    flags;
+    uint8_t                         base_q_idx;
+    int8_t                          DeltaQYDc;
+    int8_t                          DeltaQUDc;
+    int8_t                          DeltaQUAc;
+    int8_t                          DeltaQVDc;
+    int8_t                          DeltaQVAc;
+    uint8_t                         qm_y;
+    uint8_t                         qm_u;
+    uint8_t                         qm_v;
+} StdVideoAV1Quantization;
+
+typedef struct StdVideoAV1Segmentation {
+    uint8_t    FeatureEnabled[STD_VIDEO_AV1_MAX_SEGMENTS];
+    int16_t    FeatureData[STD_VIDEO_AV1_MAX_SEGMENTS][STD_VIDEO_AV1_SEG_LVL_MAX];
+} StdVideoAV1Segmentation;
+
+typedef struct StdVideoAV1TileInfoFlags {
+    uint32_t    uniform_tile_spacing_flag : 1;
+    uint32_t    reserved : 31;
+} StdVideoAV1TileInfoFlags;
+
+typedef struct StdVideoAV1TileInfo {
+    StdVideoAV1TileInfoFlags    flags;
+    uint8_t                     TileCols;
+    uint8_t                     TileRows;
+    uint16_t                    context_update_tile_id;
+    uint8_t                     tile_size_bytes_minus_1;
+    uint8_t                     reserved1[7];
+    const uint16_t*             pMiColStarts;
+    const uint16_t*             pMiRowStarts;
+    const uint16_t*             pWidthInSbsMinus1;
+    const uint16_t*             pHeightInSbsMinus1;
+} StdVideoAV1TileInfo;
+
+typedef struct StdVideoAV1CDEF {
+    uint8_t    cdef_damping_minus_3;
+    uint8_t    cdef_bits;
+    uint8_t    cdef_y_pri_strength[STD_VIDEO_AV1_MAX_CDEF_FILTER_STRENGTHS];
+    uint8_t    cdef_y_sec_strength[STD_VIDEO_AV1_MAX_CDEF_FILTER_STRENGTHS];
+    uint8_t    cdef_uv_pri_strength[STD_VIDEO_AV1_MAX_CDEF_FILTER_STRENGTHS];
+    uint8_t    cdef_uv_sec_strength[STD_VIDEO_AV1_MAX_CDEF_FILTER_STRENGTHS];
+} StdVideoAV1CDEF;
+
+typedef struct StdVideoAV1LoopRestoration {
+    StdVideoAV1FrameRestorationType    FrameRestorationType[STD_VIDEO_AV1_MAX_NUM_PLANES];
+    uint16_t                           LoopRestorationSize[STD_VIDEO_AV1_MAX_NUM_PLANES];
+} StdVideoAV1LoopRestoration;
+
+typedef struct StdVideoAV1GlobalMotion {
+    uint8_t    GmType[STD_VIDEO_AV1_NUM_REF_FRAMES];
+    int32_t    gm_params[STD_VIDEO_AV1_NUM_REF_FRAMES][STD_VIDEO_AV1_GLOBAL_MOTION_PARAMS];
+} StdVideoAV1GlobalMotion;
+
+typedef struct StdVideoAV1FilmGrainFlags {
+    uint32_t    chroma_scaling_from_luma : 1;
+    uint32_t    overlap_flag : 1;
+    uint32_t    clip_to_restricted_range : 1;
+    uint32_t    update_grain : 1;
+    uint32_t    reserved : 28;
+} StdVideoAV1FilmGrainFlags;
+
+typedef struct StdVideoAV1FilmGrain {
+    StdVideoAV1FilmGrainFlags    flags;
+    uint8_t                      grain_scaling_minus_8;
+    uint8_t                      ar_coeff_lag;
+    uint8_t                      ar_coeff_shift_minus_6;
+    uint8_t                      grain_scale_shift;
+    uint16_t                     grain_seed;
+    uint8_t                      film_grain_params_ref_idx;
+    uint8_t                      num_y_points;
+    uint8_t                      point_y_value[STD_VIDEO_AV1_MAX_NUM_Y_POINTS];
+    uint8_t                      point_y_scaling[STD_VIDEO_AV1_MAX_NUM_Y_POINTS];
+    uint8_t                      num_cb_points;
+    uint8_t                      point_cb_value[STD_VIDEO_AV1_MAX_NUM_CB_POINTS];
+    uint8_t                      point_cb_scaling[STD_VIDEO_AV1_MAX_NUM_CB_POINTS];
+    uint8_t                      num_cr_points;
+    uint8_t                      point_cr_value[STD_VIDEO_AV1_MAX_NUM_CR_POINTS];
+    uint8_t                      point_cr_scaling[STD_VIDEO_AV1_MAX_NUM_CR_POINTS];
+    int8_t                       ar_coeffs_y_plus_128[STD_VIDEO_AV1_MAX_NUM_POS_LUMA];
+    int8_t                       ar_coeffs_cb_plus_128[STD_VIDEO_AV1_MAX_NUM_POS_CHROMA];
+    int8_t                       ar_coeffs_cr_plus_128[STD_VIDEO_AV1_MAX_NUM_POS_CHROMA];
+    uint8_t                      cb_mult;
+    uint8_t                      cb_luma_mult;
+    uint16_t                     cb_offset;
+    uint8_t                      cr_mult;
+    uint8_t                      cr_luma_mult;
+    uint16_t                     cr_offset;
+} StdVideoAV1FilmGrain;
+
+typedef struct StdVideoAV1SequenceHeaderFlags {
+    uint32_t    still_picture : 1;
+    uint32_t    reduced_still_picture_header : 1;
+    uint32_t    use_128x128_superblock : 1;
+    uint32_t    enable_filter_intra : 1;
+    uint32_t    enable_intra_edge_filter : 1;
+    uint32_t    enable_interintra_compound : 1;
+    uint32_t    enable_masked_compound : 1;
+    uint32_t    enable_warped_motion : 1;
+    uint32_t    enable_dual_filter : 1;
+    uint32_t    enable_order_hint : 1;
+    uint32_t    enable_jnt_comp : 1;
+    uint32_t    enable_ref_frame_mvs : 1;
+    uint32_t    frame_id_numbers_present_flag : 1;
+    uint32_t    enable_superres : 1;
+    uint32_t    enable_cdef : 1;
+    uint32_t    enable_restoration : 1;
+    uint32_t    film_grain_params_present : 1;
+    uint32_t    timing_info_present_flag : 1;
+    uint32_t    initial_display_delay_present_flag : 1;
+    uint32_t    reserved : 13;
+} StdVideoAV1SequenceHeaderFlags;
+
+typedef struct StdVideoAV1SequenceHeader {
+    StdVideoAV1SequenceHeaderFlags    flags;
+    StdVideoAV1Profile                seq_profile;
+    uint8_t                           frame_width_bits_minus_1;
+    uint8_t                           frame_height_bits_minus_1;
+    uint16_t                          max_frame_width_minus_1;
+    uint16_t                          max_frame_height_minus_1;
+    uint8_t                           delta_frame_id_length_minus_2;
+    uint8_t                           additional_frame_id_length_minus_1;
+    uint8_t                           order_hint_bits_minus_1;
+    uint8_t                           seq_force_integer_mv;
+    uint8_t                           seq_force_screen_content_tools;
+    uint8_t                           reserved1[5];
+    const StdVideoAV1ColorConfig*     pColorConfig;
+    const StdVideoAV1TimingInfo*      pTimingInfo;
+} StdVideoAV1SequenceHeader;
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

third_party/vulkan/include/vk_video/vulkan_video_codec_av1std_decode.h

@@ -0,0 +1,109 @@
+#ifndef VULKAN_VIDEO_CODEC_AV1STD_DECODE_H_
+#define VULKAN_VIDEO_CODEC_AV1STD_DECODE_H_ 1
+
+/*
+** Copyright 2015-2024 The Khronos Group Inc.
+**
+** SPDX-License-Identifier: Apache-2.0
+*/
+
+/*
+** This header is generated from the Khronos Vulkan XML API Registry.
+**
+*/
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+
+// vulkan_video_codec_av1std_decode is a preprocessor guard. Do not pass it to API calls.
+#define vulkan_video_codec_av1std_decode 1
+#include "vulkan_video_codec_av1std.h"
+
+#define VK_STD_VULKAN_VIDEO_CODEC_AV1_DECODE_API_VERSION_1_0_0 VK_MAKE_VIDEO_STD_VERSION(1, 0, 0)
+
+#define VK_STD_VULKAN_VIDEO_CODEC_AV1_DECODE_SPEC_VERSION VK_STD_VULKAN_VIDEO_CODEC_AV1_DECODE_API_VERSION_1_0_0
+#define VK_STD_VULKAN_VIDEO_CODEC_AV1_DECODE_EXTENSION_NAME "VK_STD_vulkan_video_codec_av1_decode"
+typedef struct StdVideoDecodeAV1PictureInfoFlags {
+    uint32_t    error_resilient_mode : 1;
+    uint32_t    disable_cdf_update : 1;
+    uint32_t    use_superres : 1;
+    uint32_t    render_and_frame_size_different : 1;
+    uint32_t    allow_screen_content_tools : 1;
+    uint32_t    is_filter_switchable : 1;
+    uint32_t    force_integer_mv : 1;
+    uint32_t    frame_size_override_flag : 1;
+    uint32_t    buffer_removal_time_present_flag : 1;
+    uint32_t    allow_intrabc : 1;
+    uint32_t    frame_refs_short_signaling : 1;
+    uint32_t    allow_high_precision_mv : 1;
+    uint32_t    is_motion_mode_switchable : 1;
+    uint32_t    use_ref_frame_mvs : 1;
+    uint32_t    disable_frame_end_update_cdf : 1;
+    uint32_t    allow_warped_motion : 1;
+    uint32_t    reduced_tx_set : 1;
+    uint32_t    reference_select : 1;
+    uint32_t    skip_mode_present : 1;
+    uint32_t    delta_q_present : 1;
+    uint32_t    delta_lf_present : 1;
+    uint32_t    delta_lf_multi : 1;
+    uint32_t    segmentation_enabled : 1;
+    uint32_t    segmentation_update_map : 1;
+    uint32_t    segmentation_temporal_update : 1;
+    uint32_t    segmentation_update_data : 1;
+    uint32_t    UsesLr : 1;
+    uint32_t    usesChromaLr : 1;
+    uint32_t    apply_grain : 1;
+    uint32_t    reserved : 3;
+} StdVideoDecodeAV1PictureInfoFlags;
+
+typedef struct StdVideoDecodeAV1PictureInfo {
+    StdVideoDecodeAV1PictureInfoFlags    flags;
+    StdVideoAV1FrameType                 frame_type;
+    uint32_t                             current_frame_id;
+    uint8_t                              OrderHint;
+    uint8_t                              primary_ref_frame;
+    uint8_t                              refresh_frame_flags;
+    uint8_t                              reserved1;
+    StdVideoAV1InterpolationFilter       interpolation_filter;
+    StdVideoAV1TxMode                    TxMode;
+    uint8_t                              delta_q_res;
+    uint8_t                              delta_lf_res;
+    uint8_t                              SkipModeFrame[STD_VIDEO_AV1_SKIP_MODE_FRAMES];
+    uint8_t                              coded_denom;
+    uint8_t                              reserved2[3];
+    uint8_t                              OrderHints[STD_VIDEO_AV1_NUM_REF_FRAMES];
+    uint32_t                             expectedFrameId[STD_VIDEO_AV1_NUM_REF_FRAMES];
+    const StdVideoAV1TileInfo*           pTileInfo;
+    const StdVideoAV1Quantization*       pQuantization;
+    const StdVideoAV1Segmentation*       pSegmentation;
+    const StdVideoAV1LoopFilter*         pLoopFilter;
+    const StdVideoAV1CDEF*               pCDEF;
+    const StdVideoAV1LoopRestoration*    pLoopRestoration;
+    const StdVideoAV1GlobalMotion*       pGlobalMotion;
+    const StdVideoAV1FilmGrain*          pFilmGrain;
+} StdVideoDecodeAV1PictureInfo;
+
+typedef struct StdVideoDecodeAV1ReferenceInfoFlags {
+    uint32_t    disable_frame_end_update_cdf : 1;
+    uint32_t    segmentation_enabled : 1;
+    uint32_t    reserved : 30;
+} StdVideoDecodeAV1ReferenceInfoFlags;
+
+typedef struct StdVideoDecodeAV1ReferenceInfo {
+    StdVideoDecodeAV1ReferenceInfoFlags    flags;
+    uint8_t                                frame_type;
+    uint8_t                                RefFrameSignBias;
+    uint8_t                                OrderHint;
+    uint8_t                                SavedOrderHints[STD_VIDEO_AV1_NUM_REF_FRAMES];
+} StdVideoDecodeAV1ReferenceInfo;
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

third_party/vulkan/include/vk_video/vulkan_video_codec_av1std_encode.h

@@ -0,0 +1,143 @@
+#ifndef VULKAN_VIDEO_CODEC_AV1STD_ENCODE_H_
+#define VULKAN_VIDEO_CODEC_AV1STD_ENCODE_H_ 1
+
+/*
+** Copyright 2015-2024 The Khronos Group Inc.
+**
+** SPDX-License-Identifier: Apache-2.0
+*/
+
+/*
+** This header is generated from the Khronos Vulkan XML API Registry.
+**
+*/
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+
+// vulkan_video_codec_av1std_encode is a preprocessor guard. Do not pass it to API calls.
+#define vulkan_video_codec_av1std_encode 1
+#include "vulkan_video_codec_av1std.h"
+
+#define VK_STD_VULKAN_VIDEO_CODEC_AV1_ENCODE_API_VERSION_1_0_0 VK_MAKE_VIDEO_STD_VERSION(1, 0, 0)
+
+#define VK_STD_VULKAN_VIDEO_CODEC_AV1_ENCODE_SPEC_VERSION VK_STD_VULKAN_VIDEO_CODEC_AV1_ENCODE_API_VERSION_1_0_0
+#define VK_STD_VULKAN_VIDEO_CODEC_AV1_ENCODE_EXTENSION_NAME "VK_STD_vulkan_video_codec_av1_encode"
+typedef struct StdVideoEncodeAV1DecoderModelInfo {
+    uint8_t     buffer_delay_length_minus_1;
+    uint8_t     buffer_removal_time_length_minus_1;
+    uint8_t     frame_presentation_time_length_minus_1;
+    uint8_t     reserved1;
+    uint32_t    num_units_in_decoding_tick;
+} StdVideoEncodeAV1DecoderModelInfo;
+
+typedef struct StdVideoEncodeAV1ExtensionHeader {
+    uint8_t    temporal_id;
+    uint8_t    spatial_id;
+} StdVideoEncodeAV1ExtensionHeader;
+
+typedef struct StdVideoEncodeAV1OperatingPointInfoFlags {
+    uint32_t    decoder_model_present_for_this_op : 1;
+    uint32_t    low_delay_mode_flag : 1;
+    uint32_t    initial_display_delay_present_for_this_op : 1;
+    uint32_t    reserved : 29;
+} StdVideoEncodeAV1OperatingPointInfoFlags;
+
+typedef struct StdVideoEncodeAV1OperatingPointInfo {
+    StdVideoEncodeAV1OperatingPointInfoFlags    flags;
+    uint16_t                                    operating_point_idc;
+    uint8_t                                     seq_level_idx;
+    uint8_t                                     seq_tier;
+    uint32_t                                    decoder_buffer_delay;
+    uint32_t                                    encoder_buffer_delay;
+    uint8_t                                     initial_display_delay_minus_1;
+} StdVideoEncodeAV1OperatingPointInfo;
+
+typedef struct StdVideoEncodeAV1PictureInfoFlags {
+    uint32_t    error_resilient_mode : 1;
+    uint32_t    disable_cdf_update : 1;
+    uint32_t    use_superres : 1;
+    uint32_t    render_and_frame_size_different : 1;
+    uint32_t    allow_screen_content_tools : 1;
+    uint32_t    is_filter_switchable : 1;
+    uint32_t    force_integer_mv : 1;
+    uint32_t    frame_size_override_flag : 1;
+    uint32_t    buffer_removal_time_present_flag : 1;
+    uint32_t    allow_intrabc : 1;
+    uint32_t    frame_refs_short_signaling : 1;
+    uint32_t    allow_high_precision_mv : 1;
+    uint32_t    is_motion_mode_switchable : 1;
+    uint32_t    use_ref_frame_mvs : 1;
+    uint32_t    disable_frame_end_update_cdf : 1;
+    uint32_t    allow_warped_motion : 1;
+    uint32_t    reduced_tx_set : 1;
+    uint32_t    skip_mode_present : 1;
+    uint32_t    delta_q_present : 1;
+    uint32_t    delta_lf_present : 1;
+    uint32_t    delta_lf_multi : 1;
+    uint32_t    segmentation_enabled : 1;
+    uint32_t    segmentation_update_map : 1;
+    uint32_t    segmentation_temporal_update : 1;
+    uint32_t    segmentation_update_data : 1;
+    uint32_t    UsesLr : 1;
+    uint32_t    usesChromaLr : 1;
+    uint32_t    show_frame : 1;
+    uint32_t    showable_frame : 1;
+    uint32_t    reserved : 3;
+} StdVideoEncodeAV1PictureInfoFlags;
+
+typedef struct StdVideoEncodeAV1PictureInfo {
+    StdVideoEncodeAV1PictureInfoFlags          flags;
+    StdVideoAV1FrameType                       frame_type;
+    uint32_t                                   frame_presentation_time;
+    uint32_t                                   current_frame_id;
+    uint8_t                                    order_hint;
+    uint8_t                                    primary_ref_frame;
+    uint8_t                                    refresh_frame_flags;
+    uint8_t                                    coded_denom;
+    uint16_t                                   render_width_minus_1;
+    uint16_t                                   render_height_minus_1;
+    StdVideoAV1InterpolationFilter             interpolation_filter;
+    StdVideoAV1TxMode                          TxMode;
+    uint8_t                                    delta_q_res;
+    uint8_t                                    delta_lf_res;
+    uint8_t                                    ref_order_hint[STD_VIDEO_AV1_NUM_REF_FRAMES];
+    int8_t                                     ref_frame_idx[STD_VIDEO_AV1_REFS_PER_FRAME];
+    uint8_t                                    reserved1[3];
+    uint32_t                                   delta_frame_id_minus_1[STD_VIDEO_AV1_REFS_PER_FRAME];
+    const StdVideoAV1TileInfo*                 pTileInfo;
+    const StdVideoAV1Quantization*             pQuantization;
+    const StdVideoAV1Segmentation*             pSegmentation;
+    const StdVideoAV1LoopFilter*               pLoopFilter;
+    const StdVideoAV1CDEF*                     pCDEF;
+    const StdVideoAV1LoopRestoration*          pLoopRestoration;
+    const StdVideoAV1GlobalMotion*             pGlobalMotion;
+    const StdVideoEncodeAV1ExtensionHeader*    pExtensionHeader;
+    const uint32_t*                            pBufferRemovalTimes;
+} StdVideoEncodeAV1PictureInfo;
+
+typedef struct StdVideoEncodeAV1ReferenceInfoFlags {
+    uint32_t    disable_frame_end_update_cdf : 1;
+    uint32_t    segmentation_enabled : 1;
+    uint32_t    reserved : 30;
+} StdVideoEncodeAV1ReferenceInfoFlags;
+
+typedef struct StdVideoEncodeAV1ReferenceInfo {
+    StdVideoEncodeAV1ReferenceInfoFlags        flags;
+    uint32_t                                   RefFrameId;
+    StdVideoAV1FrameType                       frame_type;
+    uint8_t                                    OrderHint;
+    uint8_t                                    reserved1[3];
+    const StdVideoEncodeAV1ExtensionHeader*    pExtensionHeader;
+} StdVideoEncodeAV1ReferenceInfo;
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

third_party/vulkan/include/vk_video/vulkan_video_codec_h264std.h

@@ -0,0 +1,312 @@
+#ifndef VULKAN_VIDEO_CODEC_H264STD_H_
+#define VULKAN_VIDEO_CODEC_H264STD_H_ 1
+
+/*
+** Copyright 2015-2024 The Khronos Group Inc.
+**
+** SPDX-License-Identifier: Apache-2.0
+*/
+
+/*
+** This header is generated from the Khronos Vulkan XML API Registry.
+**
+*/
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+
+// vulkan_video_codec_h264std is a preprocessor guard. Do not pass it to API calls.
+#define vulkan_video_codec_h264std 1
+#include "vulkan_video_codecs_common.h"
+#define STD_VIDEO_H264_CPB_CNT_LIST_SIZE  32
+#define STD_VIDEO_H264_SCALING_LIST_4X4_NUM_LISTS 6
+#define STD_VIDEO_H264_SCALING_LIST_4X4_NUM_ELEMENTS 16
+#define STD_VIDEO_H264_SCALING_LIST_8X8_NUM_LISTS 6
+#define STD_VIDEO_H264_SCALING_LIST_8X8_NUM_ELEMENTS 64
+#define STD_VIDEO_H264_MAX_NUM_LIST_REF   32
+#define STD_VIDEO_H264_MAX_CHROMA_PLANES  2
+#define STD_VIDEO_H264_NO_REFERENCE_PICTURE 0xFF
+
+typedef enum StdVideoH264ChromaFormatIdc {
+    STD_VIDEO_H264_CHROMA_FORMAT_IDC_MONOCHROME = 0,
+    STD_VIDEO_H264_CHROMA_FORMAT_IDC_420 = 1,
+    STD_VIDEO_H264_CHROMA_FORMAT_IDC_422 = 2,
+    STD_VIDEO_H264_CHROMA_FORMAT_IDC_444 = 3,
+    STD_VIDEO_H264_CHROMA_FORMAT_IDC_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_H264_CHROMA_FORMAT_IDC_MAX_ENUM = 0x7FFFFFFF
+} StdVideoH264ChromaFormatIdc;
+
+typedef enum StdVideoH264ProfileIdc {
+    STD_VIDEO_H264_PROFILE_IDC_BASELINE = 66,
+    STD_VIDEO_H264_PROFILE_IDC_MAIN = 77,
+    STD_VIDEO_H264_PROFILE_IDC_HIGH = 100,
+    STD_VIDEO_H264_PROFILE_IDC_HIGH_444_PREDICTIVE = 244,
+    STD_VIDEO_H264_PROFILE_IDC_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_H264_PROFILE_IDC_MAX_ENUM = 0x7FFFFFFF
+} StdVideoH264ProfileIdc;
+
+typedef enum StdVideoH264LevelIdc {
+    STD_VIDEO_H264_LEVEL_IDC_1_0 = 0,
+    STD_VIDEO_H264_LEVEL_IDC_1_1 = 1,
+    STD_VIDEO_H264_LEVEL_IDC_1_2 = 2,
+    STD_VIDEO_H264_LEVEL_IDC_1_3 = 3,
+    STD_VIDEO_H264_LEVEL_IDC_2_0 = 4,
+    STD_VIDEO_H264_LEVEL_IDC_2_1 = 5,
+    STD_VIDEO_H264_LEVEL_IDC_2_2 = 6,
+    STD_VIDEO_H264_LEVEL_IDC_3_0 = 7,
+    STD_VIDEO_H264_LEVEL_IDC_3_1 = 8,
+    STD_VIDEO_H264_LEVEL_IDC_3_2 = 9,
+    STD_VIDEO_H264_LEVEL_IDC_4_0 = 10,
+    STD_VIDEO_H264_LEVEL_IDC_4_1 = 11,
+    STD_VIDEO_H264_LEVEL_IDC_4_2 = 12,
+    STD_VIDEO_H264_LEVEL_IDC_5_0 = 13,
+    STD_VIDEO_H264_LEVEL_IDC_5_1 = 14,
+    STD_VIDEO_H264_LEVEL_IDC_5_2 = 15,
+    STD_VIDEO_H264_LEVEL_IDC_6_0 = 16,
+    STD_VIDEO_H264_LEVEL_IDC_6_1 = 17,
+    STD_VIDEO_H264_LEVEL_IDC_6_2 = 18,
+    STD_VIDEO_H264_LEVEL_IDC_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_H264_LEVEL_IDC_MAX_ENUM = 0x7FFFFFFF
+} StdVideoH264LevelIdc;
+
+typedef enum StdVideoH264PocType {
+    STD_VIDEO_H264_POC_TYPE_0 = 0,
+    STD_VIDEO_H264_POC_TYPE_1 = 1,
+    STD_VIDEO_H264_POC_TYPE_2 = 2,
+    STD_VIDEO_H264_POC_TYPE_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_H264_POC_TYPE_MAX_ENUM = 0x7FFFFFFF
+} StdVideoH264PocType;
+
+typedef enum StdVideoH264AspectRatioIdc {
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_UNSPECIFIED = 0,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_SQUARE = 1,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_12_11 = 2,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_10_11 = 3,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_16_11 = 4,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_40_33 = 5,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_24_11 = 6,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_20_11 = 7,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_32_11 = 8,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_80_33 = 9,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_18_11 = 10,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_15_11 = 11,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_64_33 = 12,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_160_99 = 13,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_4_3 = 14,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_3_2 = 15,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_2_1 = 16,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_EXTENDED_SAR = 255,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_H264_ASPECT_RATIO_IDC_MAX_ENUM = 0x7FFFFFFF
+} StdVideoH264AspectRatioIdc;
+
+typedef enum StdVideoH264WeightedBipredIdc {
+    STD_VIDEO_H264_WEIGHTED_BIPRED_IDC_DEFAULT = 0,
+    STD_VIDEO_H264_WEIGHTED_BIPRED_IDC_EXPLICIT = 1,
+    STD_VIDEO_H264_WEIGHTED_BIPRED_IDC_IMPLICIT = 2,
+    STD_VIDEO_H264_WEIGHTED_BIPRED_IDC_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_H264_WEIGHTED_BIPRED_IDC_MAX_ENUM = 0x7FFFFFFF
+} StdVideoH264WeightedBipredIdc;
+
+typedef enum StdVideoH264ModificationOfPicNumsIdc {
+    STD_VIDEO_H264_MODIFICATION_OF_PIC_NUMS_IDC_SHORT_TERM_SUBTRACT = 0,
+    STD_VIDEO_H264_MODIFICATION_OF_PIC_NUMS_IDC_SHORT_TERM_ADD = 1,
+    STD_VIDEO_H264_MODIFICATION_OF_PIC_NUMS_IDC_LONG_TERM = 2,
+    STD_VIDEO_H264_MODIFICATION_OF_PIC_NUMS_IDC_END = 3,
+    STD_VIDEO_H264_MODIFICATION_OF_PIC_NUMS_IDC_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_H264_MODIFICATION_OF_PIC_NUMS_IDC_MAX_ENUM = 0x7FFFFFFF
+} StdVideoH264ModificationOfPicNumsIdc;
+
+typedef enum StdVideoH264MemMgmtControlOp {
+    STD_VIDEO_H264_MEM_MGMT_CONTROL_OP_END = 0,
+    STD_VIDEO_H264_MEM_MGMT_CONTROL_OP_UNMARK_SHORT_TERM = 1,
+    STD_VIDEO_H264_MEM_MGMT_CONTROL_OP_UNMARK_LONG_TERM = 2,
+    STD_VIDEO_H264_MEM_MGMT_CONTROL_OP_MARK_LONG_TERM = 3,
+    STD_VIDEO_H264_MEM_MGMT_CONTROL_OP_SET_MAX_LONG_TERM_INDEX = 4,
+    STD_VIDEO_H264_MEM_MGMT_CONTROL_OP_UNMARK_ALL = 5,
+    STD_VIDEO_H264_MEM_MGMT_CONTROL_OP_MARK_CURRENT_AS_LONG_TERM = 6,
+    STD_VIDEO_H264_MEM_MGMT_CONTROL_OP_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_H264_MEM_MGMT_CONTROL_OP_MAX_ENUM = 0x7FFFFFFF
+} StdVideoH264MemMgmtControlOp;
+
+typedef enum StdVideoH264CabacInitIdc {
+    STD_VIDEO_H264_CABAC_INIT_IDC_0 = 0,
+    STD_VIDEO_H264_CABAC_INIT_IDC_1 = 1,
+    STD_VIDEO_H264_CABAC_INIT_IDC_2 = 2,
+    STD_VIDEO_H264_CABAC_INIT_IDC_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_H264_CABAC_INIT_IDC_MAX_ENUM = 0x7FFFFFFF
+} StdVideoH264CabacInitIdc;
+
+typedef enum StdVideoH264DisableDeblockingFilterIdc {
+    STD_VIDEO_H264_DISABLE_DEBLOCKING_FILTER_IDC_DISABLED = 0,
+    STD_VIDEO_H264_DISABLE_DEBLOCKING_FILTER_IDC_ENABLED = 1,
+    STD_VIDEO_H264_DISABLE_DEBLOCKING_FILTER_IDC_PARTIAL = 2,
+    STD_VIDEO_H264_DISABLE_DEBLOCKING_FILTER_IDC_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_H264_DISABLE_DEBLOCKING_FILTER_IDC_MAX_ENUM = 0x7FFFFFFF
+} StdVideoH264DisableDeblockingFilterIdc;
+
+typedef enum StdVideoH264SliceType {
+    STD_VIDEO_H264_SLICE_TYPE_P = 0,
+    STD_VIDEO_H264_SLICE_TYPE_B = 1,
+    STD_VIDEO_H264_SLICE_TYPE_I = 2,
+    STD_VIDEO_H264_SLICE_TYPE_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_H264_SLICE_TYPE_MAX_ENUM = 0x7FFFFFFF
+} StdVideoH264SliceType;
+
+typedef enum StdVideoH264PictureType {
+    STD_VIDEO_H264_PICTURE_TYPE_P = 0,
+    STD_VIDEO_H264_PICTURE_TYPE_B = 1,
+    STD_VIDEO_H264_PICTURE_TYPE_I = 2,
+    STD_VIDEO_H264_PICTURE_TYPE_IDR = 5,
+    STD_VIDEO_H264_PICTURE_TYPE_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_H264_PICTURE_TYPE_MAX_ENUM = 0x7FFFFFFF
+} StdVideoH264PictureType;
+
+typedef enum StdVideoH264NonVclNaluType {
+    STD_VIDEO_H264_NON_VCL_NALU_TYPE_SPS = 0,
+    STD_VIDEO_H264_NON_VCL_NALU_TYPE_PPS = 1,
+    STD_VIDEO_H264_NON_VCL_NALU_TYPE_AUD = 2,
+    STD_VIDEO_H264_NON_VCL_NALU_TYPE_PREFIX = 3,
+    STD_VIDEO_H264_NON_VCL_NALU_TYPE_END_OF_SEQUENCE = 4,
+    STD_VIDEO_H264_NON_VCL_NALU_TYPE_END_OF_STREAM = 5,
+    STD_VIDEO_H264_NON_VCL_NALU_TYPE_PRECODED = 6,
+    STD_VIDEO_H264_NON_VCL_NALU_TYPE_INVALID = 0x7FFFFFFF,
+    STD_VIDEO_H264_NON_VCL_NALU_TYPE_MAX_ENUM = 0x7FFFFFFF
+} StdVideoH264NonVclNaluType;
+typedef struct StdVideoH264SpsVuiFlags {
+    uint32_t    aspect_ratio_info_present_flag : 1;
+    uint32_t    overscan_info_present_flag : 1;
+    uint32_t    overscan_appropriate_flag : 1;
+    uint32_t    video_signal_type_present_flag : 1;
+    uint32_t    video_full_range_flag : 1;
+    uint32_t    color_description_present_flag : 1;
+    uint32_t    chroma_loc_info_present_flag : 1;
+    uint32_t    timing_info_present_flag : 1;
+    uint32_t    fixed_frame_rate_flag : 1;
+    uint32_t    bitstream_restriction_flag : 1;
+    uint32_t    nal_hrd_parameters_present_flag : 1;
+    uint32_t    vcl_hrd_parameters_present_flag : 1;
+} StdVideoH264SpsVuiFlags;
+
+typedef struct StdVideoH264HrdParameters {
+    uint8_t     cpb_cnt_minus1;
+    uint8_t     bit_rate_scale;
+    uint8_t     cpb_size_scale;
+    uint8_t     reserved1;
+    uint32_t    bit_rate_value_minus1[STD_VIDEO_H264_CPB_CNT_LIST_SIZE];
+    uint32_t    cpb_size_value_minus1[STD_VIDEO_H264_CPB_CNT_LIST_SIZE];
+    uint8_t     cbr_flag[STD_VIDEO_H264_CPB_CNT_LIST_SIZE];
+    uint32_t    initial_cpb_removal_delay_length_minus1;
+    uint32_t    cpb_removal_delay_length_minus1;
+    uint32_t    dpb_output_delay_length_minus1;
+    uint32_t    time_offset_length;
+} StdVideoH264HrdParameters;
+
+typedef struct StdVideoH264SequenceParameterSetVui {
+    StdVideoH264SpsVuiFlags             flags;
+    StdVideoH264AspectRatioIdc          aspect_ratio_idc;
+    uint16_t                            sar_width;
+    uint16_t                            sar_height;
+    uint8_t                             video_format;
+    uint8_t                             colour_primaries;
+    uint8_t                             transfer_characteristics;
+    uint8_t                             matrix_coefficients;
+    uint32_t                            num_units_in_tick;
+    uint32_t                            time_scale;
+    uint8_t                             max_num_reorder_frames;
+    uint8_t                             max_dec_frame_buffering;
+    uint8_t                             chroma_sample_loc_type_top_field;
+    uint8_t                             chroma_sample_loc_type_bottom_field;
+    uint32_t                            reserved1;
+    const StdVideoH264HrdParameters*    pHrdParameters;
+} StdVideoH264SequenceParameterSetVui;
+
+typedef struct StdVideoH264SpsFlags {
+    uint32_t    constraint_set0_flag : 1;
+    uint32_t    constraint_set1_flag : 1;
+    uint32_t    constraint_set2_flag : 1;
+    uint32_t    constraint_set3_flag : 1;
+    uint32_t    constraint_set4_flag : 1;
+    uint32_t    constraint_set5_flag : 1;
+    uint32_t    direct_8x8_inference_flag : 1;
+    uint32_t    mb_adaptive_frame_field_flag : 1;
+    uint32_t    frame_mbs_only_flag : 1;
+    uint32_t    delta_pic_order_always_zero_flag : 1;
+    uint32_t    separate_colour_plane_flag : 1;
+    uint32_t    gaps_in_frame_num_value_allowed_flag : 1;
+    uint32_t    qpprime_y_zero_transform_bypass_flag : 1;
+    uint32_t    frame_cropping_flag : 1;
+    uint32_t    seq_scaling_matrix_present_flag : 1;
+    uint32_t    vui_parameters_present_flag : 1;
+} StdVideoH264SpsFlags;
+
+typedef struct StdVideoH264ScalingLists {
+    uint16_t    scaling_list_present_mask;
+    uint16_t    use_default_scaling_matrix_mask;
+    uint8_t     ScalingList4x4[STD_VIDEO_H264_SCALING_LIST_4X4_NUM_LISTS][STD_VIDEO_H264_SCALING_LIST_4X4_NUM_ELEMENTS];
+    uint8_t     ScalingList8x8[STD_VIDEO_H264_SCALING_LIST_8X8_NUM_LISTS][STD_VIDEO_H264_SCALING_LIST_8X8_NUM_ELEMENTS];
+} StdVideoH264ScalingLists;
+
+typedef struct StdVideoH264SequenceParameterSet {
+    StdVideoH264SpsFlags                          flags;
+    StdVideoH264ProfileIdc                        profile_idc;
+    StdVideoH264LevelIdc                          level_idc;
+    StdVideoH264ChromaFormatIdc                   chroma_format_idc;
+    uint8_t                                       seq_parameter_set_id;
+    uint8_t                                       bit_depth_luma_minus8;
+    uint8_t                                       bit_depth_chroma_minus8;
+    uint8_t                                       log2_max_frame_num_minus4;
+    StdVideoH264PocType                           pic_order_cnt_type;
+    int32_t                                       offset_for_non_ref_pic;
+    int32_t                                       offset_for_top_to_bottom_field;
+    uint8_t                                       log2_max_pic_order_cnt_lsb_minus4;
+    uint8_t                                       num_ref_frames_in_pic_order_cnt_cycle;
+    uint8_t                                       max_num_ref_frames;
+    uint8_t                                       reserved1;
+    uint32_t                                      pic_width_in_mbs_minus1;
+    uint32_t                                      pic_height_in_map_units_minus1;
+    uint32_t                                      frame_crop_left_offset;
+    uint32_t                                      frame_crop_right_offset;
+    uint32_t                                      frame_crop_top_offset;
+    uint32_t                                      frame_crop_bottom_offset;
+    uint32_t                                      reserved2;
+    const int32_t*                                pOffsetForRefFrame;
+    const StdVideoH264ScalingLists*               pScalingLists;
+    const StdVideoH264SequenceParameterSetVui*    pSequenceParameterSetVui;
+} StdVideoH264SequenceParameterSet;
+
+typedef struct StdVideoH264PpsFlags {
+    uint32_t    transform_8x8_mode_flag : 1;
+    uint32_t    redundant_pic_cnt_present_flag : 1;
+    uint32_t    constrained_intra_pred_flag : 1;
+    uint32_t    deblocking_filter_control_present_flag : 1;
+    uint32_t    weighted_pred_flag : 1;
+    uint32_t    bottom_field_pic_order_in_frame_present_flag : 1;
+    uint32_t    entropy_coding_mode_flag : 1;
+    uint32_t    pic_scaling_matrix_present_flag : 1;
+} StdVideoH264PpsFlags;
+
+typedef struct StdVideoH264PictureParameterSet {
+    StdVideoH264PpsFlags               flags;
+    uint8_t                            seq_parameter_set_id;
+    uint8_t                            pic_parameter_set_id;
+    uint8_t                            num_ref_idx_l0_default_active_minus1;
+    uint8_t                            num_ref_idx_l1_default_active_minus1;
+    StdVideoH264WeightedBipredIdc      weighted_bipred_idc;
+    int8_t                             pic_init_qp_minus26;
+    int8_t                             pic_init_qs_minus26;
+    int8_t                             chroma_qp_index_offset;
+    int8_t                             second_chroma_qp_index_offset;
+    const StdVideoH264ScalingLists*    pScalingLists;
+} StdVideoH264PictureParameterSet;
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif