Virtual Reality

VR for Players

This section explains how to set up and play FreeSpace in VR.

Note: AMD users: We have had reports of AMD cards resulting in horrific performance due to their bad OpenGL driver. If you are able to achieve acceptable performance with an AMD card, please tell us your GPU model and driver version.

Basic Setup

FreeSpace uses OpenXR for its VR implementation. Make sure that you have installed and updated the required tools and drivers to use OpenXR-based games with your headset. In addition, especially if you have SteamVR installed, it is also often advisable to set the driver from your headset (i.e. the Oculus app for Quest users) as the "default OpenXR runtime" instead of SteamVR.

Note: Users of WMR headsets (Asus / HP / Lenovo / etc.): WMR is not compatible with OpenGL, which FSO is built on, so you must use SteamVR as the default OpenXR runtime.

Now, download and install a mod manager for FreeSpace. We recommend Knossos.NET (which I'll refer to as Knossos from here). When running it for the first time, it will ask you for installation files or a completed installation of retail FS2 (such as you can buy from GoG). While you can play Total Conversions of FreeSpace without this, you must own FS2 to play FS2-based mods including the VR mod.

FreeSpace 2 in VR

In order to play FreeSpace 2, including our modern graphics updates, in VR, go to the explore tab in Knossos. Search for the mod called "VR FS2 MVPS" (MVPS being short for MediaVPs, the name for the graphical updates), and install it. Knossos will automatically install all required dependencies, and once it's done, just click play.

Other mods in VR

If you want to play other mods than the retail campaign, things require a little more effort. For the mod you want to play in VR, go into the "FSO Settings". Make sure that you are running either FSO version 24.0 or the 20231206 nightly. Then, in the flag list, under the gameplay section, make sure the following settings are enabled:

• Run in window
• Capture the mouse within the window
• Stretch interface to fill screen
• Enable virtual reality mode

Under the Game Speed section:

• Disable vertical sync

And then add the following to the custom flags list: -window_res 1000x1000 -res 2500x2500 The 2500x2500 can be replaced by a resolution of your choice and your hardware capabilities. Now, remember to click save in the FSO settings panel before you close it!

Troubleshooting other mods in VR

Not all mods will run immediately perfectly in VR. There will be some issues, some more serious then others. This list is supposed to help with them, but not all steps may be accurate for all mods, and may need to be adapted. I am aware that some of these may be asking for some more intricate mod editing and may require some expertise, so if you run into trouble or questions, don't hesitate to head over to the HLP discord for help.

I want a cockpit / no floating HUD

Begin by copying all files from the root package of the vr_mvps mod to any package of the mod you want to play. Now, go into the tables folder and look for three files: cockpits_hud-shp.tbm, cockpits-shp.tbm and cockpits-hdg.tbm. For both -shp.tbm files, copy one section starting with a $Name:, and replace the name with the ship you want to add the cockpit to. Do this for all playable ships. In the -hdg.tbm file, look for all lines starting with $Ships:, and add all playable ships. If the mod is a total conversion, you will need to remove all FreeSpace ships from all three files. Be aware that this will mess up any custom HUD gauges the mod has set up. Integrating those will require intricate understanding of the Hud_gauges.tbl.

The mod doesn't show a mainhall

Mainhalls in FSO can be changed based on resolution and aspect ratio. Unfortunately, that means it's possible for there to be a aspect ratios and In the mod files, likely a package called root or so, look for the folder tables, and within, for a file called mainhall.tbl or any file ending on -hall.tbm Look for lines that either start with +Min Aspect Ratio: or +Min Resolution:. For both, look for the one with the smallest number. Now delete all lines starting with +Min Aspect Ratio: or +Min Resolution: respectively and that have this smallest number. If the mod still doesn't show you a working mainhall, repeat step until it does. Please report this issue to the author of the mod, it should be fixed in the mod itself.

I can't read any messages

You will notice that messages look like they are displayed twice on the screen, in a way that is unreadable with an HMD. The mod is most likely using AxMessage to display messages in a more immersive manner, unfortunately incompatible with VR. In the data folder of the root package of your mod, open the tables folder, or create it if it does not exist. Now, delete a file called axmsg-sct.tbm if it exists. Go into the same data/tables folder for the vr_mvps mod, and copy the axmsg-sct.tbm file from there to the tables folder of the mod you want to play.

VR for Modders

This section details how to make a mod compatible for VR and increase player satisfaction in VR play, and what steps are needed to ensure playability.

Must Fix

These steps are required to make VR-play possible at all.

Ensure Resolution Compatibility

Launch your mod in a Resolution of 1000x1000 and 3000x3000, and make sure that it is launch- and playable at that resolution (if your monitor can't handle that resolution, you can test it using -window_res 1000x1000). Two notable common points of failure are the mainhall (make sure that you have at least one mainhall that is not locked by aspect ratio or resolution for this) and the ingame HUD (since this is also chosen based on resolution and aspect ratio, and these resolutions are rather uncommon, an error in the HUD configuration can easily slip past here).

Should Fix

These steps are highly recommended, as not following them can lead to significant player dissatisfaction, but will not cause total unplayability of a mod.

Scripted Rendering

Rendering with scripts can easily lead to problems in VR, as the two eyes of a headset are no longer pixel-compatible. Every time you are rendering with a script, you must consider whether it'll break in VR. Consider in which of the five categories your rendering falls:

1. You are rendering to a hard-coded or table-loaded XY-position in 2D-space (examples: AxMessage, the VN script, the HUD escort list, etc).
2. You are rendering to a position exclusively calculated from 3D-coordinates and vector.getScreenCoords() (examples: RadarIcon script, target boxes, the lock-on indicator).
3. You are rendering to a texture (either for later use or the texture of a ship), and not to the screen directly.
4. You are rendering exclusively using the functions from HudGaugeDrawFunctions, and are not using any functions from gr to render on screen.
5. You are rendering not during gameplay. Your rendercalls are restricted to only happen in menu states or other non-gameplay states.

If you fall into groups 2, 3, 4, or 5, you don't need to worry. Those scripts will work just as well in VR, and will not cause visual glitches. However, if your script falls into group 1, as the vast majority of rendering scripts (including all Axem script except for Markboxes AFAIK) does, you will see anything rendered by your script as two blurry images, and not rendered properly in VR. To fix this, move your script into one of the other categories. If you have a cockpit, consider using one of its surfaces as a render target for your script to move it into category 3. Otherwise, you should convert the script into a scripted HUD gauge and move it into category 4.

Fixed-Camera Cutscenes

Keep any fixed-camera cutscenes on the down-low. These have three major issues for VR-play.

1. Setting a custom FoV does not work. In VR-mode, the camera's FoV is determined exclusively from what the HMD requests, so setting the FoV has no effect.
2. The player will still be able to look around, possibly (or rather probably) reducing whatever cinematic effect you had planned for
3. Sudden, non-player controlled movement will likely cause some level of nausea, depending on the movement and its intensity.

This is not to say that you cannot use any at all, especially since you will have predominantly non-VR players, but if your target audience is VR, remember that VR players will have much less enjoyment from this type of cutscene.

Correct use of On Frame hooks

In VR mode, any On Frame hook will run twice, once per eye. This means that doing any physics calculation in On Frame is discouraged, as these calculations will also run twice. Especially if you rely on the difference to the last frame, you will get incorrect results in VR mode. Consider moving physics calculation to On Simulation if possible instead.

Can Fix

These steps are entirely optional for playability, but will improve the quality of life for players

Few-Button Playability

Consider that finding buttons on a keyboard is hard if you cannot see it. It should be possible to fully play through your mod without letting go of one position on the keyboard. Alternatively, when players use HOTAS-setups or similar, the buttons available on the HOTAS should ideally suffice to complete the campaign.

Floating HUD in Cockpits

If your mod already features modelled cockpits, consider moving all HUD elements to be rendered onto RTT-surfaces of the cockpit (even if these surfaces are just invisible planes in the model). Some players get dizzy from the axis-aligned floating HUD that is rendered when RTT surfaces are not available. HUD elements like the reticle, lead indicator, or any other HUD element that takes its position from 3D-coordinates are fine to not render onto RTT.

Cockpit Scale

Make sure that the scale of the cockpit is reasonably sensible. Since testing with no headtracking causes the scale of the cockpit to not matter, it's easy to accidentally ship a cockpit that is much too large or much too small to fit with the rest of the aesthetic. Unless you want your player to actually feel like they are flying a bus, aim to keep your cockpit smaller than 4 units (roughly corresponding to a meter) wide, and unless you want to cause claustrophobia, keep it wider than 0.8 units.