Skip to content

PrimedGun v2.0.0-alpha.2

Pre-release
Pre-release

Choose a tag to compare

View all tags
@iChris4 iChris4 released this 08 Oct 23:37
· 991 commits to OpenXR since this release
v2.0.0-alpha.2
a957345

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 alpha.2, the second 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.

What's new in alpha.2

Movement and controls

  • Directional movement, v1's left stick strafe. The left stick walks and strafes toward where the left controller points. Only the right stick turns. Speed 14, acceleration 45, air acceleration 8 and deadzone 0.25, as in v1. You can change them in the launchers' Controller tab, the VR menu's MOVEMENT tab and the F1 VR tab.
  • "HMD direction" (MOVEMENT DIRECTION: HEADSET in the VR menu) makes the left stick follow your head instead of the controller.
  • While locked on, the left stick still strafes around the target. In a grapple swing, left / right on the left stick turns the swing.
  • To get alpha.1's left stick back, where left / right turns, turn off "Left stick strafe movement" (LEFT STICK STRAFE in the VR menu).
  • Lock-on turns the view again. When your gaze picks a lock-on target, Samus and the view now turn to it during the lock, as on the TV. In alpha.1 the view kept its facing, so a boss left the view as soon as you strafed around it. The new NO CAMERA TURN ON LOCK switch brings back alpha.1's behavior. It is off by default. Find it on the VR menu's CONFIG tab, after LOOK TO GRAPPLE, and in the F1 VR tab. The launchers do not show it.

Fixes

  • Quest: the game no longer closes in Magmoor Caverns. Rooms with fog kept hundreds of per-eye image copies in memory. After a while the sound crackled, the image froze, and the headset closed the game. Memory now stays flat in those rooms. The fix is in the shared renderer, so the PC build has it too.
  • PC: the VR controllers keep working when the game's desktop window loses focus, for example after a click on another window, Alt+Tab, or a SteamVR or Virtual Desktop window. A gamepad keeps working too. The keyboard still needs the window in focus.

Launcher

  • The PC launcher no longer locks its settings while the game runs. Your changes apply in the game at once, and settings the game saves (from the VR menu or F1) show in the launcher. Enable VR waits for the next start. Select Game and Transfer wait until the game closes. A cannon texture applied while the game runs shows at once.
  • The Quest panel still locks its settings while the game runs. Use the VR menu for live changes there.
  • The movement settings no longer show "not active yet" in either launcher.

From the Metroid Prime native port

  • Built-in randomizer: F1 > Randomizer makes logic-checked seeds and plays them, with no Archipelago install. The options include the starting room and beam, elevators, doors, blast shields and locked doors. Each seed has its own save card. It is on the PC desktop window only, and not yet tried in VR.
  • Original Experience: one switch that plays the game as on the GameCube (for example no Spring Ball and no skippable cutscenes) and keeps your settings for when you turn it off. It is in the pause menu's Options > Display and at the top of F1 > Game. In the headset, the helmet and the frame interpolation keep their own settings. Not yet tried in VR.
  • Turbo fire: hold a bound key or gamepad button to fire as fast as the beam allows. Bind it in F1 > Controls ("Turbo fire (hold)", unbound by default). The PrimedGun controller scheme has no button for it.
  • Music fixes: the boss music of the Parasite Queen, the Hive Mecha and the Plated Beetle could fail to start. After Thardus, with its death cutscene skipped, the boss music no longer keeps playing instead of the room music.
  • Shader compilation counter: "Compiling shaders" with a count and a bar shows at the top of the PC desktop window while shaders compile. It does not show in the headset. F1 > Video > Quality > "Show shader compilation" turns it off.
  • Remastered rendering work (materials, room lights, HUD). It needs imported Remastered data, and the import still does not work in this build (see known issues).

Updating from alpha.1

  • PC: extract the new zip into a new folder, then copy the user folder from your alpha.1 folder into it. Or copy the new folder's files over your alpha.1 folder: the zip has no user folder, so your saves and settings stay. With a read-only install folder, everything is already in %APPDATA%\Metroid Prime. If you also play Odran's port, your settings and save states are there too, but the memory card is still in user\USA\Card A, so copy user anyway.
  • Quest: install the new APK over alpha.1, with SideQuest or adb install -r PrimedGun-v2.0.0-alpha.2-Quest.apk. Do not uninstall alpha.1 first. alpha.2 is signed with the same key and has a higher version number, so it replaces alpha.1 and keeps your memory card, settings, save states and disc copy.
  • Shaders: alpha.2 clears alpha.1's shader cache once, at its first start, so expect shader stutter again for a while. On PC, if you go back to alpha.1 with the same user folder, delete pipeline_cache.db from it (the About tab shows which folder) before you start alpha.1, and again before you start alpha.2.
  • Movement settings that alpha.1 saved but did not use (for example from a v1 transfer) now take effect.

