2. Let's Play

This QP-nano Tutorial is adapted from Chapter 1 of Practical UML Statecharts in C/C++, Second Edition
by Miro Samek, the founder and president of Quantum Leaps, LLC.

Prev: 1. Installing QP-nano and Building QP-nano Applications
Next: 3. The main() Function and the qpn_port.h Header File

The following description of the "Fly 'n' Shoot" game serves the dual purpose of explaining how to play the game and as the problem specification for the purpose of designing and implementing the software later in this Tutorial. To accomplish these two goals I need to be quite detailed, so please bear with me.

Your objective in the game is to navigate a space ship through an endless horizontal tunnel with mines. Any collision with the tunnel or the mine destroys the ship. You can move the ship up and down with UP-arrow and DOWN-arrow keys on the PC (see Figure 2-1) or the potentiometer wheel on the LM3S811 board (see Figure 2-2). You can also fire a missile to destroy the mines in the tunnel by pressing the SPACE-bar on the PC or the User button on the LM3S811 board. Score accumulates for survival (at the rate of 30 points per second) and destroying the mines.

The game lasts for only one ship. The game starts in a demo mode, where the tunnel walls scroll at the normal pace from right to left and the "Press Button" text flashes in the middle of the screen. You need to generate the "fire missile" event for the game to begin (press SPACE-bar on the PC and the User Button on the LM3S811 board). You can have only one missile in flight at a time, so trying to fire a missile while it is already flying has no effect. Hitting the tunnel wall with the missile brings you no points, but you earn extra points for destroying the mines.

The game has two types of mines with different behavior. In the original Luminary "Quickstart" application both types of mines behave the same, but I wanted to demonstrate how state machines can elegantly handle differently behaving mines.

Mine type-1 is small, but can be destroyed by hitting any of its pixels with the missile. You earn 25 points for destroying a mine type- Mine type-2 is bigger, but is nastier in that the missile can destroy it only by hitting its center, not any of the "tentacles". Of course, the ship is vulnerable to the whole mine. You earn 45 points for destroying a mine type 2.

When your crash the ship, either by hitting a wall or a mine, the game ends and displays the flashing "Game Over" text as well as your final score. After 5 seconds of flashing, the "Game Over" screen changes back to the demo screen, where the game waits to be started again.

Additionally the application contains a screen saver because the OLED display of the original LM3S811 board has burn-in characteristics similar to a CRT. The screen saver only becomes active if 20 seconds elapse in the demo mode without starting the game (i.e., the screen saver never appears during game play). The screen saver is a simple random-pixel-type, rather than the "Game of Life" algorithm used in the original Luminary "Quickstart" application. I've decided to simplify this aspect of the implementation, because the more elaborate pixel-mixing algorithm does not contribute any new or interesting behavior. After a minute of running the screen saver, the display turns blank and only a single random pixel shows on the screen. Again, this is a little difference from the original "Quickstart" application, which instead blanks the screen and starts flashing the User LED. I've changed this behavior because I have a better purpose for the User LED (to visualize the activity of the idle loop).

Running the DOS Version

The "Fly 'n' Shoot" sample code for the DOS version (in C++) is located in <qpn>\examples\80x86\watcom\game\, directory, where <qpn> stands for the installation directory you chose to install the QP-nano software.

The compiled executable is provided, so you can run the game on any Windows-based PC by simply double-clicking on the executable game.exe located in the directory <qpn>\examples\80x86\watcom\game\dbg\.

Figure 2-1 The Fly 'n' Shoot game running in a DOS window under Windows XP.

The first screen you see is the game running in the demo mode with the text "Push Button" flashing in the middle of the display. At the top of the display you see a legend of keystrokes recognized by the application. You need to hit the SPACE key to start playing the game. Please press the ESC key to cleanly exit the application.

If you run "Fly 'n' Shoot" in a window under Microsoft Windows, the animation effects in the game might appear a little jumpy, especially when compared to the ARM-Cortex version of the same game. You can make the application execute significantly smoother if you switch to the full-screen mode by pressing and holding the Alt key and then pressing the Enter key. You go back to the window mode by the same Alt-Enter key combination.

As you can see in Figure 2-1, the DOS version uses simply the standard VGA text mode to emulate the OLED display of the LM3S811 board. The lower part of the DOS screen is used as a matrix of 80x16 character-wide "pixels", which is a little less than the 96x16 pixels of the OLED display, but is still good enough to play the game. I specifically avoid employing any fancier graphics in this early example because I have a bigger fish to fry for you than to worry about the irrelevant complexities of programming graphics. My main goal is to make it easy for you to understand the event-driven code and experiment with it.

To this end, I chose the Open Watcom toolset to build this example as well as several other examples in this book. Open Watcom it is available under a OSI-certified open source license that permits free commercial and non-commercial use. You can download Open Watcom C/C++ toolset for DOS from ftp://ftp.openwatcom.org/. Please select the open-watcom-c-dos-1.8.exe installer. Ready to print documentation in PDF format is also available from http://www.openwatcom.org/index.php/Manuals.

