The setup wizard

The first time you start PinReady, a wizard walks you through eight pages. Each option has a small info marker: hover it, or click it on a cabinet, for a plain-language explanation.

Your answers are written into VPinballX.ini, the settings file of Visual Pinball, and the comments in that file are kept. If the file does not exist yet, PinReady first has Visual Pinball create its complete default file, then adds your choices to it. You can reopen the wizard at any time from the Configuration button of the launcher or with pinready --config: every field shows your current settings. Most settings can also be changed while playing, from the Visual Pinball menu on F12.

Reset the configuration throws away every answer, sets the global VPinballX.ini aside as VPinballX.ini.reset-backup and starts again at page one. Your tables are left alone.

1. Screens

The first page shows the detected system (for example Ubuntu 24.04 LTS · X11 · GNOME) so that bug reports always carry their context, lets you pick the interface language, and installs Visual Pinball if needed.

• Number of screens: 1 for a desktop computer, 3 or 4 for a full pincab (playfield, backglass, DMD and an optional topper).
• Roles: each display is listed with its name, resolution, refresh rate (Hz) and physical size. PinReady suggests a role from the screen sizes: the largest becomes the playfield, then the backglass, the DMD and the topper. Change any role from its list, or set a screen to Unused.
• Display mode: Desktop (windowed, for a normal computer), Cabinet (the playfield drawn for a screen lying flat, backglass and DMD on their own screens) or Full Single Screen (playfield and backglass on one tall screen). It switches to Cabinet once you have 2 screens or more, and you can still change it.
• External DMD device (ZeDMD, PinDMD…): tick it if you have a physical score display; Visual Pinball detects it when a table starts.
• Disable touch screen: turns off the touch overlay of VPX, useful when the playfield is not a touch screen or when you control the cabinet remotely.
• Cabinet dimensions: lockbar width and height, playfield slope, your height and where you stand. Drag the handles on the drawing or type the values; they give the 3D view the right perspective.

2. Rendering

Graphics settings for the playfield. The advice on the page: start with the defaults, then adjust to your machine.

• Synchronization: No sync, Vertical sync, Adaptive sync or Frame pacing, the Visual Pinball default. Each choice explains its trade-off between smoothness and input delay.
• FPS limit: set to the refresh rate of your playfield screen, so no frame is drawn faster than the screen can show it.
• Image quality: supersampling, MSAA, post-processing anti-aliasing (FXAA and others), sharpening, reflections and maximum texture size.
• Show FPS (on by default) displays a frame counter in game, handy to check your settings right after setup.
• Round ball (on by default) keeps the ball from looking slightly egg-shaped when it moves fast. Purely cosmetic.

3. Inputs

Every Visual Pinball action has two columns, Keyboard and Joystick, and both work side by side. Click Map and press a key or a button: a key fills the keyboard column, a joystick button the joystick column. Auto-map all inputs walks through every action in one pass. Essential actions (flippers, MagnaSave, start, credit, launch ball…) are shown first; advanced ones are one click away. PinReady warns you when a key is already used by another action.

Pinball controller boards. When a Pinscape KL25Z, Pinscape Pico, DudesCab or PinOne board is detected, PinReady picks the matching profile and fills the joystick column with the board's factory button layout; Visual Pinball then handles the plunger and the accelerometer nudge by itself. Choose None to map every button yourself. A detected gamepad can also be used for the flippers, plunger and nudge.

KL25Z (KL Shield V5.1 / Brain / Rig Master)

Button	Label on the board	VPX action
0	START	Start
1	EXTRA-B	ExtraBall
2	COIN1	Credit1
3	COIN2	Credit2
4	L BALL	LaunchBall
5	EXIT	ExitGame
7	L FLIPP	LeftFlipper + LeftStagedFlipper
8	R FLIPP	RightFlipper + RightStagedFlipper
9	L MAGNA	LeftMagna
10	R MAGNA	RightMagna
11	FIRE	Lockbar
13	DOOR	CoinDoor
14	SERVICE EXIT	Service1
15	SERVICE -	Service2
16	SERVICE +	Service3
17	ENTER	Service4
19	VOL-	VolumeDown
20	VOL+	VolumeUp

