Twilight Princess VR for Apple Vision Pro

Hyrule, all around you.

_{The Window view at Ordon Ranch, in the visionOS Simulator's living room.}

The Legend of Zelda: Twilight Princess (2006) running natively on Apple Vision Pro, in six degrees of freedom. Swing Link's sword with your own arm, raise the shield, draw the bow, or hang Hyrule on your wall as a window you can lean into. No PC, no streaming: just the headset.

Twilight Princess VR is Trevorbilt's native visionOS port, built on JoeyAW's TPVR mod for Dusklight: you bring the game, you build the app, Hyrule does the rest. It's listed in the AVP Ports Index.

Important

There are no game files and no app download here. You need your own Twilight Princess disc (GameCube or Wii) and a Mac to build with. Twilight Princess VR is a fan project. It isn't affiliated with or endorsed by Nintendo.

What you get

• Three ways to play, picked in the launcher:
  • Full: Hyrule all around you, in first person and at life scale. Menus, loading screens and fades to black can float in your room instead of a black void.
  • Progressive: a portal into Hyrule that the Digital Crown widens and narrows.
  • Window: the GameCube game in third person, in a window beside your other apps. The game's own 3D scene is rebuilt behind the glass every frame and rendered from wherever your eyes actually are, so you can lean in and look around. The HUD sits on the glass, and the game's bloom and colour tints glow on what they light.
• Your hands are Link's hands. PS VR2 Sense controllers put the sword and shield where yours are. No controller? In Full and Progressive, play with your bare hands. A DualSense, Xbox or other gamepad works too.
• Sharper than a GameCube ever was. SMAA or FXAA anti-aliasing, and render resolution up to 150%.
• Polite to your living room. The game pauses when you take the headset off, and if you wander too far from where you started, Hyrule fades into your room before you meet the coffee table.

_{Full immersion at Ordon Ranch (the Simulator shows one eye's view).}

_{The Window view from off to one side (Simulator again). That's real depth back there, not a picture.}

What you'll need

• A headset: Apple Vision Pro with visionOS 26 or later. It's tested on visionOS 27.

• A Mac with Apple silicon and Xcode at /Applications/Xcode.app (a path with a space in it trips up CMake), with its visionOS platform installed. Built and tested with Xcode 27 on macOS 27.

• Some tools: Homebrew, then:

  brew install cmake ninja xcodegen rustup
  export PATH="$(brew --prefix rustup)/bin:$PATH"
  rustup toolchain install nightly-2026-09-30 --profile minimal
  rustup target add --toolchain nightly-2026-09-30 aarch64-apple-visionos

• An Apple Account, signed in to Xcode (Xcode › Settings › Accounts). The app asks for the increased memory limit; it's been built with a paid developer team, and whether a free account can sign it is untested.

• The game: your own Twilight Princess disc image, from a disc you own.

• Patience: about 15 GB of free disk, and up to an hour for the first build (it compiles Google's Dawn graphics library once; later builds take minutes).

First time running your own app on a Vision Pro? Pair it with Xcode (Window › Devices and Simulators) and turn on Developer Mode on the headset.

Build it

1. Get the code, with its submodules:

   git clone --recurse-submodules https://github.com/edgytoast/tpvr-visionos.git
   cd tpvr-visionos

2. Prepare the checkout. This fetches the two graphics submodules at their pinned commits and applies this port's patches to them:

   visionos/scripts/bootstrap.sh

3. Build and install. With the headset awake, unlocked and paired:

   visionos/scripts/build-visionos.sh --team YOURTEAMID --install

   Your team ID is the 10-character ID shown for your team in Xcode › Settings › Accounts. With a free Apple Account, the headset won't open the app until you trust it: Settings › General › VPN & Device Management.

The full install guide, with troubleshooting, is AVP-INSTALL.md.

Bring your game

Twilight Princess VR plays your own disc image: GameCube (GZ2E01, GZ2P01 or GZ2J01) or any Wii release except the Korean one, as .iso, .rvz or .wbfs. Dolphin's guide explains how to dump your disc. A Wii disc plays as the GameCube version, which the decompilation matches. Any of these get it onto the headset:

• AirDrop it to your Vision Pro and choose Twilight Princess VR to open it with.
• From Files: put it anywhere Files can reach, then tap Import Disc in the app.
• By hand: copy it into the app's own folder in Files (On My Apple Vision Pro › Twilight Princess VR).

The app uses the newest disc image in its folder. Then tap Play.

Play

Before you press Play, the launcher asks how you'd like to play: Full, Progressive or Window, plus Show my room around menus (Full only), with Foveated rendering under Advanced. Its Controls tab shows every button and gesture for what you're holding, Ports browses the AVP Ports Index, and About has the credits, licences and an update check. In Full or Progressive, press the Digital Crown to pause: the game holds where you are, and the launcher offers Resume or Quit (if it doesn't appear, open the app from Home). In Window, close the window to quit. The game autosaves when you enter a new area or open a dungeon door (Settings › Gameplay › Autosave, on by default), so quitting loses only what you've done since then.

Sense controllers play TPVR's layout: the sword follows your sword hand (right by default; VR › Combat › Sword Hand) and the shield your other hand.

Bare hands play in Full and Progressive:

Gesture	Acts as
Index pinch (either hand)	trigger
Thumb + middle	A (right hand), X (left hand)
Thumb + ring	B (right hand), Y (left hand)
Left thumb + little	menu
Fist	grip
Left thumb + middle, held and moved	walk (a quick tap is still X)
Right thumb + little, held and moved sideways	turn

The Window view plays like the original game, so it takes a gamepad (whenever one is on, it plays), or both Sense controllers held as one: right half Cross A, Circle B, R2 R (shield), R1 Z (Midna), Options Start; left half Square X, Triangle Y, L2 L (targeting), and the D-pad on L1 (up, item ring), Create (left, map), L3 (down, item ring) and R3 (right, map). Look at the game window to give it your controller, since visionOS hands a controller to whichever window you're looking at. Close the window to quit. The round button just above the window's top-right corner shows Hyrule in 3D or, as the original, flat in 2D (on a gamepad, L1 and R3 together); the choice is kept.

The game's settings (Dusklight's menu) open with a gamepad's View / Create button. With Sense controllers in Full and Progressive, hold Create and R2 together for a second; with bare hands, hold a left little-finger pinch and a right index pinch together for a second; in the Window view, press R2 and Options together. The port's own options live there: VR › Vision Pro › Anti-Aliasing and VR › Performance › VR Render Resolution.

If something goes sideways

• CMake can't find Xcode. Xcode must be at /Applications/Xcode.app, not a path with a space.
• Signing fails on the memory entitlement. Keep the team suffix on the bundle ID (the default, dev.tpvr.vision.YOURTEAMID): a bare ID may already belong to another team.
• The install hangs. Wake and unlock the headset, then run the build command again.
• The app won't open after a week. Apps signed with a free account expire after 7 days. Build and install again; your disc and saves stay put.
• The Window view ignores your controller. Look at it. See above.
• Anything else. The app's log lines start with [TPVR]. Run it from Xcode and the console tells you what happened.

How it works

The game is Dusklight (Twilight Princess on PC, built on the zeldaret decompilation) with JoeyAW's TPVR VR mod, compiled for visionOS as a framework that a SwiftUI app runs on its own thread. TPVR's OpenXR layer talks to a visionOS OpenXR provider (from WiiCompiled Vision) built on CompositorServices and ARKit, and the game renders with Metal straight into the compositor's images in a full, mixed or progressive immersive space. The Window view is the odd one out: visionOS gives apps no head tracking there, so the GameCube graphics stream is decoded as the game draws, each draw's material reduced to what RealityKit can render, and the scene rebuilt every frame behind a portal, where RealityKit renders it from your real eyes.

Design notes, decisions and measurements: visionos/README.md and visionos/PORT_PLAN.md.

What's in this repository

Only what the Apple Vision Pro build uses, so it's quick to review:

Path	What
visionos/	The visionOS app (SwiftUI, RealityKit window, launcher), its build scripts, patches to the two graphics submodules, the vendored OpenXR provider, design notes
src/, include/, libs/	The game: Dusklight's decompiled Twilight Princess code and its PC layer, with TPVR's VR layer in src/dusk/vr/ and the visionOS bridge in src/dusk/visionos/
extern/	Submodules: Aurora (graphics) and Borealis (platform layer)
res/	Fonts and UI files bundled into the app
cmake/, CMakeLists.txt, files.cmake, sdk/include/, assets/GZ2E01/	Build configuration and the generated headers the build includes
docs/images/	The screenshots and logo on this page

Other platforms (Windows PC VR, Android, iOS, macOS), code mods and the decompilation's matching tools aren't here; they live upstream in Dusklight and TPVR.

How it was built

Built by Trevorbilt with Claude Code as an AI pair programmer; every commit is co-authored. Each change was measured (frame times, GPU cost), checked in the visionOS Simulator, where window frames were rendered offline and compared with the game's own picture, and tested on Apple Vision Pro at each milestone, with an independent review agent checking the larger builds before they reached the headset.

Support

Twilight Princess VR is made and maintained by Trevorbilt. If it made your day, come see what else is on the workbench.

Credits

The Vision Pro port is Trevorbilt's: the visionOS app and launcher, the immersive spaces and the room around the menus, the Window view's scene mirror, the input, and the build, tested on a real Vision Pro.

It stands on years of other people's work:

• Nintendo made The Legend of Zelda: Twilight Princess, released in 2006 for GameCube and Wii.
• zeldaret decompiled it, with the wider GameCube and Wii decompilation community.
• The Twilit Realm team built Dusklight, Twilight Princess on PC, with its contributors. Dusklight's official website is twilitrealm.dev.
• JoeyAW made it VR with TPVR: the first-person play, the physical sword, shield and bow. This port builds directly on that work. Support JoeyAW: Patreon · Discord.
• encounter wrote Aurora, the GameCube and Wii graphics layer, and iChris4's WiiCompiled Vision is the source of the visionOS OpenXR provider.
• TPVR also thanks Automata and the TP speedrunning community.

For PC VR on Windows, use JoeyAW's TPVR itself.

License

This repository is CC0-1.0 (LICENSE.md): Dusklight, the decompilation, TPVR and Trevorbilt's own code for the Vision Pro port (the app in visionos/, src/dusk/visionos/ and the port's other changes) are dedicated to the public domain. The exceptions are GPL-3.0-or-later:

• the vendored OpenXR provider, Trevorbilt's changes to it included (visionos/openxr-provider/);
• five files adapted from WiiCompiled Vision, each marked at its top: visionos/scripts/build-dawn-visionos.sh, src/dusk/visionos/visionos_host.h, src/dusk/visionos/visionos_host.mm, visionos/App/Sources/GameModel.swift and visionos/App/Sources/ImmersiveGame.swift.

The app links the provider, so the built app is GPL-3.0. None of that covers:

• the game, its characters and its art, including what shows in the screenshots in docs/images/, which belong to Nintendo (and the game files, which are yours to bring);
• the Trevorbilt name and logo;
• the fonts in res/: Alegreya SC, Fira Sans, Inter and Noto Mono are under the SIL Open Font License 1.1 and Material Symbols under Apache-2.0, with their licences in res/licenses/, which the app carries too;
• TrevorbiltKit, the launcher every Trevorbilt port shares, vendored in visionos/TrevorbiltKit: its code is MIT (its licence), its fonts (Space Mono and Roboto) are under the SIL Open Font License 1.1, and its brand assets (the badge, other apps' icons) aren't licensed (its notice);
• SMAA in the provider, which is MIT (its licence);
• the submodules and the libraries the build downloads, which keep their own licenses.

_{Made with an unreasonable number of rupees by Trevorbilt.}