Fix a game that starts flat or looks wrong in PortXR

One section per problem: the game starts flat, is not listed, ignores the controllers, has something in the view or a black UI panel.

By EncidXVII. Checked with PortXR 0.5.0. Updated .

Most problems with PortXR come from a few causes: the VR runtime was not running when the game started, the controllers reach the game in a form it does not read, or something in the game gets in the way of the view. Each section below is one symptom, with its cause and the fix. If none of them fits, export the logs and report it (see the end of this page).

The game starts flat

Cause: the game started before the VR runtime, or PortXR found no runtime to use.

Fix:

  1. Start your headset’s runtime first (SteamVR, Virtual Desktop, Quest Link, WiVRn or Monado) and put the headset on.
  2. Press Play in VR on the game’s page. The page names the runtime PortXR will use, warns when none is set up, and says when the game is in VR or what to check if it is not.
  3. On Linux, check the game’s Steam launch options (below). Without them Proton does not load PortXR.

If the runtime restarts or drops while you play, the game carries on flat and VR comes back by itself once the runtime is up again.

The game is not in the list

Cause: PortXR looks for games on Steam, Epic and GOG. A game from somewhere else, or in a folder it does not know, is not found.

Fix: press Add game and pick the game’s folder.

If it is still missing:

  • It may be unsupported. The All tab leaves out games PortXR cannot run. Open the Unsupported tab to see the game and the reason. The supported games guide explains each reason.
  • It may use another engine. The library lists only Unity, Unreal Engine and Godot games.
  • On Linux, older Unreal and Godot 3 games are not listed, and a game with its own Linux build is marked Linux build. Force Proton for it in Steam (Properties, Compatibility), let Steam download the Windows version, and it is ready.

The controllers do nothing, or the game wants a gamepad

Cause: the controllers reach the game as a keyboard and mouse or as an Xbox pad, and the game reads only one of those. Auto, the default, presents an Xbox pad in games that ship a gamepad input library and a keyboard and mouse everywhere else. Some games read neither the way PortXR expects.

Fix: open the VR menu (double-tap the left menu button, or press F11) and set Controls in the Quick tab.

  • Gamepad suits games on Unity’s Input System package and games that read XInput.
  • Keyboard and mouse suits Unity 2021 and newer games on the old input manager. They read controllers through Windows.Gaming.Input, which Gamepad mode does not reach.
  • Off leaves the game to your own keyboard, mouse or gamepad. The controllers then only work the VR menu and the laser pointer. Check that Controls is not set to Off by mistake.

In Unreal Engine and Godot games the controllers act as a gamepad inside the game. The laser pointer clicks in the game only where the game shows its cursor. To move a key to another button, use the VR menu’s Controls tab or Button layout on the game’s page.

Something blocks the view

Cause: the game puts a helmet, the player’s own body or another object in front of its camera.

Fix: in the VR menu, open the Game tab and choose Hide objects. Point at the object and pull the trigger. PortXR remembers it for that game, and Show hidden brings it back. This works in Unity and Godot games and in Unreal Engine 4.25 and newer games.

If the whole view comes from the wrong camera, pick another one in the Game camera list on the same tab. A fix that needs more than this can go in a per-game script.

The UI panel is solid black

Cause: the game paints its UI panel solid, usually with a full-screen effect on its UI camera, so the panel hides the world behind it.

Fix: in the VR menu, go to View, UI black.

  • Auto (the default) notices a solid panel, makes the black see-through and dim tints translucent.
  • See-through always makes the black see-through.
  • Keep leaves the panel as the game paints it.

This setting is for Unity games. The app hides it for Godot and Unreal Engine games, where it does not apply.

After a game update or Steam’s file check

Steam’s Verify integrity of game files leaves PortXR’s files in the game folder. To take them out, use Remove VR on the game’s page: it puts the folder back byte for byte from PortXR’s receipt.

A game update can replace or remove PortXR’s files. You do not need to do anything: every Play in VR checks the game first, brings PortXR’s files back up to date and adds VR again where it is missing. If the update added anti-cheat, PortXR takes itself out of the game and refuses it from then on.

Windows or antivirus warnings

Cause: PortXR’s builds are not code-signed yet.

  • Windows may say PortXR.exe comes from an unknown publisher. Choose More info, then Run anyway.
  • Some antivirus tools flag winhttp.dll inside game folders. It is the mod loader’s entry point in Unity games.

Every release has a SHA-256 checksum. Compare it with your download before you run anything.

Linux: the game ignores PortXR

Cause: Proton loads PortXR only with these in the game’s Steam launch options (Properties, General):

WINEDLLOVERRIDES="winhttp,dwmapi=n,b" PRESSURE_VESSEL_IMPORT_OPENXR_1_RUNTIMES=1 %command%

Fix: the game’s page in PortXR shows them with a Copy launch options button until Steam has saved them. Paste them in and start the game again. Games from other stores run outside Steam’s Proton: start them from their launcher with WINEDLLOVERRIDES="winhttp,dwmapi=n,b" set.

Linux support is experimental, so a report helps whatever happens.

Export logs and report

  1. Select the game in PortXR.exe and press Export logs. It saves one zip to your desktop.
  2. Open a game report on GitHub. Say what you saw, your headset and runtime (for example “Quest 3, Virtual Desktop”), and attach the zip.

A phone photo through the lens helps when something looks wrong. If the game works perfectly, say that too.

Edit this page on GitHub