KartFrame 0.9.0-alpha.1 (pre-release)

KartFrame 0.9.0-alpha.1 (pre-release)

Mario Kart Wii in VR, running natively on the Valve Steam Frame. KartFrame is a fork of heurazy's Wiicompiled VR PLUS with a native Linux Arm64 build, Vulkan on SteamVR's own device, and frame pacing written for SteamVR on the Frame. No Lepton, no APK, no PC.

This is a pre-release. It plays, at 120 Hz and 1728 pixels per eye, and has been through twenty headset sessions, but one problem is still being worked on (below), and a few smaller things are listed as known issues. Version numbers stay below 1.0.0 until that is done.

You need your own PAL Mario Kart Wii disc image. No game data is in this repository or its releases.

What you get

• The game built on your Frame from your own disc, once, in about 6 minutes.
• A Steam library entry that starts it in SteamVR with the right per-app settings every time.
• Both eyes rendered on every refresh of the 120 Hz display from that refresh's head pose; races hold 119-120 sets a second with under 1 % late.
• The 2D menus on a flat, steady screen in front of you; the race HUD on the virtual screen.
• The Frame controllers, with the grips holding the wheel in the cockpit view.

The known issue: the double image

In races, turning your head could show the world twice, one copy a little ahead of the other, worse in one eye. Twenty sessions of measurement found the mechanism: SteamVR's compositor on the Frame takes each eye's newest handed-over image at its own point inside the refresh, the right eye after the left, and a hand-over landing near those points made consecutive refreshes disagree. This build hands every frame over at a fixed point against the compositor's own clock (KARTFRAME_END_PHASE=after, the launch wrapper's default), which removes the doubling. What remains: the right eye runs one set ahead of the left, which reads as the right eye being a touch more sensitive to head movement, and the compositor now and then shows a frame twice. The README explains it in full; the cause behind the cause is still being chased.

Other known issues

• The Time Trial ghost is drawn flat.
• Full-view 2D effects (Blooper ink, the black of a respawn) do not cover the whole view.
• The laser pointer's dot is not visible on the 2D menu screen; the ray is.
• Two and four player races are heavier and not yet measured in the headset.

Download

• kartframe-0.9.0-alpha.1-linux-arm64.tar.gz
• kartframe-0.9.0-alpha.1-linux-arm64.tar.gz.sha256

Install

Clone the repository, run frame/install.sh with the tarball as its argument, then ~/Games/KartFrame/app/setup.sh with your disc image. The README has the steps. Updating is the same two commands; your game files, saves and settings stay where they are.

Reporting problems

Open an issue with what you did, what you expected and what happened, and the archive from ~/Games/KartFrame/app/tools/collect-logs.sh. It masks addresses, names and ids before anything leaves your Frame.

v1.3.1-frame.3: Steam Frame build 3 (grips, Frame controllers)

Steam Frame build 3, on upstream v1.3.1. Same as frame.2, plus the grips change and the Frame's own controllers in the menus.

What's new since frame.2

• Grips in first person. Hand steering is on now. In the first-person cockpit the grips hold the wheel; in the original and diorama cameras they still drift. The right bumper drifts in every camera. It kind of works: grabbing and steering work, but upstream's grab range and steering feel were tuned for Quest controllers and I haven't adjusted them. If you don't like it, set hand_steering = false under [vr] in Config.toml; then the grips drift everywhere and you steer with the stick, like frame.2.
• Steam Frame controllers in the menus instead of Quest Touch ones. This part isn't in the APK: steam-frame/install.sh converts the Frame controller models from your own SteamVR install and the launch wrapper puts them in place. The first try used the full models and made the menus lag to 45-60 fps, so the script now simplifies them to about the Touch models' size. With that the menus hold 90 Hz again (checked in the frame-timing log). Use WCF_FRAME_MODELS=0 steam-frame/install.sh ... to keep the Quest controllers. Run install.sh from this release's commit or newer, or you won't get them.

Updating from frame.2 changes the kit fingerprint, so the headset has to build the game again (about 13 minutes, same BuildGame command as in the README). Your disc import and settings are kept. The Frame controllers show from the second launch after an update, because the app unpacks its own resources again first.

Tested: this exact file (sha256 in SHA256SUMS.txt) is what I play. It was built on my headset from this kit, raced in the normal and first-person cameras, with the Frame controller models in the menus.

Known issues (README): the empty item box still shows; grip steering is rough as above; there are small occasional hitches. One tip: leave openxr_logging off. It writes a log line every second, and I could feel tiny hitches with it on.

Written by Anthropic's Claude (Opus 5.5 and Fable 5.1), tested by me in the headset; see the README's AI disclosure.

v1.3.1-frame.2: Steam Frame build 2 (tested)

Steam Frame build 2, on upstream v1.3.1. Use this one; v1.3.1-frame.1 does not build on the headset.

WiiCompiled-VR-SteamFrame-v1.3.1-frame.2.apk is upstream's v1.3.1 Quest APK with four game-kit files replaced by ones compiled from this branch (90 Hz interpolation, the Frame controller layout, menus drawn in the eyes, the attempted item-box fix), the classes.dex clipboard fix, and a new kit fingerprint. It contains no game data; your Steam Frame builds the game from your own disc. Install with steam-frame/install.sh, then follow "Setting it up on a Steam Frame" in the README.

Tested on my Frame from a clean start: installed with install.sh, game built on the headset against this kit (about 13 minutes), launched from the Steam library, raced. This exact file is what I play.

What changed from frame.1: the kit objects are compiled with NDK r29 (the kit's own NDK) instead of r30, whose libc++ headers referenced std::__hash_memory and broke the headset's final link; build.sh now refuses objects that import C++ symbols the kit's originals do not. The launch wrapper only starts the game when the built game matches the APK's kit.

Known issues, all in the README: the empty item box still shows, the menus draw Quest Touch controllers, grips do not grab the wheel in first person (hand steering is off on purpose), occasional small hitches.

Written by Anthropic's Claude (Opus 5.5 and Fable 5.1), tested by me in the headset; see the README's AI disclosure.

v1.3.1-frame.1: BROKEN, use v1.3.1-frame.2

Do not use. The kit objects in this APK were compiled with NDK r30, and the game build on the headset fails at the final link (undefined symbol: std::__ndk1::__hash_memory). The APK has been removed from this release. Use v1.3.1-frame.2.