The Open Watcom C/C++ toolset for DOS is distributed as a Windows installer. After you download the open-watcom-c-dos-1.8.exe file, please launch the installer and follow the instructions it provides.

Note:: I strongly recommend that you install the Open Watcom toolset into the directory C:\tools\watcom\. That way, you will be able to use directly the provided make scripts. If you choose to install Open Watcom into a different location, you can still use the make scripts supplied with the QP distribution, but you need to define the WATCOM environment variable. You should not install Open Watcom in the standard "Prgram Files" directory or any directory name with a space.

To experinment with the "Fly 'n' Shoot" game code you can use any code editor to modify the source code. Then you re-build the application by means of the supplied make.bat script, which is located in the directory <qpn>\examples\80x86\watcom\game\.

In the next section, I describe briefly how to run the embedded version of the game. If you are not interested in the ARM-Cortex version, please feel free to skip to the following Section 3. The main() Function and the qpn_port.h Header File, where I start explaining the application code.

Running the ARM-Cortex Version

In contrast to the "Fly 'n' Shoot" version for DOS running in the ancient real mode of the 80x86 processor, the exact same source code runs on one of the most modern processors in the industry: the ARM-Cortex.

Figure 2-2 The Fly 'n' Shoot game running on the ARM Cortex-M3 LM3S811 evaluation board.

The sample code for the ARM Cortex-M3 LM3S811 board is located in <qpc>\examples\arm-cortex\vanilla\iar\game-ev-lm3s811\ directory, where <qpc> stands for the root directory you chose to install the accompanying software. The code for the ARM-Cortex kit has been compiled with the 32KB-limited Kickstart edition of the IAR Embedded Workbench for ARM (IAR EWARM) v 5.40, which is provided with the ARM Cortex-M3 EKI-LM3S811 kit. You can also download this software free of charge directly from IAR Systems (http://www.iar.com), after filling out an online registration.

The installation of IAR EWARM is quite straightforward, as the software comes with the installation utility. You also need to install the USB drivers for the hardware debugger built into the LM3S811 board, as described in the documentation of the ARM Cortex-M3 LM3S811 kit.

Note:: I strongly recommend that you install the IAR EWARM toolset into the directory C:\tools\iar\arm_ks_5.40 That way, you will be able to use directly the provided EWARM workspace files and make scripts.

Before you program the "Fly 'n' Shoot" game to the LM3S811 board, you might want to play a little with the original "Quickstart" application that comes pre-programmed with the LM3S811 kit.

To program the "Fly 'n' Shoot" game to the flash memory of the LM3S811 board, you first connect the LM3S811 board to your PC with the USB cable provided in the kit and make sure that the Power LED is on (see Figure 2-2). Next, you need to launch the IAR Embedded Workbench and open the workspace game-ev-lm3s81eww located in <qpn>\examples\arm-cortex\iar\game-ev-lm3s811\ directory. At this point your screen should look similar to the screenshot shown in Figure 2-3. The game-ev-lm3s811 project is set up to use the LMI FTDI debugger, which is the piece of hardware integrated on the LM3S811 board (see Figure 2-2). You can verify this setup by opening the "Options" dialog box via the Project->Options menu. Within the "Options" dialog box, you need to select the Debugger category in the panel on the left. While you are at it, you could also verify that the flash loading is enabled by selecting the "Download" tab. The checked "Use flash loader(s)" checkbox means that the flash loader application provided by IAR will be first loaded to the RAM of the MCU, and this application will program the flash with the image of your application. To start the flash programming process, select the Project->Debug menu, or simply click on the Debug button (see Figure 2-3) in the toolbar. The IAR Workbench should respond by showing the flash programming progress bar for several seconds, as shown in Figure 2-3. Once the flash programming completes, the IAR EWARM switches to the IAR C-Spy debugger and the program should stop at the entry to main(). You can start playing the game either by hitting the "Go" button in the debugger, or you can close the debugger and reset the board by pressing the Reset button. Either way, "Fly 'n' Shoot" game is now permanently programmed into the LM3S811 board and will start automatically upon every power up.

Figure 2-3 Loading the Fly 'n' Shoot game into the flash of LM3S811 MCU with IAR EWARM IDE

The IAR Embedded Workbench environment allows you to experiment with the "Fly 'n' Shoot" code very easily. You can edit the files and recompile the application at a click of a button (F7). The only caveat is that the first time after the installation of the IAR toolset you need to build the Luminary Micro driver library for the LM3S811 MCU from the sources. You accomplish this by loading the workspace ek-lm3s81eww located in the directory <IAR-EWARM>\ARM\examples\Luminary\Cortex-M3\boards\ek-lm3s811, where <IAR-EWARM> stands for the directory name where you've installed the IAR toolset. In the ev-lm3s81eww workspace, you select the "driverlib - Debug" project from the drop-down list at the top of the Workspace panel, and then press F7 to build the library.

Prev: 1. Installing QP-nano and Building QP-nano Applications
Next: 3. The main() Function and the qpn_port.h Header File