TUTORIAL_EN
- 1. Overview
- 2. Installation
- 3. First Launch Configuration
- 4. Understanding Profiles
- 5. Creating a New Profile — Complete Guide
- 6. PuPPacks Manager
- 7. Activating a Profile
- 8. Import and Export Profiles
- 9. Automatic Updates
- 10. Frequently Asked Questions (FAQ)
- 11. Report a Bug / Contribute
VPX Config Switcher is a configuration profile manager for Visual Pinball X (VPX). It lets you instantly switch between multiple configurations in just one click.
On a pinball cabinet (pincab) or a desktop PC, changing modes — for example switching from 2D to VR — normally requires manually replacing several configuration files: VPinballX.ini, DMDDevice.ini, PuPPacks pup files and ScreenRes.txt. This is tedious, error-prone, and impossible to do quickly.
VPX Config Switcher automates all of this in a single click: it replaces the files, switches the Windows audio output and redirects symbolic folder links, in under a second.
Configuration files (per profile):
| Element | Description |
|---|---|
VPinballX.ini |
Main VPX configuration file (graphics, resolutions, controls, physics…) |
DMDDevice.ini |
DMD device configuration (real pinball-style score display) |
ScreenRes.txt |
Position and resolution of VPX windows (playfield, backglass, DMD) |
| Windows audio output | The active sound output device (cabinet speakers, VR headset…) |
| Symbolic links (Symlinks) | Folder redirection, e.g. PuPVideos pointing to a 2D or VR version |
| Custom commands | Scripts or executables launched automatically when the profile is activated |
What the software does NOT touch:
- VPX pinball tables
- VPinMAME ROMs
- PinUP Popper and its configuration
| OS | Windows 10 / 11 — 64-bit only |
| VPX | All versions of Visual Pinball X (auto-detected) |
| Requirements | None — Python, PyQt6 and audio tools are bundled inside the exe |
Go to the project's GitHub page: https://github.com/Nesta78/VPXConfigSwitcher then click on the Releases tab in the right-hand column.
Download the VPXConfigSwitcher.exe file. There is nothing to install: it is a portable executable.
Place the exe in a dedicated folder, for example:
C:\Tools\VPXConfigSwitcher\VPXConfigSwitcher.exe
⚠️ Do NOT place it directly in the VPX folder, or in a system folder likeProgram Files.
💡 Create a shortcut on your desktop or taskbar for quick access. You can also simply leave the .exe directly on your desktop.
Double-click VPXConfigSwitcher.exe. On the very first launch, Windows may display a SmartScreen security warning. Click "More info" then "Run anyway".
📝 This warning appears because the exe is not signed with a commercial certificate.
On first launch, VPX Config Switcher displays an initial setup wizard with two steps. It is important to complete it correctly before creating your profiles.
The software automatically scans your PC to detect installed versions of Visual Pinball X in common folders (C:\vPinball, C:\Visual Pinball, etc.). It lists all found versions with their full path.
- Check the VPX versions you want to use with the switcher (this allows you to adjust settings directly in VPX and have your changes saved to the configuration files).
- Uncheck versions you do not want to manage (unused old versions, etc.).
- If a version is not detected automatically, click "Add manually" and browse to the desired VPX exe.
- Click "Validate" to confirm your selection.
📝 You can return to this list at any time via Preferences → Manage VPX executables.
⚠️ If you manage multiple VPX versions (e.g. VPX 10.8 and VPX 10.7), check them all. Each profile can then choose which VPX version it should use. For example, I personally checked the Standard X64 version for 2D mode, and the GL_X64 version for VR mode.
Before you can switch configurations, at least one profile must exist in the software. The wizard guides you to create your first profile from your current VPX configuration — the one you are already using.
This first profile will be your reference point. It represents your setup as it is right now.
- The wizard offers to automatically read your current configuration files:
-
VPinballX.ini(auto-detected from the checked VPX exe folder) -
DMDDevice.ini(if present) -
ScreenRes.txt(if present)
-
- Click "Read current configuration" to import these files into the profile.
- Give your profile a name (e.g. "2D Pincab" or "Current config").
- Click "Create profile" to finish.
📝 You are not required to configure all options at this stage. You can do so later by editing the profile if needed.
Once the wizard is complete, the main VPX Config Switcher window opens.
| Area | Role |
|---|---|
| Profile list | Displays all your created profiles. The active profile is highlighted. |
| **ACTIVATE** button | Applies the selected profile (replaces files, switches audio, manages symlinks). |
| **New profile** button | Opens the profile creation dialog. |
| **Edit** button | Opens the selected profile for editing. |
| **↺ Backups** | Access to automatic backups of .ini, DMD and ScreenRes files, with one-click restore. |
| **Preferences** menu | Manage VPX executables, change language, reset the app. |
A profile is a complete snapshot of your VPX configuration. It stores:
- The content of
VPinballX.ini - The content of
DMDDevice.ini - The content of
ScreenRes.txt - The audio output to activate on switch
- The associated VPX executable
- Symlinks (folder redirections)
- Custom commands to execute
When you activate a profile, the software replaces the active files on your disk in this order:
- Backup of current files (automatic timestamped backup)
- Writing the new
.ini/DMDDevice.ini/ScreenRes.txtfiles - Switching audio output (if configured)
- Applying symlinks (if configured)
- Running custom commands (if configured)
Everything is stored locally on your PC. Nothing is sent over the internet.
| Data | Location |
|---|---|
| Profiles | %APPDATA%\VPXConfigSwitcher\profiles.json |
| VPX .ini backups | %APPDATA%\VPXConfigSwitcher\backups\ |
| DMD backups | %APPDATA%\VPXConfigSwitcher\backups_dmd\ |
| ScreenRes backups | %APPDATA%\VPXConfigSwitcher\backups_screenres\ |
| VPX executables | %APPDATA%\VPXConfigSwitcher\executables.json |
| Language | %APPDATA%\VPXConfigSwitcher\language.txt |
| PuPPacks config | %APPDATA%\VPXConfigSwitcher\puppack_settings.json |
Before each profile activation, VPX Config Switcher automatically creates a timestamped backup of your current files. The last 10 backups are kept for each of the three files (VPinballX.ini, DMDDevice.ini, ScreenRes.txt).
To access backups, click ↺ Backups in the main interface. Three tabs appear:
-
VPX .ini — backups of
VPinballX.ini -
DMD — backups of
DMDDevice.ini -
ScreenRes — backups of
ScreenRes.txt
To restore a backup, select it in the list and click "Restore".
Before activating a profile, VPX Config Switcher checks that Visual Pinball X is closed. If VPX is still running, the software displays a warning and refuses to apply the profile.
⚠️ Never attempt to replace.inifiles while VPX is in use. This could corrupt your configuration.
To create a new profile, click "New profile" in the main interface. The creation window opens with several tabs.
Give your profile a short, descriptive name. This name will appear in the main list. Examples: "MODE 2D PINCAB", "MODE VR QUEST 3", "PERFORMANCE TEST".
Choose from the dropdown list which VPX version this profile should use. This list contains the executables you checked during initial setup.
📝 If you only have one VPX version, the executable is already pre-selected.
This is the most important tab. It contains the content of VPinballX.ini that will be applied when the profile is activated.
Click "Read current .ini" to import into the profile the VPX configuration currently on your disk. This is the fastest method to create a profile based on your existing setup.
This is the recommended method to create a profile with settings you have just modified in VPX:
- Click "Launch VPX" in the tab — this opens Visual Pinball X directly.
- In VPX, access the options and adjust your settings (resolution, graphics quality, controls, physics…).
- Close VPX.
- Back in VPX Config Switcher, the software automatically reads the
.inifile modified by VPX and imports it into your profile.
Once the .ini is imported, you can edit it directly in the built-in editor.
⚠️ The editor does not validate syntax. If you manually edit the.ini, respect the[Section]/key=valueformat.
This tab works exactly like the VPX .ini tab, but for the DMDDevice.ini file. This file controls the configuration of your DMD device (digital score display).
If you don't have a DMD (or don't need a different DMD configuration per profile), you can leave this tab empty. The software will then not overwrite the existing DMDDevice.ini file on activation.
Once a profile is activated and VPX is open, tables may modify DMDDevice.ini (table-specific calibrations). When you close VPX, the software compares the current DMDDevice.ini with the one stored in the active profile. If a difference is detected, a popup (wait a few seconds) offers you:
- "Update active profile" — to save the table calibrations into the profile
- "Ignore" — to change nothing
This tab manages the ScreenRes.txt file, which defines the resolution and position of VPX windows: the playfield window, the backglass and the DMD.
In 2D pincab mode, you typically have 3 screens with precise positions. In VR mode, the windows are repositioned differently as rendering happens inside the headset.
Use the "Read current ScreenRes" button to import the existing file.
This tab lets you define which Windows audio output should be activated when this profile is applied.
The dropdown list shows all available audio output devices on your PC, detected in real time. Common examples:
- "Speakers (Realtek Audio)" — for a classic pincab
- "Headphones (Meta Quest 3)" — for a VR profile
- "HDMI (Graphics card)" — depending on your setup
Select the device that matches your profile, or leave "No change" if you don't want the profile to modify the audio output.
📝 Audio switching uses the native Windows API (IPolicyConfig). No third-party software is required.
Symlinks (NTFS Junctions) allow you to redirect a folder to another one when the profile is activated, without moving or copying any files.
If you have different PuP videos for 2D and VR:
C:\vPinball\PuPVideos_2D\ ← your videos for 2D pincab mode
C:\vPinball\PuPVideos_VR\ ← your videos for VR mode
C:\vPinball\PuPVideos\ ← the symlink (ghost folder that PinUP Popper always reads)
When the 2D profile is activated, PuPVideos\ is redirected to PuPVideos_2D\. When the VR profile is activated, it points to PuPVideos_VR\. The switch is instant, regardless of the folder size.
- Click "+ Add symlink"
- Link: path of the ghost folder (the one VPX / PinUP Popper will read)
- Target: path of the real folder to point to
- Repeat for each folder to manage
📝 The application creates NTFS Junctions, which do not require administrator rights or Windows developer mode.
⚠️ Before configuring symlinks, create your target folders separately and fill them with the appropriate files. The software does not copy your files.
This tab allows you to run arbitrary Windows commands automatically when the profile is activated, after all files have been written.
Usage examples:
| Type | Example |
|---|---|
.bat script |
C:\scripts\config_2d.bat |
| Executable | C:\tools\mytool.exe --mode 2d |
| Reg command | reg add "HKCU\Software\MyApp" /v "MyKey" /t REG_DWORD /d 1 /f |
| Windows command | taskkill /f /im MyProcess.exe |
📝 Commands run silently in the background (no visible CMD window), in the order they appear in the list.
Once all tabs are configured, click "Save". The profile appears immediately in the main list.
A PuPPacks Manager tab is built into the software. It lets you view at a glance which PuPPacks exist in one folder or another, and copy them where they are missing if needed. The idea is to only duplicate PuPPacks you want to use in VR to avoid wasting too many disk storage.
- Close Visual Pinball X if it is open.
- In the main interface, click on the profile you want to activate.
- Click the "ACTIVATE" button.
- The software performs the operations in order (backup → files → audio → symlinks → commands).
- Launch VPX normally — it will start with the activated profile's configuration.
You can also switch between profiles with a right click on app icon in Windows tray bar.
The currently active profile is visually highlighted in the list (different background color, validation icon).
In case of error, the software displays an error message and attempts to restore the files from the last backup.
Most common failure causes:
| Cause | Solution |
|---|---|
| VPX is open | Close VPX and try again |
.ini file not found |
Check that the VPX executable in the profile is correctly configured |
| Insufficient rights | Restart VPX Config Switcher as administrator |
Profiles can be exported as .vpxprofile files (JSON) to share with the community or for backup purposes.
- Select the profile in the main list
- Click "Export" (or right-click → Export)
- Choose the save location
- The
.vpxprofilefile is created
- Click "Import" in the main interface
- Browse to the
.vpxprofilefile - The profile appears in your list
- Edit it if necessary to adapt the paths to your installation
⚠️ An exported profile contains the file paths as they exist on the original machine. If your VPX installation is in a different folder, remember to update the paths in the Symlinks and Custom Commands tabs.
VPX Config Switcher automatically checks at startup whether a new version is available on GitHub Releases.
- A notification appears with the new version number and release notes
- Click "Download and install" to update automatically
- The application closes and installs the update
📝 Your profiles and settings are never deleted during an update. They are stored in AppData, independently of the exe.
Will my profiles be lost if I reinstall the software?
No. Profiles are stored in %APPDATA%\VPXConfigSwitcher\profiles.json, independently of the exe. You can delete and reinstall the software without losing your profiles.
Can I have multiple profiles active at the same time?
No. Only one profile can be active at a time.
Does the software modify my VPX tables?
No. VPX Config Switcher only touches configuration files (.ini, ScreenRes.txt). Your tables (.vpx files) are never modified.
How do I back up all my profiles?
Copy the file %APPDATA%\VPXConfigSwitcher\profiles.json to a safe location. To restore, place this file back in the same location.
Audio switching is not working
Check that:
- The audio device is plugged in and recognized by Windows
- It appears in Settings → System → Sound
- You have selected it in the profile's Audio tab (and not "No change")
Symlinks are not being applied
Check that:
- The target folders actually exist on disk
- The "link" folder is not an existing real folder (it must be absent for the Junction to be created)
- VPX Config Switcher has sufficient rights (try running as administrator if needed)
VPX won't start after a profile switch
Use ↺ Backups to restore the last working configuration.
VPX Config Switcher is a project currently in testing phase. Use at your own risk :)
- Go to https://github.com/Nesta78/VPXConfigSwitcher/issues
- Open a new issue describing the problem (steps to reproduce, error message if applicable)
- Join the discussion in existing issues if your problem has already been reported
— End of tutorial —