# 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:

- System name: Enter a name of your choice here, as this is used mostly for display purposes in the user interface. If you're migrating from PinballX, and you want to use the same media and table list files, you should make sure this matches the name used in your PinballX settings.
- Enable: Check this box to enable the system; un-check it to disable it. Disabling a system prevents any of its games from appearing in the user interface, so it's effectively like deleting the system from your configuration entirely, except that it lets you keep the settings around in case you want to restore them in the future.
- Media folder: This is name of the sub-folder (within the main PinballX or PinballY media folder tree) where the image, video, and sound files for this system's games are stored.

  If you leave this blank, the System Name is used as the default folder name. That's the best choice in most cases.

  Important: enter only a sub-folder name, not a full path with a drive letter. This sub-folder is always within the main Media folder, which you can set separately in the Folder Options page.

- Database folder: This is the name of the sub-folder (within the main PinballX or PinballY database folder tree) where the game listing files for this system are located.

  If you leave this blank, the System Name is used as the default folder name. That's the best choice in most cases.

  Important: as with the Media folder, enter only a sub-folder name, not a full path with a drive letter. This sub-folder is always within the main Table Database folder, which you can set separately in the Folder Options page.

## 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:

- Create two separate "system" pages, one for VP 9.2 and one for 9.9
- In the VP 9.2 page, set the Program EXE box to VPinball921.exe (or whichever version is current)
- In the VP 9.9 page, set the Program EXE box to VPinball995.exe (or whichever version is current)

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 X

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

### Visual Pinball with PinUp Player

PinUp Player is an add-on for Visual Pinball and other systems that displays videos in secondary windows during the game. In principle, it shouldn't require anything extra in the PinballY options, since it should act like an extension of the player system. However, some people have problems with PinUp windows staying open after the Visual Pinball game exits. The root of the problem is that VP can sometimes crash or exit abnormally, and PinUp doesn't detect this, so it just leaves its windows open forever when this happens. The way to ensure that PinUp closes when VP exits is to explicitly terminate the PinUp processes at the end of each game, which you can do as follows:

- Create a file called ClosePinUp.bat in your PinballY folder, containing the following:
  taskkill /f /m PinUpPlayer.exe taskkill /im PinUpDisplay.exe
- In the "Run After 1" box, enter:
  [HIDE] cmd /c [PINBALLY]\ClosePinUp.bat

### 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:

- For Visual Pinball 9 or earlier, enter `.vpt`
- For Visual Pinball X, enter `.vpx`
- For Future Pinball, enter `.fpt`

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".

- For Future Pinball, enter `FP`
- For Pinball FX2, enter `FX2`
- For Pinball FX3, enter `FX3`

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:

- Leave it blank: PinballY will automatically launch the program that's associated in the Windows registry with the filename extension in the "Table Extension" box. For example, if the extension is set to .vpt, the program associated with the .vpt extension would be launched. This is the same program that Windows launches when you double-click on a file of that type in the Windows desktop.

  Use this option whenever possible, since it's the most future-proof choice. If you use this approach, you won't have to worry about updating the PinballY settings the next time you update the program to a new version, or reinstall it in a different folder, since PinballY should be able to pick up the new location automatically from the registry.

- Specify the .exe name only: If you enter the .exe name without a path prefix (e.g., `VPinball921.exe` rather than `c:\VisualPinball\VPinball921.exe`), PinballY will look for the file in the folder containing the program that's associated with the file extension, but it will replace the registered program with the named program instead.

  This option is especially good for Visual Pinball, since it's common to have multiple VP 8/9 versions installed on one pin cab at the same time. All VP 8/9 versions use the .vpt file extension, but Windows only allows one program to be associated with a given extension, so they can't all use the fully automatic lookup of the "leave it blank" option. This ".exe name only" option is the next best thing in this case. As long as all of the different VP executables are installed in the same folder, this option lets you specify the specific VPinballXXX.exe program to run for each version, but still lets PinballY find the folder location based on the .vpt registry settings. That at least makes the settings future-proof against reinstalling VP in a different folder.

- Specify a full path: If you don't have a Windows registry association for the file extension, you'll have to enter the full path for the program, as in `c:\VisualPinball\VPinball921.exe`. PinballY will simply launch this exact program file without consulting the registry or any other hidden information. Clicking on the folder button next to the box lets you browse for the program .exe file.
- [STEAM]: For Steam-based programs like Farsight's Pinball Arcade or Pinball FX2/FX3, you can enter the special name [STEAM] (exactly like that, including the brackets). This tells PinballY to find the Steam executable using Steam's installation records in the Windows registry. As with the "leave it blank" option, this future-proofs the settings against updates to Steam or changes to its location.

### 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.

