VR Support - syd711/vpin-studio GitHub Wiki

VPin Studio includes experimental VR mode support that allows you to run your pinball tables in a VR headset. When VR mode is active, the application automatically swaps the emulator launch script and key configuration files so that VPinball X starts in VR rather than desktop mode.

Note: VR support is currently in an experimental state and requires additional testing. Use with care on production cabinets.

VR Preferences

The VR preferences panel is where you configure VR support for your cabinet. It is accessible from the main preferences dialog.

Enabling VR Support

The VR Support Enabled checkbox activates the VR feature system-wide. When unchecked, the VR toggle button in the toolbar is hidden and VR mode cannot be activated. You must enable this before doing any other VR configuration.

VR Mode Config Files

VR mode requires two emulator configuration files to be provided in their VR versions:

File Purpose
dmddevice.ini Controls DMD display behavior in VR mode
vpinballx.ini VPinball X settings optimized for VR

For each supported VPX emulator (selectable via the emulator dropdown), you upload a VR-specific version of these files using the Upload buttons. The original files on disk are shown alongside the VR replacements so you can verify which versions are in place.

When VR mode is toggled on, VPin Studio renames the original file with a .vr backup suffix and copies the uploaded VR version in its place. When VR mode is toggled off, the backup is restored and the VR version is removed.

VR Mode Switch / Controller Input

The Configure Controller Inputs button opens the button recorder dialog, where you can map a hardware button or controller input to trigger the VR mode toggle. This lets you switch between desktop and VR modes directly from your cabinet without touching the PC.

VR Toggle Button (Toolbar)

The toolbar contains a VR Mode toggle button that lets you enable or disable VR mode with a single click.

The button is only visible when VR support has been enabled in the VR preferences. Its icon changes color to reflect the current state:

State Icon Color
VR mode off Gray
VR mode on Green

Clicking the button triggers the full VR toggle sequence (see What Happens When VR Mode Is Toggled below).

VR Launch Script Tab (Emulators)

Each VPX emulator in the emulator settings panel has an additional VR Launch Script tab alongside the standard Launch Script and Exit Script tabs.

This tab contains a script editor (identical in structure to the regular Launch Script tab) where you define the launch command used when VR mode is active. A typical VR launch script points VPinball X to a VR-specific executable or passes VR-specific command-line arguments.

Behavior

  • The VR Launch Script tab is only available for VPX emulators. It is disabled (grayed out) for all other emulator types.
  • While VR mode is active, the tab becomes read-only. You must turn VR mode off before editing the VR launch script.
  • The script is saved per emulator and stored in the VPin Studio database.

What Happens When VR Mode Is Toggled

Toggling VR mode triggers an automated sequence that reconfigures all VPX emulators simultaneously. The steps are:

Enabling VR Mode

  1. Preference saved — VRSettings.vrEnabled is set to true and written to the database.
  2. Launch script swapped — For each VPX emulator:
    • The current launch script is backed up internally (stored in EmulatorDetails.originalLaunchScript).
    • The VR launch script (stored in EmulatorDetails.vrLaunchScript) is applied as the active launch script.
  3. Config files swapped — For each VPX emulator, two files are replaced:
    • The original dmddevice.ini is renamed to dmddevice.ini.vr (backup).
    • The uploaded VR version of dmddevice.ini is copied into place.
    • The same process is applied to vpinballx.ini.
  4. Emulator cache cleared — The in-memory emulator cache is invalidated so all subsequent reads reflect the new configuration.
  5. UI updated — The toolbar button icon turns green. The emulator editor becomes read-only to prevent accidental changes while VR mode is running.

Disabling VR Mode

  1. Preference saved — VRSettings.vrEnabled is set to false and written to the database.
  2. Launch script restored — The backed-up original launch script is applied to each VPX emulator.
  3. Config files restored — For each VPX emulator:
    • The current dmddevice.ini (VR version) is deleted.
    • The backup dmddevice.ini.vr is renamed back to dmddevice.ini.
    • The same process is applied to vpinballx.ini.
  4. Emulator cache cleared.
  5. UI updated — The toolbar button icon returns to gray. The emulator editor becomes editable again.

File System Layout

VR replacement files are stored under the VPin Studio resources directory:

resources/
└── vr/
    └── {emulatorId}/
        ├── dmddevice.ini      ← uploaded VR version
        └── vpinballx.ini      ← uploaded VR version

Backups created when VR mode is enabled:

<emulator install path>/
├── dmddevice.ini              ← active file (VR version while VR is on)
├── dmddevice.ini.vr           ← backup of original (exists only while VR is on)
├── vpinballx.ini              ← active file (VR version while VR is on)
└── vpinballx.ini.vr           ← backup of original (exists only while VR is on)