The Amulet of Quang

Contents
� 1. Introduction
� 2. The name of the game
� 3. Let's get serious
� 4. Designing the interface
� 5. Music
� 6. Sound effects
� 7. Speech
� 8. Sound design
� 9. Inventory
� 10. Items
� 11. Areas
� 12. Player position
� 13. Looking around
� 14. Moving around
� 15. Object manipulation
� 16. Game loop
� 17. Use your imagination
1. Introduction
Welcome to the third and final installment of Practical BGT, the series of
tutorials in which you develop actual playable games while learning the basic
concepts
and techniques of BGT programming. If you haven't completed the first two
installments in this series, we strongly recommend that you do so before starting
out
on part III.

Let us take just a few minutes to go over what you learned in the first two parts.

In part I, Memory Train, you took a straight dive into the syntax and basic
functionality of BGT. You learned how the execution of your game program can be
described
in terms of functions calling other functions and making decisions based on what
they return. More specifically, you saw how to display a game window and ask for
keypresses, how to load and play sounds and background music, how to keep track of
time, and, last but not least, how to exit your game.

In Part II, Windows Attack, you took a more systematic approach to game design. You
took the description of a game and extracted from it a list of required sounds,
a description of the game state, and finally, the source code of the game itself,
complete with a self-made script class. In addition, you learned to harness the
power of a sound pool to position an arbitrary number of sounds in real-time.

This final installment will provide you with some powerful programming techniques
and design approaches to make your life easier as you begin to work on larger-scale

projects. You will probably not learn any new syntactic constructions here, nor
will the mini game you will write be anywhere as spectacular as those you
programmed
in the first two parts. Instead, this part is designed to put the tools into your
hands which, combined with imagination and creativity, will allow you to create
games of high software quality and consistent user experience.

If anything in this tutorial should appear confusing or unclear, chances are you
will find the missing puzzle pieces in the language tutorial, the BGT reference,
or, indeed, in the first two parts of this series. Sometimes it is also a good idea
to just continue reading with dogged determination, and you might find the answer
in the next paragraph. In any case, you should take frequent breaks, maintain a
calm, rational, detective-like approach to complexity, and remember that bugs
happen
to the best of us, and are valuable lessons only real life can teach.

With that in mind, let the games begin!

2. The name of the game
In ancient and altogether more interesting days, ages before the golden days of
yore, the mysterious days of lore, and the ridiculously long-ago days of nevermore,

the Kingdom of Quang stood proudly. Proudly indeed it stood, impervious to the
ravages of slime, until its two supreme rulers, during one of their regular and
excessive
drinking binges, got into a fateful and bloody argument about who stole the cookies
from the cookie jar. The question was never answered, but such was the monstrosity
of the ensuing war that the mighty Kingdom of Quang fell and sank beneath the sea.
The wizards of Quang, however, having gazed deeply into their crystal balls,
knew that tragedy was afoot, and managed to transfer all the knowledge of their
high culture into a powerful magical artefact---the Amulet of Quang.

You, a secret agent of the even more secret world government, have been transported
to the vast underground empire of Quang. Your mission is to recover the Amulet
of Quang and transport it back to the surface of the earth.
3. Let's get serious
Here is a more serious description of the game.

The Amulet of Quang is an audio adventure in which the player can explore his
surroundings, walk from place to place, and interact with the various objects which

