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

- If PinballX is installed on your system, the main media folder is <PinballX install folder>\Media
- Otherwise, it's <PinballY install folder>\Media

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:

- Media\Company Logos (PNG files with manufacturer logos: Williams, Gottlieb, etc)
- Media\Flyer Images (pictures of promotional flyers for the games)
  - Front
  - Inside1
  - Inside2
  - Inside3
  - Inside5
  - Inside6
  - Back
- Media\Instruction Cards
- Media\System Logos (PNG files with game system logos: Visual Pinball, etc)

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:

- Media\<system folder>\Backglass Images
- Media\<system folder>\Backglass Videos
- Media\<system folder>\DMD Images
- Media\<system folder>\DMD Videos
- Media\<system folder>\Launch Audio
- Media\<system folder>\Real DMD Color Images
- Media\<system folder>\Real DMD Color Videos
- Media\<system folder>\Real DMD Images
- Media\<system folder>\Real DMD Videos
- Media\<system folder>\Table Audio
- Media\<system folder>\Table Images
- Media\<system folder>\Table Videos
- Media\<system folder>\Topper Images
- Media\<system folder>\Topper Videos
- Media\<system folder>\Wheel Images

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 this pattern:

Game Title (Manufacturer Year).ext

For example, the playfield image for Funhouse might 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 game, not the file function. The only way you can tell which file is which is by their folder locations.

To display the exact base filename 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:

- If PinballX is installed on your system, the main table database folder is <PinballX install folder>\Databases
- Otherwise, it's <PinballY install folder>\Databases

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:

- If you use the Windows Setup installer (the .msi file distribution) to install PinballY, it creates a registry entry that the Windows "Add or Remove Programs" control panel uses to list installed programs and uninstall them on demand. This key has one of the following forms, depending on whether you installed the 32-bit or 64-bit version of PinballY:
  - HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\{XXXXX}
  - HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows\CurrentVersion\Uninstall\{XXXXX}

  Setup uses the first key if you're installing 32-bit PinballY on 32-bit Windows, or 64-bit PinballY on 64-bit Windows. The second key is used when you install the 32-bit PinballY on 64-bit Windows.

  The {XXXXX} part is a long sequence of hexadecimal digits enclosed in curly braces, known as a GUID (globally unique identifier). Each release has a different randomly generated GUID. That wasn't our bright idea; it's an artifact of the Windows Setup process. The easiest way to find the key for your current version is to select the parent Uninstall key in RegEdit, press Ctrl+F to bring up a search box, and type PinballY into the search box. That will find a "DisplayName" property under the right key, which will let you see the install GUID.

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