From 47611ce31747eff7ece313ee173c2748dfed4c19 Mon Sep 17 00:00:00 2001
From: simplysanatori <149214925+simplysanatori@users.noreply.github.com>
Date: Mon, 12 Oct 2026 21:55:47 -0400
Subject: [PATCH] frame/DEV.md, mockrun.sh

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 frame/DEV.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 frame/DEV.md

diff --git a/frame/DEV.md b/frame/DEV.md
new file mode 100644
index 0000000..1dbf5be
--- /dev/null
+++ b/frame/DEV.md
@@ -0,0 +1,46 @@
+# KartFrame development notes (lane 0)
+
+## Build
+
+    frame/build-dawn.sh                      # once: patched static Dawn into ~/.cache/kartframe/dawn/<rev>-<patch hash>/
+    ~/Games/KartFrame/kfbuild.sh <worktree> WiiCompiled      # the game, binary build-linux/kartframe
+    KF_CONFIGURE_ONLY=1 ~/Games/KartFrame/kfbuild.sh <worktree>   # configure only (no lock)
+
+`kfbuild.sh` takes the shared build lock, uses ccache (~/.cache/ccache-kf), links the worktree's
+`generated` to the development translation (`~/Games/KartFrame/data/generated-dev`, never committed),
+and passes the newest Dawn package (or `KARTFRAME_DAWN_DIR`) as `-DMKW_DAWN_PACKAGE_DIR`. The project
+only accepts `CMAKE_BUILD_TYPE=Release`. The translated shards are the heavy part;
+`MKW_TRANSLATED_COMPILE_JOBS` (default 3 in kfbuild) caps how many compile at once.
+
+The CMake wiring for Linux: OpenXR on by default, pinned Vulkan headers and the pinned static OpenXR
+loader (vendored jsoncpp) are fetched, the patched Dawn package is linked statically (its
+`AuroraDawnVulkan*` ABI resolves at link time), SDL3 is built from source (audio: ALSA, JACK, PipeWire,
+PulseAudio loaded at run time, plus dummy; video: Wayland, X11, KMS/DRM, offscreen, dummy). The shard
+manifest and the blob assembly of a translation made elsewhere are relocated at configure time.
+
+## Where the runtime looks for things
+
+Executable `kartframe` (target `WiiCompiled`). Its resources (`dsp_coef.bin`, `initial_pipeline_cache.db`,
+`wii_bootstrap/`, `resources/`) are copied next to it in the build directory and are found next to the
+executable.
+
+User state, from `runtime_config.h`:
+
+- Normal install: `$XDG_DATA_HOME/WiiCompiled` (default `~/.local/share/WiiCompiled`), holding
+  `Config.toml`, `NAND/`, `Cache/`, `Logs/`.
+- Portable: a file `portable.txt` in the executable's directory or up to a few parents makes
+  `<that dir>/UserData` the root instead.
+- `Config.toml` is created with defaults on first start. The game files are not found automatically:
+  `[paths] dvd_root` must name the extracted DATA directory (the one holding `sys/fst.bin` and
+  `files/`); a relative value is relative to the Config.toml. `[paths] nand_root` is optional; when it
+  is absent the managed NAND is `<state dir>/NAND` (the licence is made in-game on first boot).
+- `[vr] enabled = true, required = false` (defaults) try OpenXR and fall back to the desktop renderer.
+  The OpenXR loader reads `~/.config/openxr/1/active_runtime.json` (SteamVR) unless `XR_RUNTIME_JSON`
+  is set. `[vr] force_steamvr` does nothing on Linux.
+- The program takes no command line arguments.
+
+## Tools and runs
+
+`frame/tools/mockrun.sh` runs the game against the mock runtime (xrmock) or flat, headless
+(`SDL_VIDEO_DRIVER=offscreen`, `SDL_AUDIO_DRIVER=dummy`, no DISPLAY), in a scratch state dir. It aborts
+when the mock runtime file is missing or empty. Never run the game with the real runtime from an agent.