litter the game world. Every area of the game map may provide its own background
music, and objects may or may not emit sound. The player will be informed by means
of a spoken message when the main character spots a new object. The player can
obtain a detailed description of an object by examining it. Some objects can be
picked
up. The objects the player is carrying are organized into an inventory list which
can be accessed at any time during the game. It is possible to use objects in
the inventory list. The game can be paused at any time.
4. Designing the interface
Exercise
Analyzing the description in the previous section, create a detailed specification
of the game's interface. The interface consists of everything the player needs
to know in order to successfully play your game. Mostly, this would be the kind of
information you might put into a user manual. Here are a few questions to put
you on the right track:
1. How does the player walk around the map?
2. When and in which way is the player informed of available objects?
3. Will there be footstep sounds?
4. How does the player examine, pick up, or use an object?
5. How does the player access the inventory list?
6. How does the player examine or use an object in the inventory list?
7. How does the player pause and unpause the game?
8. Finally, how would the player exit the game?
Here is my solution. In case our answers differ, this does not mean that you have
got it wrong, but merely that we have chosen to create slightly, or maybe even
dramatically, different kinds of games. The main reason why I am detailing my
solution here is to show you the level of detail required for a user interface
specification.
In general, the more complete your specification at design time, the less trial and
error at coding time. It is perfectly reasonable at design time to leave certain
details open to discussion or change, but this should happen as the result of
deliberate choice rather than unconscious omission. So let us agree for the moment
to stick to my specification, and if afterwards you feel that your solution is
worthwhile trying, I shall leave it as an exercise to you to go back and redo from
that point onward. In fact, I highly recommend doing so. Also, do not be put off if
it seems to take days, or even weeks, to get exactly right. This is to be expected.

The player walks around the game map by using the four arrow keys. Pressing and
then immediately releasing an arrow key will move the player exactly one step in
the corresponding direction. Holding an arrow key will move the player one step in
the corresponding direction every half second. In this way, a steady motion is
established just by comfortably holding down a key, but an impatient player can
still accelerate the process by tapping the key more quickly.

To give the player feedback that motion has indeed occurred, the game will play a
footstep sound for every step the player takes. If, after taking that step, the
available directions for the next step have changed, we will play a slightly
modified footstep sound to alert the player to that change. For example, assume the

player is walking down a long east-west corridor, and suddenly comes upon an exit
to the north. This would be the time when our modified footstep sound would be
played. So we define two footstep sounds, one of them soft and unobtrusive, the
other slightly more demanding, which might be accomplished by making it slightly
louder or higher in pitch.

Let's move on to what we might call the model of visibility. This is the set of
rules which determine what objects the player sees at any given time. Such a model
could get arbitrarily complex, taking into account such details as distance and
size of objects, lighting conditions, fog, or other objects which obstruct the
view.
For this design, however, we will keep it simple by defining just two basic
visibility rules. An object is visible if
1. it has the same x or y coordinate as the player, i.e. it is straight to the
north, east, south, or west,
and
2. there is no wall anywhere between the player and the object.

Whenever the player moves such that a new item is spotted, we will provide a spoken
message stating what kind of object it is, in what direction it lies, and how
many steps it would take to get to it. Note that we will only speak the objects as
they move into view, not those which were already visible before. For example,
if the player took one step north, we wouldn't need to speak any visible objects to
the north or south because they would have been visible before taking the step.
If this sounds confusing, I recommend you reread the two visibility rules above and
then form some examples in your mind to illustrate how they work. Specifically,
it is important to understand that taking a step to the north or south can only
change what is visible to the east or west, and vice versa.

A general description of the area at large is spoken when the player enters it, and
repeated as requested via the l command. Note: l as in look.

To examine, pick up, or use an object, the player must first move to that object's
location. A special sound is then played to indicate that an object has been
reached, and the object is announced. To examine it, the player uses the x command.
The t command will attempt to pick up the object. Finally, hitting the space
bar will attempt to interact with the object in some way. For instance, hitting the
space bar on a door might try to walk through that door, and hitting the space
bar on a gong might strike the gong.

The tab command will cycle through the objects in the player's inventory. To use an
object in the inventory, the player first cycles to this object by pressing
tab until the object is announced, and then presses u, as in use. To examine an
object in your inventory, you would first cycle to it by pressing tab repeatedly,
and then press i, as in inventory information.

To pause the game at any time, the player can press the p command. The same command
also resumes a paused game.

Finally, the escape key will exit the game. The game may also exit when the player
wins or dies, but escape is always available to exit prematurely.

Pressing page up or page down will allow the player to adjust the volume of the
music. This is especially useful in conjunction with spoken messages, because the
music might drown out the voice if too loud.

