Pinball Player System Setup

This dialog lets you configure your pinball player systems, such as Visual Pinball and Future Pinball, for use with PinballY.

PinballY tries to be as "system agnostic" as possible, so it tries to avoid hard-coded special handling for any one system. Instead, it gives you a big collection of tunable options that you can tailor to each system. The downside is that it makes the setup dialog pretty complex; it might look a little daunting when you first bring it up just because there are so many options. But it's not as bad as it looks at first glance, because you can leave many of the options blank in most cases. PinballY will try to choose a suitable default for anything you leave blank.

Adding a new system

To add a new system, click on the "Systems" item in the list on the left, then click the "Add a new system" button. This will create a new system page that you can fill in with the system's details.

Migrating from PinballX

If you've already set up PinballX on your system, and you've already gone through the process of setting up its list of tables and installing media packs, you can use all of those existing table lists and media files in PinballY without moving or copying any files. (So it's not really "migrating" in the usual sense - you don't have to go through any conversion process.) All you have to do is make sure that the System name settings in your PinballY setup match those in your PinballX setup. PinballX keys all of the folder locations for its table database and media files to the system name, so as the PinballY system name settings match your old PinballX system name settings, PinballY should be able to find your existing PinballX files. You should also go to the "Folders" page and make sure that you've selected the "Auto" setting for both the main media folder and main table database folder; this will tell PinballY to use your existing PinballX folder trees.

As long as you set the system name correctly for each system (to match the system name as it appeared in your PinballX setup), you can leave the "Media folder" and "Database folder" boxes blank.

Settings for all systems

Some of the settings are handled the same way for all types of player systems:

Recipes for the common systems

The basic settings for the most common systems are listed below. Apart from the "System Name", "Media Folder", and "Database Folder", you should simply leave any fields not mentioned in the recipes blank. Set the System Name to a name of your choosing, but note that it should match the corresponding system name from your PinballX setup if you're migrating (see above). The Media Folder and Database Folder boxes can be left blank, which uses the System Name as the default folder name in each case.

Visual Pinball 8/9

System class: Visual Pinball 9 or earlier
Program EXE: leave blank (see below)
Parameters: /play -"[TABLEPATH]\[TABLEFILE]"
Window Mode: Minimize
Table folder: Tables
Table extension: .vpt

For the Program EXE box, if you leave it blank, PinballY will use the Visual Pinball executable that's assigned for .vpt files in the Windows registry. This only works if you have only one version of VP installed, and you ran the VP SETUP program to set up the file associations in the registry. If the .vpt file associations aren't set up, you'll have to enter the full path to the Visual Pinball .exe file; you can click the little folder icon button next to the Program EXE box to browse for the file.

Many people keep multiple versions of VP 8-9 installed at the same time. In this case, Windows only allows one of them to be associated with .vpt files, so the "leave it blank" advice will only work for that one version that's assigned in the registry. For the other versions, you'll have to specify the version of VPinballXXX.exe to use. For example, if you have both VP 9.2 and VP 9.9 installed (as many people do), follow this procedure:

You can repeat that procedure to create additional system pages for any other VP versions that you have installed. Note that the default settings when you first install PinballY come with entries already filled in for VP 9.2, VP 9.9, and VP 10, so you probably won't have to create those yourself. But you can create as many additional entries as you need.

In the system settings lists below, type all of the text literally as shown, even when you see special characters like [square brackets] or "quotes".

Visual Pinball 10

System class: Visual Pinball 10
Program EXE: leave blank
Parameters: /play -"[TABLEPATH]\[TABLEFILE]"
Window Mode: Minimize
Table folder: Tables
Table extension: .vpx

Future Pinball

System class: Future Pinball
Program EXE: leave blank
Parameters: [TABLEPATH] /open "[TABLEPATH]\[TABLEFILE]" /play /exit /arcaderender
Window Mode: Minimize
Table folder: Tables
Table extension: .fpt
Startup Keys: [click playfield]
DOF Prefix: FP

Future Pinball + BAM

System class: Future Pinball
Program EXE: BAM\FPLoader.exe
Parameters: [TABLEPATH] /open "[TABLEPATH]\[TABLEFILE]" /play /exit /arcaderender
Window Mode: Minimize
Process name: Future Pinball.exe
Table folder: Tables
Table extension: .fpt
Startup Keys: [click playfield]
DOF Prefix: FP

