Merge pull request #11 from mitch030504/claude/docs-and-credits-41qj9z

Credit ported work and document today's merged changes
2026-10-06 06:00:25 +02:00 · 2026-10-05 18:24:31 +02:00
commit 9be271d49a
@@ -39,9 +39,19 @@ That's ok, but rules apply:
  game (hardware comparison, logs, whatever fits).
 - Review feedback. It's about the code, not about you ;).

+## Porting from other projects
+
+This fork takes fixes from upstream WiiCompiled and other forks. When you port one:
+
+- name the source repository and commit in the commit message ("Ported from owner/repo abc1234");
+- keep the original author on the commit when the change is taken as is, and say what you changed
+  when it is adapted;
+- add a line to [`CREDITS.md`](CREDITS.md), and check the source's license is compatible with
+  GPL v3.0.
+
 ## Bug reports

-See the FAQ in the [README](README.md)
+See [Reporting problems](README.md#reporting-problems) in the README.

 ## A note on related projects

@@ -0,0 +1,79 @@
+# Credits
+
+WiiCompiled VR for the Steam Frame is the work of many people. This fork adds the SteamOS build,
+the install and diagnostics scripts and the Frame-specific rendering, but most of what you play
+was written elsewhere, and a good part of this fork's own fixes were ported from other people's
+projects. This page lists where everything came from.
+
+Every project below is GPL-3.0 licensed like this one unless it says otherwise. Ported commits name
+their source repository and commit in their messages, and keep the original author where the
+change was taken as is, so `git log` is the full record. Bundled libraries and their licenses are
+in [`THIRD-PARTY-NOTICES.md`](THIRD-PARTY-NOTICES.md).
+
+## The projects this fork is built on
+
+- **[WiiCompiled](https://github.com/patchzyy/Wiicompiled)** by patchzyy and its contributors: the
+  static recompilation of Mario Kart Wii itself, the translator, the runtime and the Aurora-based
+  renderer.
+- **[WiiCompiled OpenXR VR](https://github.com/iChris4/Wiicompiled_VR)** by iChris4: the OpenXR VR
+  renderer, the Quest app, the headset settings panel, foveation and the first-person cockpit. This
+  fork contains all of its `openxr-work` branch up to 2026-10-01.
+- **[mario-kart-wii-VR-port](https://github.com/heurazy/mario-kart-wii-VR-port)** by heurazy: the
+  cockpit's turning steering wheel, hand steering and USB wheel support, which came in through
+  WiiCompiled OpenXR VR.
+- **[DolphinXR](https://github.com/iChris4/dolphinXR)**: the OpenXR Wii Remote input design and its
+  default button profile, which the controller code (`runtime/src/vr/openxr_input.cpp`) and the
+  Steam Frame controller profile's input paths are adapted from.
+
+## Ported into this fork
+
+### From WiiCompiled (upstream)
+
+Cherry-picked or adapted from [patchzyy/Wiicompiled](https://github.com/patchzyy/Wiicompiled) after
+this fork's line split from it:
+
+| Change | Author | Upstream |
+| --- | --- | --- |
+| TLS through mbed TLS on Linux and Android, which online play (Retro Rewind WFC) needs there | dorPXP, with patchzyy | #144 |
+| NAND moves across mount points on Linux (saves on a different drive or the SD card) | Daan Vervacke | #212 |
+| Controller mapping platform, player index sync, and socket send errors | Michael G ([DarthMDev](https://github.com/DarthMDev)) | #251 |
+| `bltl` translation | patchzyy | #254 |
+| The KartPad batch: KD and NCD kept while offline, RFL alarm interrupt context, shared LR continuation dispatch, pipeline cache size checks, pipeline waiter wake-ups, packed three-byte vertex reads, draw merging bounds, GEN_MODE decode, EFB copy and readback fixes, graphics startup errors, and the staging buffer wait | patchzyy, adapting Chris Sotraidis's [KartPad](https://github.com/chrissotraidis/wiicompiled) fixes | #244 |
+
+### From other WiiCompiled forks
+
+| Change | Author | Source |
+| --- | --- | --- |
+| Scene-load crash fix (`GXClearVtxDesc` keeps the position descriptor) | heurazy | [Wiicompiled_VR-PLUS](https://github.com/heurazy/Wiicompiled_VR-PLUS) c2b2500 |
+| `[vr] adaptive_resolution` | heurazy | Wiicompiled_VR-PLUS, adapted |
+| Building and installing Retro Rewind from its own update server (`steam-frame-install.sh --retro-rewind`) | heurazy | Wiicompiled_VR-PLUS, adapted |
+| Faster disc reads: bulk DVD DMA copies, Yaz0 (SZS) decoding through host buffers, per-thread disc file handles | Chris Sotraidis | [KartPad](https://github.com/chrissotraidis/wiicompiled) ec14a0d, 97cdc9a, affabbd |
+| No debug labels in the ImGui passes in normal builds (an Adreno driver crash) | Chris Sotraidis | KartPad 420b828, extended to this fork's extra passes |
+| A TLS session that failed a write is kept instead of its socket being deleted | Michael G ([DarthMDev](https://github.com/DarthMDev)) | [DarthMDev/Wiicompiled](https://github.com/DarthMDev/Wiicompiled) a2ecc0f, fcf8646 (upstream PR #258) |
+| `Config.toml` saved through a temporary file and a rename | BlackAndBlue95 | [Strikers-WiiCompiled](https://github.com/BlackAndBlue95/Strikers-WiiCompiled) 435daf3 |
+| No depth writes while the Z compare is off (the Stormship lightning) | BlackAndBlue95 | Strikers-WiiCompiled 369ec99 |
+| NEON forms of the AX audio mix kernels | rooklz | [rooklz/Wiicompiled](https://github.com/rooklz/Wiicompiled) 4346362 |
+| Emptied WC24 bootstrap files are refilled | nx-mod | [wiicompiled-nx](https://github.com/nx-mod/wiicompiled-nx) d0149e6, adapted |
+| Guest memory access checks folded away on 4 KiB-page builds | nx-mod's finding | wiicompiled-nx 18ef16f, done here as a compile-time constant |
+
+## Tools and references
+
+- **[aurora](https://github.com/encounter/aurora)** by Luke Street: the GX rendering and windowing
+  backend the whole graphics layer sits on (MIT).
+- **[Dawn](https://dawn.googlesource.com/dawn)**: Google's WebGPU implementation, under Aurora.
+- **[OpenXR](https://www.khronos.org/openxr/)** by Khronos: the VR API.
+- **[Mbed TLS](https://github.com/Mbed-TLS/mbedtls)**: TLS for online play on Linux and Android.
+- **[Dolphin Emulator](https://github.com/dolphin-emu/dolphin)**: a reference for Wii hardware
+  behaviour, and the source of the DSP coefficient ROM, the WiiConnect24 bootstrap tree and the
+  Riivolution parser bundled with the runtime.
+- **[nod](https://github.com/encounter/nod)** by Luke Street: `nodtool`, the disc image extractor.
+- **[Retro Rewind](https://wiki.tockdom.com/wiki/Retro_Rewind)** by ZPL and team: the mod
+  distribution this project supports.
+- **[Wheel Wizard](https://github.com/TeamWheelWizard/WheelWizard)**: the mod manager the PC build
+  integrates with, and the model for how the install script fetches Retro Rewind.
+- **[Frame Control](https://github.com/saphid/frame-control)** by saphid: installing the game into
+  the Frame's Steam library, and its notes on how the Frame's software fits together.
+- **Inkwreck**: the logo.
+- Everyone in the static recompilation community.
+
+If something of yours is in this fork and missing here, or credited wrongly, please open an issue.
@@ -1,5 +1,9 @@
 # Windows VR distribution

+This page covers upstream's Windows releases, kept for the PC build. The Steam Frame releases
+(`frame-*` tags) are source only and are published by `.github/workflows/frame-release.yml` with
+the notes in `docs/releases/<tag>.md`; see the [README](README.md#quick-start).
+
 Distribute only `WiiCompiled-Setup.exe` and its checksum from
 [iChris4/Wiicompiled_VR](https://github.com/iChris4/Wiicompiled_VR/releases), and
 `WheelWizardVRWindows.exe` from [iChris4/WheelWizard_VR](https://github.com/iChris4/WheelWizard_VR/releases).
@@ -147,6 +147,15 @@ headroom. It is live: **F10 → VR → Render resolution** (also on the headset
 in percent, applies it when the slider is let go, and saves it. Below the slider, *Each eye* gives
 the left eye's size now and, while they differ, the size the slider's value gives.

+`adaptive_resolution` (default off; *Adaptive resolution (experimental)* on the VR tab) lowers the
+race's eye resolution in 10% steps, down to 70% of `render_scale`, while new eye frames fall below
+85% of the game's 60 FPS, and raises it again after three seconds on time. The eyes render into the
+top-left corner of the full swapchain image and the projection layer shows only that corner, so the
+compositor scales them up and no swapchain is rebuilt; each step does rebuild the foveation maps.
+`console.log` records every change as `OpenXR: adaptive resolution`. It is offered on the Quest and
+the Linux (Steam Frame) build, not on Windows, whose bridges copy whole eyes. Adapted from
+heurazy's [Wiicompiled_VR-PLUS](https://github.com/heurazy/Wiicompiled_VR-PLUS).
+
 A new scale never interrupts the picture. Each backend keeps two swapchain pairs, one on display and
 one Aurora writes next, and rebuilds only the second, at the start of the frame that writes it; the
 other follows a frame later, once it is the one written. The new swapchains are created before the
@@ -357,6 +357,9 @@ Unraid keeps `/usr/local/bin` in memory, so repeat this after a reboot.
  Vulkan hook and density map ABIs that Aurora compiles against.
 - **Headset only.** The game neither shows nor finishes rendering a desktop window, and is compiled
  for the Frame's Cortex-X4 cores (`-mcpu=cortex-x4`, overridable with `--cpu`).
+- **Tuned for ARM64.** The Frame's kernel uses 4 KiB memory pages, so the `steam_frame` build drops
+  the page-size check from every translated memory access; it checks the page size once at startup
+  and refuses to start if it is ever different. Audio mixing uses NEON on ARM64.
 - **Every refresh from the game.** The game draws 60 frames a second. When it handed SteamVR only
  those, SteamVR ran it at half rate and made up every other refresh itself, even with Motion
  Smoothing off. With `[vr] repeat_frames`, the pacing thread waits for the next frame until 1.5 ms
@@ -384,8 +387,8 @@ play. [`docs/quest-port.md`](docs/quest-port.md) covers the Android build.

 Open an issue on this repository with:
 - what you did and what you saw (which eye, where in the picture, racing or menus);
- the run's `console.log` (and `crash_sigsegv.txt` after a crash) from
-  `~/.local/share/WiiCompiled/Logs/` on the Frame;
+- the archive [`frame-diagnostics.sh`](#troubleshooting) makes, or at least the run's `console.log`
+  (and `crash_sigsegv.txt` after a crash) from `~/.local/share/WiiCompiled/Logs/` on the Frame;
 - or, for a build problem, the last lines of the failing step.

 Problems that also happen on a PC or a Quest belong upstream, in
@@ -394,7 +397,10 @@ Problems that also happen on a PC or a Quest belong upstream, in
 ## From upstream

 The fork keeps everything [WiiCompiled OpenXR VR](https://github.com/iChris4/Wiicompiled_VR) does;
-its README covers it in full. In the headset that means:
+its README covers it in full. On top of that it carries fixes taken from
+[WiiCompiled](https://github.com/patchzyy/Wiicompiled) itself and from other WiiCompiled forks, such
+as Linux TLS for online play, faster disc reads, safer settings saves and NEON audio mixing; each is
+listed with its author in [`CREDITS.md`](CREDITS.md). In the headset that means:

 - Menus and unsupported scenes on a head-locked virtual screen, and races in immersive stereo.
 - A first-person cockpit whose steering wheel or handlebar turns with your steering, and hand
@@ -436,13 +442,20 @@ sharing.

 **Can it run on other SteamOS or Linux ARM64 devices?**
 Leave out `--headset steam_frame` and pass `--cpu` for your CPU to get a generic Linux VR build;
-it needs an OpenXR runtime with `XR_KHR_vulkan_enable2`. Untested.
+it needs an OpenXR runtime with `XR_KHR_vulkan_enable2`. Untested. The generic build also works on
+kernels with memory pages larger than 4 KiB, which the `steam_frame` build refuses.

 ## AI usage
 AI coding tools were used during development of this project. 
 All translated output is verified against real hardware behavior and most importantly, physics accuracy is proven synced across Wii, Dolphin, and WiiCompiled (see FAQ). 

 ## Credits
+
+This fork stands on other people's work: WiiCompiled by patchzyy, WiiCompiled OpenXR VR by iChris4,
+and fixes ported from heurazy's Wiicompiled_VR-PLUS, Chris Sotraidis's KartPad, DarthMDev,
+BlackAndBlue95's Strikers-WiiCompiled, rooklz and nx-mod's wiicompiled-nx. [`CREDITS.md`](CREDITS.md)
+says what came from whom. In short:
+
 - **inkwreck** - making the logo
 - **[aurora](https://github.com/encounter/aurora)** - the GX rendering/windowing backend this
  project's whole graphics layer sits on. MIT licensed.
@@ -463,8 +476,8 @@ All translated output is verified against real hardware behavior and most import
 - **[Wheel Wizard](https://github.com/TeamWheelWizard/WheelWizard)** - the mod manager this
  project integrates with as a launch backend.
 - **[nod](https://github.com/encounter/nod)** - nodtool, the disc image extractor.
- **[DolphinXR](https://github.com/iChris4/dolphinXR)** - the Steam Frame controller profile's
-  input paths.
+- **[DolphinXR](https://github.com/iChris4/dolphinXR)** - the OpenXR Wii Remote input design, and
+  the Steam Frame controller profile's input paths.
 - **[Frame Control](https://github.com/saphid/frame-control)** by saphid - installing the game into
  the Frame's Steam library, and its notes on how the Frame's software fits together.
 - Everyone in the static recompilation community.
@@ -88,6 +88,19 @@ wheel geometry and guest reads in `runtime/src/vr/mkw_vr_first_person.cpp` and
 (`runtime/include/physical_wheel.h`, `runtime/src/physical_wheel.cpp` and their test). The files
 carry that attribution in their headers.

+### Mozilla CA certificate bundle - MPL-2.0
+
+The root certificates Mbed TLS verifies servers against on Linux, macOS and Android
+(`runtime/assets/certs/cacert.pem`), copied next to the built game. Extracted from Mozilla's
+`certdata.txt` and redistributed unmodified as curl's CA bundle.
+Source: <https://curl.se/docs/caextract.html>
+
+### Code ported from other WiiCompiled forks - GPL-3.0-or-later
+
+Fixes taken from other GPL-3.0 forks of WiiCompiled (heurazy's Wiicompiled_VR-PLUS, KartPad,
+DarthMDev, Strikers-WiiCompiled, rooklz and wiicompiled-nx) are listed with their authors and
+source commits in [`CREDITS.md`](CREDITS.md).
+
 ### pugixml - MIT

 Copyright (c) 2006-2025 Arseny Kapoulkine.
@@ -0,0 +1,70 @@
+The third beta of WiiCompiled VR for the Steam Frame: Mario Kart Wii, statically recompiled to
+native ARM64 code, running in VR on SteamOS through SteamVR. This one brings in fixes from upstream
+WiiCompiled and from other WiiCompiled forks, Retro Rewind in the installer, and a diagnostics
+script. Thanks to everyone whose work is in it; [`CREDITS.md`](https://github.com/mitch030504/Wiicompiled_VR_Frame/blob/openxr-work/CREDITS.md) lists who wrote
+what.
+
+**This release is source only.** The game is always built from your own clean PAL `RMCP01` disc,
+and nothing built from it may be distributed, so there is no ready-built game here.
+
+## New
+
+- **Retro Rewind in the installer.** `steam-frame-install.sh --retro-rewind` downloads the Retro
+  Rewind pack from its own update server, builds Retro Rewind beside the base game and adds it to
+  your Steam library. `--retro-rewind-pack DIR` uses a pack you already have. Online play works on
+  Linux now that TLS does (below). From heurazy's Wiicompiled_VR-PLUS.
+- **Adaptive resolution** (`[vr] adaptive_resolution`, off by default): lowers the race's eye
+  resolution down to 70% while frames fall behind, and raises it again once they keep up.
+  Experimental and not yet tried in a race on the Frame. From Wiicompiled_VR-PLUS.
+- **`Launcher/frame-diagnostics.sh`** gathers the logs, crash files, settings, SteamVR logs and
+  system state from the Frame into one archive, with a summary of how far startup got. Attach it
+  to bug reports.
+
+## Fixed
+
+- A crash while a scene loads (`GXClearVtxDesc`). From Wiicompiled_VR-PLUS.
+- TLS on Linux, through Mbed TLS, so online services can connect at all (upstream #144), and a
+  timed-out TLS write no longer frees a session the game still holds (DarthMDev).
+- Saves on a different drive or the SD card can be moved (upstream #212); the game keeps its local
+  Wii identity services while offline, and emptied WiiConnect24 files are refilled, so it no longer
+  reports a save error for them (upstream #244, nx-mod).
+- `Config.toml` is saved through a temporary file, so a crash mid-save can't empty it
+  (BlackAndBlue95).
+- Renderer fixes from upstream's KartPad batch (#244): draws no longer read past their own vertices,
+  three-byte vertex attributes, GEN_MODE, EFB copies and readback, pipeline cache rows and pipeline
+  compile wake-ups. Waiting on the GPU now sleeps instead of holding a CPU core busy.
+- Effects no longer vanish while the world is darkened, such as Stormship's lightning
+  (BlackAndBlue95).
+- Controller player indices and socket errors (upstream #251), and a `bltl` translation (#254).
+
+## Faster
+
+- Disc reads and SZS decompression take bulk copies and keep file handles open per thread
+  (KartPad).
+- Audio mixing uses NEON (rooklz).
+- Translated memory accesses no longer check the page size each time, since the Frame uses 4 KiB
+  pages; the game checks once at startup (from nx-mod's finding).
+
+## Updating from frame-beta-2
+
+Run the install command again; you can leave out `--disc`. Dawn's patches did not change, so it is
+not rebuilt. Most of the game is, since the translator changed as well as the runtime and renderer,
+so expect a longer update than usual. The build now also downloads Mbed TLS. Add `--retro-rewind` to get Retro Rewind too.
+
+## Known issues
+
+Unchanged from frame-beta-2:
+
+- Images double in races and on the HUD, sometimes in the right eye only. Foveation is the main
+  suspect; try foveation Off if it bothers you, and report the result.
+- Foveation follows the right eye less well than the left.
+- VR frame interpolation is not recommended on the Frame.
+- The Android (`steamFrame`) flavour cannot show a picture in Lepton; use the native build.
+
+## Recommended settings
+
+`render_scale = 1.25`, `foveation = "medium"`, `repeat_frames = true`, `frame_interpolation_fps = 0`
+under `[vr]`, and `resolution_multiplier = 2` under `[video]`. SteamVR at 120 Hz.
+
+Reports with the run log from `~/.local/share/WiiCompiled/Logs/`, or the archive
+`frame-diagnostics.sh` makes, are welcome as issues.