To make the experience of learning the interface as smooth as it could possibly be,
we will implement a help feature which will make our game self-documenting.
Help can be accessed at any time by pressing f1, whereupon the game will provide
spoken information about all the possible keyboard commands at that time.
5. Music
Exercise
One important aspect of game music is its ability to gracefully fade in and out.
Write a fade function which can be called as follows:
fade(sound@ noise, double start_volume, double end_volume, double time, bool
interruptable);
When called, this function should fade the given sound object from the start volume
to the end volume in the given time in milliseconds. If interruptable is true,
the player can interrupt the process by pressing the space bar. The fade function
returns true if the player interrupted the process using the space bar, and false
otherwise.

Here is one possible solution:

bool fade(sound@ noise, double start_volume, double end_volume, double time, bool
interruptable)
{
noise.volume = start_volume;
timer t;
double elapsed = t.elapsed;
while(elapsed < time)
{ noise.volume = start_volume + (end_volume-start_volume)*elapsed/time;
wait(10);
elapsed = t.elapsed;
if(key_pressed(KEY_SPACE) && interruptable)
{
return true;
}
}
noise.volume = end_volume;
return false;
}

We will use a sound object to play our in-game music, so let us declare this object
now:

sound music; // The one sound object used for all music

Next, we need a variable to keep track of the current volume of the music as the
player configured it using the page up and page down commands:
int music_volume; // Volume for all game music

Now let us define a function to change the currently playing music. This function
will accept as parameter the filename of the music to change to. The elegant thing
about this function is that it will fade out the currently playing song, then fade
in the new one, resulting in a graceful transition from one track to the next.

// Changes the music, fading if appropriate

void music_change(string music_file)
{
if(music.playing)
{
fade(@music, music_volume, -50, 500, false);
}
music.stream(music_file);
music.volume = -50;
music.play_looped();
fade(@music, -50, music_volume, 500, false);
}

And while we are at it, let's define some more music-related functions:

// Fades out the music

void music_stop()
{
if(music.playing)
{
fade(@music, music_volume, -50, 500, false);
}
}

// Pauses the music abruptly

void music_pause()
{
music.pause();
}

// Resumes the music abruptly

void music_resume()
{
music.play_looped();
}

// Increases the volume of the music gracefully

void music_volume_up()
{
if(music_volume <= -5)
{
int old_volume = music_volume;
music_volume += 5;
fade(@music, old_volume, music_volume, 200, false);
}
}

// Decreases the volume of the music gracefully

void music_volume_down()
{
if(music_volume >= -55)
{
int old_volume = music_volume;
music_volume -= 5;
fade(@music, old_volume, music_volume, 200, false);
}
}

Note that in the remainder of our source code, we will never manipulate the music
object directly, but only through the functions we just defined. Software
engineering
calls this approach modularization. It makes sure that whenever something is wrong
with the music, we need only check the correctness of our music functions, because
since all music-related activity takes place through these functions, this is where
any music-related bug would logically be found.

Another advantage of modularization is that if the underlying implementation of the

music module changes in the future, no source code outside this module would
need to be adjusted because the rest of our source code does not rely on the
underlying implementation but only upon the functions which our module exposes to
the
outside world. For example, a future incarnation of our music module might use midi
files and sound fonts instead of prerecorded audio. All we need to change in
order to accomplish this would be the functions we just defined. No other part of
our source code would need to be modified because all music-related activity is
channeled through the above functions.
6. Sound effects
In part II of this tutorial series you learned about the sound_pool class. Let us
use this class now to define some sound-related functions:

sound_pool pool; // The sound pool used for all sound effects

// Plays a sound in the center of the stereo field

void sound_play_centered(string filename)
{
pool.play_stationary(filename, false); // Not looping
}

// Pause all sounds

void sound_pause_all()
{
pool.pause_all();
}

// Resume all sounds

void sound_resume_all()
{
pool.resume_all();
}

// Gets rid of all sounds at once

void sound_purge()
{
pool.destroy_all();
}
Exercise
Our example game is relatively simple in that it uses only centered sounds. As your
games become more complex and challenging, you will want to use positional audio.
Extend the sound module accordingly. Apply what you know about the sound_pool
class, and consult the reference when in doubt.
7. Speech
The third and final auditory component of our game will be spoken messages. For
now, the voice which delivers them will be computer-generated, so we will use the
tts_voice class you already saw in the first two installments of Practical BGT.

