Tutorial 15: Add scoring - The Mission Pinball Framework (2024)

By now you have a "playable" game with a base game mode, and you'vegot a score showing on the display, but it's still pretty boring sincenothing is actually configured to register a score yet. So in this stepwe're going to add some scoring.

1. Understand how scoring works in MPF

MPF includes a core module called the Variable Player which isresponsible for adding (or subtracting) points from a player's score.Actually, that's not a completely accurate description. We shouldreally say that the variable player is responsible for adding orsubtracting value from any player variable. (A player variable is just akey/value pair that is stored on a per-player basis.) The score is themost obvious player variable. But MPF also uses player variables totrack what ball the player is on, how many extra balls the player has,etc. You can create player variables to track anything you want. Rampsmade, combos made, number of modes completed, aliens destroyed, etc.

The variable player is responsible for adding and subtracting value fromany player variable based on events that happen in MPF. You configurewhich events add or subtract value to which player variables in thevariable_player: section of a mode's configuration file.

2. Add a variable_player: section to your base.yaml mode config file

The first step is simply to add a variable_player: section to yourbase mode's base.yaml config file. So in this case, that will be<your_machine>/modes/base/config/base.yaml. Add a new top levelconfiguration item called variable_player:, like this:

variable_player:

3. Add point values for events

Then inside the variable_player: section, you create sub-entries forMPF events that you map back to a list of player variables whose valueyou want to change. By default, whenever a switch is hit in MPF, itposts an event (switch_name)_active . (A second event called(switch_name)_inactive is also posted when the switch opens backup.) To give the player points when a switch is hit, add sub-entries tothe variable_player: section of your config file, with some switchname followed by "_active", like this:

##! mode: basevariable_player: s_right_inlane_active: score: 100 s_left_flipper_active: score: 1000

Now save your config, start a game (S), hit the L key to launch aball, then hit the Q key to trigger the right inlane switch . Youshould immediately see a score of 100 points. Then if you hit the Zkey for the left flipper, you'll see the player's score increase by1000 points. You can hit it as many times as you want to see the scoreincrease:

Remember from the previous step that the slide_player: section of theconfig contains a text widget with a value of (score) in parentheses,and any values in parentheses are updated automatically when theunderlying player variable changes. So that's how the display isupdating automatically here.

By the way, there's areference list of many built-in events in the documentation, so you can browse through that to getan idea of the various types of events that exist which you can use totrigger display slides or score events.

Note that variable_player: events in a mode's config file are onlyactually active when that mode is active. So the section we're addingin this step is in the base mode's config, which we've set to startany time a ball starts. But if the base mode ever wasn't running, thenthe s_right_inlane_active and s_left_flipper_active events wouldn'ttrigger a score.

When you create more modes in the future, you can actually configurethat a score event in a higher-priority mode "blocks" thevariable_player/scoring event in a lower-priority mode. So you couldhave a pop bumper that is worth 100 points in a base mode, but then youcould also make it worth 5,000 points in a super jets mode whileblocking the 100 point score from the base mode since if the scoringfrom both modes was active, you'd get two scoring events--the 100 fromthe base mode and the 5,000 from the super jets mode. (More on thatlater.)

Later on you can also configure shots which can control lights andmanage sequences of switches and lots of other cool things, so that'show you can track the ball moving left-to-right or right-to-left arounda loop, and from there you'll be able to configure different scoringevents for each direction. (Again, we'll get to this later. For now youcan just wire up scoring to a switch to see it working.)

4. Play with more player variables

As we said, you can add or subtract value from any player variable viathe variable_player: section--even player variables that you make up.

For example, try changing your scoring section to this:

# we will initially set the value to 0 when the machine starts upplayer_vars: potato: initial_value: 0##! mode: base# in your base mode (modes/base/config/base.yaml)variable_player: s_right_inlane_active: score: 100 s_left_flipper_active: score: 1000 potato: 1 s_right_flipper_active: potato: -2

We use the word "potato" here to illustrate that player variables canbe anything. So now when the left flipper is active, the player variablecalled "score" will increase by 1000, and the player variable called"potato" will increase by one. (If you make a reference to a playervariable that hasn't been defined before, it will automatically becreated with a value of 0.)

Also notice that when the right flipper is hit, the player variablecalled "potato" will have a value of 2 subtracted from it.

Player variables exist and are tracked even if they're not displayedanywhere. So if you run your game now and start flipping, the potatovalue will change. Again, player variables are stored on a per-playerbasis, so if you start adding additional players to the game, they'lleach have their own copies of their own player variables. Also theplayer variables are destroyed when the game ends. (It is possible tosave certain variables from game-to-game, but we'll discuss thoselater, as those are not player variables.)

So now that we're tracking this potato variable, let's add it to thedisplay. To do this, let's add another widget to the slide that is showwhen the base mode starts. (So we're going to be editing<your_machine>/modes/config/base.yaml again. Add the potato textentry, like this:

#! player_vars:#! potato:#! initial_value: 0##! mode: base# in your base mode (modes/base/config/base.yaml)slide_player: mode_base_started: widgets: - type: text text: (score) number_grouping: true min_digits: 2 font_size: 100 - type: text text: PLAYER (number) y: 10 x: 10 font_size: 50 anchor_x: left anchor_y: bottom - type: text text: BALL (ball) y: 10 x: right-10 anchor_x: right anchor_y: bottom font_size: 50 - type: text text: 'POTATO VALUE: (potato)' y: 40%##! test#! start_game#! start_mode base#! advance_time_and_run .1#! assert_text_on_top_slide "PLAYER 1"#! assert_text_on_top_slide "BALL 1"#! assert_text_on_top_slide "POTATO VALUE: 0"

Notice that we put text: 'POTATO VALUE: (potato)' in quotes. That'sbecause we actually want to show the colon as part of the text that'sdisplayed on the screen. However colons are important in YAML files. Soif we made our entry like this: text: POTATO VALUE: (potato), then wewould get a YAML processing error because the YAML processor would freakout. "OH MY THERE ARE TWO COLONS?? WHAT'S THIS MEAN??? "

So we use quotes to tell it that the second colon is just part of ourstring.

Now you can run your game (via mpf both), S to start a game, L tolaunch a ball, then use the Z and / keys to left and right flip whichwill adjust the potato value accordingly.

Notice that when you first start a game, the onscreen text saysPOTATO VALUE: (potato). That's because when this slide is firstdisplayed, there is no player variable called "potato"--it's notcreated until you hit a flipper button--so the text widget doesn'tknow what to do with "potato", so it just prints it as is. Laterwe'll learn how to properly initialize variables, but the main thingfor now is to see how the scoring and slide player works.

Check out the complete config.yaml file so far

If you want to see a complete config.yaml file up to this point, it'sin the mpf-examples/tutorial/step_15 folder with the nameconfig.yaml. You can run it be switching to that folder and runningmpf both:

C:\mpf-examples\tutorial_step_15>mpf both