The Pinball Arcade (Farsight)

System class: STEAM
Program EXE: [STEAM]
Parameters: -applaunch 238260
Window Mode: Minimize
Process name: PinballArcade.exe
Table folder: [PinballY]\Farsight
Table extension: .pinballArcade
Startup Keys: [pace 250] [pause 25] [click] [pause 5] up up right right right right right [click] [pause 5] up up left left left left left right [click] [pause 10] up left left left left left [click] [pause 5] [pace 1000] down [gridpos down right] [click] [pause 3] [click]

Note that the Program EXE setting should be literally [STEAM], including the brackets.

Notes about those Table Folder and Extension settings: Pinball Arcade isn't like most of the other systems, in that it doesn't have "table files" analogous to Visual Pinball's .vpt/.vpx files. Its tables are more or less built in to the program. This means that PinballY's normal way of searching for playable table files won't work for this system. To make up for that, PinballY has its own folder that contains dummy files that list all of the Farsight tables. These files all have names like The Addams Family (Midway 1992).pinballArcade, so the Table folder and Table extension settings shown above will allow PinballY to find all of these files and thereby recognize the game names. The files are all empty; all of the information is contained in their names.

Farsight adds new tables from time to time, so your version of TPA might have some tables that haven't made it into the list supplied with PinballY yet. If that happens, you can simply create a new file for the new table by copying one of the old ones and renaming it to reflect the new table's name.

The "Startup Keys" sequence is a huge mess, I know, but it seems to be the only way to automatically navigate to a particular game. The key sequence is designed to step through Pinball Arcade's menu screens to get to the icon for the game, using the grid position configured for the game. You can just copy and paste that whole sequence into the field.

The Pinball Arcade DX11

System class: Other
Program EXE: [STEAMDIR]\SteamApps\common\PinballArcade\PinballArcade11.exe
Parameters:
Process name:
Environment: SteamAppId=238260;SteamGameId=238260
Window Mode: Show
Table folder: [PinballY]\Farsight
Table extension: .pinballArcade
Startup Keys: same as Pinball Arcade above

Pinball Arcade DX11 with Free Camera Mod (FCM)

System class: Other
Program EXE: C:\TPAFreeCamMod\TPAFreeCamMod.exe
Parameters:
Process name: PinballArcade11.exe (see note below)
Environment: SteamAppId=238260;SteamGameId=238260
Window Mode: Show
Table folder: [PinballY]\Farsight
Table extension: .pinballArcade
Startup Keys: same as Pinball Arcade above

Note: you'll have to adjust the C:\... path in the Program Exe entry to match the location where you've installed the program. PinballY doesn't have any special knowledge of the Free Camera Mod install location (the way it does with Steam), so that has to be entered with the exact folder path.

Pinball FX2

System class: STEAM
Program EXE: [STEAM]
Parameters: -applaunch 226980 "[TABLEFILE]"
Window Mode: Minimize
Process name: Pinball FX2.exe
Table folder: steamapps\common\Pinball FX2\data\steam
Table extension: .pxp
DOF Prefix: FX2

The Program EXE text should be entered literally as [STEAM], including the brackets. Don't substitute a file path or anything else; just write it literally like that.

Pinball FX3

System class: STEAM
Program EXE: [STEAM]
Parameters: -applaunch 442120 "-table_[TABLEFILE]"
Window Mode: Minimize
Process name: Pinball FX3.exe
Table folder: steamapps\common\Pinball FX3\data\steam
Table extension: .pxp
DOF Prefix: FX3

The Program EXE text should be entered literally as [STEAM], including the brackets. Don't substitute a file path or anything else; just write it literally like that.

Details on the settings

The individual settings are explained below. For most systems, you should be able to leave most of the fields blank.

System name

This is the name that PinballY displays when referring to the system in the user interface, such as in the summary information box shown when the game is selected in the "wheel" menu. The name is really only for display purposes, and doesn't have any special meaning to PinballY.

Delete System

Click this button if you want to completely remove this system from your PinballY configuration.

This button has no effect on the actual installed program system that the setting page refers to. It won't uninstall your Visual Pinball player or anything crazy like that. It just deletes the PinballY settings for the system.

Enable

Check this box if you want to include the system's games in the "wheel" menu list. If this box isn't checked, the system's games will be ignored.