tts_voice voice; // The voice used for all in-game messages

// Speaks some text

void voice_speak(string text)
{
voice.speak(text);
}

// Speaks some text, interrupting text which is being spoken

void voice_speak_immediately(string text)
{
voice.speak_interrupt(text);
}

// Silences the voice

void voice_stop()
{
voice.stop();
}
8. Sound design
Exercise
From the specification in section 4, extract a list of required sounds.

Here is my solution:
� step.wav: A standard footstep
� step_alert.wav: A footstep after which the available directions have changed
� item.wav: The player has reached an object
9. Inventory
Now we are slowly making our way from the very general-purpose modules to the more
game-specific functionality. In this section we deal with the player's inventory
list, a dynamically expanding or shrinking list of all the items the player is
currently carrying. We are going to use an array to keep track of the handles to
the items in the player's inventory, and we will provide functions through which
this array is manipulated.

item@[] inventory; // The inventory is an array of handles to items

int inventory_position = -1; // Current position in the inventory list

// Adds an entry to the inventory list

void inventory_add(item@ entry)
{
int old_length = inventory.length();
inventory.resize(old_length+1);
@inventory[old_length] = entry;
}

// Removes an item from the inventory; returns true on success, false on failure
bool inventory_remove(item@ entry)
{
uint index; // For searching the inventory for the entry
for(index=0; index<inventory.length(); index++)
{
if(inventory[index] is entry) // Found it
{
break;
}
}
if(index >= inventory.length()) // Entry not found
{
return false;
}
// Move all above entries one slot down
for(uint i = index+1; i<inventory.length(); i++)
{
@inventory[i-1] = @inventory[i];
}
// Finally, make the inventory one slot smaller
inventory.resize(inventory.length() - 1);
inventory_position = -1; // Make it invalid
return true;
}

// Gets the current inventory entry

item@ inventory_current()
{
if(inventory_position < 0) // No current item {
return null;
}
return @inventory[inventory_position];
}

void inventory_cycle()
{
if(inventory_position+1 >= int(inventory.length()))
{
inventory_position = 0; // Go back to first if at the end
}
inventory_position++;
}
10. Items
The inventory list is all about managing and cycling through the items in the
player's possession. Let us now turn to the question of what an item is in the
first
place.

In an adventure game, an item can be defined as any object with which the player
might want to interact. For example, if one of the game's challenges consisted
of unlocking a door with a key, both the door and key would be considered items. We
use the word item here as a generic term for any object in the game world,
including
treasures, monsters, doors, and weapons.

For our purposes, an item must provide at least three pieces of information:
1. A name; this is how the game refers to the item when describing what the player
sees, or when cycling through the inventory.
2. A description; this is what the player hears when examining the item.
3. A takeable flag; this determines whether or not the item can be picked up. Note
that flag is just programmer lingo for bool. Setting a flag to true is sometimes
referred to as just setting it, and setting it to false can also be called clearing
it.
Let us translate this into code:

class item
{
string name;
string description;
bool takeable;
item()
{
alert("Programming Error", "Cannot make item without parameters.");
}
item(string name, string description, bool takeable)
{
this.name = name;
this.description = description;
this.takeable = takeable;
}
}
11. Areas
Areas comprise the geography of an adventure game. They have been known under
various names, including rooms, levels, or maps. But no matter how we refer to
them,
they are the world through which the player navigates.

Some mainstream games go out of their way to simulate real world geography,
complete with heights, textures, and weather conditions. While all of this is
certainly
possible in BGT, for simplicity's sake we shall stick with a basic setup here,
keeping track of just the locations of walls and items on our maps. We represent
this information in two arrays, both of them two-dimensional. In addition, every
area will provide a general description of where the player is located. This will
be announced when the player chooses to look around by pressing the l command.

