New System Setup

To a first approximation, adding a new pinball player system to PinballY is straightforward: bring up the Option Settings dialog, navigate to the Systems section in the list on the left, click the Add a new system button to create a blank options page for a new system, and then fill in the details on the new system page. The trick is in figuring out those "details".

Before you set about re-inventing the wheel, please check the list of Recipes for common systems in the main System Options section. Most of the pinball game systems that people use on pin cabs are listed there. If the system you're looking to add isn't there, though, the information below should help. If you do have to add a brand new system, please send me the details once you have it working reliably, and I'll be happy to add it to the common recipe list.

What not to do

You shouldn't have to manually edit any of the XML "Database" files or PinballY's internal ".csv" game list file. PinballY will take care of editing those files automatically if you follow the procedures below. It's safer to let PinballY maintain those files instead of editing them manually, because they're very picky about getting the syntax exactly right.

Finding the new system's games

The first potentially tricky part of setting up a new system is: how do you get PinballY to recognize the new system's games and add them to the "wheel" UI that shows all of your available games?

To understand how to accomplish this, we have to understand what PinballY thinks of as a "game". To PinballY, every game is represented by a file on your hard disk that it calls a "table file". In most cases, this isn't a file you have to create - it's a file that you'll already have, and that PinballY finds.

The concept of a "table file" comes from the design of the most popular free programs, Visual Pinball and Future Pinball. Those programs both use a file on your hard disk to store everything about a particular game. In the case of VP, these files have names ending with .vpx (for version 10 of VP, also known as VPX) and .vpt (for VP versions 9 and earlier). Future Pinball uses a suffix of .fpt for its table files. For example, when you download a copy of Funhouse for Visual Pinball, it'll consist of a file called something like Funhouse_v3.vpx. That's what PinballY calls the "table file" - that main file that you open with Visual Pinball when you want to edit or play that game.

(Games designed for Visual Pinball and other systems might also have a bunch of other associated files, such as the .directb2s files that many VP games use for backglass displays, and the ROM .zip files that VPinMAME loads when playing a game. PinballY doesn't really care about those; it just cares about that main file for each game that we call the table file.)

The table file is what PinballY uses to detect the existence of a game. This works great for Visual Pinball and similar systems, because it means that PinballY can find all of your installed games almost by magic, without any work on your part to slog through your table folders and manually enter all of the games. For any system like VP that uses table files, you only have to provide two pieces of information in the system settings dialog, and PinballY will automatically find all of your games:

Each time you run PinballY, it scans the Table Folder for each system and looks for all files matching the system's filename extension. For each file it finds, it automatically adds an entry for that game to the wheel UI. As a result, there's no need to manually create a list of your games anywhere. PinballY just figures it out automatically by scanning for matching files.

Table files for systems that don't use them

The snag with the table file scheme is that some pinball game systems - particularly some of the commercial games - don't use table files at all. Some game systems have all of the games built in to the program, or stored online, or something else entirely.

So how are you supposed to tell PinballY what tables exist for a system that doesn't have any table files?

The answer is that you still need the table files. But in this case, they don't need to be "real" table files that actually came with the game. They can be "dummy" files that you create manually:

Database files and media files

In addition to the basic "table file" that in effect declares the existence of a game to PinballY, the system also keeps several other pieces of information about each game:

To set up a new system, you actually don't have to think too much about these, because PinballY will take care of them automatically for the most part. The system will select default locations for the database and media files based on the name of the system that you enter in the new system's settings page when you first create it. PinballY will also automatically create the database files as needed when you use the Edit Game Details dialog to set up an individual game that's associated with the new system, and it'll automatically create media files for the system's games when you use the Media Capture commands.

So, in most cases, you can just leave the Database folder and Media folder entries blank when setting up a new system, and let PinballY select defaults based on the system name that you enter. You should only enter values in these boxes if you have some reason to override the defaults. See Files & Folders for more details on how these locations work.

Special settings for Steam games (and some others)

Many of the commercial pinball games these days are based on Steam. Steam games use a two-step launch process that requires some special attention in the PinballY setup. Some other game systems, including Future Pinball with the BAM extension, use the same approach, and need the same sort of special handling in PinballY.

"Two-stage launch" means that the game program starts up with not one but two .EXE program launches in Windows. You start the game by launching the Steam executable, Steam.exe, with a parameter telling Steam which actual game you're trying to start. Steam then fires up a second process using the actual .EXE program that contains the game's programming. After Steam starts up the real game program, Steam exits, leaving the game program running.

This requires some special setup in PinballY because of the way PinballY monitors the launched game to determine when it quits. Normally, PinballY assumes that the program you tell it to launch is the actual game program. So to figure out when the game is over, PinballY monitors that launched program process, and assumes that the game has ended when the program exits. This doesn't work for a two-stage launch process, however, because the program that PinballY launches initially doesn't keep running for long - it only runs long enough to start the second phase, and then exits. With PinballY's default assumption that the launched program is the game itself, this makes PinballY take control again prematurely, since it thinks the game is done as soon as that first "launcher" stage exits.

This two-stage arrangement is fairly common, so PinballY has special handling for it. But PinballY can't figure out on its own when the special handling is needed; you have to say so explicitly. The way you do this is via the Process Name box in the settings page for the system in the PinballY options dialog.

For any Steam-based game, the standard recipe for setting up the two-stage launch is as follows: