Memory Train

In this first tutorial we will develop a game called "Memory Train." No, it will
not involve motorized strolls down Memory Lane, and neither will we deal with
wagonloads
of microchips. This game will train your memory, hence the title.
Contents

� 1. An overview of the game creation process

� 2. Designing Memory Train
� 3. Implementing Memory Train
� 3.1 Preparations
� 3.2 The smallest possible BGT script
� 3.3 A script that does something
� 3.4 Making decisions
� 3.5 A menu for Memory Train
� 3.6 Sound and speech
� 3.7 Time
� 3.8 Keyboard input
� 3.9 The main function
� 3.10 Keyboard practice
� 3.11 Playing a tone
� 3.12 Playing the game
� 3.13 Playing a sequence
� 3.14 Testing the player's memory
� 3.15 Putting it all together

1. An overview of the game creation process

The story of every game begins with an idea, an initial metaphorical spark in the
designer's brain. This is the one creative impulse out of which the entire project
evolves. It is vital that we hold on to that initial idea throughout the entire
process of designing, implementing, and testing. Only when we hold on to that first

creative impulse will we later be able to determine if we are still on track and
take corrective measures if it turns out that we are not. Such an initial idea
will usually fit into one small paragraph of text, often a single sentence.

Before we dive into programming tasks, let us talk briefly about the process that
leads from that initial idea to the finished game. This process involves a number
of activities, including gameplay design, story design, sound design,
implementation, and testing. For the purposes of describing the game creation
process, let
us assume that each of these activities is carried out by another person.

The central role is played by the gameplay designer because her job is to create
the high-level design of how the game will operate. If we were to design a card
game, for instance, the gameplay designer would primarily concern herself with
creating the rules of the game. Here are some questions the gameplay designer would

need to ask herself: How many cards does the game use? Will it be a trump game?
Will there be suits and ranks? How will the score be determined? How long should
the typical game take? Will it be possible to play against the computer? Against a
human opponent at the same computer? Over the network? All of these questions
can be answered without drawing a single picture, without recording a single sound
effect, and without writing a single line of code.

In determining the high-level design, the gameplay designer generates the input
required by most of the other team members. For example, the programmer needs to
know the exact rules of the game in order to be able to translate them into code.

Eventually, the combined effort of programmer and sound designer will culminate in
a finished prototype. This is in turn closely inspected by the gameplay designer
to ensure that the finished product will meet her expectations. In case the
prototype does not live up to the gameplay designer's expectations, the appropriate

changes will be performed by the various team members and a new prototype is
created. This loop continues until the gameplay designer determines that the
resulting
prototype is in fact the game she designed. Finally, as with any piece of software,
the game will have to go through the various stages of alpha and beta testing
to ensure its quality. Alpha testing is performed behind closed doors by a
dedicated team of testers, while beta testing is performed by potential customers
volunteering
to give your product a try before it is finally released.

2. Designing Memory Train

For this project the initial idea is as follows:

The objective in our game is to repeat sequences of tones which get more complex as
the game progresses.

Here's how it works: The game is played using the arrow keys, and each of the four
arrow keys is associated with a specific tone. When the game begins, the computer
randomly plays one of the four tones, and the player has to hit the corresponding
arrow key. Next, the computer plays that first tone again and then adds a second
tone, and the player has to hit the two corresponding arrow keys in sequence. If
the player gets it right, the computer adds yet a third tone, and the player has
to repeat all three tones in sequence by hitting the corresponding keys. This
process continues until the player makes a mistake by either pressing the wrong key

or failing to react within a certain amount of time. When the player makes a
mistake the computer will play a special sound after which the final score will be
announced. The final score is the number of tones which the player was able to
repeat in sequence.

Here's an example:
The computer plays the tone for the up arrow key.
The player hits the up arrow key.
The computer plays the tones for up arrow and left arrow, one after the other.
The player hits up arrow then left arrow.
The computer plays the tones for up arrow, left arrow, left arrow.
The player hits up arrow, left arrow, left arrow.
The computer plays the tones for up, left, left, down.
The player presses up arrow, right arrow, thereby making a mistake.
The game ends, and the final score is 3 points because the longest sequence the
player successfully repeated consisted of three tones.

A key aspect of successfully playing this game is memorizing which arrow key is
tied to which tone. To make this as easy as possible we will implement a keyboard
practice mode in which the player can press the arrow keys and listen to the tones
they generate without any time constraints. To enter this practice mode, the
player selects the appropriate option from a menu. Not only will this make our game
look considerably more professional but it will also allow me to explain how
to create menus in BGT. And if you thought it would end there, let me inform you
that our menu will also have background music.
Exercise:

Reread the above game design and create a list of the sounds the game will contain.

Here is my solution to the above exercise:

- Four sounds for the four different tones
- An error sound to play when the player makes a mistake
- A music loop to play when the menu is active

Since this is a tutorial about programming rather than sound design, you will need
to create the sounds that you wish to use for the game. In the below code, we
have selected the filenames that we use for each of these sounds. The four tones
are named 1.wav, 2.wav, 3.wav and 4.wav, the error sound is named error.wav, and
the music loop is named, appropriately enough, music.wav.

3. Implementing Memory Train

3.1 Preparations

It is almost time to actually start programming! But before diving into source
code, let us get some preliminaries out of the way.

Given the fact that you are reading this tutorial, it is quite likely that you have
already installed BGT on your computer. But just in case you haven't, now is
the time to do so.

Next, please create a new, empty directory for this project, and place the sounds
you created inside this directory.

Finally, open your favorite text editor and create an empty text file called
memory_train.bgt in the newly created directory. Some text editors, including
Notepad,
have a tendency to add a .txt extension to any file name that does not already end
in .txt. A tried and tested remedy for this is to include the file name in double
quotes. Another way to prevent the automatic .txt extension is to choose "all
files" in the file type field before clicking the "Save" button.

3.2 The smallest possible BGT script

If you have studied the language tutorial, you will know that every BGT script
contains one or more functions. The word "function" comes from the Latin "functio"
which means "execution" or "performance." In programming, a function is some code
that performs a well-defined task.

A function, in performing its task, can call other functions to carry out subtasks.
The important thing to keep in mind here is that when one function calls another,
the calling function is not finished. This leads to the rather peculiar fact that
several functions may be executing at the same time but only one of them is in
control. As an example from daily life, let us assume that the function
"get_dressed" has called the function "put_on_socks". Now the function
"put_on_socks" is
in control but the function "get_dressed" is not finished. Instead, it is patiently
waiting in the wings for "put_on_socks" to finish. As soon as this happens,
"get_dressed" is back in control and continues executing where it left off, which
will be just after the call to "put_on_socks".

I strongly urge you to reread the previous paragraph until you understand it
completely. One of the main reasons why people find programming confusing is that
they
have misunderstood the concept of functions and function calls. In case you are
still confused, the next time you put on your socks you will feel a warm glow
inside
and the concept of function calls will make perfect sense.

As an added bonus, once a function finishes it may return a value to its caller.
This is appropriately called the function's return value, or simply its result.

It is well worth our time to take a look at the smallest BGT script which could
possibly be written. For although it stops almost immediately after it starts and
does exactly nothing in between, it yet provides the structure, or framework, of
any other BGT script including Memory Train. Since it will eventually become part
of Memory Train anyway, now is also the time to copy it into your memory_train.bgt
file. Here it is, in full:

void main()
{
}

This defines a single function called main. The word "void" specifies that this
function has no return value, which makes sense once you realize that it is the
solitary function in this script and thus has nobody to return anything to. But its
lack of a return value has a much more practical reason, and this has to do
with the special significance of the name "main". The main function is special in
that it is where execution of every BGT script begins, and the execution of every
BGT script ends when the main function finishes. The two braces you see above
embrace between themselves the entire execution of your script.

