Install on Linux

Linux covers ordinary desktops and dedicated cabinets — one build, not a special one.

Linux: vPinOps works — Visual Pinball's window focus is the open issue

vPinOps itself runs on Linux and is tested on a dedicated Linux cabinet here. First run and Settings, importing loose tables and packaged .vpxz files, fetching media, mapping cabinet controls, the wheel with its backglass, DMD and topper across three screens, launching tables and returning from them — that all works, and it is the same build as Windows and macOS.

The open issue is not ours: on a Wayland session, Visual Pinball’s own window focus — see the warning further down, because it is the one thing that decides whether a hands-off cabinet works.

⚠ Linux desktops vary far more than Windows or macOS. If something does not behave, the run log is what to send us.

Install it

1. Download the Linux build from Releases and unpack it — ~/vpinops/app/ is the suggestion, and nothing looks for it in a fixed place.

   It carries its own runtime. There is no .NET to install first, and nothing is added to your system — it ran on a machine that had never had .NET on it.

2. Run ./vPinOps.

   It creates ~/.vpinops/ on this first run: your config, your run log, and a generated OpsLink password. Nothing is installed system-wide and nothing needs root.

3. Open Settings from the tray icon and check the network.

   That window does one job: it makes OpsLink reachable. Port, password and Listen on — that is everything this window holds, deliberately, because those three are exactly what you cannot fix from a phone that cannot connect.

   Leave all three as they are unless something else already wants port 7833.

   Your paths are not in this window

   VPX, Tables, PinMAME and the rest are set in OpsLink, in a browser — along with your screens and your library. (Mapping a controller is the one thing that is neither: it is in the same menu as Settings.) Get the network working here first; everything else happens there.

4. Check your phone can reach it.

   The run log names the address every time it starts. Open it in any browser on the same network and sign in with the password from ~/.vpinops/remote-password, then change it in Settings. More: connecting to OpsLink.

   If the machine answers itself but nothing else can reach it, that is your firewall — whatever your distribution uses (ufw, firewalld, nftables), port 7833/tcp on the local network is what OpsLink needs. That is a decision about your machine’s security, so it is yours to make.

5. In OpsLink, open Settings and point it at your stuff.

   Settings → Where your stuff lives. Press Fill these in for me and it fills in the suggested layout for you:

   • Tables → ~/vPinOpsData/tables
   • VPX settings → ~/vPinOpsData/visualpinball
   • PinMAME and Your content as well

   Then set VPX yourself — point it at ~/vPinOpsData/visualpinball/app/VPinballX_BGFX using Browse…. The button deliberately leaves this one alone: vPinOps does not install Visual Pinball, so it will not write a path to a file it has not checked is there. It is also the one path you cannot skip — without it the page says Not ready to play.

   Change any of them — nothing refuses to work if you ignore the suggestion. Nothing is saved until you press Save settings, and folders under your content root are created for you when you do.

   What the PinMAME box is actually for

   It matters only if you keep your ROMs in one shared folder. vPinOps reads it to check a table’s ROM is there before launching, so it can tell you what is missing instead of dropping you into a black screen. If every table carries its own pinmame/roms/ you can leave whatever the button put there — nothing looks in it. It is not passed to Visual Pinball; VPX has its own setting for the shared folder. See ROMs and nvram.

   Visual Pinball first, if you have not already

   Put VPinballX_BGFX in ~/vPinOpsData/visualpinball/app/ and run it once on its own so it writes its settings. The build sits one level below its own settings deliberately: clear app/ to replace a Visual Pinball version and VPinballX.ini survives it.

6. Now put some tables in it.

   That works the same on every platform, so it lives in one place: Importing.

Building a dedicated cabinet

Two things decide whether a Linux cab works, and neither is your distribution.

1 · Use a normal user account with auto-login. Not a daemon account.

A daemon account — a systemd service, a nologin shell, no session — can serve OpsLink perfectly well, because that is just an HTTP listener. What it has no way to do is put a window on a display, because there is no graphical session for it to put one in. That is how Linux works rather than anything about vPinOps.

⇒ So if you want vPinOps to play tables, give it a logged-in graphical session. A normal user with auto-login is exactly that, and it needs no privileges of any kind.

Auto-login is a setting in your display manager, not in vPinOps:

GDM	/etc/gdm3/custom.conf, the [daemon] section
LightDM	/etc/lightdm/lightdm.conf
SDDM	/etc/sddm.conf

