HighScoresEvent

This event class is fired when the system retrieves high score information for a game. High score information is normally handled through the external program PinEMHi. PinEMHi is included with the PinballY install, and PinballY invokes it automatically when needed, so this isn't something that the user is even normally aware of.

This event has the following subtypes:

• highscoresrequest: Fired when PinballY is about to launch PinEMHi to retrieve high scores for a game. This event can be canceled, which prevents PinballY from invoking PinEMHi, and can return its own substitute high score information.
• highscoresready: Fired when PinballY receives results from PinEMHi. This event can't be canceled, since the high scores have already been received.

The event target for this event type is the gameList object.

When are high scores requested?

PinballY normally requests high scores for a game when the game is first selected in the wheel UI. Once the scores are obtained from this initial request, they're kept in memory, so that they can be used again the next time the game is selected.

When you launch a game session, PinballY discards any cached scores for the launched game, just in case you have a particularly good time with it and set a new high score. PinballY will make a fresh request for the game's high scores the next time it's selected in UI, which usually happens as soon as you exit the game and return to the PinballY window.

See High Scores for more on the high score detection system.

Where does PinEMHi find score information?

PinEMHi can read two sources of high score data:

• VPinMAME NVRAM files. VPinMAME is the program that Visual Pinball uses to emulate ROM software for arcade game re-creations. In their original arcade incarnations, most solid-state pinball machines had special "non-volatile" memory (RAM) chips that they used to store settings and high score information. VPinMAME emulates this non-volatile RAM using disk files, so for any Visual Pinball game you've played on your machine, you'll find a corresponding rom-name.nvram file in the VPinMAME folder tree. These files contain the exact byte layout that the original arcade ROMs used, so it can be pretty random looking to the naked eye. Fortunately, the NVRAM memory layout for most commercially released games has been decoded over the years by hobbyists with good reverse-engineering skills (and a lot of time on their hands). PinEMHi uses those known memory layouts to read your VPinMAME NVRAM files and extract the high scores in a human-readable format.

  (As an interesting bit of pinball trivia, the "non-volatile" RAM that they used on the original machines wasn't truly non-volatile; flash memory hadn't been invented yet. They actually used ordinary volatile RAM, with a trio of AAA batteries supplying a constant trickle of power to keep the data alive. Ask any Williams System 11 pinball machine owner how badly damaged their system board is from the alkaline battery leakage.)

• Future Pinball NVRAM files. Future Pinball doesn't use VPinMAME or ROM emulation. Instead, it provides its own Visual Basic scripting that table authors use to re-create game rules. One of FP's scripting features is its own equivalent of VPinMAME's NVRAM files. These use FP's own proprietary format, not the original ROM format. PinEMHi knows how to parse these files to retrieve high score data.

In both cases, PinballY automatically figures out where to find the relevant files based on program install paths.

Note that PinEMHi only understands the two formats above. For example, it doesn't work with any of the commercial pinball game systems. More subtly, it also doesn't work with any Visual Pinball games that don't use ROM emulation. That means that PinEMHi can't read high score information for VP re-creations of electro-mechanical (EM) games (since EM games don't use ROMs) or of most VP "originals" (games not based on arcade machines, but designed from scratch as VP virtual tables).

Setting custom scores

You can use the high score events to override or supplement the normal PinEMHi score retrieval mechanism.

To override PinEMHi score retrieval for a given game, create a listener for the highscoresrequest event, and use event.preventDefault() to cancel the event. This tells PinballY to abort the PinEMHi invocation. PinballY will simply consider the game to have no high score information at that point until you supply your own custom data.

To supplement PinEMHi score retrieval, create a listener for the highscoresready event, and check the success property of the event object. If success is false, it means that PinEMHi was unable to retrieve the score data for the game. You can use this to detect games that PinEMHi doesn't cover, such as Farsight Pinball Arcade games or Visual Pinball games that don't use ROM emulation, and supply our own code to read high scores for games that you know how to handle specially.

In either case, you can then call gameInfo.setHighScores() to apply your own high score data to the game. See the description of that method for more details.

Properties

This event type has all of the standard event properties and methods (see the Event class). In addition, it has the following:

• game: A GameInfo object identifying the game whose high scores are being requested or received.
• scores: For a highscoresready event only, this contains an array of strings giving the retrieved score information.
• source: For a highscoresready event only, this is a string identifying the source of the score data. This is one of the following string values:
  • "cache": the scores were already cached in memory for this game
  • "file": the data came from a .pinballyHighScores file associated with the game
  • "javascript": the data came from a highscoresready event that was canceled via preventDefault()
  • "pinemhi": the scores were retrieved via the PinEMHi program
• success: For a highscoresready event only, a boolean indicating whether or not the request succeeded.