Downloads

File What it is Who needs it
PrimedGun-v2.0.0-alpha.2-Windows-x64.zip PC build: the PrimedGun.exe launcher and the game PC VR players. This includes Quest players who stream from a PC with Virtual Desktop or Link.
PrimedGun-v2.0.0-alpha.2-Quest.apk Standalone Quest app, for sideloading Quest players who play without a PC
PrimedGun-v2.0.0-alpha.2-Windows-x64-symbols.zip Debug symbols (.pdb) for the two PC programs Nobody, to play. They let anyone read the PC crash dumps of this exact build. With metroid_prime_port.pdb next to metroid_prime_port.exe, the crash report in the log also names functions and lines.
PrimedGun-v2.0.0-alpha.2-licenses.zip Licence texts: the PC zip's licenses folder, which also covers the Quest APK Anyone who wants the licence texts on their own, mainly Quest users
SHA256SUMS.txt SHA-256 checksums of the files above Optional, to check your downloads

PrimedGun.exe, the game and the Quest app all report revision a957345b9a63 (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 92 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.2-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.

While the game runs, settings you change in the launcher apply in the game at once. The VR menu and F1 on the game's desktop window also change settings live. Enable VR waits for the next start, and Select Game and Transfer wait until the game closes.

Install and play on Quest

  1. Turn on developer mode for your headset. Install PrimedGun-v2.0.0-alpha.2-Quest.apk with SideQuest, or run adb install PrimedGun-v2.0.0-alpha.2-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).

Action Control
Walk and strafe Left stick, toward where the left controller points
Turn Right stick left / right
Strafe around a target Left stick left / right while locked on
Jump Right stick up
Shoot (hold to charge) Right trigger
Lock on / scan Left trigger. Your gaze picks the target.
Missile Right grip
Map Left grip
Morph ball Left X
Pause Left Y
Beam wheel Hold right B, point the cannon, release B
Visor select Left hand next to your head + left stick
Set height Click the right stick
VR menu Click the left stick (or press the left menu button)
  • 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-centers your position on your head (not your facing). It is ignored while your left hand is at your head.
  • Movement: the left stick walks and strafes toward where the left controller points, at v1's speed and acceleration. "HMD direction" in the Controller tab (MOVEMENT DIRECTION in the VR menu) uses your head's direction instead. While locked on, left / right strafes around the target. In a grapple swing, left / right turns the swing. With "Left stick strafe movement" off (LEFT STICK STRAFE in the VR menu), left / right turns, as in alpha.1.
  • 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 degrees (30, 60 or 90 also available). Let the stick return to the center 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.
  • 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. With the right stick, the right controller sets the direction.
  • 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.

Not in this alpha yet

  • 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

  • Not room-scale: stay near the center 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: HUD VERTICAL, HUD HORIZONTAL, VISOR HELMET and HEIGHT PROMPT (CALIBRATION, page 1), and FLOOR POSITION MARKER (CALIBRATION, page 2). Exception: Mirror view on the PC launcher's Port Config tab is tagged but works. 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.2, revision a957345b9a63.
  • 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.

6b733063625510af5445b82ba0748676daa3ff324de99ac547af8e712f06993d  PrimedGun-v2.0.0-alpha.2-Windows-x64.zip
fb4a28e879267acee35ceb9f29718e58d973216b33f129a5a08892f009ffaa9b  PrimedGun-v2.0.0-alpha.2-Quest.apk
24077a846440ff5a66eaab33dfb426486ae6341fcdddc262659c7ec336e56a3e  PrimedGun-v2.0.0-alpha.2-Windows-x64-symbols.zip
5619ef9a1936786a7866e94afe2899994021f62f361619cfe6124b280fd5626d  PrimedGun-v2.0.0-alpha.2-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.2/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.2/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 (c) 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 (c) 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.2-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.2 tag, https://github.com/iChris4/MetroidPrimePortVR/tree/v2.0.0-alpha.2, 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.

Contributors

iChris4 and Nobbie248
Assets 7
Loading