Most desktops also expose it in their own Settings → Users panel, which is the easier route. Then make vPinOps start with that session — your desktop’s Startup Applications, or a .desktop file in ~/.config/autostart/.

vPinOps does not write your display manager’s config, and it never will. Those files need root, they differ on every distribution, and a front end that edits them is a front end that breaks somebody’s login. We document it; you choose it.

2 · Wayland or X11

Known issue: Visual Pinball focus on Wayland

On Wayland, Visual Pinball’s playfield will sometimes lose focus when a table opens, and the table waits instead of starting. This is a Visual Pinball issue and is tracked upstream.

Two ways around it:

• Click the playfield once when the table opens, and it runs.
• Run Visual Pinball under X11 by launching it with SDL_VIDEODRIVER=x11, which gives the playfield focus normally. vPinOps does not set this for you — it uses whichever video driver Visual Pinball chooses.

Wayland and your screens

Your screens work on Wayland. The wheel and its backglass, DMD and topper go where you put them, and Visual Pinball’s own surfaces reach the right monitors too — vPinOps asks the same display names Visual Pinball does, so the two always agree about which screen is which.

One thing worth knowing, because it explains what you see: on Wayland an application cannot place its own windows — the desktop decides. So Visual Pinball’s backglass and score view are put on their monitors by going fullscreen there, which is the one placement Wayland offers. A surface sharing a screen with the playfield is left where it is rather than covering the table.

⚠ Tested on KDE Plasma. GNOME and the wlroots compositors are not, and a tiling desktop manages window geometry itself, so it may fight a cabinet layout.

If something lands on the wrong screen, the useful things to tell us are which desktop you use, whether you are on Wayland or X11, and what the run log said.

X11 sessions are going away

Some distributions have already dropped their X11 session, and more will. If your desktop still offers one at the login screen it is a valid way to run a cabinet today — but it is not something to build a new cab around.

What ended up on your disk

~/vpinops/app/               the program. Ours. Replaced wholesale when you update.
~/vPinOpsData/               your content. Never touched by an update.
    tables/                      one folder per table
    pinmame/                     the shared ROM fallback
    .inbox/                      tables sent from another device land here
    visualpinball/               Visual Pinball's own settings
    visualpinball/app/           Visual Pinball itself
~/.vpinops/                  your config, your run log, your OpsLink password

Same rule as everywhere: ours versus yours. The updater writes only inside app/, and the content root is never inside the install root — so an update cannot reach your library and uninstalling is deleting a folder.

The dot in .inbox is load-bearing

vPinOps searches your content several levels deep and skips any folder whose name begins with a dot. Rename .inbox and a half-finished upload shows up on the wheel as a table you cannot play.

Where things are

The program	wherever you unpacked it — ~/vpinops/app/ is the suggestion
Your content	~/vPinOpsData/
Config	~/.vpinops/config.json
Run log — read this first when anything is wrong	~/.vpinops/last-run.log
OpsLink password	~/.vpinops/remote-password
Uploads waiting to be imported	~/vPinOpsData/.inbox

What is not here yet

• Starting a table without a mouse, on Wayland. See the warning above — this is the blocker, and it is Visual Pinball’s, not ours.
• Desktops other than KDE. Testing here is on KDE Plasma. Nothing about GNOME, Xfce or the wlroots compositors is known to be broken — and nothing about them is known to work either. A tiling compositor actively manages window geometry, so it may well fight a cabinet layout.
• A mixed-DPI cabinet. Every display on the machine this was measured on runs at scale 1, so a Linux cab with displays at different scales has never been exercised.
• Visual Pinball’s own screen setup, which is the fiddly half. vPinOps is the easy part; getting Visual Pinball to put each window on the display you meant is where the work is. It matches displays on a name that comes from SDL, which is not always the connector name your desktop settings show you. If a surface opens on the wrong screen, start there rather than with the front end.
• The machine’s own volume. vPinOps reads and sets the system output volume on macOS with no permission at all; on Linux that needs pactl or amixer and is unbuilt. The control is shown with its reason rather than hidden, so you are told why it is unavailable instead of wondering.
• Steam games. Native Steam keeps its registry somewhere neither of the other platforms looks, so Pinball FX is a separate unknown here.
• A packaged build. It is a folder you unpack; there is no .deb, no .rpm, no Flatpak.