iChris4/MetroidPrimePortVR v2.0.0-alpha.1

PrimedGun v2.0.0-alpha.1

on GitHub

PrimedGun v2 is Metroid Prime in VR, running natively with no emulator. PrimedGun v1 ran the game inside Dolphin. v2 builds the game from the PrimeDecomp decompilation, through Odran's Metroid Prime native port, and adds PrimedGun's @Nobbie248 VR controls and features on top. It runs on PC VR (Windows, OpenXR) and as a standalone app on Meta Quest. This is an early alpha, published as a pre-release. Expect bugs and missing features, and read the known issues before you start. You need your own Metroid Prime disc image (USA, v1.00). No game data is included.

Downloads

PrimedGun.exe, the game and the Quest app all report revision b39d9de6dfed (shown on the launcher's About tab).

What you need

Your game disc

• Your own Metroid Prime for GameCube, USA, v1.00: game ID GM8E01, revision 0. This is the "NTSC Revision 0 (1.0)" disc that PrimedGun v1 needed.
• Formats: ISO, GCM, NKit ISO, RVZ, CISO, WBFS. GCZ is not supported.
• Other revisions (for example v1.02), PAL and Japanese discs are rejected with a message.

PC

• Windows 10 or 11, 64-bit, with a Direct3D 12 graphics card. The VR path is Direct3D 12 only.
• The latest Microsoft Visual C++ Redistributable (x64): https://aka.ms/vc14/vc_redist.x64.exe. It is not in the zip. Install it even if you already have an older copy: this build needs a recent one.
• An OpenXR runtime, set as the active runtime. It must support Direct3D 12.
  • SteamVR: tested with PSVR2 at 90 Hz.
  • Virtual Desktop (VDXR): tested with a Quest 3 streaming from the PC.
  • Meta Horizon Link (Link cable or Air Link): untested. PrimedGun v1 recommended SteamVR or Virtual Desktop over Meta's runtime.
• With no OpenXR runtime, the game opens flat on the desktop.
• About 85 MB of disk space, plus shader caches and saves.

Quest

• Tested on Quest 3. Quest 2, Quest 3S and Quest Pro can install it but are untested. Quest 2 performance is unknown.
• Developer mode, to sideload the APK with SideQuest or adb. SideQuest's guide explains how to turn it on: https://sidequestvr.com/setup-howto
• Controllers. Hand tracking is not used.
• Space for the disc copy: about 1.3 GB (NKit ISO) to 1.5 GB (full ISO). The image you pick also needs space until you delete it.

Install and play on PC

1. Extract the whole zip into a normal folder you can write to, such as C:\Games. Do not run it from inside the zip. Do not use Program Files or a folder that OneDrive syncs (Documents and Desktop often are). The zip holds one folder, PrimedGun-v2.0.0-alpha.1-Windows-x64. Windows' Extract All may put it inside a second folder with the same name, which is fine.
2. Install the Visual C++ Redistributable from the link above.
3. Set your OpenXR runtime as active, and start it.
   • SteamVR: Settings > OpenXR > Set SteamVR as OpenXR Runtime (older SteamVR versions: Settings > Developer).
   • Virtual Desktop: VDXR becomes the runtime while you stream. If SteamVR starts instead, set Virtual Desktop's "Preferred OpenXR runtime" option to VDXR.
   • Meta Horizon Link app (formerly Meta Quest Link): Settings > General > OpenXR Runtime > Set Meta Horizon Link as active.
4. Run PrimedGun.exe. The programs are not signed. If Windows shows "Windows protected your PC", click More info, then Run anyway.
5. On the Setup tab, click Select Game... and pick your disc image. A wrong disc shows "Wrong game", "Wrong revision" or "Format not supported".
6. Optional, coming from PrimedGun v1: click Transfer PrimedGun Memory Card / Settings.
   • Transfer searches for an old PrimedGun folder near this install. Choose Folder... lets you pick it. If none is found, it offers Dolphin's own memory card.
   • Your Metroid Prime saves go into user\USA\Card A. Your old PrimedGun.ini settings load as unsaved changes: click Save Settings to keep them.
   • Save states do not carry over from Dolphin. Save in the game with v1 before you transfer.
7. Optional: adjust the Controller, Calibration, Cannon Textures and Port Config tabs, then click Save Settings. Play also saves.
8. Click Play and put on your headset. Click the right stick to set your height. Click the left stick to open the VR menu.
9. To quit, click EXIT GAME twice in the VR menu, close the game window, or click Stop in the launcher. The game saves its settings and shader caches as it exits.

The launcher locks its settings while the game runs. For live changes, use the VR menu, or press F1 on the game's desktop window.

Install and play on Quest

1. Turn on developer mode for your headset. Install PrimedGun-v2.0.0-alpha.1-Quest.apk with SideQuest, or run adb install PrimedGun-v2.0.0-alpha.1-Quest.apk. The app has its own package (org.primedgun.v2), so it installs next to the Dolphin-based PrimedGun app and does not replace it.
2. Connect the headset to your PC with a USB cable, put it on and allow access to data when it asks. Then copy your disc image to it, for example into Download.
3. Open PrimedGun v2 from your Library, under Unknown Sources. It opens on the launcher panel, with the same tabs as on PC.
4. On the Setup tab, tap Select Game... and pick your image. The app checks it and copies it into its own folder as disc.iso. When it says "... is ready. Press Play.", you can delete the original.
   • Select Game has not been confirmed on a headset yet. If it fails, open the app once so its folder exists, then copy your image to /sdcard/Android/data/org.primedgun.v2/files/ yourself and name it disc.iso, whatever its format (the game reads the format from the file itself). From a PC over USB that is Android\data\org.primedgun.v2\files. You can also run adb push <your image> /sdcard/Android/data/org.primedgun.v2/files/disc.iso.
5. Optional, coming from PrimedGun v1: first use Export User Data in v1 to save a zip into Download (the file picker cannot open the v1 app's own folder), or copy your v1 memory card into Download from a PC. Then tap Transfer PrimedGun Memory Card / Settings and pick the zip, the memory card (.raw, .gcp or .gci) or your PrimedGun.ini. The game imports the card the next time you press Play, and shows a report. Imported settings appear as unsaved changes: tap Save Settings to keep them (Play also saves). Save states are not transferred.
6. Tap Play. The game opens in VR, and the panel locks until it closes. Click the right stick to set your height, and the left stick for the VR menu.
7. To quit, click EXIT GAME twice in the VR menu, press the Meta button and choose Quit, or tap Stop on the panel. The game saves its settings as it exits.

About the signing key. This alpha is signed with a development key. If a later release switches to a permanent key, you will have to uninstall this version before you install it. Uninstalling deletes /sdcard/Android/data/org.primedgun.v2/files: your memory card (USA/Card A), settings (port_settings.ini), save states and disc copy. Copy that folder to your PC before you uninstall. If the install fails with INSTALL_FAILED_UPDATE_INCOMPATIBLE, you have a build signed with another key: back up the folder, uninstall that build, then install this one.

Controls

Default scheme: PrimedGun, right-handed. The launcher's Layout tab and the VR menu's LAYOUT tab show the same bindings. Buttons use Quest Touch names: on other controllers, A and X are the lower face buttons and B and Y the upper ones (PSVR2: Cross / Square and Circle / Triangle).

• Menus, pause, map, logbook, message boxes, cutscenes and morph ball switch to a plain GameCube layout. Left stick = Control Stick, right stick = C-Stick, right A = A, right B = B, left X = X, left Y = Start, left trigger = L, right trigger = R, left grip = Z, right grip = Y.
• Visor gesture: hold your left controller next to your head and push its stick: up = Combat, right = X-ray, down = Thermal, left = Scan. While your hand is there, that stick does not move you.
• Beam wheel: hold right B and point the cannon up = Power, right = Wave, down = Ice, left = Plasma, starting from where it pointed when you pressed B. The chosen beam's box lights up on the HUD. Release B to switch.
• Set height: re-centres your position on your head (not your facing). It is ignored while your left hand is at your head.
• Snap turn: off by default. Turn it on in the launcher's Controller tab or the VR menu's MOVEMENT tab. Flick the right stick to turn by 45° (30, 60 or 90 also available). Let the stick return to the centre before the next flick. With snap turn on, the right stick does not turn smoothly.
• VR menu: point with the right controller's laser. Right trigger or A clicks. On a number, click the left half of its box to lower it and the right half to raise it. Resets, EXIT GAME and save-state actions need a second click. Changes apply at once, except rows marked NEXT START. SAVE SETTINGS writes them to disk now. The game keeps running behind the menu.
• Options: "Longer held press for VR menu" (hold for 1 s) and "VR menu requires controller near head to activate". "Use A button for jump" moves jump to right A (see known issues).
• Left-handed ("Left hand" in the Controller tab): shoot = left trigger, lock on = right trigger, missile = left grip, map = right grip, beam wheel = left Y, morph ball = right A, pause = right B. The visor gesture uses the right hand and right stick. The VR menu moves to the right stick click. Movement stays on the left stick. The movement stick setting (Left stick / Right stick) swaps the sticks.
• Other schemes (Port Config): Gamepad makes the controllers act as a gamepad that you bind in the port's Controls page (click both sticks for the VR menu). None ignores the controllers, so you can play with a real gamepad or keyboard (left Y opens the VR menu).
• PC desktop window: F1 opens the port's overlay, with a VR tab for live settings. F5 / F9 save / load a state.

What's in v2

Native game, true stereo

• The game runs natively, drawn by Aurora (SDL3 + WebGPU/Dawn).
• Each eye gets its own view, with the lighting fixed to the world. On Quest, one multiview pass draws both eyes.
• It runs at the headset's refresh rate. The game logic stays at 60 Hz, and frames in between are interpolated. A steady 90 Hz was measured on PSVR2.
• 6DOF head tracking. The sticks turn your body. There is no camera bob or idle sway.
• The audio follows your head.

Arm cannon and HUD

• 6DOF arm cannon with PrimedGun's calibration: position, rotation, and the Default arm and Samus arm presets.
• The cannon's idle fidget is removed.
• v1's cannon texture slots are back: Default, Slot 1-4, Custom (.png or .dds), Remove Shine and Restore Shine.
• The HUD and minimap stay in front of your head. Size (default 0.75) and distance (0.10) are adjustable.
• Menus, pause, map, logbook, save screens and cutscenes appear on a virtual screen where you look. By default it is 1.5 m away and 2.0 m wide.
• The morph ball HUD, region title cards and hint messages are also on the virtual screen.

Targeting and visors

• Look to scan: in the scan visor, your gaze picks the scan target.
• Look to lock-on and look to grapple: your gaze picks the lock-on target and grapple points. Both are on by default. The switches are in the VR menu's CONFIG tab and the F1 VR tab.
• The thermal and X-ray visors render correctly in each eye.
• The scan window is built per eye and shows the view 1:1. "Scan window zoom" brings back the TV's magnification.
• Scan icons and the lock-on, scan and grapple reticles face your head and stay upright.

Visual fixes for VR

• No cinematic bars: morph ball and visor transitions no longer shrink the view.
• Sky at infinity: planets and stars look far away.
• The charge-shot space warp is drawn in the world at half strength. You can turn it off.
• Refracting particles sample the right spot in each eye.

Controls and comfort

• PrimedGun control scheme, with an automatic GameCube layout in menus and cutscenes.
• The visor gesture, the beam wheel with HUD highlight (in place of v1's floating icon panel), snap turn and one-click height set.
• Rumble on the controllers: right hand by default, with target and intensity settings.
• Left-handed mode and a stick swap.
• Lean back from -45° to 45°, for seated or lying play.
• World scale (default 1.5) and render scale (1.0 on PC, 0.85 on Quest).
• Refresh rate setting (72, 80, 90 or 120 Hz) on runtimes that support it: Quest and Virtual Desktop. It is in the VR menu's CONFIG tab, the F1 VR tab and the Quest launcher's Port Config. The PC launcher does not show it.
• On PC, Mirror view picks what the desktop window shows (default: left eye).

Launchers and menus

• PrimedGun.exe: v1's launcher, ported, with the tabs Setup, Controller, Calibration, Cannon Textures, Layout, Port Config and About.
• Memory card and settings transfer from v1, on PC and Quest.
• v1's blue in-headset VR menu, with the tabs LAYOUT, CONFIG, CALIBRATION, CONTROL, MOVEMENT, TEXTURES, STATES and DEBUG, and the game's FPS.
• Save states in the headset: 8 slots in the STATES tab.

Quest standalone

• A standalone app, with v1's Quest launcher as a 2D panel.
• Quest 3 holds 90 Hz at the Chozo Ruins plaza at render scale 1.00.
• Passthrough shows your room around the virtual screen, never during play.
• Fixed foveated rendering option: Low, Medium or High. Off by default.
• No "pick up your controllers" check at launch.

From the Metroid Prime native port

• Spring Ball is on by default: right stick up in morph ball, once you have the bombs. The helmet is hidden by default.
• Skippable cutscenes, off by default. Turn them on in F1 > Game > Cutscenes on the PC desktop window; the Quest launcher and the VR menu have no switch for them. They are always on in randomizer and Archipelago games. Left Y (Start) or right A skips a cutscene.
• Mods folder, user and HD texture packs, memory card import and export.
• Randomizer and Archipelago, set up in the F1 overlay on the PC desktop window. The Quest build has nowhere to set them up: neither its launcher nor the VR menu has settings for them.

Not in this alpha yet (compared with v1)

• Full directional movement, v1's headline feature: left stick strafing, movement relative to the controller or the headset, deadzone, speed and acceleration. The launchers show those settings tagged "not active yet". The VR menu's MOVEMENT tab shows them without a tag. Either way they are saved but do nothing. The stick swap does work.
• The height reminder prompt. The one-click height set works.
• The visor helmet option, which brought the helmet back from the pause menu.
• The floor position marker.
• HUD up / down / left / right offsets. HUD size and distance work.
• Linux, SteamOS and macOS. PC VR is Windows only for now.
• v1's MultiworldGG setup. It used the Dolphin Memory Engine, and v2 has no Dolphin. Use the built-in Archipelago client instead (F1 > Archipelago, PC).

Your saves, updating and uninstalling

• PC: saves live in the user folder next to the game: memory card in user\USA\Card A, plus settings, save states, logs and shader caches. To update, copy user into the new version's folder, or copy the new version's files over the old folder: the zip has no user folder, so your saves are not overwritten. To uninstall, delete the folder; copy user somewhere first if you want to keep your saves. The game keeps its data in that folder, except in the two %APPDATA%\Metroid Prime cases below.
• Players of Odran's Metroid Prime Port: if %APPDATA%\Metroid Prime\port_settings.ini exists and user\ has no port_settings.ini (as in a fresh install), v2 uses that folder for settings, save states, mods, logs and caches, and shares it with the native port. The memory card still goes to user\USA\Card A. The About tab shows which user folder is in use. To keep v2 separate, copy port_settings.ini from that folder into user\ next to the game.
• Read-only install folder (such as Program Files): everything moves to %APPDATA%\Metroid Prime, memory card included.
• Quest: everything is in /sdcard/Android/data/org.primedgun.v2/files: memory card (USA/Card A), settings (port_settings.ini), save states, logs and the disc copy. A later APK signed with the same key installs over this one and keeps it all. Uninstalling deletes it, so back up USA/Card A and port_settings.ini first (see "About the signing key" above).

Known issues

• Movement: left stick left / right turns instead of strafing. With snap turn on, the left stick still turns smoothly.
• Not room-scale: stay near the centre of your play space and face forward.
• Left-handed mode: the VR menu takes the right stick click, so set height has no button. Use your headset's own recenter instead, or open and close the pause menu or the map: going back into play from the virtual screen re-centers your position the same way. (Found in the code, not yet tested in a headset.)
• Paused message boxes: the GameCube layout (A to continue) has not been tried on a real in-game message yet.
• Settings tagged "not active yet" in the launchers are saved but do nothing yet. The VR menu shows the same settings without a tag: LEFT STICK STRAFE, MOVEMENT DIRECTION, MOVEMENT DEADZONE, MOVEMENT SPEED, MOVEMENT ACCELERATION and AIR ACCELERATION (MOVEMENT tab), HUD VERTICAL, HUD HORIZONTAL, VISOR HELMET and HEIGHT PROMPT (CALIBRATION, page 1), and FLOOR POSITION MARKER (CALIBRATION, page 2). Look yaw sensitivity has no effect above 1.0.
• Archipelago: ws:// servers only. wss:// servers fail on PC and Quest, because neither build includes TLS (OpenSSL). Not yet tested in VR.
• Metroid Prime Remastered import (a feature of the native port) does not work in this build. Reading the Switch .nsp needs OpenSSL. The movie import also needs ffmpeg.exe next to metroid_prime_port.exe or on your PATH, and none is included. Remastered models and materials that are already imported do load, but their lighting is not correct per eye.
• First start: the game compiles shaders in the background, so expect some stutter at first. Later starts are faster. Quit with EXIT GAME, Stop or the window's close button, so the caches are saved.
• Quest settings: "Pipelined rendering" does nothing on Quest. Foveated rendering costs GPU time on Quest 3 instead of saving it. Going from Off to a level needs a restart.
• Windows security: the programs are unsigned. If Windows 11 Smart App Control is on, it can block them, and it has no per-app exception.

Reporting bugs

Open an issue at https://github.com/iChris4/MetroidPrimePortVR/issues. Please include:

• The version and revision from the About tab: 2.0.0-alpha.1, revision b39d9de6dfed.
• PC or Quest, your headset and runtime (SteamVR, Virtual Desktop, Link), and on PC your graphics card.
• What you did, what you expected, and what happened.
• PC files. They are in the user folder, normally user next to the game. Port Config > Open User Folder opens it, and so does Setup > Game Options... > Open User Folder once a game is selected. The About tab shows its path. Attach:
  • metroid_prime_port.log
  • metroid_prime_port.old.log (the run before, if you restarted the game since)
  • primedgun_last_run.log
  • metroid_prime_port.dmp, if the game crashed. It is in the user folder too: Port Config's Open Crash Dumps button opens the wrong folder.
  • Put them in a .zip, because GitHub does not accept .dmp files directly. You do not need to send the symbols zip.
• Quest files. Copy metroid_prime_port.log (and last_error.txt if it is there) from Android\data\org.primedgun.v2\files over USB. Setup > Game Options... > Last Run Log shows the log in the panel.

Checksums

SHA-256 of each file, also in SHA256SUMS.txt. To check a file, run Get-FileHash <file> -Algorithm SHA256 in PowerShell and compare; upper or lower case does not matter.

fe6ed5cf282374c958b8487a5808c602ed1b19d13057fa86a98b0ddc540b67de  PrimedGun-v2.0.0-alpha.1-Windows-x64.zip
0d704e8714bfce7ea926e1b504916c28097671e2220c4c87f8e66b88dd50cba0  PrimedGun-v2.0.0-alpha.1-Quest.apk
8d19628d54aecc6b35ee2ced8ae557f180884093a6ee07cc5d6b64b19f833aed  PrimedGun-v2.0.0-alpha.1-Windows-x64-symbols.zip
528bf1685910d53488e7323d0dfdb97301d6f5ebebccf21d93e1df770b7998ca  PrimedGun-v2.0.0-alpha.1-licenses.zip

Credits

• PrimedGun by @Nobbie248 and DolphinVR Redux by @iChris4.
  • v2 ports PrimedGun v1's code to the native game: the controls, VR menu, launcher, look to scan and beam wheel.
  • The v2 native VR port is by @iChris4. Its OpenXR stereo and head tracking come from @iChris4's Wiicompiled VR work.
• Odran, for the Metroid Prime native port that v2 is a fork of: https://github.com/Odrannnn/MetroidPrimePort
• The PrimeDecomp team, for the Metroid Prime decompilation: https://github.com/PrimeDecomp/prime
• Aurora, by Luke Street (encounter) and contributors, which draws the game.
• The Dolphin team. PrimedGun v1 was built on Dolphin, and parts of the launcher come from it.
• Kenney, for the Input Prompts icons (CC0).
• The randomprime contributors, Electro1512 and lil David, for the data behind the randomizer, Archipelago and skippable cutscenes (see the port's NOTICE: https://github.com/iChris4/MetroidPrimePortVR/blob/v2.0.0-alpha.1/NOTICE).
• v1's thanks still apply: the Metroid Prime modding community, Metaforce and PrimeHack, v1's early testers, and budwheizzah for Quest testing. The full list is in the launcher's About tab.

Licences

• PrimedGun v2's VR code and the PrimedGun launcher: GPL-3.0-or-later. Parts come from PrimedGun v1 (GPL-2.0-or-later) and Wiicompiled VR (GPL-3.0).
• The Metroid Prime native port's own code: MIT. It does not cover the decompiled game code; see NOTICE: https://github.com/iChris4/MetroidPrimePortVR/blob/v2.0.0-alpha.1/NOTICE
• The PC launcher uses Qt 6.5.1 under the LGPL-3.0. The Qt DLLs are separate files that you can replace. Qt source: https://download.qt.io/archive/qt/6.5/6.5.1/
• Every other component keeps its own licence (MIT, BSD, Apache-2.0, zlib and others). This includes Dawn, SDL3, nod, the OpenXR loader, MusyX and Dear ImGui.
• Portions of this software are copyright © 2026 The FreeType Project (www.freetype.org). All rights reserved. (FreeType 2.14.3 in the game. Qt's FreeType 2.13.0 in the PC launcher: portions copyright © 2023 The FreeType Project, www.freetype.org.)
• The licence texts are in the licenses folder, in the PC zip and on its own as PrimedGun-v2.0.0-alpha.1-licenses.zip. That folder also covers the Quest APK, whose built-in licence list is incomplete in this alpha.
• Source code: the v2.0.0-alpha.1 tag, https://github.com/iChris4/MetroidPrimePortVR/tree/v2.0.0-alpha.1, and the "Source code" archives on this page.

Metroid Prime is a trademark of Nintendo. PrimedGun is not affiliated with Nintendo or Retro Studios. No game data is included: you need your own disc image.