The main reason for this box is that it lets you retain the default configuration settings for all of the pre-defined systems, even those that you don't currently have installed, just in case you ever want to install them in the future. If you do install one of these systems in the future, you'll be able to use it in PinballY simply by checking the existing entry's Enable box, rather than having to enter all of the system's options anew.

Media folder

This is the name of the sub-folder for this system's "media" files: "wheel" icons, instruction card images, flyer pages, images and videos for the playfield and backglass, etc.

This is always a sub-folder of the main PinballY media folder, which you can configure in the "Folders" page in the options dialog. The folder name entered here shouldn't contain any path prefix or any "\" characters; it's just the name of the sub-folder.

By default, each system's media folder name is simply the same as the system name. Leave the folder name blank to use this default. If you're migrating from a PinballX installation, its media folders are always named the same as the corresponding systems.

It's okay to have multiple systems sharing the same media folder. For example, if you have both Visual Pinball 9.2 and 9.9 installed, you might want to use a single "Visual Pinball" media folder for both systems.

You can enter the folder name directly into the text box, or you can browse for an existing folder by clicking the folder icon () next to the text box.

Database folder

This is the name of the sub-folder for this system's "table database" files. These are the XML files that list the games for the system and provide their bibliographic details (titles, manufacturers, etc).

This is always a sub-folder of the main PinballY table database folder, which you can configure in the "Folders" page of the options dialog. The folder name entered here shouldn't contain any path prefix or any "\" characters; it's just the name of the sub-folder.

The default folder name is the same as the system name. Leave the folder name blank to use this default. If you're migrating from PinballX, its database folders are always named the same as the corresponding systems.

Every system must have its own separate table database folder. Table database folders can't be shared.

You can enter the folder name directly into the text box, or you can browse for an existing folder by clicking the folder icon () next to the text box.

System class

We said above that we try to be "system agnostic", avoiding special handling for any one system, but a few systems are so ubiquitous that we do have some special recognition for them. Specifically, Visual Pinball 8-9, Visual Pinball 10, Future Pinball, and Steam-based games. This doesn't mean that PinballY only supports those systems; it just means that PinballY has some special handling for those systems.

You should select the option here that matches the system you're setting up. If you don't see your system in the list, it's not a problem! Just select "Other".

Table extension

If the system uses separate table files, enter the filename extension for the files:

Leave this blank if the system doesn't use table files (e.g., any of the Steam-based systems).

DOF prefix

This is a prefix code used for entries in the DOF configuration. This is just a convention used in the DOF Config Tool, to distinguish the DOF settings for the same game written in different player systems. For example, the Config Tool database includes listings for numerous re-creations of real games that were written for both Visual Pinball and Future Pinball. Entering the correct prefix helps PinballY identify the right DOF settings to use depending on which game is selected in the "wheel".

Leave it blank in other cases. The DOF Config Tool treats Visual Pinball games as the "default" system, so the different versions of VP never use a prefix.

Program EXE

This is the name of the application file (.exe) that PinballY will launch when you play a table using this system. There are several choices here:

Parameters

Enter the command-line parameters for the command here. There's no general rule to how the parameters look; the parameters are entirely peculiar to the individual programs. See the "recipes" section above for the parameter formats for the common systems.

There are some special "substitution variables" that you can use in the parameters. When the program is launched, these will be replaced with value specific to the game you're launching.

Environment

The "environment" is a Windows internal feature that lets programs create a list of NAME=VALUE strings in memory. The main use of these is to pass information from a parent program to a child program that it launches. It serves much the same purpose as the command line parameters, but it's a different mechanism. Some programs depend upon having certain information passed this way rather than using the command line parameters, which is why PinballY lets you specify these variables.

Windows has a "global" list of environment variables that you can set via the system control panel, and these global variables are passed to each program that you launch from the Windows desktop. But programs can also add their own "local" variables that are only visible to child processes they create. That's the type we're creating here. The variables you list here will be added to the environment that PinballY receives from Windows, and passed to the game program when you launch it, but they won't affect the global system environment variables at all.

To add environment variables, list them in the edit box as NAME=VALUE pairs. You can list as many of these as you want; separate them with semicolons (;). If you want to use a semicolon within a value, double it (";;") to distinguish it from a variable separator.

For example, to directly launch Pinball Arcade DX11, you have to pass a couple of environment variables to the program:

    SteamAppId=238260;SteamGameId=238260

Window Mode