- [TABLEPATH]: the full path name to the table file for the game you're running. For example, for a Visual Pinball game, this is the full path of the VP "Tables" folder, so it'll be something like `c:\VisualPinball\Tables`.
- [TABLEFILE]: the filename of the table file for the game you're running, without any path prefix. For example, for a Visual Pinball version of Funhouse, this might be something like `funhouse_v2.vpt`.
- [PINBALLY]: the full path to your PinballY install folder (e.g., `c:\PinballY`).
- [LB]: a literal left square bracket, [.
- [RB]: a literal right square bracket, ].

### 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:

- Show shows the window normally
- Minimize minimizes the window to the taskbar
- Hide hides the window

"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:

- First, to set focus on the right window after launch if needed. Future Pinball in particular needs a mouse click on its playfield window before it'll accept keyboard input. You can do this with a simple [click playfield] sequence, which sends a mouse click to the middle of the playfield window.
- Second, to click through any initial dialogs the game system displays at startup. You can use a sequence like enter enter to send a couple of Enter key presses to the program to dismiss dialogs.
- Third, to navigate any menus the game presents at startup. This is needed for Farsight's Pinball Arcade, since it presents its own game selection menu.

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:

Command | Meaning
--- | ---
esc | Escape key
tab | The Tab key
enter | The Enter key
lshift | The left Shift key
rshift | The right Shift key
lctrl | The left Ctrl key
rctrl | The right Ctrl key
lalt | The left Alt key
ralt | The right Alt key
capslock | The Caps Lock key
f1-f12 | Function keys F1 through F12
tilde | The tilde (~) key
0-9 | Digit keys 0 through 9
A-Z | The alphabetic keys A through Z
dash | The -_ key
plus | The += key
backslash | The \| key
lbracket | The [{ key
rbracket | The ]} key
colon | The :; key
quote | The "' key
comma | The ,< key
period | The .> key
slash | The /? key
home |
up | Cursor up key
down | Cursor down key
left | Cursor left key
right | Cursor right key
end | End key
ins | Ins key
del | Del key
pageup | Page Up key
pagedown | Page Down key
kp0-kp9 | Keypad 0 through 9 keys
decimal | Keypad . key
add | Keypad + key
subtract | Keypad - key
times | Keypad * key
divide | Keypad / 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.

- Close Window: This is the default. This simply closes all of the program's open windows, as though you manually closed them with the mouse. This is considered the best way to terminate a program, since it's the way most programs expect to be terminated under normal conditions, and because it allows the program to perform an orderly shutdown, releasing system resources before it exits. This option should be used in most cases. Consider other options only if this one doesn't work reliably for a particular game system.
- Kill Process: This asks Windows to terminate the process directly. This is a more forceful way to stop a program, because it doesn't require any cooperation from the program itself. It's the same thing that Task Manager does when you ask it to kill a process. However, if you've ever done this with Task Manager, you're familiar with that warning message it displays about how this kind of termination can harm system stability. Killing a process doesn't give the target program a chance to do the cleanup work it would normally do on exit. This can, in some cases, leave system resources (like files or devices) locked or in other dubious states. This option is sometimes necessary, though, because some programs won't cooperate properly with the more polite Close Window approach. Use this as a last resort when the Close Window option doesn't work reliably.

### 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:

- Leave it blank: PinballY assumes that tables are in the same folder as the program EXE if you leave this blank.
- Enter a full folder path: If you enter a full, absolute folder path with drive letter (e.g., `c:\VisualPinball\Tables`), PinballY will simply use the exact path you enter.
- Enter a "relative" folder name: If you enter a relative path with no drive letter prefix (e.g., `Tables`), PinballY will treat it as a sub-folder of the main folder containing the program EXE.

  It's best to use this format when possible, because you won't have to update this setting if you should reinstall the player system in a different main program folder in the future. PinballY will automatically use whatever main program folder is current on each run.

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.

- [PinballY] is replaced with the full path to the PinballY program folder. This is in absolute path format, so it can only be used at the start of the folder path. For example, [PinballY]\Farsight points to the Farsight folder within the PinballY install folder.
- [PinballX] is replaced with the full path to the PinballX install folder, if present on your machine.
- [SteamDir] is replaced with the full path to the Steam program install folder, if present on your machine.
- [lb] is replaced with a literal left square bracket, [.
- [rb] is replaced with a literal right square bracket, ].

### 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:

