Tutorial 10: Run a real game
This is part of our Getting Started guide.
The guide starts here.
It's been awhile since this tutorial has been updated. If you find anything that is no longer relevant, please let us know, or better yet, edit or update it yourself!
Holy Moly! It's actually time to run your first real game with MPF. When we say a "real" game, we're talking about with multiple players and balls machine flow from attract to game mode and back to attract once the game is over.
1. Make one quick addition to your display configuration
We know that at this point, you just want to run your game. The problem
is if we run it now, the display will continue to show "ATTRACT MODE"
throughout the entire game since we haven't configured it for anything
else. So let's make a quick addition to the
slide_player: section of
your config so it will show the player and ball number when a game is in
progress. (Later in this tutorial we'll revisit this and explain
what's actually going on. For now just make this change.) In your
config file, add a
ball_started: entry with the following information.
slide_player: section should now look like this:
#! slides: #! welcome_slide: #! widgets: #! - type: text #! text: PINBALL! #! font_size: 50 #! color: red #! - type: rectangle #! width: 240 #! height: 60 #! attract_started: #! widgets: #! - text: ATTRACT MODE #! type: text slide_player: init_done: welcome_slide mode_attract_started: attract_started ball_started: widgets: type: text text: PLAYER (number) BALL (ball) ##! test #! advance_time_and_run .1 #! assert_slide_on_top attract_started #! assert_text_on_top_slide "ATTRACT MODE"
2. Add initial active switches and bind trough switches to your keyboard
If you are not using physical hardware you need some way to control the
ball inside your trough. We will first make sure that the trough
switches will be active (as if there was a ball sitting on them) when
your virtual machine starts up. Additionally, we add keyboard bindings
for ball switches to the numbers
5 and the plunger switch to
#! switches: #! s_trough1: #! number: #! s_trough2: #! number: #! s_trough3: #! number: virtual_platform_start_active_switches: - s_trough1 - s_trough2 - s_trough3 keyboard: 1: switch: s_trough1 toggle: true 2: switch: s_trough2 toggle: true 3: switch: s_trough3 toggle: true 4: switch: s_trough4 toggle: true 5: switch: s_trough5 toggle: true p: switch: s_plunger toggle: true
This way you can drain balls by activating trough switches.
3. Change your flipper config so they don't automatically enable on machine boot
Almost there! The other quick change we need to make is to remove the
enable_events: from the flipper configuration that we added back in
the Get Flipping! step.
This is because by default, MPF will automatically enable your flippers when a ball starts and disable them when a ball ends. But since we added a configuration setting to your flippers that set them to automatically enable themselves immediately when MPF loaded, that setting overwrote the default setting which enables your flippers when a ball starts. So as your config file is now, the flippers enable when MPF boots, then they disable when the first ball ends, and that's it. They won't enable again for Ball 2.
To make this change, simply remove the
enable_events: machine_reset_phase_3 line from each of your two
flipper sections of your config file. So now your
section should look like this: (It might not be 100% identical since you
might have single-wound flipper coils and/or EOS switches.)
#! switches: #! s_left_flipper: #! number: 0 #! s_right_flipper: #! number: 1 #! coils: #! c_flipper_left_main: #! number: 0 #! c_flipper_left_hold: #! number: 1 #! allow_enable: true #! c_flipper_right_main: #! number: 2 #! c_flipper_right_hold: #! number: 3 #! allow_enable: true flippers: left_flipper: main_coil: c_flipper_left_main hold_coil: c_flipper_left_hold activation_switch: s_left_flipper right_flipper: main_coil: c_flipper_right_main hold_coil: c_flipper_right_hold activation_switch: s_right_flipper
4. Running your game with physical hardware
If you have a physical machine attached, go ahead and run your game
-X command line options. (If you don't have a
physical machine and you want to simulate a game using the keyboard
keys, skip to Step 4 below.)
C:\pinball\your_machine>mpf both -X
Make sure you have at least one ball in the trough and then run your game. The display should display "ATTRACT MODE." Hit the start button. A ball should be kicked out of the trough and into the plunger lane, and the display should change to "PLAYER 1 BALL 1." If you have a coil-fired plunger, you should be able to hit the launch button and the coil should fire. If you have a manual plunger, you should be able to plunge and flip. If you hit the start button a second time during Ball 1, a second player should be added. (The display won't show this since we haven't configured it to show a message, but you can see this in the logs and when the ball drains then it should go to Player 2 Ball 1 instead of Player 1 Ball 2.)
A few caveats to this early bare-bones game:
- Since you haven't configured any scoring yet, this game will be boring and nothing will score. But hey, you're playing!
- If your flippers, trough eject, or plunger coil is too weak or too
strong, you can adjust them in the coil's
default_pulse_ms:setting in the config file.
- If you start MPF with a ball in the plunger lane and you have a coil-fired plunger, MPF will immediately fire the plunger to kick out the ball. This is by design since you don't have a "home" tag in your plunger ball device's configuration, which means that MPF will automatically eject the ball to get all the balls into ball devices tagged with "home."
- If you shoot a ball into a playfield lock or any other ball device, it will get stuck there since you haven't configured that device. (In this case you need to add configuration entries for those ball devices so MPF can know about them. Then it will automatically kick out any balls that enter. We'll get to that later.)
- By default MPF is configured to allow a maximum of 4 players per game, with 3 balls per game. You can change this in the game: section of the machine config.
5. "Playing" a game without a physical machine attached
If you've been adding keyboard switch map entries to your config file as you've been going through this tutorial, you can actually "play" a complete game on your computer keyboard. Here's how you do it:
- Launch the MPF game engine and the MC. Note that in order for this
to work, we want to use the "smart virtual" platform. This will be
the default, but make sure you do not have
platform: virtualin your config. (If you do have a platform entry in your config, make sure it's
platform: smart_virtual.) If you have a different platform setting for your physical hardware, you can still run without the hardware connected by using the
-X(uppercase X) command line option to specify the smart virtual platform interface.
- Push the "S" key to start a game. At this point MPF will eject a ball from the trough to the plunger
- If you have a coil-fired plunger, push the "L" key (or whatever key you mapped to your launch button) to launch the ball.
- If you do not have a coil-fired plunger, push the "P" key (or whatever key you mapped to your plunger lane switch) to un-toggle that switch which simulates the ball leaving the plunger lane. Note: The toggle option in the keyboard: section is useful for testing your game from your computer when you're not around your physical machine.
- Now you can "flip" with the "Z" and "?" keys.
- After you get bored of this, push the "1" key to activate a trough ball switch. At this point MPF will think a ball drained and you should see the display switch to Ball 2 and the trough switch should open and the plunger lane switch should close as the "smart virtual" platform ejects a ball from the trough to the plunger.
- Repeat until you're bored.
- After Ball 3 is over the display will change back to the "ATTRACT MODE" text and you can push "S" again to start another game.
- Congrats! You just played your first virtual pinball game. Yeah, it's boring, but you did it!
6. What if your game won't start?
If your game doesn't start or doesn't work, hopefully we've given you enough information in this tutorial to work out what the problem is. That said, here's a list of things that could go wrong:
- If you see a config error try running
mpf both -t -v -V -Xto disable the text ui and add verbose logging.
- No ball in the trough.
- Virtual games need balls too; add the
virtual_platform_start_active_switchessection of the complete config file. (Alternatively, if you are using the smart_virtual platform with
2to add balls to the trough via keyboard)
- Ball in the trough, but not activating the switch.
- Trough switches are optos but you didn't add
type: NCto your switch configurations. (Mechanical trough switches do not need a
- Trough is trying to eject, but the trough coil's
default_pulse_ms:setting is too weak and the ball can't get out.
- Incorrect switch or coil numbers which don't match up to your actual hardware inputs and outputs.
- Some other setting isn't configured properly, which could lead to who-knows-what error? (Maybe compare your config file to the complete config from mpf-examples?)
If you're still having problems, feel free to post to the mpf-users Google group.
Check out the complete config.yaml file so far
If you want to see a complete
config.yaml file up to this point, it's
You can run this file directly by switching to that folder and then running the following command:
C:\mpf-examples\tutorial>mpf both -X
Remember though that unless you're following this tutorial with an actual Demolition Man, you'll have some differences in your config file.
Something missing or wrong? You can fix it!
This website is edited by people like you! Is something wrong or missing? Is something out of date, or can you explain it better?
Please help us! You can fix it yourself and be an official "open source" contributor!
It's easy! See our Beginner's guide to editing the docs.
Page navigation via the keyboard: < >
You can navigate this site via the keyboard. There are two modes:
General navigation, when search is not focused:
- F , S , / : open search dialog
- P , , : go to previous page
- N , . : go to next page
While using the search function:
- Down , Up : select next / previous result
- Esc , Tab : close search
- Enter : go to highlighted page in the results