# GameSysInfo

A GameSysInfo object provides information on the PinballY configuration settings for a game player system, such as Visual Pinball or Future Pinball.

PinballY has very little built-in knowledge about the different player systems. PinballY tries to treat each system the same way, as a generic external program, with all of the information about playing a game with a given system captured in the configuration settings. As a result, almost everything that PinballY knows about a system is accessible to Javascript code via the GameSysInfo object.

The properties of the GameSysInfo object are actually "getter" methods that return live information from PinballY's internal configuration data for the various systems. You can't change these values by assigning to the properties.

## Creation

You don't create GameSysInfo objects directly. You get these objects from PinballY whenever it references player systems. The main source is the system property of the GameInfo object, which indicates which system a particular game is associated with.

## Lifetime

A GameSysInfo object is a Javascript object, so it stays valid as long as you keep a reference to it from somewhere in your Javascript code. The underlying system object that serves as the data source for the properties, however, can be affected by changes to the settings. For this reason, it's best to avoid storing references to these objects in global variables or object properties.

## Properties and methods

closeWindowName: A string giving the name or regular expression pattern to match to the title of the game window or windows that will receive the "close window" commands selected via the terminateBy property, when the user terminates a running game by pressing the Exit Game button. If this is left blank, the close commands are sent to all of the game's open windows. Otherwise, the close commands are only sent to the game's windows whose names match the string given here.

The interpretation of this property depends upon closeWindowNameIsRegex. If that property is false, the window name given here is just a literal string to match to the window titles. The window name has to match the property string exactly, except that upper/lower-case differences are ignored. If closeWindowNameIsRegex is true, the string here is treated as a regular expression pattern, using the normal Javascript-style regular expression syntax. The close command is then sent to windows that match the pattern.

The regular expression option lets you deal with applications where the window name is different every time, but follows some predictable template pattern. For example, if the game window is always named "Super Deluxe Pinball Pro (The Addams Family)", with the name of the active table inserted in the parenthesized part, you could match this with a regular expression pattern like "Super Deluxe Pinball Pro \\(.*\\)", since the .* sequence will match whatever table name gets inserted between the parentheses.

closeWindowNameIsRegex: A boolean specifying whether closeWindowName is treated as a literal string (closeWindowNameIsRegex is false) or as a regular expression pattern (true).

closeWindowTimeout: A number giving the maximum time, in milliseconds, that PinballY waits for the game program to close after sending the window-closing commands specified by terminateBy. If the game program doesn't exit by itself within this time limit, PinballY will try to close the program by terminating its process. This is meant to be a last resort for programs that crash or freeze when their windows are closed, which would make PinballY get stuck indefinitely if it just waited without a time limit for the program to exit.

databaseDir: A string giving the name of the folder containing the XML database files that list this system's configured games. This is the name of the folder only, with no path; the full path is based on the system-wide database folder setting. See Table Databases for details on how these folders are laid out.

dbFiles: An array of objects describing the table database files found for this system. The table database files are the XML files that list the games associated with this system and store most of the metadata for each game (title, manufacturer, year, etc). Each system can have one or more of these XML files. There's always a primary "generic" file, whose full path is given by the genericDbFile property, and which also appears in this list. Any additional files are "category" files. These have exactly the same layout as the primary file, but the games in any of these additional files are implicitly given category tags matching the filename of the containing XML file. For example, if there's a file called "Fantasy.xml" in the database folder, the games listed in this file are given the category tag "Fantasy". This multi-file layout is for compatibility with HyperPin and PinballX, which use it as a simple category scheme that can assign each game to one category. PinballY has a more generalized category scheme that lets you assign any number of category tags to a game, which it handles through the separate GameStats.csv database file, but PinballY also recognizes the legacy file structure, so that existing database files can be used directly.

Each object in the dbFiles array corresponds to one such file, and has the following properties:

- category: If this file defines a category, the category name as a string. This is omitted for the primary "generic" XML file for the system, which doesn't imply any category tags.
- categoryFilter: A FilterInfo object describing the category filter. This is omitted for the primary "generic" XML file for the system.
- filename: The full filename (with absolute path) of the database file.

defExt: The default filename extension for the system's game files, including the initial period: ".vpt" for Visual Pinball 9, for example. An empty string if the system has no default extension.

displayName: The display name of the system. This is the name used to refer to the system in the UI, such as in the settings dialog, game information popups, etc.

dofTitlePrefix: The prefix string used to form DOF ROM names for games of this system. For example, Future Pinball uses "FP:" as a prefix for its DOF entries, to distinguish games from the Visual Pinball equivalents.

envVars: A string giving any environment variables added to the system environment variable block when launching the system's executable to play a game. The standard format for Windows environment variables is used, "VAR=VALUE". Multiple variables are separated by semicolons.

exe: A string giving the filename (with full absolute path) of the program executable (.EXE file) for the game system. This is just the filename, with no command-line parameters; parameters are stored separately in params.

expand(str, game): Expand command-line substitution variables in the string str, using the game details from game, a GameInfo object specifying a game to use. Subsitution variables can be specified using [square brackets] in the params and runXxx variables. This method carries out the same variable substitutions that PinballY would normally apply when launching the given game with this system. game should be a game associated with this system; the results aren't meaningful for games associated with other systems.

genericDbFile: The filename (with full absolute path) of the primary "generic" XML database file for the system. This is the main file, which doesn't imply any category tags for its games. This file also appears in the dbFiles array.

mediaDir: A string giving the name of the parent folder for media files (table images, table videos, etc) for games based on this system. This is the parent folder name only, with no path; the full path is based on the system-wide root media folder path. This is the "parent" folder in that all of the individual media files are in type-specific subdirectories within this folder. See Media Files for more details on the media folder structure.