- Leave it blank: PinballY will use the standard NVRAM path for the system. In the case of Visual Pinball, this is the NVRAM folder from your VPinMAME setup, as recorded in the registry. For Future Pinball, this is the fpRAM sub-folder of the main Future Pinball program folder. This is the best option in most cases, because you won't have to update it if you ever reinstall the player system in a new location.
- Enter a full path: If you enter a full, absolute path with drive letter (e.g., `c:\VisualPinball\VPinMAME\nvram`), PinballY will use the folder exactly as specified.
- Enter a relative path: If you enter only a sub-folder name with no path prefix (e.g., `fpRAM`), PinballY will look in that sub-folder of the system's main program folder.

### 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 user selects "Play Game" from the menu to launch the game
- PinballY updates the playfield window to show a completely blank, black display
- The command in slot (1) is executed
- PinballY displays a "Launching game" message in the playfield window
- The command in slot (2) is executed
- The game is launched

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:

- NOWAIT: PinballY will execute the command and leave it running. If you don't specify this, PinballY will wait for the program to exit before proceeding to the next step. The benefit of NOWAIT is that it can make the game start up more quickly, since the game launch doesn't have to wait for this pre-launch task to finish. Be careful with this, though, because it will leave the program running until it exits on its own. If you launch a program with NOWAIT, and that program doesn't exit on its own in a reasonable amount of time, you could end up with many copies of the program running, since a new copy will be launched every time you start a new game. You also shouldn't use NOWAIT if the program does something that needs to be finished before the game starts, because the whole point of NOWAIT is that it doesn't force the game to wait for the task to finish.
- TERMINATE: PinballY will explicitly terminate the running process as soon as the game exits. Use this in combination with WAIT (that is, specify [NOWAIT TERMINATE]) for a program that you want to leave running to carry out some background task throughout the game session, but that you want to shut down as soon as the game finishes. This is often a better option than the plain NOWAIT, since it ensures that each copy of the program launched is terminated when the game ends.
- HIDE: Launches the command with its window hidden. This is useful for CMD scripts, so that you don't see a DOS box window pop up briefly while the script is running.
- MINIMIZE: Launches the command with its window minimized. This is useful for a background task that you want to leave running (via NOWAIT), so that its window doesn't appear in the UI but is still accessible through the Windows desktop if necessary.
- ROTATE(window,angle): Rotate the given UI window by the given angle just before executing the command. The window can be PLAYFIELD, BACKGLASS, DMD, TOPPER, or INSTRUCTIONS. The angle is always clockwise, and can be 90, 180, or 270. Note that there must be no spaces in the whole construct. For example, to rotate the playfield window by 90 degrees clockwise, write [ROTATE(PLAYFIELD,90)]. If you need to do a counter-clockwise rotation, just remember that 90 degrees counter-clockwise is the same as 270 degrees clockwise, and vice versa, and 180 degrees is the same in either direction.

  The system automatically undoes the cumulative rotation for all windows after the game exits, just before returning to the main UI after the game exits. This means that it's not strictly necessary to use a ROTATE flag in the Run After to compensate for one in the Run Before. But you're certainly free to write one anyway, so that you can control the timing of the change. For example, if you place [ROTATE(PLAYFIELD,90)] in the Run Before (1) command, you'd usually place [ROTATE(PLAYFIELD,270)] in the Run After(2) to cancel out the change and return to the original rotation.

- ADMIN: Launches the command in Administrator mode. This is available only when running PinballY via the PinballY Admin Mode.exe version of the program.

  You should only use the [ADMIN] option as a last resort. Avoid Admin mode whenever possible, in part because it exposes your system to more security risks, but more so because it creates a lot of complications for other software. Windows restricts normal program-to-program interactions when an Admin mode program is running, which can cause weird problems in the user interface and can make some program features stop working.

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:

- [TABLEPATH]: the full path name to the table file for the game you're running. For example, for a Visual Pinball game, this is the full path of the VP "Tables" folder, so it'll be something like `c:\VisualPinball\Tables`.
- [TABLEFILE]: the filename of the table file for the game you're running, without any path prefix. For example, for a Visual Pinball version of Funhouse, this might be something like `funhouse_v2.vpt`.
- [PINBALLY]: the full path to your PinballY install folder (e.g., `c:\PinballY`).
- [LB]: a literal left square bracket, [.
- [RB]: a literal right square bracket, ].

### 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:

- The user presses the Exit Game key (or otherwise exits the game)
- PinballY attempts to bring its window to the foreground (if Windows allows it)
- PinballY displays the "Exiting game" message in the playfield window
- PinballY waits for the game program to terminate
- The command in slot (1) is executed
- PinballY updates the playfield window to show a blank, black screen
- The command in slot (2) is executed
- PinballY restores the normal interactive playfield display

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:

- Run Before (1)
  - Run Before (2)
    - Game
  - Run After (1)
- Run After (2)

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:

- If Run Before (1) is executed, Run After (2) will also be executed
- If Run Before (2) is executed, Run After (1) will also be executed

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.