Basic Game Features

Scoring

The P3 framework contains a static class scoring-related functionality. That class is Multimorphic.P3App.Modes.ScoreManager, and it is set up automatically in BaseGameMode.

A common thing to customize in a game is the way the score and related information are displayed to the player. The framework includes the Multimorphic.P3App.GUI.PlayerScoreDisplay script which works on the P3 Sample App's HUD scoring object, but you can display scores however you want. The ModeToGUI events associated with display scores include:

Event Name	Parameter Type	Parameter Meaning	Event Description
Evt_Score	long	Current score	Update the current player's score on-screen
Evt_ScoreReset	any	N/A	Reset all score display data
Evt_ScoreAddPlayer	string	Player's name	Add a new player to the game
Evt_ScoreRemovePlayer	int	1-based number of player being removed	Remove a player from the game
Evt_ScoreActivatePlayer	int	0-based number of newly active player	Inform which player is currently playing

By handling these events, you can show the names of all of the players in a game, show which one is currently playing, and show all of their current scores.

In a mode, you can always access the current player's score with the following code:

data.currentPlayer.GetData("Score", 0L));

Replays

Replay logic monitors the player's score to see when it crosses a replay threshold. Immediately upon that occuring, an "Evt_ReplayAchieved" event is sent as a ModeToMode event and a ModeToGUI event, with the (long)threshold as the parameter (to be handled as desired by game code). Then, at the end of game, the replay threshold may be adjusted up or down based on players achieving or not achieving the threshold.

The following are protected properties in SettingsMode that you can change in your SettingsMode subclass:

Property	Property Type	Default Value	Property Description
replayScoreLevelsEnabled	bool	true	High level enable for the replay subsystem

The following GameAttributes are defined by default if the above replayScoreLevelsEnabled property is true

Name	Description	Min	Max	Increment	Default
ReplaysEnabled	Replay feature enabled				true
MinReplayScore	Minimum replay score	1000000L	10000000L	250000L	1000000L
CurrentReplayScore	Current replay score	1000000L	10000000L	250000L	1000000L
DynamicReplayScoreIncValue	Amount to increase the reply score when the current one is achieved (at end of game)	100000L	1000000L	50000L	250000L
DynamicReplayScoreDecValue	Amount to decrement the reply score when the current one is not achieved in some time	100000L	1000000L	50000L	250000L
DynamicReplayConsecutiveMissesBeforeDec	Number of consecutive games failing to reach the replay score before decrementing the replay score	1	1000	1	5
DynamicReplayConsecutiveMissesSoFar	Current number of consecutive games failing to reach the replay score	0	1000	1	5

When the player's score exceeds a replay level, the following event is posted as both a ModeToMode event and a ModeToGUI event.

Event Name	Parameter Type	Parameter Meaning	Event Description
Evt_ReplayAchieved	long	target score of replay level achieved	Player's score just exceeded a replay level

Also, at the end of the game, the CurrentReplayScore is incremented if one or more players achieved the replay threshold. If no players achieved the replay threshold, then DynamicReplayConsecutiveMissesSoFar is incremented (one time, regardless of the number of players per game), and if the new value reaches DynamicReplayConsecutiveMissesBeforeDec, then the replay threshold is decremented.

Note - Restored games via player profiles are explicitly excluded from replay level checks.

Game Management

The P3 framework has built-in logic to manage the skeleton structure of a game, including managing the coin slots for credit management, start button for adding players to a game, launch button for launching the first ball in a player's turn, and processing end-of-ball/end-of-game and typical features associated with that, like end of ball bonuses, tilt handling, and high-score checking and name entry.

If your game or application does not need standard start of game handling (credits and start button handling), you can disable that functionality by overriding PossiblyStartGameManagerMode() in your <AppCode>BaseGameMode class. Then you can optionally add your own start of game handling.

protected override void PossiblyStartGameManagerMode()
{
    // Your custom implementation here
}

End Of Ball Bonus

By default, bonusMode will be added to the mode queue at the end of each ball to handle bonus calculations. When the framework code instantiates bonusMode, it also passes the bonusInfo object into it. bonusInfo is instantiated by the framework as a Multimorphic.P3App.Modes.BonusInfo object and simply needs to be assigned to a Multimorphic.P3App.Modes.BonusInfo in <AppCode>BaseGameMode.BallEndedEventHandler. An example:

protected override bool BallEndedEventHandler(string eventName, object eventData)
{
    if (!forcePlayerChangeActive)
    {
        // Reset scoring multiplier before applying bonus.
        ScoreManager.SetX(1);
        bonusInfo = homeMode.getBonusInfo();
    }
 
    return base.BallEndedEventHandler(eventName, eventData);
}

For displaying the bonus, the framework (via bonusMode) will post:

PostModeEventToGUI("Evt_SetBonusData", data);

and it will subscribe and wait to receive the GUIToMode event "Evt_BonusComplete" before finishing end of ball processing. The framework also takes care of adding the bonus to the score after the GUI event "Evt_BonusComplete" is received.

To turn off framework handling of the end of ball bonus, set "bonusModeEnabled" to false in <AppCode>BaseGameMode.

Tilt Handling

By default BaseGameMode instantiates tiltMode (an instance of Multimorphic.P3App.Modes.TiltMode), which monitors the tilt switch in the P3 (p3.Switches["tilt"]). A switch active event will cause both a ModeToMode and ModeToGUI Evt_TiltWarning event when the number of warnings hasn't been exceeded. Otherwise, it will issue only a ModeToMode Evt_Tilted event.

HomeMode handles the Evt_Tilted event as follows: it stops its playlist; it sends the ModeToGUI event Evt_Tilted to provide on-screen feedback; it starts TiltedMode; finally it sends the Evt_TiltProcess event.

