Files & Folders

PinballY stores a bunch of files to keep track of your list of games and their media files. Ideally, you shouldn't have to know anything about these files or where they're stored, because PinballY tries to make all of its internal storage details as invisible as possible. But "invisible" is only good when things are working. It backfires when something goes wrong, because it's hard to troubleshoot what you can't see.

So, for the sake of troubleshooting, this section gives you the details on where PinballY stores its various files. Hopefully, this will let you figure out what PinballY is thinking when looking for a particular file, so that you can figure out why PinballY can't find it, is finding the wrong copy, or whatever else seems to be wrong.

Media Files

PinballY uses the same media folder structure that HyperPin and PinballX use, to make it easier to use existing files that you already have installed from one of those programs.

Main media folder location: All media files are stored within the main Media folder, which you can configure via your settings (see Folder Options). You can choose a specific folder location in the settings if you wish, but I'd recommend using the default setting. Here's how the default setting works:

System folders: Each "system" (that is, pinball player program, like Visual Pinball 9 or Future Pinball) has its own subfolder under this main media folder. By default, this folder has the same name as the system, but you can set it for each system individually using the options dialog.

So, for example, the system folder for Visual Pinball 9 might be <PinballX install folder>\Media\Visual Pinball 9.

Media type folders: Each "media type" has its own subfolder. Things get a little hairy(ier) here, because some media types are "generic", meaning that they're not differentiated by system, and others are system-specific. I probably wouldn't have made this distinction if it weren't already the way that PinballX and HyperPin did it, but I carried it over for the sake of compatibility; such is the cost of easy migration.

The "generic" media types have their type folders directly under the main Media folder. These are as follows:

Note that the Flyer Images folder has its own subfolders, which store the individual pages of the flyers, one page per image and one image per folder.

The system-specific media types are nested under the system folder for each system:

The <system folder> path element is replaced by the "Media Subfolder" name for the system, which you can view and change via the options dialog. The default subfolder name is the same as the system's name (e.g., "Visual Pinball" or "Future Pinball").

Media files for each game: The media files for a game (the playfield image, backglass image, etc) are distributed among the media folders listed above according to their function: the main playfield image goes in the Table Images folder, the backglass video goes in Backglass Images, and so on.

Within those folders, all of the files for a given game have the same name, based on the game's "Media Name" setting. By default, when you first set up a new game, the Media Name is set based on this pattern:

Game Title (Manufacturer Year)

For example, for Funhouse, the media name might be set by default to Funhouse (Williams 1990). PinballY uses that default pattern for the Media Name because it's the pattern used by HyperPin and PinballX.

You can also override the Media Name for each game, by setting a different setting in the Game Details dialog.

Once you know the Media Name for the game, you can easily figure out the names for all of the game's media files. They all use the base Media Name plus an appropriate file type suffix (extension). For example, for a JPEG file, you'd take the base Media Name and add .jpg, the standard suffix for any JPEG file. So if the Media Name is Funhouse (Williams 1990), a JPEG playfield image would be called Funhouse (Williams 1990).jpg. The backglass and DMD images for Funhouse could have exactly the same name, since the naming pattern is based purely on the Media Name. The way you tell these files apart is by their folder location.

To display the exact Media Name used for a game's media files, select the "Information" command in the main menu to bring up the game info box. The base media filename is displayed in the box. You can also get a full list of the specific media files that PinballY found for the current game, with full names and folder locations, using the "Show Media Files" command in the Game Setup Menu (reachable from the Operator Menu).

Why we use this crazy "same name for everything" format: Blame history. This scheme of using the same name for multiple files might seem rather confusing, especially when you're trying to manage the files manually in Windows Explorer. It might seem more logical to use different names for each file. I'd completely agree. But the reason we do it this way is that there's a large collection of existing files out there that already use this scheme. This format became so widely used for media packs on the Web because it's the format that HyperPin used. HyperPin was the original front end, and the only one around for many years, so it quickly became the standard format by default. When PinballX came along, it used the same format for the sake of compatibility, so that people could use all of those existing media pack files from HyperPin. We're continuing the tradition for the same reason.

Manufacturer logos: Please see Info Box Options for details on how to set up manufacturer logo files.

System logos: Please see Info Box Options for details on how to set up manufacturer logo files.

Table Databases

PinballY keeps track of the games displayed in the "game wheel" via a set of table database files. These files use the conventions used by HyperPin and PinballX, because we wanted you to be able to use your existing files if you already had one of those systems previously installed.

Main table database folder location: The table databases are all stored within the main Table Databases folder, which you can configure via your settings (see Folder Options). You can choose a specific folder location in the settings if you wish, but I'd recommend using the default setting. Here's how the default setting works:

System folders: Each "system" (that is, pinball player program, like Visual Pinball 9 or Future Pinball) has its own subfolder under this main database folder. By default, a system folder has the same name as the system, but you can set it for each system individually using the options dialog.

