steam-frame/mitch030504--Wiicompiled_VR_Frame
1
0 Fork 0
mirror of https://github.com/mitch030504/Wiicompiled_VR_Frame.git synced 2026-10-06 09:00:28 +02:00
Code Issues Packages Projects Releases 3 Wiki Activity
Files
17b3d3de32b0e0f5efdf6bceb4af6d16260d416d
mitch030504--Wiicompiled_VR…/README.md
T
iChris4andClaude Opus 5.5 a21e22b605 Pose the cockpit hands from the headset's hand tracking 
- New [vr] hand_tracking (default off, Quest only for now): the Quest launcher's Settings > VR and
  the headset panel's VR tab, under hand steering. Two XR_EXT_hand_tracking trackers are located
  every XR frame: with the controllers held the Quest builds the joints from their touch sensors
  (XR_EXT_hand_tracking_data_source's controller source), once they are put down from its
  cameras. The trackers exist only while the option and hand steering are on and also serve the
  runtime hand mesh; the extensions (plus XR_FB_hand_tracking_aim) are asked for when either is
  on at launch.
- Aurora skins the runtime mesh with the joints themselves (tracked pose times inverse bind pose,
  no curl, no grip); runtimes with joints but no mesh get a skeleton; non-finite joints put only
  that hand back on its grip curl. AuroraCockpitHand carries the 26 seated-frame joints and radii.
- The manifest declares horizonos.permission.HAND_TRACKING (and the deprecated
  com.oculus.permission.HAND_TRACKING), both normal permissions with no prompt on a Quest 3, and
  oculus.software.handtracking as optional; without it Horizon OS keeps the app controllers-only.
  Bare hands then drive khr/simple_controller, so on Android a hand whose squeeze action is
  inactive and select active is treated as bare: with the option off it presses nothing but the
  menu gesture, is not drawn and feeds no Wii Remote motion.
- Interaction-profile changes and tracker sources are logged. The pure rules (grasp from finger
  flexion, bare latch, pinch gate, bare-hand buttons, flick) live in the OpenXR-free
  vr/openxr_hand_tracking.h with mkw_vr_hand_tracking_tests; the driving and flick parts are
  wired in the next commits. Docs: OPENXR.md, docs/quest-port.md, README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 00:05:48 +02:00

300 lines
16 KiB
Markdown
Raw Blame History

<img width="4190" height="2464" alt="Mario Kart WiiCompiled VR logo (logo by Inkwreck)" src="docs/images/wiicompiled-vr-logo.png" />
# WiiCompiled OpenXR VR
<p align="center">
<a href="https://github.com/patchzyy/Wiicompiled/releases"><img alt="Windows 10 / 11, x64" src="https://img.shields.io/badge/Windows-10%20%2F%2011%20%C2%B7%20x64-0078D4"></a>
<a href="https://github.com/patchzyy/Wiicompiled/releases"><img alt="Linux, x64 / ARM64" src="https://img.shields.io/badge/Linux-x64%20%2F%20ARM64-FCC624?logo=linux&amp;logoColor=white"></a>
<a href="https://github.com/patchzyy/Wiicompiled/releases"><img alt="macOS 14+, Apple Silicon" src="https://img.shields.io/badge/macOS-14%2B%20%C2%B7%20Apple%20Silicon-0A84FF?logo=apple&amp;logoColor=white"></a>
</p>
<p align="center">
<a href="#building-from-source"><img alt="PowerPC static recompilation" src="https://img.shields.io/badge/PowerPC-static%20recompilation-FF9F0A"></a>
<a href="#retro-rewind"><img alt="Retro Rewind supported" src="https://img.shields.io/badge/Retro%20Rewind-supported-FF375F"></a>
<a href="https://github.com/TeamWheelWizard/WheelWizard/releases"><img alt="Install with Wheel Wizard" src="https://img.shields.io/badge/install%20with-Wheel%20Wizard-8B5CF6"></a>
<a href="LICENSE"><img alt="License: GPLv3" src="https://img.shields.io/badge/license-GPLv3-2EA44F?logo=gnu&amp;logoColor=white"></a>
</p>
A native PC port of Mario Kart Wii, made with static recompilation.
There's no emulator in the loop, no interpreter, no JIT, no PowerPC
anywhere at runtime.
> [!IMPORTANT]
> There is no Nintendo code, no assets and no game data anywhere in this project or its releases.
> You need your own legally dumped copy of the PAL version of the game. Setup only ships the
> toolchain, the translation runs on your machine against your disc image, and nothing ever gets
> uploaded.
[Download WheelWizard VR](https://github.com/iChris4/WheelWizard_VR/releases/latest)
---
## What it does
**Unlocked framerate with interpolation.**
The original game is hard-locked to 60 fps. The runtime can generate interpolated frames in between, so on a
120/144 Hz monitor things genuinely look smoother.
> [!WARNING]
> Interpolation is experimental right now and will show artifacts in specific scenarios.
**Any aspect ratio you want.**
Drag the window bigger, wider, whatever, the camera adjusts
live.
**Native rendering via aurora.**
The graphics layer is built on
[aurora](https://github.com/encounter/aurora). Aurora is a source-level GameCube & Wii compatibility layer.
**High internal resolution.**
Play at several times the console's resolution.
**Experimental OpenXR VR.**
Windows builds can render through an OpenXR runtime on D3D12, or on Vulkan with a custom Dawn
build, without CPU readback. Menus and
unsupported scenes appear as a head-locked virtual screen; a validated single-camera race switches
to immersive stereo rendering. VR is opt-in and falls back to the normal desktop renderer if the
runtime or headset is unavailable. In first person you sit in the cockpit, where the steering wheel
or handlebar turns with your steering, and hand steering by heurazy lets you grab it with the
tracked controllers and turn it. On a Quest the hands can follow the headset's own hand tracking.
See [`OPENXR.md`](OPENXR.md) for setup, configuration, and the current limitations.
**Music ducking.**
Start playing something else, Spotify, a YouTube video, and
the game automatically mutes its own music until the other audio stops. Optional, if you'd
rather it didn't. All audio that shows in your display media controls on your windows pc fall under this.
**An in-game settings bar.**
Press **F10** while the game window has focus:
- Internal resolution
- FPS counter
- Controller assignment for all four ports
- Full per-controller button mapping, including the bumpers
- Dolphin-syntax input expressions and GCPadNew.ini import
- Controller vibration on/off
- Volume, instant mute, and the music ducking toggle
Everything you change is saved to `Config.toml` on the spot and restored next launch.
**Dolphin-compatible input expressions.**
Each GameCube control can carry an expression in Dolphin's input syntax, with the same operators
and the same functions.
A Dolphin `GCPadNew.ini` can be imported directly from the F10 bar.
**Vibration toggle.**
Force feedback can be turned off for every port at once.
The official Wii U / Switch GameCube adapter (WUP-028) works too; as with Dolphin, on Windows the
adapter must be switched to the WinUSB driver once (Zadig).
**Real Wii Remotes over Bluetooth.**
Pair a Wii Remote with Windows (Settings > Bluetooth > Add device, press 1+2 or SYNC, leave the
PIN empty)
Known limitations of the Wii Remote path:
- No IR pointer yet: menus are navigated with the D-pad and A (the game treats the remote as
pointing away from the screen).
- Battery level is not reported to the game and the remote's speaker is not implemented.
- Only the Wii Remote's own accelerometer is calibrated; the Nunchuk's uses SDL's fixed zero point.
- The Classic Controller's L/R triggers reach the game as digital (full pull on click): SDL does not
expose their analog travel.
- Turn the Wii Remote support off in that menu if you use a Mayflash DolphinBar, which already
presents the remote as a regular gamepad.
**USB steering wheels and pedals.**
Ported from heurazy's [mario-kart-wii-VR-port](https://github.com/heurazy/mario-kart-wii-VR-port).
Open **F10 > Controllers > USB wheel and pedals (player 1)**; it is also in the headset's settings
panel. Pick the steering device and axis and record full left, full right and centre, then each
pedal's released and fully pressed positions. Assign the right paddle to drift and the left paddle to
items; trick, confirm, pause and back are optional. Any wheel SDL sees as a joystick works this way,
with no gamepad mapping: separate USB pedals, reversed axes and combined pedal axes (select the same
axis for both pedals) all calibrate the same. The settings are saved in `PhysicalWheel.toml` beside
`Config.toml`.
The wheel is player 1's GameCube controller. Press its confirm button at the title screen so the game
uses a GameCube controller; its D-pad, confirm and back then work the menus. In a race it owns
steering and the pedals. The brake pedal brakes, then reverses, and beats the accelerator and drift.
In VR, the cockpit's wheel turns with it and hand steering steps aside. Setting the VR controllers to
**Gamepad** keeps them for menus, pause and item aiming alongside the wheel. Light vibration is
optional, off by default, capped at 15 % and follows the game's own rumble. No centering spring or
steering force is requested.
Logitech wheels (G29, G920, G923, G27, G25, Driving Force GT, PRO Racing Wheel) are recognised by SDL
as wheels and marked "(wheel)" in the device list. This has not been tried on a physical wheel yet:
- Install Logitech G HUB (Logitech Gaming Software for a G27 or G25). Without the driver a Logitech
wheel starts in a compatibility mode, typically with a smaller rotation range and both pedals on
one axis. A G920 or G923 for Xbox also starts as an Xbox controller, which the game would read as
an ordinary pad.
- Set a G29's mode switch to PS3 on PC.
- Full lock is wherever you record full left and right. Recording them a quarter turn each way
(90°) matches the VR cockpit's wheel, or lower the operating range in G HUB.
- A Driving Force Shifter's gears reach the game as buttons of the wheel and can be assigned like
any other. A gear stays pressed while it is engaged: on the item button it keeps the item held
behind you until you shift back to neutral. The clutch is not used.
- Turn on the centering spring in G HUB if you want the wheel to self-centre.
## Requirements
- Windows 10 or 11, 64-bit
- GPU: GTX 1650 / RX 6400 / Arc A310 or higher
- CPU: Intel Core i5-8400 / AMD Ryzen 5 2600 (4c/6c, ~3.5GHz+) or higher
- About 20 GB of free disk space during installation (Final game size ~5 GB)
- This fork's packaged release supports Windows x64. Other platforms are not release targets.
- A clean, unmodified **PAL `RMCP01`** disc image of Mario Kart Wii, dumped by you. ISO, GCM,
GCZ, CISO, WBFS, WIA and RVZ are accepted.
> [!NOTE]
> GPU/CPU minimums are set by driver support and D3D12/Vulkan feature requirements, not by the game's actual demands.
Only the clean PAL revision will work. Anything else (other
regions, patched executables) is rejected outright.
> [!NOTE]
> Nobody here will tell you where to get the game. Dumping your own disc is on you, and links to
> game files won't be provided or tolerated.
## Installing
Use [WheelWizard VR](https://github.com/iChris4/WheelWizard_VR/releases/latest). Select your clean PAL
`RMCP01` image in Settings, then open **Settings → Other → WiiCompiled (beta)** and enable
**Enable WiiCompiled OpenXR VR (beta)**. Press Install on Home. Installation builds both Base game
and Retro Rewind locally using the bundled toolchain; a developer toolchain is not required.
Home lets you choose **Base game** or **Retro Rewind**. The normal WiiCompiled switch selects the
original backend; turning both switches off selects Dolphin. Only one recompilation switch can
be enabled at a time. VR uses a separate `RecompVR` installation beside the normal `Recomp` folder.
Saves and Miis use the normal installation's effective NAND; Retro Rewind retains its separate
XML-directed saves and ghosts. Graphics, VR preferences, caches, and compiled binaries stay separate.
Uninstalling either backend in WheelWizard VR preserves configuration and shared progress.
Managed VR launches enable OpenXR with D3D12; the Vulkan binding is opt-in through
`video.graphics_api` (see [OPENXR.md](OPENXR.md)). If the runtime or headset is unavailable, the game
continues on the desktop and displays the failure briefly; **F10 → VR** retains the explanation.
See [OpenXR configuration](OPENXR.md) and [distribution and validation](DISTRIBUTION.md).
> [!CAUTION]
> Only take builds from this repository's
> [Releases](https://github.com/iChris4/Wiicompiled_VR/releases) page. If someone's sharing an
> installer through Discord or some random download site, don't touch it!!
## A note on related projects
WiiCompiled, Wheel Wizard, Retro rewind and other related projects are developed
**independently** and each has its **own** contribution rules and all have their own
rules. What applies here does not automatically apply there,
and vice versa. Check each project's own CONTRIBUTING and README files.
## Retro Rewind
[Retro Rewind](https://wiki.tockdom.com/wiki/Retro_Rewind), ZPL's Mario Kart Wii mod distribution,
can be built as its **own static profile**: instead of applying `Code.pul` as runtime patches,
the Kamek/Pulsar code is statically translated together with the base game into a separate native
executable.
Wheel Wizard drives this too.
## Building from source
Owning the game is still required even if you compile everything yourself.
You'll need: .NET 8 SDK, CMake, Ninja, and LLVM/Clang (the shipped build uses LLVM-MinGW targeting
`x86-64-v3`).
Build the translator:
```powershell
dotnet build translator/Translator.sln -c Release
```
The default test suite needs no binaries and no host C++ compiler, so you can hack on the
translator without any game data around.
For everything beyond that, feeding in your own `main.dol`/`StaticR.rel`, running the
translation, generating the manifest and build graph, and compiling, see [`translator/README.md`](translator/README.md).
For a step-by-step guide on compiling both WiiCompiled and Retro Rewind from source on macOS (Apple Silicon), see the [macOS Build Guide](docs/building-macos.md).
## FAQ
**Is this an emulator?**
No. Everything is compiled to native code before you ever press play. At runtime there's nothing
emulating a Wii CPU or GPU.
**Do you provide the game?**
No. Don't ask. Nothing in this repo or any release contains Nintendo code or assets.
**Why does setup take so long?**
Because we **don't** ship the translated binary, most other recomp projects do, but we
don't want to risk it right now, setup has to run a static recompiler over the whole game
and then throw a C++ compiler at the result. It's a **one-time cost** on your machine.
**Which game version works?**
Clean PAL `RMCP01`. Other regions and modified executables are **rejected**. Translating
them against the wrong manifest would give you a subtly broken game that's miserable to debug for us.
**Can I recompile other GameCube/Wii games with it?**
The translator itself handles DOLs and RELs generically, see
`projects/examples/generic-dol.yml`. The catch is that a *playable* port also needs a runtime:
audio, input, GX, everything the game touches.
**The game crashed / stopped with an error.**
Errors are deliberately loud instead of quietly swallowed. Send a report along with the run log
from `%LOCALAPPDATA%\WiiCompiled\Logs`.
**Will you fix original bugs?**
Not in the base game, behavior identical to real hardware is the goal. Only report things where this port differs
from the original game. As for Retro Rewind, some base-game behavior **is** patched, so if it differs from the
base game, that's normal. If Retro Rewind behavior differs between Dolphin/Wii and WiiCompiled, open an issue on GitHub.
**How accurate are the physics?**
100% - this is proven by in-game ghosts. Since ghosts are replay files based on inputs rather
than tracked positions, matching ghosts prove the physics match across Dolphin/Wii/WiiCompiled.
**Is it done?**
Not fully. The game is in a state where everything should be playable and the physics do match
100% with the original game, but compatibility, rendering, networking and performance are all
actively being worked on. If you do find an issue, we strongly encourage you to open one on
GitHub so we can take a look at it.
## 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
- **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.
- **[Dawn](https://dawn.googlesource.com/dawn)** - Google's WebGPU implementation, powering
aurora's Direct3D, Vulkan and OpenGL backends.
- **[OpenXR](https://www.khronos.org/openxr/)** - the Khronos cross-platform API used by the
experimental VR renderer.
- **heurazy** - the VR cockpit's turning steering wheel and hand steering, ported from
**[mario-kart-wii-VR-port](https://github.com/heurazy/mario-kart-wii-VR-port)** (GPL-3.0).
- **[Dolphin Emulator](https://github.com/dolphin-emu/dolphin)** - an invaluable reference for Wii
hardware behavior during development, plus the source of the free DSP coefficient ROM and the
unmodified default WiiConnect24 bootstrap tree bundled with the runtime.
- **[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 this
project integrates with as a launch backend.
- Everyone in the static recompilation community.
Bundled third-party components and their licenses live in
[`THIRD-PARTY-NOTICES.md`](THIRD-PARTY-NOTICES.md).
## License
WiiCompiled is free software: you can redistribute it and/or modify it under the terms of the
[GNU General Public License, version 3](LICENSE) as published by the Free Software Foundation.
WiiCompiled is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
Any mkwii distribution making use of WiiCompiled must be licensed under GPL v3.0.
Not affiliated with, endorsed by, or associated with Nintendo. Mario Kart Wii is a trademark of
Nintendo. No Nintendo intellectual property is contained in, distributed with, or obtainable
through this project.
Reference in new issue View Git Blame Copy Permalink