3.3 A script that does something

Let us now make our script actually do something by placing some instructions
between those braces.

Exercise:

Find the alert function in the BGT reference, and with the help of the reference
modify your script to display a message box. The title of the message box should
be "Important Information", and the message text should be "Hello, I am John Doe,
and I am a programmer." Instead of John Doe, put your own name into the message.

Hint on using the reference: The "alert" function is part of BGT's foundation
layer.

Your script should now look something like this:

void main()
{
alert("Important Information", "Hello, I am Jane Smith, and I am a programmer.");
}

To execute your script, simply save the file, locate it in Windows Explorer and hit
enter on it. Note that this only works when BGT is installed.

In case you didn't notice, the line:

alert("Important Information", "Hello, I am Jane Smith, and I am a programmer.");
is a function call. The function being called is "alert", and the calling function
is "main". You can see that to call a function, we write its name, followed by
a pair of parentheses in which we specify the information we would like to pass to
the function, and finally a semicolon. In this case we pass two pieces of
information
to the "alert" function: a title and a message. There is a technical term for
pieces of information passed to a function, by the way. They are called parameters.

Let's see what happens if we add another function call. Our new script is as
follows:

void main()
{
alert("Important Information", "Hello, I am Jane Smith, and I am a programmer.");
alert("How many roads must a man walk down?", "The answer is 42.");
}

When you run this script, you will notice that, as you might expect, it displays
two message boxes, one after the other. This serves to illustrate the point I made
above, namely, that the main function is not stopped when it calls the alert
function. As soon as the alert function has finished doing its first job, control
flows
back into the main function which then proceeds to call the alert function again.

3.4 Making decisions

A BGT script can do much more than carry out instructions in sequence. Sooner or
later our scripts must learn to make decisions based on what the user does. Only
then can we develop interactive scripts, and interactivity is, after all, what
differentiates a game from a play.

Look at the following script:

void main()
{
question("A personal question", "Do you believe in the flying spaghetti monster?");
}

When you execute this script, it displays a message box similar to the one
displayed by a call to alert. However, this time the solitary OK button is replaced
by
a Yes and a No button.

Exercise:

Read the entry on the question function in the BGT reference.

Asking the user a question without reacting to the answer is pretty pointless, so
we will now modify the script to make a decision based on which of the two buttons
the user clicks. As you learned by consulting the reference, the "question"
function returns a value of 1 for the Yes button, 2 for the No button, and 0 if an
error
occurs.

To keep track of this return value, we will introduce a variable. A variable is a

named container for a value. It is called variable because the value it contains
may change.

To define a variable, we write its type followed by its name followed by a

semicolon, like so:
int answer;

This defines a variable named "answer" which can hold a value of type "int". "int"
is shorthand for "integer" and means a whole number, i.e. a number without a
decimal point. If you would like to learn about the various other types supported
by BGT, let me refer you to the language tutorial.

When we have defined a variable, we can assign a value to it by writing the name of
the variable, an equals sign, the value we would like to assign, and finally
a semicolon:
answer = 42;

In our running example, we don't want to place the number 42 in our variable.
Instead, we would like our variable to store the value that the "question" function

returned. We achieve this by simply replacing our 42 with the call to the
"question" function:

