LaunchEvent

Events of this class are fired to track the progress of a game session when the user launches a table. This event has the following subtypes:

• prelaunch: Fired just before a game is about to be launched. This event occurs before any part of the launch process begins, so you can cancel the event (via preventDefault()) to prevent the launch. This event also has the unique ability to modify anything about the command line that will be used to launch the game, including the executable path and command-line options, by setting properties of the overrides object in the event object (explained below, under the event properties). For example, you can use overrides to add special command-line parameters that depend upon the particular game being launched or the command that was used to launch it.
• gamestarted: Fired when PinballY detects that the launched game has successfully started and opened a window. The exact timing of the event isn't predictable, since the game program runs as a separate Windows process. You can count on the event firing some time after the game has opened its first window, but be careful not to assume that the game is actually ready to play, from the player's perspective. The first window the program opens might not be the game's actual "playfield" window. Visual Pinball, for example, always opens its editor window first, before displaying the game window, so this event usually fires for VP well before the game is ready to play. There's unfortunately nothing we can do in general to detect when the game is actually ready, since that's too dependent on the inner workings of the pinball player system. If you want to wait until the game is truly ready to play, a simple heuristic might be to use a timeout to add a short delay, which you can gauge by trial and error for the games you play most frequently. If you're writing this event handler for a situation where you know you're working with a particular player system, you could potentially use low-level Windows APIs to communicate and coordinate with the game process, but short of that, there's not much we can do. This event can't be canceled, since it's fired after the fact.
• gameover: Fired after PinballY detects that the child game process has terminated, and before any of the post-launch tasks (such as the game system's "Run After" commands) have been executed. This event can't be canceled, since it's fired after the game process has already exited. (You can prevent PinballY from trying to stop the game in the first place, by blocking the "Kill Game" command via the command event. That obviously doesn't prevent the game process from exiting on its own, or from the user taking an external action outside of PinballY that ends the game process, such as closing its window with the mouse or killing the process via Task Manager. The gameover event fires regardless of what caused the process to terminate; it's just a notification that PinballY detected that the process exited.)
• launcherror: Fired if a game launch fails. This event is mutually exclusive with gamestarted and gameover, since those events will only be fired if the game successfully starts running; a launcherror event means that the launch attempt was unsuccessful, so no further action on the launch will occur. You can cancel this event to prevent the error message from being displayed (canceling it has no other effect, though, as the event fires after the launch attempt has already failed).
• postlaunch: The counterpart of prelaunch that fires at the very end of the launch procedure, after the game has exited and all of the "after game" tasks have been completed.
• runafter: Fired after the game has exited, with the "Game Exiting" message displayed in the main PinballY window. This runs just after the external "Run After" command defined for the system runs. This event can't be canceled.
• runafterpost: Fired after the runafter event completes and the main PinballY window is blanked. This event cannot be canceled.
• runbefore: Fired just before the game program is launched, with the main PinballY window displaying the "Loading Game" message. Canceling this event aborts the launch.
• runbeforepre: Fired before the runbefore event, with the main PinballY window showing a blank, black background. Canceling this event aborts the launch.

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

Launch event sequence

The process of launching a game has many steps, which is why the launch event has such a large number of subtypes. Here's how all of these events get fired in the course of a game launch.

The runbeforepre, runbefore, runafter, and runafterpost events run in that order, and correspond to the similarly named external commands that can be set up for each system in the options. The separate "pre" and "post" events are provided for finer control over the display appearance during each step. During the runbeforepre and runafterpost commands, the main PinballY window is blank, showing just a uniform black background. This makes it a good time to perform any changes to the physical monitor layout, such as rotating the monitors or changing the screen resolutions, since the blank window won't show any obvious visual effect and thus will help achieve a visually seamless transition to the new layout.

For a successful launch, the full order of the events, including the external commands, is as follows:

• prelaunch fires
• The main PinballY window is blanked
• The game system's external "Run Before Pre" command runs
• runbeforepre fires
• The "Loading Game" message is displayed in the main window
• runbefore fires
• The game system's external "Run Before" command runs
• The game launches
• gamestarted fires
• The game runs until the user quits
• The "Game Exiting" message is displayed in the main window
• gameover fires
• The game system's external "Run After" command runs
• runafter fires
• The main window is blanked
• runafterpost fires
• The game system's external "Run After Post" command runs
• postlaunch fires

Error handling: The sequence above is for successful launches. Launches involve a lot of external moving parts, obviously, so there are many places where something can fail. If an error occurs, the event sequence will change accordingly:

• If the game system launch itself fails (for example, if the game program can't be started, or if it terminates or crashes before opening a UI window), a launcherror event will be fired instead of gamestarted and gameover.
• If a Run Before command fails, the launch will be cut short at that point in the sequence, without attempting to launch the game.
• If a given Run Before step is executed successfully, the system tries to ensure that the corresponding Run After step is also executed, no matter what else went wrong along the way. The Run After steps might need to undo global changes made in the paired Run Before steps, so it's important that these get executed even if other launch errors occur, so that everything's in its proper state to return to the PinballY wheel UI.

Properties

Launch events include all of the standard event properties and methods (see the Event class), plus the following:

• command: The command ID of the command used to launch the game, typically command.PlayGame or command.CaptureGo.
• error: For a launcherror event only, this is a string describing the error. This message is normally displayed to the user via a popup message, but you can prevent that by canceling the event.
• game: A GameInfo object describing the game being launched.
• overrides: For prelaunch only, this is initially set to an empty object. Event listeners can set properties of this object to override the normal launch parameters taken from the game system's settings in the options. The following properties can be set:
  • envVars: Windows environment variables to pass to the game process. This is a string with one or more variables, separated by semicolons (";"), with each variable using the format NAME=VALUE. If specified, this completely replaces the environment variables defined in the system settings, so if you want to keep those as well, you must explicitly include them in this property.
  • exe: A string giving the full filename with absolute path of the program executable (.EXE) to launch.
  • params: A string giving the command-line parameters to pass to the program executable. This can contain the usual expansion variables in [square brackets]; see Parameters in the System Options dialog for the list of variables.
  • processName: A string giving the name of the process to monitor to determine when the game has terminated.
  • runAfter: A string giving the full command line to use as a replacement for the Run After command in the system's settings.
  • runAfterPost: A string giving the full command line to use as a replacement for the Run After Post command in the system's settings.
  • runBefore: A string giving the full command line to use as a replacement for the Run Before command in the system's settings.
  • runBeforePre: A string giving the full command line to use as a replacement for the Before Pre command in the system's settings.
  • swShow: An integer value giving the initial window mode; typically SW_SHOW, SW_SHOWMINIMIZED, or SW_HIDE.
  • terminateBy: A string giving the termination mode for the program; see terminateBy in the GameSysInfo object.
  • workingPath: A string giving the full absolute path to use as the working directory for the game process.