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.
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. The folder structure is hierarchical - folders within folders - and each level of the folder path comes from a different option setting that you can change.
The basic hierarchical path for a media file looks like this:
Within those folders, each game has a media file named according to the games title, manufacturer, and year. Read on for where all of these different pieces come from.
Main media folder: 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:
Per-system media 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.
For example, Visual Pinball 9's system folder 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:
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.
Okay, we've seen how PinballY looks for the media files for a given game. But what happens when there isn't a matching file? In this case, PinballY displays a default media file, which acts as a placeholder for missing game media. PinballY comes with a set of default default files, which you can replace those with your own images and videos if you prefer.
There are actually two layers of default files: per-system defaults, which apply to all games built with a given system (for example, a default backglass for all Visual Pinball 9 tables); and global defaults, which serve as the last-resort fallback for all games. The per-system default media files are always preferred when they're present, and the global defaults are used when no system default files are available.
Per-system default media: Default videos and images that you want to supply for a particular system go in the following folders:
Within these folders, create any combination of the following files, which are used in the respective windows:
The extensions (.ext) are the usual set of supported format extensions for images and video files: .png, .jpg, .mp4, etc. ("No Custom Window Media" is used for custom windows created through Javascript; see Custom Media Windows for details.)
For example, here's how you'd name a default video for the backglass window for Visual Pinball 9 games (assuming that your VP9 media folder is called "Visual Pinball 9"):
Note that the folder and file naming conventions for the per-system default media files are the same that PinballX uses, so if you're already set up these sorts of defaults for PinballX, they should carry over without any changes.
Global default media: When a game doesn't provide its own media files, and there aren't even any per-system default files, PinballY looks for a global default video or image. PinballY comes with a set of default image files, but you can supersede these with your own video or image files if you have nicer-looking ones that you prefer.
The custom global default files go in the following folders:
Within those folders, the default files for the individual windows have the following filenames:
PinballY defaults: If you don't provide your own global default media files as described above, PinballY falls back on its own default images as a last resort. These are stored the Assets folder within your main PinballY install folder. Within Assets, the same subfolders and default image file names are used as in the global default media folders (Images\Default Backglass.png, etc).
Note that you shouldn't customize by replacing the files in the Assets folder, since PinballY thinks of those as its own, and thus might feel free to modify them on future updates. Always use the Media folder locations above for your customizations instead.
This is an advanced topic that will only be interesting to you if you're planning to run both PinballX and PinballY on an ongoing basis, so that you can switch back and forth between the two.
If you're planning to continue using both programs, you're probably sharing the media files between both programs, by keeping everything in PinballX's media folder tree, and telling PinballY to use the media from PinballX's folder. In this case, PinballY has a special feature that lets you override just the default media files, while keeping all of the other files shared. That gives you the ability to give PinballY a slightly different, custom look, at least when default backgrounds are involved.
The trick is to place your default images and videos in the PinballY\Media tree rather than in the PinballX media tree. In the sections above where we started a path with the <Main media folder>, you'd just replace that portion of the path with <PinballY install folder>\Media. Everything else stays the same.
Here's how this "override" feature works. For the various default media items, PinballY always searches in its own PinballY\Media folder before checking your "Main" media folder from your settings. If it finds the file it's looking for in the PinballY\Media, it uses that one; otherwise, it repeats the search in the main media folder. So if you're sharing media from the PinballX media folder tree, this ensures that a PinballY "override" is found first and used instead. If you don't want to overide anything, you don't have to, since the files in your main media folder are still used by default.
For the most part, image and video files are simply displayed just as they appear in the file, scaled to match the window size or display area size.
Playfield images and videos must be rotated so that the bottom of the playfield is at the left side of the image/video:
This is the same orientation used in the HyperPin media packs, so downloadable media you find on vpforums.org and similar sites will usually already be rotated properly. Likewise, if you capture live game play images and videos through PinballY's built-in capture feature, PinballY will capture them in the correct orientation. Since PinballX uses the same rotation for its media, capture tools designed to create media for PinballX should also produce the correct results. If you're using generic screen capture tools, though, you'll need to tell your tool to apply the necessary rotation during capture, or go back and edit the file after the capture to apply the rotation. If you don't already have a tool that can do that, you can use ffmpeg - it can rotate a video and re-encode it with the new rotation.
This weird rotation rule applies only to playfield images and videos. The media shown in the backglass window and the other windows are displayed with their original orientation.
Wheel icon image file formats:
Instruction card image file formats:
Image file formats (other contexts):
Video file formats:
Audio file formats:
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">
<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.
The <game name="xxx"> field in the XML specifies the table file name. This must not include a directory/folder path, since the system uses the system settings to determine the directory location for table files. The player system's filename suffix is optional (e.g., .vpx for Visual Pinball 10 games), but it's usually omitted.
The title of the game that's displayed in the wheel UI comes from the <description> field. This should use the format Title (Manufacturer 1980), where 1980 is the release year.
Why do we include the manufacturer and release year in the <description> field, when they're also specified separately in the <manufacturer> and <year> fields? Because that's the way HyperPin and PinballX do it. PinballY generates its XML using the same redundant format so that those other programs will still be able to read the XML. And PinballY accepts the redundant information when reading the files, so that you can directly use XML files that were originally created for the other programs. PinballY will also accept <description> text that only has the title, using the separate XML fields to get the manufacturer and release year data. However, it's better to use the full form, because that's more compatible with the other programs (in case you ever want to switch), and it will also avoid any ambiguity if the game title itself happens to contain a parenthetical at the end.
If there's no <description> field, the filename from the <game name="xxx"> attribute will be used as the display title.
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 located in the main PinballY folder by default, but you can override its location with a command line option, /GameStats, when launching PinballY.
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.)
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.
This file is located in the main PinballY folder by default, but you can override its location with a command line option, /Settings, when launching PinballY.
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.
PinballY stores nothing of its own in the Windows Registry. The registry is such a source of misery for other software that I try to avoid it entirely.
However, if you install via the Windows SETUP installer using the .msi download, the installer places two keys in the registry. These keys are purely for SETUP's use, and aren't used by PinballY itself, so deleting or changing them won't have any effect on normal program operation. They're also unique to PinballY, so they won't affect any other programs.
The {XXXXX} part is randomly generated for each PinballY version, so it changes on each version. It's a long sequence of characters (hexadecimal digits, to be more precise) in curly braces, known as a GUID (Globally Unique IDentifier). This is Microsoft's way of uniquely identifying program versions. Unfortunately, being random, it has no relationship to the nominal program version, so there's no way to determine it other than to search the registry. The easiest way to find it is to open RegEdit, navigate to the parent key (...\Uninstall), press Ctrl+F to bring up a search box, and type in PinballY. That will find the key via its DisplayName property, which the installer will have set to "PinballY".
If you're running the 32-bit version of PinballY on a 64-bit Windows system, the key will have a slightly different name, due to the way Windows segregates 32-bit and 64-bit applications: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows\CurrentVersion\Uninstall\{XXXXX}
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.