void main()
{
int answer;
answer = question("A personal question", "Do you believe in the flying spaghetti
monster?");
alert("Thank you!", "Your answer was " + answer + ". See you later.");
}

If you try out this script, you will notice that you get different messages
depending on which of the two buttons you choose. This is because the variable
"answer"
receives the value returned by the "question" function. So this is in fact our
first interactive script.

Note also how we used the plus sign to tie several things together into something
larger:
"Your answer was " + answer + ". See you later."
Scanning this from left to right, we find some text in double quotes, a plus sign,
a variable name, another plus sign, and some more text in double quotes. In this
case, the plus signs serve to tie these three things together into the message we
would like to display, like tying together three strings of pearls into a longer
string of pearls. Programmers refer to a piece of text as a string because it is
easily visualized as a string of characters. To use this term in context, we have
just added a string, a number, and another string to form our message, which is
itself a string.

You might be wondering, if the plus sign is used for tying strings together, how
would you add two numbers? The surprising answer is that the plus sign is used
for that purpose as well. The plus sign is a symbol which may refer to different
activities, depending on context. In technical terms, the plus sign is an
overloaded
operator.

In our running example, our script is now able to react differently depending on
which button the user clicks, but our reactions are not yet very meaningful.
Wouldn't
it be great if we could display completely different messages depending on the
user's response? The following script does exactly that:

void main()
{
int answer;
answer = question("A personal question", "Do you believe in the flying spaghetti
monster?");
if(answer == 1)
{
alert("How interesting!", "Thank you for being that honest.");
}
else if(answer == 2)
{
alert("I thought so!", "Now don't tell me the invisible pink unicorn got you
first.");
}
else
{
alert("Whoops!", "Something is dreadfully wrong here! Maybe it's the monster taking
revenge.");
}
}

This script uses the "if" statement to make a decision based on the value of the
"answer" variable. If the value is 1, the first message is displayed. Otherwise,
if the value is 2, the second message is displayed. Finally, if the value is
neither 1 nor 2, the third message is displayed, indicating that an error has
occurred.

Keep in mind that the keyword "if" is always followed by a condition in

parentheses, and that in this case the closing parenthesis is never, I repeat,
never, followed
by a semicolon.

A condition is something which can either be true or false. This is in line with
the usage of the word in every-day English. For example, the condition for going
by train is that you are in possession of a valid ticket. If the condition is false
you may not board the train.

The condition to test whether two things are equal looks like this:
a == b
Note the use of a double equal sign. This is required because the single equal sign
is already used for something else.

Exercise:

What is the single equal sign used for? Hint: The answer is contained earlier in
this tutorial.

Note that we have enclosed every branch of the above "if" statement in its own pair
of braces. Strictly speaking, this is necessary only if a branch consists of
multiple instructions. Since all three branches in the above script consist of a
single instruction, namely, a call to "alert", we could just as well have written
the following:

void main()
{
int answer;
answer = question("A personal question", "Do you believe in the flying spaghetti
monster?");
if(answer == 1)
alert("Ramen to you, then!", "Thank you for being that honest.");
else if(answer == 2)
alert("I thought so!", "Now don't tell me the invisible pink unicorn got you
first.");
else
alert("Whoops!", "Something is dreadfully wrong here! Maybe it's the monster taking
revenge.");
}

Over the years of my programming career I have formed the habit of always including
the braces from the start even in such cases where they are not strictly necessary.

This way, when I add more statements at a later date I never have to worry about
whether or not to add another pair of braces.

Just so that you know, the braces in a function definition are mandatory. For
instance, the definition of your main function will always contain braces even if
the function consists of a single instruction---in fact, even if it should consist
of no instructions at all!

Exercise:

Read the relevant parts of the language tutorial to familiarize yourself with the
various programming constructs for making decisions. In particular, pay close
attention to the if, while, and for statements as they will be used in this
tutorial.

3.5 A menu for Memory Train

In our quest for theoretical background we have digressed quite a bit from our
original endeavor, which was to implement the game we designed in the previous
chapter.
Now is the time to get back to it.

Let's go back to our simplest of scripts, which was this:

void main()
{
}

Exercise:

The helper layer contains a helpful tool for creating menus. Can you find it in the
reference?

The tool we are after is called dynamic_menu. It allows us to easily put together a
menu in which the player can select an item with the up and down arrow keys
and activate it by pressing enter. As you undoubtedly know, such menus abound in
audiogames, with typical menu items being "start game", "test speakers", "options",

and "exit game".

Let's take a moment to summarize what you already know about functions and
variables.

� A BGT script contains one or more functions.

� A function is a piece of code that performs a well-defined task. Note that code
is just another word for program text.
� Every script contains a special function called "main". Execution of your script
begins at the start of this function and ends when this function has finished
executing.
� Functions can delegate subtasks to other functions.
� When function f asks function g to perform its task, we say that function f calls
function g.
� When f calls g, f may pass some pieces of data to g. These pieces of data are
called parameters.
� When g has finished, it may pass a single piece of data back to f. This is called
a return value.

A variable is a named container for a value which may change.

Every variable has a type, and while the value of a variable may change, the type
never will. This means that an int variable will only ever store values of type
int, and a string variable will only ever store strings. This may sound awfully
restrictive, but it also means less work for the computer and fewer opportunities
for programming errors. Besides, why should you want to use a single variable for
vastly different purposes when you can have as many variables as you like?

In this section we will go one step further and talk about a kind of variable which
has other variables and functions living inside it. A value with variables and
functions inside it is called an object, and a variable holding an object is called
an object variable, just as a variable holding an int is called an int variable.
If this all sounds just a bit confusing, let me assure you that it will quickly
become second nature to you once you see it in action. In just a few paragraphs
you will realize that objects are all about simplicity.

Examine the following script:

#include "dynamic_menu.bgt"

void main()
{
show_game_window("Memory Train");
dynamic_menu menu;
menu.add_item_tts("Start game");
menu.add_item_tts("Keyboard practice");
menu.add_item_tts("Exit game");
menu.allow_escape = true;
menu.wrap = true;
menu.run("Please choose a menu item with the arrow keys, then hit enter to activate
it.", true);
}

Exercise:

With the help of the reference, try to figure out what the above script will do.
Test your hypothesis by running the script. Note: This script contains some
constructs
we have not covered yet, but they will all be explained below.

Let's start with the elements you already recognize. First, you will immediately
have noticed that this is your standard main function with a sequence of
instructions
between the braces. Next, examine the following line:
show_game_window("Memory Train");
This is some name followed by a pair of parentheses with some data between them,
and finally a semicolon. What do we call such a thing? Yes, a function call.

Exercise:
How many parameters does the above function call have?

Exercise:
Find out what the function does.
You may be wondering why we would want to display a window in the first place when
our game will not have any visual elements. The answer is that on Microsoft
Windows,
any program that handles keyboard input should display a window. Our game will only
be able to react to keyboard input when our game window is active. This will
also allow the player to switch back and forth between our game and other running
applications.

Next, take a close look at the following line:

dynamic_menu menu;

If this confuses you, it might be helpful to realize that this is structurally

similar to something we have seen earlier:
int answer;

Both of these statements are variable definitions. One of them defines a variable
of type int and gives it the name "answer", the other one defines a variable of
type dynamic_menu and gives it the name "menu". And just as int is a data type for
numbers, dynamic_menu is a data type for menus. The word "dynamic" is used here
meaning "flexible" because you, as game programmer, can decide which items the menu
will contain.

Let's go ahead and add some items to our menu:

menu.add_item_tts("Start game");
menu.add_item_tts("Keyboard practice");
menu.add_item_tts("Exit game");

Notice the striking similarity to function calls? The only difference is that this
time we are calling a function that lives inside our menu variable. Recall that
an object is a value with variables and functions living inside it. In this case we
have on our hands an object of type dynamic_menu.

To call a function inside an object, we write the variable name, a full stop, and
then the name of the function we are calling. This is followed by the usual pair
of parentheses which, as we have learned, is part of every function call. A
function inside an object is called a method. To use this term in context:
add_item_tts
is a method of the menu object.

An object gets its methods from its type. Thus, to find out what methods an object
provides we need only know what type, or class, the object belongs to. The "menu"
object is of class dynamic_menu, so we need only consult the reference of
dynamic_menu to find out about the available methods.

Exercise:

The following statement defines an object variable:

file saved_game;
Which of the following statements are valid?
saved_game.open("test.dat", "w");
saved_game.print("Hello, world!");
saved_game.write("Hello again!");
saved_game.close();
saved_game.open("test2.dat");

With the menu set up the way it is, we need to perform one more step to present it
to the user:

menu.run("Please choose a menu item with the arrow keys, then hit enter to activate
it.", true);

3.6 Sound and speech

This section covers two additional building blocks required for putting Memory
Train together. Let us begin with sound, which will be an essential feature of any
audio game you will ever develop.

In BGT, every sound is represented by a sound object. One way of visualizing a

sound object is to picture it as a tape player with its various controls. For
example,
while your tape player probably has buttons labelled play, stop, and pause, as well
as a volume knob or slider, the sound object has methods named play, stop, and
pause, as well as a volume property. In addition, a program sometimes needs to
check if a sound is still playing. To allow this, the sound object has a property
called playing which will be true as long as the sound is playing, and will become
false as soon as it has stopped. The following example illustrates how the sound
object can be used:

void main()
{
sound intro; // Creates the sound object.
intro.load("intro.wav"); // Loads the sound; equivalent to putting a tape into the
player.
intro.play(); // Starts playing.
while(intro.playing)
{
// Do something while the intro is playing.
wait(5); // Give other Windows tasks 5 milliseconds time.
}
// The sound has stopped.
}

Some games, including Memory Train, make use of a speech synthesizer on the
player's computer. The way to do this in BGT is to use a tts_voice object, where
tts
stands for "text to speech." The two most interesting methods of tts_voice are
speak and speak_wait. The speak method will begin speaking the string which was
passed
to it and will continue speaking in the background while your program may do other
things. In comparison, the speak_wait method will additionally wait until the
speech has stopped, and only then will your program continue with the next
instruction.

3.7 Time

All but the simplest of games need to keep track of time in some way. BGT provides
a timer object for this purpose. The most important features of the timer object
are the restart method and the elapsed property. By calling the restart method,
your program is able to reset the timer back to zero in much the same way as if
you were restarting a stopwatch. The elapsed property will always contain the
number of milliseconds since the timer was last restarted, or, if it was never
restarted,
elapsed will contain the number of milliseconds since the timer was created.

It is considered good behavior for a Windows application to regularly wait for a

few milliseconds. Not only does this give other processes in the system more time
to execute their own tasks but it also increases the system's ability to save
energy. In BGT, you can use the wait function to put your program to sleep for the
specified number of milliseconds. Note that the time which actually passes may
differ from the time you specified, so it is advised that you use a timer to check
how many milliseconds have actually passed. When in doubt, do not use the wait
function to time game events, but use a timer instead as timers are usually
accurate
to the millisecond.

3.8 Keyboard input

In order for your game to be able to respond to keyboard input, BGT contains two
functions which let you check the status of any given key on the user's keyboard.
Use the key_down function to find out if a given key is being held down at that
moment. Note that key_down will return true as long as the key is being held down.
If you are not interested in how long a key is being held but rather would like to
be informed of every keypress just once, use the key_pressed function instead.
When a key is held down, key_pressed will return true only the first time you check
that particular key, and false on subsequent calls. Only if the key was released
and is now being held down once more will key_pressed return true again.

To find out which keys can be checked and how they are expressed in BGT, consult
appendix A of the BGT help system.

3.9 The main function

Armed with a basic understanding of the fundamental features of BGT, we can now
begin coding the bulk of Memory Train. Let us start with the main function which,
as you learned earlier in this tutorial, is the heart of any BGT script. The
responsibilities of the main function are as follows:
� 1. It loads the various sounds required by the game into memory.
� 2. It sets up the game menu.
� 3. It speaks a short intro.
� 4. It repeatedly runs the menu and executes the function the user has chosen.
� 5. The repetition ends as soon as the user presses the escape key in the menu or
chooses the "exit game" entry.

While we are at it, we will also define some global variables the main function
refers to. Our code now looks as follows:

#include "dynamic_menu.bgt"

// Sound objects.
sound music;
sound error_sound;
sound[] tone(4); // The four tones used for sequences.

void main()
{
// Load the four tones.
tone[0].load("1.wav");
tone[0].volume = -10;
tone[1].load("2.wav");
tone[1].volume = -10;
tone[2].load("3.wav");
tone[2].volume = -10;
tone[3].load("4.wav");
tone[3].volume = -10;

// Load the error sound.

error_sound.load("error.wav");
error_sound.volume = -10;

// Load the music.

music.load("music.wav");
music.volume = -10;

// Set up voice.
tts_voice voice;

// Set up menu.
dynamic_menu menu;
menu.allow_escape = true;
menu.wrap = true;
menu.add_item_tts("Start game");
menu.add_item_tts("Keyboard practice");
menu.add_item_tts("Exit game");

// Show game window and speak welcome message.

show_game_window("Memory Train");
voice.speak_wait("Welcome to Memory Train!");

// Loop the music in the background before running the menu.

music.play_looped();

int choice; // This stores the user's menu selections.

do
{
choice = menu.run("Please choose a menu item with the arrow keys, then hit enter to
activate it.", true);
if(choice==1)
{
music.stop();
play_round(); // We will define this function later.
music.play_looped();
}
else if(choice==2)
{
music.stop();
keyboard_practice(); // We will define this function later.
music.play_looped();
}
}
while(choice!=0 and choice!=3);

// The user pressed escape or chose to exit.

voice.speak_wait("Thanks for playing.");
}

3.10 Keyboard practice

If the user chooses the keyboard practice item from the menu, our above main
function will call a function named keyboard_practice. This has the following
responsibilities:
� 1. It speaks instructions on how to operate the keyboard practice mode.
� 2. It waits for the user's keypresses.
� 3. When an arrow key has been pressed, it plays the appropriate tone.
� 4. When escape has been pressed, keyboard practice is aborted.
Here is the code for the keyboard_practice function:

void keyboard_practice()
{
tts_voice voice;
voice.speak_wait("Press the arrow keys to find out which key generates which
tone.");
voice.speak_wait("Press escape to stop practicing.");
while(!key_pressed(KEY_ESCAPE))
{
if(key_pressed(KEY_LEFT))
{
play_tone(0);
}
else if(key_pressed(KEY_DOWN))
{
play_tone(1);
}
else if(key_pressed(KEY_RIGHT))
{
play_tone(2);
}
else if(key_pressed(KEY_UP))
{
play_tone(3);
}
wait(5);
}
}

3.11 Playing a tone

Notice how we introduced the play_tone function in the above code for
keyboard_practice. The responsibility of play_tone is to play a single tone. Here
is the corresponding
code:

void play_tone(int i)
{
tone[i].stop();
tone[i].play();
}

This function first stops the tone in case it is already playing, then restarts
playing it. By the way, if the expression tone[i] confuses you, this might be a
good time to read up on the subject of arrays in the language tutorial.

3.12 Playing the game

If the user chooses the "start game" item from our game menu, the main function
calls the play_round function. This function is responsible for carrying out an
entire round of play, after which the score is announced. Here is the code for
play_round:

void play_round()
{
// Initialize game state.
bool game_over = false; // The game will continue as long as this is false.
int[] sequence; // The running sequence.
int sequence_length = 0;
float time_between_tones = 500; // The initial speed at which tones are played, in
milliseconds.
float time_between_inputs = 2000; // Maximum time to input next key before player
gets bounced.
do
{
// Add another tone to the sequence.
sequence_length++;
sequence.resize(sequence_length);
sequence[sequence_length-1] = random(0,3);
// Play back the sequence from start to finish.
output_sequence(@sequence, time_between_tones);
// Let them repeat it if they can.
game_over = input_sequence(@sequence, time_between_inputs);
// Every time another five tones have been mastered:
// increase the speed ever so slightly.
if((sequence_length%5) == 0)
{
time_between_tones = time_between_tones*0.9;
// Make sure it does not fall below 150.
if(time_between_tones < 150)
{
time_between_tones = 150;
}
}
}
while(!game_over);
int score = sequence_length-1; // minus 1 because they failed on the last.
tts_voice voice;
voice.speak_wait("Your final score was " + score);
}

3.13 Playing a sequence

The output_sequence function plays a sequence of tones so that the player may try
to memorize it. It requires two parameters, the sequence to output, and the time
between the tones. This flexible approach was taken to enable the game to increase
the speed over time. Here is the code for output_sequence:

void output_sequence(int[]@ sequence, float time_between_tones)

{
timer clock;
int current;
for(uint i=0; i<sequence.length(); i++)
{
// For every tone but the first, wait before playing.
if(i>0)
{
clock.restart();
while(clock.elapsed < time_between_tones)
{
wait(5);
}
}
current = sequence[i];
play_tone(current);
}
// Finally, wait for the last sound to subside.
while(tone[current].playing)
{
wait(5);
}
}

3.14 Testing the player's memory

The final puzzle piece is the input_sequence function. This function is responsible
for testing if the player remembers the sequence correctly. If the player fails
to press one of the arrow keys in a given time, or presses the wrong arrow key,
this function will return true to indicate that the game is over. If, on the other
hand, the player manages to replay the sequence correctly, then this function
returns false, indicating that the game is to continue. Here is the code for
input_sequence:

bool input_sequence(int[] @sequence, float time_between_inputs)

{
timer clock;
for(uint i=0; i<sequence.length(); i++)
{
// Do the following for every tone in the sequence:
clock.restart();
int input = -1; // Set it to something invalid.
while(clock.elapsed < time_between_inputs)
{
if(key_pressed(KEY_LEFT))
{
input = 0;
}
else if(key_pressed(KEY_DOWN))
{
input = 1;
}
else if(key_pressed(KEY_RIGHT))
{
input = 2;
}
else if(key_pressed(KEY_UP))
{
input = 3;
}
if(input>=0)
{
break; // Stop waiting because something was typed.
}
wait(5);
}
// Game is over if timed out or wrong key.
if(input!=sequence[i])
{
error_sound.play_wait();
return true;
}
// Play back successful tones as feedback
play_tone(input);
}

// The player managed to replay the entire sequence.

// Wait one second to let them catch their breath.
clock.restart();
while(clock.elapsed < 1000)
{
wait(5);
}
return false;
}

3.15 Putting it all together

The complete source code for Memory Train is contained in the code fragments given
in sections 3.9 to 3.14. In order to test the game, you can simply paste all
of the code fragments into the file memory_train.bgt which you created earlier. To
run the game, simply navigate to the file memory_train.bgt in Windows Explorer,
then press enter to start.

Final exercises:

� 1. Extend the game to provide a two-player mode. Both players sit at the same
keyboard. Player one uses the arrow keys to play, and player two uses the keys a,
s, d, and w. In this variant, sequences are not randomly generated by the computer.
Instead, player 1 starts with one tone, player 2 repeats the one tone and adds
another, player 1 repeats the two tones and adds a third, etc. The game ends when
one of the two players fails to press a key in time, presses the wrong key, or
presses a key when it was not his or her turn. The player making the mistake loses,
and the other player wins with a score equal to the longest sequence he typed.

� 2. Extend the game so that it provides different difficulty levels. Note that
this is both a design and an implementation exercise.