nvramPath: The path to the NVRAM (non-volatile RAM) files for the system, as specified in the configuration. This is for the sake of the PinEMHi high-scores program, which uses the NVRAM files to read high score information. This is usually an empty string, which means that the standard NVRAM path location for each system is used. PinEMHi currently only works with Future Pinball games and VPinMAME ROM-based games, so this isn't meaningful for other systems.

params: The command-line parameters to use when launching the system's executable to play a game. This is the "raw" version of the parameters, which can contain substitution variables enclosed in [square brackets]. See Parameters in the System Options dialog for a list of the substitution variables.

processName: A string giving the process name to monitor when the game is running, to determine when the game has terminated. This is used for systems where the program specified in the exe parameter is actually just a launcher that starts the real game program, such as Steam. This is an empty string for most systems, where the process to be monitored is the same as the program specified in exe.

runAfter: A string giving the "Run After" command, which is invoked after a game launched using this system terminates. The main PinballY window displays a "Game Exiting" message while this command is running. This is given as a full Windows command line string, specifying a program to be run and its parameters.

runAfterPost: A string giving the "Run After Post" command. This is a second "after" command that runs after the runAfter command. The main PinballY window is cleared to show only a blank, black background while this command is running. This is a full Windows command line string, specifying a program to be run and its parameters.

runBefore: A string giving the "Run Before" command, which is invoked immediately before a game for this system is launched, after the "Launching" message has been displayed in the PinballY main window. This is a full Windows command line string, specifying a program to be run and its parameters.

runBeforePre: A string giving the "Run Before Pre" command, which is invoked as the first step in launching a game with the system, with the main PinballY window showing nothing but a blank, black background. This is a full Windows command line string, specifying a program to be run and its parameters.

startupKeys: A string giving a sequence of keystrokes to send to the program after it launches.

swShow: An integer giving the Windows "Show Window" code to use when launching the system's executable. This can be any valid Show Window code (see the Windows SDK documentation for the full list), but it's usually one of the following:

- 0 (SW_HIDE) - hide the window
- 2 (SW_SHOWMINIMIZED) - minimize the window and make it active (that is, give it keyboard focus)
- 5 (SW_SHOW) - show the window normally and make it active

systemClass: A string with the "system class". This is one of the following:

- "FP" - Future Pinball (any version)
- "STEAM" - any Steam-based game
- "VP" - Visual Pinball 9 or earlier
- "VPX" - Visual Pinball 10
- "" - any other system

Note that PinballY tries to treat each system as an equal "black box", with all of the information about a system captured in the settings. There's almost nothing in PinballY that depends on knowing if a system is a Visual Pinball variant or whatever else. The black box approach is important because it makes the program adaptable to new systems and future versions of existing systems. The only places that PinballY uses the system class internally are (1) to streamline the settings dialogs, by filling in suitable defaults when possible, (2) to provide intelligent defaults for missing information when loading the config files, and (3) when invoking PinEMHi to get high scores, since that program has hard-coded dependencies on VP and FP.

tablePath: The full absolute directory path for the playable game files for this system. For Visual Pinball, for example, this is usually the Tables folder within the VP program folder.

terminateBy: A string giving the termination mode for the program, which determines how PinballY tries to terminate a running game when the user presses the "Exit Game" button. This can one of the following:

- "CloseWindow" - PinballY sends both the WM_CLOSE and SC_CLOSE commands to the target windows. This is a way of not having to choose between the two command types, by letting PinballY simply try each one to see which works. Some applications will respond to one and ignore the other, some will accept both, and some won't respond to either one; it's just a matter of how the individual application is programmed, so the only way to find out is by experimentation. This option is the default because it's the most automatic, but some applications might have an adverse response to one or the other command; the "WM_CLOSE" and "SC_CLOSE" options let you choose more specifically for such cases.
- "WM_CLOSE" - PinballY sends the WM_CLOSE command to the target windows. This is equivalent to clicking on the window's "close box", which is the "X" icon at the top right of the window's caption bar. Windows that don't have close boxes displayed might not respond to this command.
- "SC_CLOSE" - PinballY sends the SC_CLOSE system command to the target windows. This is equivalent to pressing Alt+F4, or clicking on the window's "system icon" at the top left of the window's caption bar and selecting Close from the menu that drops down. Most top-level windows will respond to this command by exiting the application, but some programs might simply ignore it.
- "PinSim::FrontEndControls" - PinballY sends a terminate command via the PinSim::FrontEndControls message interface, which is a published protocol that's designed to help front-end programs like PinballY coordinate actions with the programs they launch. This option only works with programs that implement the special protocol, which is currently limited to new versions of Visual Pinball released in October 2024 and later. This option should be the most reliable option for programs that implement it, because the special protocol has a well-defined command that explicitly tells the program to exit, which allows the target program to initiate the necessary steps to terminate. All of the other options can only try to get the program to exit implicitly as a side effect of closing its last window, which doesn't always work.
- "KillProcess" - PinballY asks Windows to terminate the process (without going through the program's user interface).
- "" - use the default (same as CloseWindow).

The "target window" for the close commands is chosen by the closeWindowName property. When the property is left blank, PinballY sends the close commands to all of the game's open windows. When the property names a window, PinballY only sends the close commands to matching windows.

workingPath: The working directory path to use when launching the system's executable, as a full absolute path. This sets the current working directory for the child process, which determines its default folder location if it accesses files without absolute path specifiers. This is usually the same as the folder containing the program exectuable.