Pinscape Pico (OpenPinballDevice)

Button	Label on the board	VPX action
0	Start	Start
1	Exit	ExitGame
2	Extra Ball	ExtraBall
3	Coin 1	Credit1
4	Coin 2	Credit2
5	Coin 3	Credit3
6	Coin 4	Credit4
7	Launch Ball	LaunchBall
8	Fire	Lockbar
9	Left Flipper	LeftFlipper
10	Right Flipper	RightFlipper
11	Upper Left Flipper	LeftStagedFlipper
12	Upper Right Flipper	RightStagedFlipper
13	MagnaSave Left	LeftMagna
14	MagnaSave Right	RightMagna
16	Slam Tilt	SlamTilt
17	Coin Door	CoinDoor
18	Service Cancel	Service1
19	Service Down	Service2
20	Service Up	Service3
21	Service Enter	Service4
22	Left Nudge	LeftNudge
23	Forward Nudge	CenterNudge
24	Right Nudge	RightNudge
25	Volume Up	VolumeUp
26	Volume Down	VolumeDown

DudesCab (Arnoz)

Button	Label on the board	VPX action
0	Start	Start
1	ExtraBall	ExtraBall
2	Coin1	Credit1
3	Coin2	Credit2
4	LaunchBall	LaunchBall
5	Return	ExitGame
7	Flipper Left	LeftFlipper + LeftStagedFlipper
8	Flipper Right	RightFlipper + RightStagedFlipper
9	Magna Left	LeftMagna
10	Magna Right	RightMagna
12	Fire	Lockbar
13	Door	CoinDoor
14	ROM Exit	Service1
15	ROM -	Service2
16	ROM +	Service3
17	ROM Enter	Service4
18	VOL -	VolumeDown
19	VOL +	VolumeUp

CSD PinOne

Button	Label on the board	VPX action
0	VPX 1	RightFlipper
1	VPX 2	RightMagna
2	VPX 3	LeftFlipper
3	VPX 4	LeftMagna
4	VPX 5	ExtraBall
5	VPX 6	Start
6	VPX 7	Credit1
7	VPX 8	ExitGame
8	VPX 9	Lockbar
15	VPX 16	VolumeUp
16	VPX 17	VolumeDown
17	VPX 18	CoinDoor
18	VPX 19	Service1
19	VPX 20	Service2
20	VPX 21	Service3
21	VPX 22	Service4
23	VPX 24	LaunchBall

Button numbers are the ones SDL reports, counted from 0. Buttons a profile leaves unmapped are not listed.

4. Accessories

DOF effects (lights and toys)

VPX 10.8.1 standalone includes DOF (Direct Output Framework), which drives the solenoids, lights, shaker motor, knocker or beacon of a cabinet. It only needs a configuration describing your hardware. The page walks you through it:

1. Create a free account on the VPUniverse ConfigTool.
2. Create a table matching your cabinet, add its output system (Pinscape, LedWiz, PinOne, DudesCab, PacLed, TeensyStripController…) and attach your devices to the outputs.
3. Click Generate, download the zip and extract it into the target folder: the Open folder in file manager button takes you there.
4. Turn DOF on: Visual Pinball ships with every plugin disabled, so nothing fires in game until you do.

PinReady can also look for your output board over USB and tell you which controller type to pick in the ConfigTool. On Linux it shows, copies or installs the udev rules that give access to the board. An output tester that pulses each output in turn, with a built-in safety stop, currently runs on a simulator only.

Head tracking

For cabinets with a Kinect or a camera on the backglass or topper: the perspective of the table follows your head. One click downloads the head tracking plugin and its demo, enables the plugin, switches Visual Pinball to the Window view mode it needs, and opens the demo so you can install the camera drivers and check that you are tracked. Not available on Intel Macs.

5. Tilt / Nudge

Settings for the accelerometer that detects when you shake (nudge) the cabinet.

• Nudge sensor type: Game Controller for a gamepad stick, Intent Sensor for cabinets with an accelerometer board such as Pinscape or DudesCab (it ignores small vibrations and turns a real shove into a nudge), Cabinet Sensor for a fast, clean sensor whose readings are applied as measured.
• Strength: how hard a shake pushes the ball. In practice, the one setting worth tuning.
• Dead zone: tiny readings below this level are ignored, so vibrations and sensor noise do not move the ball.
• Accelerometer range: a fact about your board, not a preference. PinReady reads it from the board when the board publishes it, and warns you if the selected value does not match.
• TILT threshold: how hard you can nudge before the game calls a tilt.

Shake the cabinet and watch the live view: a dot shows each shake against rings for the dead zone, the nudge threshold and the tilt; crossing the red ring means TILT. PinReady also keeps the measured peak, tells you when the tilt angle is out of the sensor's reach, and asks you to check which way the board is mounted, since a board turned the wrong way swaps or mirrors the nudge directions.

6. Audio

Visual Pinball plays sound on two devices, and PinReady lists your sound cards for each:

• Backglass: music, voices and general game sounds.
• Playfield: the mechanical sounds (flippers, bumpers, rolling ball). For surround or SSF, this must be the multi-channel output.

Playfield output mode. PinReady preselects a mode from the number of channels it detects, and shows a diagram of the speaker layout with the wiring it requires.

Wiring for a 7.1 sound card, the recommended SSF setup (jack colours can vary between cards):

Volumes and tests. Set the music and playfield volumes, then check your wiring: test 1 loops music on the backglass with a left/right balance; test 2 plays a sound on each playfield speaker in turn, and sweeps a rolling ball from the top to the bottom and from left to right. If the ball moves the wrong way from front to back, change the output mode; from left to right, check the wiring. A sound card with only 3 jacks (green, pink, blue) can often be switched to 5.1 or 7.1: see the guides for Linux, Windows, macOS.

7. Tables

Choose the folder that holds your tables, one subfolder per table: the layout used by Visual Pinball 10.8.1.

Tables/
└── Table Name/
    ├── Table Name.vpx            table file (required)
    ├── Table Name.directb2s      backglass (optional)
    ├── Table Name.ini            per-table settings (optional)
    ├── Table Name.vbs            script patch (optional)
    ├── medias/launcher.png       launcher picture (optional)
    ├── pinmame/roms/<rom>.zip    ROM (required for ROM tables)
    ├── altsound/<rom>/          alt-sound pack (optional)
    ├── pupvideos/<rom>/         PinUP Player videos (optional)
    ├── serum/<rom>/<rom>.crz    Serum colorization (optional)
    └── vni/<rom>/<rom>.vni      VNI colorization, with .pal (optional)

DMD colorization in Serum (.crz) and VNI (.vni + .pal) formats is supported; proprietary formats such as .pac are not.

• Bring your collection into the new layout. Point PinReady at one folder (a table collection, an old VPX install, even a whole drive). It indexes everything inside, then gives each table its own folder with the ROM, backglass, PUP pack, alt-sound, colorization and music that belong to it. If your tables already have one folder each, they stay where they are and missing files are added. Run a dry run first to preview, then choose to copy (safe) or move the files.
• Visual Pinball Standalone compatibility (off by default): PinReady recognizes the script built into each table and, when Le-Syl21/vpx-standalone-scripts has a patch for it, places the patched .vbs next to the .vpx. A .vbs of your own is kept as <table>.pre_standalone.vbs.
• Catalog enrichment (on by default): matches each table against the Virtual Pinball Spreadsheet and downloads a backglass picture and an audio jingle from VPinMediaDB into the table's medias folder. The first sync downloads about 7 MB of catalog data, plus a few MB per matched table. Turn it off on an offline cabinet.

8. System

Optional conveniences, best suited to a dedicated cabinet:

• Launch PinReady automatically at startup.
• Menu shortcuts and .vpx file association: adds PinReady and Visual Pinball to the application menu (GNOME, KDE or XFCE on Linux, Launchpad on macOS, Start Menu on Windows) and opens .vpx files with Visual Pinball. Untick it and finish the wizard again to remove it.
• Desktop shortcut, and on GNOME, pin to the dock.
• Self-hosted mirror: fetch the script patches and the media database from your own server instead of GitHub.