class area
{
int size_x; // East-west size of area
int size_y; // North-south size of area
bool[][] walls; // true for wall tiles, false for floor space
item@[][] items; // Items on the map
string description; // Announced when looking around
area()
{
alert("Programming Error", "Cannot construct area without parameters.");
}
area(int size_x, int size_y, string description)
{
this.size_x = size_x;
this.size_y = size_y;
this.description = description;
walls.resize(size_x);
items.resize(size_x);
for(int i=0; i<size_x; i++)
{
walls[i].resize(size_y);
items[i].resize(size_y);
for(int j=0; j<size_y; j++)
{
walls[i][j] = false;
@items[i][j] = null;
}
}
}
void add_wall(int x, int y)
{
walls[x][y] = true;
}
void add_item(item@ entry, int x, int y)
{
@items[x][y] = @entry;
}
bool get_wall(int x, int y)
{
if(x<0 or x>=size_x or y<0 or y>=size_y)
{
return true; // The wall of the universe
}
bool ret = walls[x][y];
return ret;
}
item@ get_item(int x, int y)
{
item@ ret = @items[x][y];
return ret;
}
}
12. Player position
To represent the player's current position, we need to store the current area as
well as the player's current x and y coordinates.

area@ player_area;
int player_x;
int player_y;
13. Looking around
Let us now define a function which looks out from the player's location in a given
direction, and reports on what the player sees. This function takes an x and
a y increment. For instance, to look eastward, you would supply an x increment of 1
and a y increment of 0. To look south, you would supply an x increment of 0
and a y increment of -1.

void look(int x_increment, int y_increment)

{
int x = player_x;
int y = player_y;
string direction; // Name of direction, such as east or north
if(x_increment<0) // Westerly
{
if(y_increment<0) // Southwest
{
direction = "southwest";
}
else if(y_increment==0) // West
{
direction = "west";
}
else // Northwest
{
direction = "northwest";
}
}
else if(x_increment==0) // North/south
{
if(y_increment<0) // South
{
direction = "south";
}
else if(y_increment==0) // Right here
{
direction = "here";
}
else // North
{
direction = "north";
}
}
else // Easterly
{
if(y_increment<0) // Southeast
{
direction = "southeast";
}
else if(y_increment==0) // East
{
direction = "east";
}
else // Northeast
{
direction = "northeast";
}
}
while(true)
{
x += x_increment;
y += y_increment;
if(player_area.get_wall(x, y))
{
break; // Hit a wall
}
if(player_area.get_item(x, y) is null)
{
continue; // Nothing there, so look on
}
// Found an item
int distance = absolute(x-player_x) + absolute(y-player_y);
voice_speak(player_area.get_item(x, y).description + ", " + distance + " " +
direction);
}
}
14. Moving around
Exercise
Write a function
bool move(int x_increment, int y_increment)
that moves the player in the given direction if possible. The function should
return true if the movement was successful, false otherwise. If this function
returns
false, the player's position should not be altered. This function should play the
appropriate footstep sound.
15. Object manipulation
Exercise
Write a function
examine()
that examines the item at the player's position. The function should speak the
description of the item, or an appropriate message if there is no item at this
position.
Hint: To find out if the handle x indeed refers to an object, use the expression (x
!is null).
Exercise
Write a function
use()
that uses the object at the player's position, giving an appropriate spoken message
if there is no object there, or if the object at this position cannot be used.
Hint: You will modify this function frequently as you add items to your game.
Exercise
Write a function
use_inventory()
that uses the currently selected object in the player's inventory, giving an
appropriate spoken message if no object was selected, or if the currently selected
object cannot be used.
Hint: You will modify this function frequently as you add items to your game.
16. Game loop
Exercise
Write a function
game_loop()
that continually checks for keypresses and carries out the appropriate commands
until the game is over.
Hint 1: Use a flag for the game over condition, and set this flag at an appropriate
place, for instance in your use or use_inventory function.
Hint 2: You may wish to write a helper function for pause mode.
17. Use your imagination
Exercise
Using the adventure game framework you created, begin adding areas and items to
your game.
Hint: It might be a good idea to create a separate initializer function for each
area.