The gameList object represents the program's internal database of games. Methods on this object provide Javascript access to the list of loaded games and their details.
gameList is an event target object, so you can use the standard event methods (on(), off(), addEventListener(), etc) to add and remove event listeners. See EventTarget.
gameList serves as the event target for the following event types:
The gameList object has the following properties and methods:
gameList.createCategory(name): Creates a new category with the given name.
gameList.createFilter(desc): Defines a custom filter, which selects games for the wheel UI according to a selection rule you define. desc is an object describing the filter. Returns a command ID, automatically assigned as a unique menu command for the filter. You can use the command ID to place the filter on custom menus. See Custom Filters for details and examples.
gameList.createMediaType(desc): Defines a new custom media type, which can be used with Custom Media Windows or simply to access other types of media (beyond the standard types that PinballY knows about, such as Backglass Images and Table Videos) through Javascript. desc is an object describing the new media type; see Media Types for full details on using this method to create a new media type.
gameList.createMetaFilter(desc): Creates and installs a custom metafilter. desc is an object describing the new filter. See Metafilters for more details. The return value is an opaque identifier that uniquely identifies the filter, which can be used to later remove the filter via removeMetaFilter().
The new metafilter is placed into effect immediately, and the current game selection list in the wheel UI is refreshed so that the new filter is taken into account.
A metafilter is a "global" filter that's always active in addition to the current user-selected filter, allowing it to further narrow the games selected by the regular filter, or even completely override the decisions of the regular filter. More than one metafilter may be active at once, so creating a new one doesn't replace or remove any others that are already in effect.
gameList.deleteCategory(name): Deletes the given category. The category tag is removed from any games tagged with the given category, and the category is removed from the master list of categories returned by gameList.getAllCategories().
gameList.getAllCategories(): Returns an array with the names of all of the categories currently defined. Categories are arbitrary tags, defined by the user, that can be assigned to games for filtering purposes. Each category implicitly defines a "category filter" that the user can select through the menu system to show only games with the corresponding category tag. This lets the user select subsets of games based on personal criteria beyond the built-in filter options that the system provides.
gameList.getAllFilters(): Returns all of the filters currently defined, as an array of FilterInfo objects. Each object represents one filter.
gameList.getAllGames(): Returns an array consisting of a GameInfo object for each loaded games. The array is arranged in wheel display order, which is alphabetical by the display name of each game. If you need to iterate over all games, this is more efficient than calling getGame() for each game. In addition, the returned array is a snapshot of the complete game list at the time you call this function, so it isn't be affected by subsequent insertions, deletions, or reorderings of the live game list, as getGame() is. This makes it suitable for making edits to the live game list in the course of the iteration, since edits to the live list won't affect the snapshot and thus won't affect the iteration.
gameList.getAllWheelGames(): Returns an array consisting of a GameInfo object for each game on the wheel. That is, each game selected by the currently active filter. The first (0th) element of the array represents the currently selected game. Each subsequent element represents the next game to the right on the wheel. Since the wheel is conceptually circular, the last element is the game displayed in the wheel one position left from the current game.
gameList.getCurFilter(): Returns a FilterInfo object describing the filter currently selected in the wheel UI.
gameList.getFilterInfo(id): Returns a FilterInfo object describing the filter identified by id. The id value is a string with the filter ID. See FilterInfo for details.
gameList.getGameInfo(id): Returns a GameInfo object, which has properties to access most of the details of the specified game. id can be either a config ID string (the permanent identifier for a game, suitable for storing in an external location such as a config file) or a numeric game ID (the internal ID that refers to the in-memory record for a loaded game). If the ID is invalid or refers to a game that's no longer loaded, the function returns null.
gameList.getGame(n): Returns a GameInfo object representing the nth game in the loaded game list. n is an index into the list of all loaded games, ranging from 0 to the number of games in the list minus 1. Returns null if n is out of range. You can get the total number of games currently in the list from getGameCount().
gameList.getGameCount(): Returns the number of games in the list of all loaded games. You can retrieve individual games via getGame(n), where n ranges from 0 to the game count minus 1.
gameList.getMediaDir(): Returns a string giving the Windows file system path of the media folder. This is the root folder where game media are stored, as configured in the option settings.
gameList.getWheelGame(n): Returns a GameInfo object representing the game at offset n from the selected game in the wheel. The currently selected game is at offset 0, so gameList.getWheelGame(0) refers to the current game. Offset 1 is the next game to the right of the current game, 2 is the next game to the right of that, and so on; -1 is the game to the left of the current game, -2 is the game to the left of that, and so on. Since the wheel is conceptually a circle, offset N comes back to the currently selected game when N is the number of games showing on the wheel (and by the same token, offset -N, 2N, -2N, etc all wrap back to the current game).
This method is specifically restricted to the games that are included in the current game wheel, taking into account the current active filter. This is the same as the list of games that the user can currently navigate through via the Next and Previous command buttons. If the user (or your Javascript code) selects a different filter, it will naturally change the list of games that this method can access. If you want to directly access all of the games that PinballY current knows about, use the getGame() method instead; that gives you access to the entire current list of games.
gameList.getWheelCount(): Returns the number of games currently shown in the "wheel" UI. This includes all games selected by the current filter.
gameList.refreshFilter(): Refreshes the filtered game list, as though switching to the current filter anew. This can be used after making any changes to game metadata or other factors that might affect which games are selected by the current filter, to ensure that the updated selections are immediately reflected in the wheel UI.
gameList.renameCategory(oldName, newName): Renames the given category. An error occurs if the category referenced by oldName doesn't exist, or if there's already an existing category with the new name. The category tag is renamed globally, so any games tagged with the old category name are updated to the new name.
gameList.removeMetaFilter(id): Removes the metafilter identified by id, which is an identifier returned from a previous call to createMetaFilter(). This cancels the specified metafilter and removes its effect on the game selection list. The current wheel selection list is updated as a side effect, as though you refreshed the current filter.
gameList.resolveMedia(subfolder, baseFileName, type): Resolves a "global" media file. Global media are unrelated to any particular game; they're used for the default background images when a game has no media of its own for a given window, startup audio and video, and for the underlay. This method uses the same search algorithm that the system uses for its own global media files, so it ensures that you find the same file the system would for a given case. subfolder is a folder name within the main media folder where the file is located, such as "Images" or "Videos". baseFileName is the root part of the file name to find, without any path or extension. type is an optional string specifying the media type to search for, which determines which filename extensions will be matched, using the same file type extensions that the system would use when searching for the corresponding media type. The possible values for type are:
If you omit type (or set it to an empty string), the method simply searches for the exact file name you specify, which in this case must include the desired extension. This lets you limit the search to, say, a .PNG file, excluding other image file types that the system would normally accept.
If a matching file is found, the full file name (with path and extension) is returned as a string. If no match is found, undefined is returned.
gameList.setCurFilter(id): Changes the active filter for the wheel UI. id can a string with the ID of the desired filter, or a number in the range command.FilterFirst to command.FilterLast (see Commands), identifying the filter by its associated menu command. The filterselect event is not fired when you change the filter with this function. However, a gameselect event is fired if the current game selected in the wheel must be changed as a result of the filter change. This happens if the previously selected game isn't included by the new filter, requiring the system to automatically switch to a game that is included by the new filter.
gameList.setWheelGame(n, options): Changes to a new game selection in the wheel UI. n is a number giving the offset from the currently selected game, in wheel slots: 1 is the next game to the right, 2 is the next game after that, and so on, while -1 is the next game to the left, -2 is the next game before that, etc. Since your Javascript code is initiating the game selection change, the gameselect event is not fired.
The options argument, if provided, is an object with properties that specify how the game change looks in the UI. If this is omitted, the defaults are used for all options:
Even when animation mode is used, this method doesn't trigger the sound effects or DOF effects that are normally used when the user navigates through the wheel with the buttons. If you want to simulate the exact effect of navigating by button presses, you can use mainWindow.doButtonCommand() with the "Next" and "Prev" button codes.