TiltedMode is a high priority mode that disables flippers and bumpers, turns off all leds, and ensures no other scoring events happen until the end-of-ball is processed. It will also relaunch balls if they fall into a hole.

GameModes do not handle Evt_Tilted directly, as it must first be processed by HomeMode. Instead, they respond to the Evt_TiltProcess event sent by HomeMode. By default, the TiltProcessEventHandler in P3SAGameMode stops the mode playlists and removes the mode, which is often sufficient. However, if a mode produces dynamic visual effects (e.g., MovingTargetMode in P3SampleApp), it will likely override TiltProcessEventHandler to send an event to the GUI to stop the effect. Multiball modes must also override TiltProcessEventHandler to disable the mode while continuing to track ball count, so that the game can proceed and process the end-of-ball when all active balls drain.

After an Evt_Tilted event, TiltMode waits until the tilt switch has been inactive for at least the TiltSettleDelay before sending the Evt_TiltSettled event. HomeMode delays the end of ball processing until all balls have drained and the Evt_TiltSettled event has been received. This ensures the next player is not penalized by a spurious tilt caused by the previous player.

When the end-of-ball and/or end-of-game is processed, tiltMode is removed from the mode queue, and that causes the ModeToMode Evt_TiltProcessingComplete event to fire.

Tilt ModeToMode events issued by Multimorphic.P3App.Modes.TiltMode

Event Name	Parameter Type	Parameter Meaning	Event Description
Evt_TiltWarning	int	Warning number	Tilt warning when the number of warnings hasn't been exceeded - to be handled by app code.
Evt_Tilted	any	N/A	Tilt warnings exceeded - override TiltedEventHandler() in <AppCode>BaseGameMode and call the base class.
Evt_TiltSettled	any	N/A	After an Evt_Tilted event, notifies the tilt bob did not activate for at least the configured Tilt Settle Time
Evt_TiltProcessingComplete	any	N/A	Tilt mode removed after end-of-ball processing completed, including the tilt bob settling - override TiltProcessingCompleteEventHandler() in <AppCode>BaseGameMode and call the base class.

Tilt ModeToGUI events issued by Multimorphic.P3App.Modes.TiltMode

Event Name	Parameter Type	Parameter Meaning	Event Description
Evt_TiltWarning	int	Warning number	Tilt warning when the number of warnings hasn't been exceeded - to be handled by app code.
Evt_Tilted	any	N/A	Tilt warnings exceeded
Evt_TiltComplete	any	N/A	Tilt processing is complete

Tilt ModeToMode events that are handled by Multimorphic.P3App.Modes.TiltMode and that can be posted by app code.

Event Name	Parameter Type	Parameter Meaning	Event Description
Evt_EnableTilt	bool	Enable tilt detection	Used to enable the tilt logic to process tilt switch events. The tilt logic is automatically enabled/re-enabled when the warnings are reset, and it's automatically disabled after a tilt occurs.
Evt_ResetTiltWarnings	any	N/A	Reset the warning count to 0

Tilt can be disabled by the machine operator via the settings menu, but to fully disable the tilt logic, set "tiltModeEnabled" to false in <AppCode>BaseGameMode.

By default, the framework resets the number of tilt warnings to 0 at the beginning of each ball.

The application can query to current number of tilt warnings. One reason to do this is to set the number of tilt warnings at the beginning of the next ball, thereby preserving the count across balls.

int numWarnings = 0;  // a class member variable
 
AddModeEventHandler("Evt_TiltWarningCountResponse", TiltWarningCountResponseEventHandler, Priority);
PostModeEventToModes("Evt_GetTiltWarnings", null);
data.currentPlayer.SaveData("TiltWarnings", numWarnings);
 
private bool TiltWarningCountResponseEventHandler(string evtName, object evtData){
    numWarnings = (int)evtData;
    RemoveModeEventHandler("Evt_TiltWarningCountResponse", TiltWarningCountResponseEventHandler);
    return EVENT_STOP;
}

// Set the number of tilt warnings
int numWarnings = data.currentPlayer.GetData("TiltWarnings").ToInt();
PostModeEventToModes("Evt_SetTiltWarnings", numWarnings);

High Score Tracking

Automatic high score tracking can be disabled by the programmer by setting "highScoreCheckEnabled" to false in <AppCode>BaseGameMode. For more information on High Score logic, see High Scores

Credits

The framework includes logic to handle credit functionality. This includes options to set the game to 'free play' or to require players to insert money to play the game. When 'free play' is on, the framework doesn't need to do anything. When 'free play' is off, the framework will post some ModeToGUI events to indicate what is happening:

Event Name	Parameter Type	Parameter Meaning	Event Description
Evt_NewCoin	N/A	N/A	A new coin was inserted, and it wasn't enough money to add a new credit
Evt_NewCredit	N/A	N/A	A new coin was inserted, and it resulted in a new credit
Evt_NoCredit	N/A	N/A	The start button was pressed, but no game was started, either because maxPlayers was reached or no credit was available
Evt_TextCredits	string	Credits available	Sets the credits message to display on-screen, the text is either "Free Play" or "Credits: NNN"
Evt_NoCreditAvailable	N/A	N/A	The player tried to start a game with no credits available

These events can be used to play sounds and update GUI content as credits are added or consumed.

How the credit subsystem converts money to credits is determined by the operator adjustable GameAttributes shown in Credit Handling.

The application can send this event to add credits programmatically:

int numCreditsToAdd = 2;

PostModeEventToModes("Evt_AddCredits", numCreditsToAdd);

.