So, for example, the system folder for Visual Pinball 9 might be <PinballX install folder>\Databases\Visual Pinball 9.

XML files: Finally, we come to the actual files! Each table database file is an XML file. You'll find one or more of these in the system folder for each system.

Each system has one "main" XML file. This is the "main" file because it has the exact same name as the system folder, plus of course the .xml suffix. For example, the Visual Pinball 9 main file might be <PinballX install folder>\Databases\Visual Pinball 9\Visual Pinball 9.xml.

In addition to the "main" file, you can have any number of additional .xml files with other names. PinballX used these files to represent "lists", which is PinballX's version of a category. PinballY recognizes these files and treats them as categories as well, so that your existing PinballX data gets treated the same way in PinballY. PinballY automatically creates a category for each .xml file it finds apart from the "main" file for each system. All known categories are available as filters in the main menu, so that you can limit the view to games in a given category.

Apart from the category identification, PinballY treats all of the XML files in a single system folder as one big list of that system's games. So the games that you should see listed in the "game wheel" for a given system should be the combination of all of the contents of all of the XML files in that system's database folder.

The XML files follow the HyperPin and PinballX XML format, which looks like this:

    <menu>
        <game name="Hot Shot (Gottlieb) (1973)">
            <description>Hot Shot (Gottlieb 1973)</description>
            <rom></rom>
            <manufacturer>Gottlieb</manufacturer>
            <year>1973</year>
            <type>EM</type>
            <hidedmd>True</hidedmd>
            <hidetopper>True</hidetopper>
            <hidebackglass>True</hidebackglass>
            <enabled>True</enabled>
            <rating>3.5</rating>
        </game>
    </menu>

It's better not to edit these files by hand, since it's easy to miss a < or > or otherwise mess up the rigid XML format. It's better to edit the game information via the Game Setup dialog, which you can access from the Operator Menu in the program. But these files are pretty easy to read, so it's helpful to know where they are, and to be able to take a look inside, if you're trying to troubleshoot a problem. You can view their contents with any text editor.

Table Statistics

In addition to the table database files above, PinballY keeps a separate collection of information on tables in a file called GameStats.csv, in the main PinballY install folder. This file stores additional information on the tables beyond what the HyperPin/PinballX database format can store.

This file is in an all-text format, so you can view it with any text editor, but it uses a structured format that makes it kind of hard to read (and I definitely wouldn't recommend editing it by hand). The file uses the CSV (comma-separated value) format, which was designed for data exchange between programs like spreadsheets and database managers that work with tabular data. If you do want to view it, the first line of the file gives a list of column names that describe the structure of the data, and each line after that is a "database row" that contains the data for one game, in the column format described by that first column name line.

If you want to import the GameStats.csv file into another program or convert it to a different format, you'll need to know which CSV parameters it uses, since CSV files come in several varieties. We use commas as field separators, double quote marks (") as quotes, and stuttered quotes ("") for embedded quotes in values. With those parameters set properly, you can mechanically translate CSV into just about any other format.

(It would have been nicer to store everything about a game in one place, namely the XML database file. There are two reasons we don't. The first is that we wanted to maintain the greatest degree of compatibility possible between the PinballY and HyperPin/PinballX databases, so that you can switch between the programs easily. So we didn't want to add anything to the XML files that the other programs wouldn't understand, to avoid confusing them or making them unable to read the files. We therefore only use the XML files for the metadata that the other programs already store there. The second reason is that XML entries only exist for "configured" games, where you've manually set up the metadata. PinballY, unlike the other front ends, lets you see all of your table files in its wheel UI. So we needed a separate place to store information about unconfigured games.)

Settings

All of PinballY's option settings are in the file Settings.txt, stored in the main PinballY install folder. This is a human-readable, plain text file that you can peruse and edit by hand if you wish. You shouldn't need to edit options this way, because all of the options are configurable through the program (via the Options dialog or via various menus), but it can be handy for troubleshooting purposes because it lets you see all of your settings in one place.

Resetting to defaults: If you think you've done something to muck up your settings beyond repair, and you want to restore the original factory defaults, simply delete Settings.txt. There's no need to uninstall the program if you just want to reset the options, since all of the changeable settings are in that single Settings.txt file.

Windows Registry

PinballY stores absolutely nothing* in the Windows Registry. The registry is such a source of misery for other software that I try to avoid it entirely.

*Okay, what I really meant was nothing of its own. There actually is one key that might be set, depending on how you installed the program:

Task Scheduler

If you enable automatic program launch at startup via the Options dialog, PinballY will create a system Task Scheduler task called "PinballY Startup Task". This will appear in the top-level group of system tasks, which you can view by running the Windows Task Scheduler control panel: press Windows+R and type taskschd.msc into the Run box.

You can modify or delete the PinballY startup task using the Task Scheduler control panel. It's better to let PinballY manage it, so that you don't accidentally make a change that makes the task stop working, but it's perfectly safe to simply delete the task if you want to turn off the automatic launch.