This lets you specify the initial visibility of the launched game program's first window when the program starts up:

"Minimize" mode is useful for Visual Pinball and Future Pinball, because these programs always open their editor windows first, and you don't really want to see those when launching straight into playing a game. It makes the game startup a little smoother if you don't see that editor window flash into view briefly while the game is being loaded.

"Minimize" is also good for games launched through Steam, since you don't need to see the Steam launcher window; you want the first visible window to be the game itself.

"Show" is best for any game that you launch directly (not through Steam) that goes straight to its game window. Use this when directly launching the Pinball Arcade DX11 executable, for example.

Process name

This is a weird special case needed mostly for Steam games (that is, games that are installed and launched via Valve's "Steam" system). Steam games use a two-step launch procedure where you run the STEAM.EXE application first, and that in turn runs the separate game program .exe (application) file. In Windows terminology, each running .exe is a "process". So when you run a Steam-based game like Farsight's Pinball Arcade or Pinball FX2, you're really launching two processes: STEAM.EXE, and the actual game's .exe file. This complicates things a bit for PinballY, because it needs to monitor each launched game process to determine when the game terminates, so that PinballY can take over when the game exits. And the real complication is that STEAM.EXE itself terminates as soon as it launches the game .exe, so PinballY can't use STEAM.EXE as a proxy for whether the game is running; it has to monitor the separate process where the game's .exe is running.

That's where the "Process name" setting comes in. This lets you identify the name of the game process that Steam launches. This is simply the name of the game's .exe file, without any path prefix. For example, for The Pinball Arcade, this is PinballArcade.exe.

Startup keys

This defines a sequence of keystrokes and mouse clicks to be sent to the launched program after it starts up. There are three main uses for this:

See the "recipes" section above for the recommended settings for the various systems. If you need to create a custom key sequence, here are the key names and special commands you can use:

CommandMeaning
escEscape key
tabThe Tab key
enterThe Enter key
lshiftThe left Shift key
rshiftThe right Shift key
lctrlThe left Ctrl key
rctrlThe right Ctrl key
laltThe left Alt key
raltThe right Alt key
capslockThe Caps Lock key
f1-f12Function keys F1 through F12
tildeThe tilde (~) key
0-9Digit keys 0 through 9
A-ZThe alphabetic keys A through Z
dashThe -_ key
plusThe += key
backslashThe \| key
lbracketThe [{ key
rbracketThe ]} key
colonThe :; key
quoteThe "' key
commaThe ,< key
periodThe .> key
slashThe /? key
home
upCursor up key
downCursor down key
leftCursor left key
rightCursor right key
endEnd key
insIns key
delDel key
pageupPage Up key
pagedownPage Down key
kp0-kp9Keypad 0 through 9 keys
decimalKeypad . key
addKeypad + key
subtractKeypad - key
timesKeypad * key
divideKeypad / key
{comment}Comment text - ignored
[pause n]Pause for n milliseconds
[pace n]Set the "pace" (time between keystrokes) to n milliseconds
[click]Click the left mouse button at the current mouse position
[rclick]Click the right mouse button at the current mouse position
[click window]Click the left mouse button in the middle of the given window, using the PinballY window layout; the window can be playfield, backglass, dmd, or topper
[rclick window]Click the right mouse button in the middle of the given window
[gridpos down right]Send a sequence of down and right keys to move to the "grid position" defined for the game being launched. The grid position is set in the game's settings. The down and right keys are key names from the list above, as in [gridpos comma period] or, more likely, [gridpos down right]

Terminate by

This specifies how PinballY terminates a running game launched with this system when you press the Exit Game button.

Table folder

Enter the folder where this system's tables are located.

If you're new to virtual pinball, it might seem puzzling and limiting that you have to specify a single folder here. But that's the long-standing convention that's more or less forced by the design of Visual Pinball and Future Pinball, so it's assumed by most of the rest of the pin cab ecosystem. It's not great for people who download a large number of tables and want to impose some kind of order on things, but you'll just make things unnecessary hard on yourself if you try to work around it.

There are three formats for the entry here:

Within the folder path, you can use some special substitution variables. PinballY will replace these with actual file system paths when the program starts up.

NVRAM folder

This is the folder where NVRAM (non-volatile RAM) files for the system's games are stored. The NVRAM files are where the high score listings are stored, so this path needs to be set correctly for PinballY to be able to display high scores in the game list.

This setting is only meaningful for Future Pinball and Visual Pinball, since PinballY can only read high scores from those types of systems.

There are three ways to enter this setting:

Run Before

The Run Before (1) and (2) boxes let you enter commands to run just before launching a game, each time a game using this system is launched. You can use these to do any preparation needed before this system starts up, such as modifying the monitor layout, resetting hardware devices, or starting background tasks that run concurrently with the game.

The commands in the (1) and (2) slots are executed in sequence, under slightly different visual display conditions. Here's the exact sequence of events:

The important distinction between the (1) and (2) slots is that the command in the (1) slot is executed with a completely blank, black playfield window, whereas the command in the (2) slot is executed after the "Launching game" message has been displayed. This might be important to you if the command you're launching does something that affects the system-wide visual layout of the monitors, such as changing the rotation or scaling factors. You might prefer to take that sort of action in phase (1), since the blank playfield window will help make the transition to the new visual layout smoother by avoiding any obvious change in the on-screen graphics. A completely black screen looks the same at any rotation or scale, so the moment when the layout changes won't be visually apparent to the user.

You can use each slot to launch just about any Windows program. Use the standard Windows command line syntax, as though typing a command into the Windows+R "Run" box. If you want to run a series of commands, the easiest approach is to create a .BAT file containing the commands, and run that with a command line like this:

    CMD /c c:\users\bob\BatchFile.bat

The .BAT format is a standard way in Windows to write a simple command script to carry out a series of commands. If you're not familiar with the .BAT format, you can find lots of information about it on the Web by searching for "Windows batch script".

You can put a special "flags" string at the very start of the command line to control how the command is processed. The flags are specified in square brackets, at the very start of the command. The flag keywords are:

You can specify multiple flags for the same command by writing a series of the flag keywords within the single pair of square brackets, separating the keywords by spaces. For example:

    [HIDE ROTATE(PLAYFIELD,90) ROTATE(BACKGLASS,180)] cmd /c ...

There are also some "substitution variables" you can use anywhere within the command string:

Run After

The Run After (1) and (2) boxes let you enter commands to run just after the game exits. These work very much like the Run Before commands, but run after the game instead of before.

As with the Run Before commands, there are two Run After slots, which run their respective commands under slightly different display conditions. Here's the sequence for the Run After commands:

This sequence is essentially the reverse of the Run Before sequence with respect to the display conditions. The command in the (2) slot is executed with a blank screen showing in the playfield window, so it's the right place to run any command that will modify the system-wide monitor layout.

You can use the same flags and substitution variables as with Run Before. As with the Run Before command, you should be careful when using [NOWAIT] that you can count on the program to exit on its own in a reasonable amount of time.

[NOWAIT TERMINATE] is accepted for the Run After commands, but it's not very useful, since the termination condition in this case is the return to the normal PinballY interactive interface. Since that will happen almost immediately after these commands are launched, they'll only have a few moments to run before PinballY terminates them. It's difficult to think of a situation where the [NOWAIT TERMINATE] combination would be useful for a Run After command.

Run Before/After pairings

The overall sequence of the launch is as follows:

It's best to think of these as "nested" steps, as suggested by the indentation in the list above. The Run Before (1) and Run After (2) are the "outer" steps: they're done first and last. The Run Before (2) and Run After (1) steps are the "inner" steps, done just before and just after the game runs. And the game itself is the "innermost" step, nested within the others.

The point of this nested view of the steps is that it should help you decide where to put any necessary cleanup tasks when you're arranging your command sequence. If Run Before (1) makes any system-wide changes, they should be undone in Run After (2), since that's the matching After step for Run Before (1) in the nested view. Similarly, any system-wide changes made in Run Before (2) does should be undone in Run After (1). Cleanup is necessary for any system-wide changes you make, such as changes to the monitor layout, or changes to your mouse or keyboard settings. You'll need to reverse such changes before the main PinballY window returns, so that settings are back to normal after the game finishes.

PinballY tries to help ensure that any cleanup steps are properly executed by always running the paired commands suggested in the nesting diagram above. In particular, the following pairings are guaranteed:

The steps will always be carried out in those matched pairs, even in case of error, and even if the user manually interrupts the game launch by pressing the Exit Game button during one of the early steps. This should help ensure that your commands will always have a chance to undo any system-wide setting changes made during the launch process so that everything is returned to normal after each game session.