The Developer Kit includes comprehensive documentation that clocks in at over 20,000 words. It's easy-to-read documentation, that explains every aspect of building your own adventure game.
A large part of this documentation is a tutorial which examines the sample game, step-by-step. By examining each text script file in detail, the tutorial explains all of the inner workings of this sample game, and also serves as a reference for writing your own game's script.
The AGE Tutorial Document is extensive, and very cohesive and complete. The following is a small extract, examining the script for a single scene of the sample game...
The full Tutorial Document is included with the hobbyist edition of the AGE Adventure Game Engine that comes free when you purchase The Sydney Mystery for only $19.95. Click here to visit The Sydney Mystery website. You can also download a free demo of The Sydney Mystery, at the website, to see what the AGE Adventure Game Engine is capable
The first game scene (with a look-at region)
| Once the flyby cutscene ends (either by simply finishing, or through the
user hitting the ESC key), a new scene is loaded. We have already seen one scene –
which served simply as the title screen. This time, we are loading a scene that can truly
be considered an "in-game" scene – the scene is part of the game
player’s normal playing of the game. Take a look at the scenes\front\ directory. This is where the scene’s script file is stored, in the file front.txt. There are two additional files, the backing image (a JPEG image) and an audio .WAV file. We have already examined the fundamental structure of a scene file, when we examined the workings of the title screen. Open the file front.txt (in the scenes\front\ directory) for reference. Take a look at the first part of this file. |
| Room_begin "Outside the Islands" // name of scene "scenes\front\" // filename prefix "front.jpg" // backing image "scapes\island1\island1.txt" // soundscape normal // default mouse pointer "wrong_object" // sound when object wrongly used |
| Consult the discussion of the title screen, for a formal description of
these items. As before, we begin with a Room_begin token, followed by four strings, a
token, and then another string. The comments in the file indicate their purpose. The
earlier discussion on the title screen’s script file gives full, detailed
descriptions of each line’s purpose and usage. Then come the definitions of the clickable regions in this first game scene. The first region is defined as follows: |
| // a clickable region - looks at
an object (plays streaming audio) region 560, 640, 130, 260 // coordinates of region { } // required flags look // mouse pointer 0, 0, "" // hover overlay image "Look at" // verb string "the distant island" // noun string look // region type: looks at something "island.wav" // audio wave file to play (streamed off disk) {} // flags to set |
| Inspecting this in more detail, we can see that the first section of this region definition is similar to that of the walk region we encountered in the title screen: |
| // a clickable region - looks at an
object (plays streaming audio) region |
| We begin with a token declaring the beginning of a clickable region. |
| 560, 640, 130, 260 // coordinates of region |
| We have a bounding rectangle for this region, giving the minimum x, maximum x, minimum y and maximum y, respectively, of the bounding rectangle for this region. |
| { } // required flags |
| We have an empty list of required flags, indicating that the region is always available, requiring no particular configuration of flag values to be active. |
| look // mouse pointer |
| This time, the mouse pointer should change to the preloaded look mouse pointer. This mouse pointer indicates that the player may "look" at a region. |
| 0, 0, "" // hover overlay image |
| Since the hover overlay image’s filename is empty, no special overlay image will be displayed while the mouse hovers over this region. The coordinates are just set to 0, 0, but are essentially meaningless, since there’s no image. |
| "Look at"
// verb
string "the distant island" // noun string |
| The verb and the noun string will be combined to display
"Look at the distant island" when the mouse hovers over this region. The next section of this region definition has a slightly new format, due to the first token being look: |
| look
// region type: looks at something "island.wav" // audio wave file to play (streamed off disk) {} // flags to set |
| As pointed out, the look token appears. This indicates that the region is
made to be looked at. When clicked, a piece of audio is played. This audio would usually
contain dialogue, containing a description of the region. In this sample adventure, the
region is a distant island to be looked at. Clicking will play back a .WAV file with the
game’s narrator describing the distant islands. Next comes a string giving the filename of a piece of audio to be played. This audio will be streamed off disc, played continuously until finished, mixed with the current game audio while the game continues. The current scene’s filename prefix ("scenes\front\" as specified earlier in the scene’s script) is added to the beginning of this filename, so that the audio played is actually the file "scenes\front\island.wav". This is the .WAV file that sits in the same directory as the scene’s script file and backing image file, of course. Next comes a flag-list. This would specify flags that are to be set when the game player clicks on this region to look at it. In this case, no such flags are changed. Look regions serve a second purpose. If the pointer is currently an inventory item, the displayed string will indicate that the game player may attempt to use the inventory item with this region. For example, if the user has the "silverball" item as their current pointer, then the string displayed will be "Use silverball with the distant island". This is the reason for separating the verb and noun strings – any look region in the game, as well as allowing the player to look at the region, also allows an inventory item to be used on that region. Most of the time, and in this region’s case, there will be no specifically useful item for a region. In this case, the preloaded sound (for an incorrect object’s use) will be played. As specified in the opening section of this scene’s script, the preloaded sound "wrong_object" will be played if an item is used on this region. And there ends the specification of the look region. Next in the scene’s description is a simple walk region, allowing the user to walk towards the island. |
| // a clickable region - jumps to
a new scene region 130, 500, 160, 350 // coordinates of region { } // required flags forward // mouse pointer 0, 0, "" // hover overlay image "Travel to" // verb string "the first island" // noun string walk // region type: walks to a new scene "scenes\island1a\island1a.txt" // filename of destination cutscene "travel" // preloaded sound to be played { } // set these flags |
| This region is quite similar to the region which entered
the cutscene from the title screen. The first part of the region definition is quite
familiar. In fact, all regions share this same set of properties. It is the region type
token that specifies the type of the region, and it is this type that determines the
remaining properties to be specified. To show the region-type and its particular properties again: |
| walk
// region type: walks to a new scene "scenes\island1a\island1a.txt" // filename of destination cutscene "travel" // preloaded sound to be played { } // set these flags |
| We can see that the walk token indicates a region that moves the game
player to a new scene. (The player "walks" to this new scene.) Next comes a string giving the name of the next scene’s script file. A full path, relative to the game’s home directory, is given for this script file. Next comes a string giving the name of the preloaded sound to be played when the user successfully clicks on this region. Finally, a flag-list is given, specifying any flags which are to be set when the game player moves to this new scene. In this case there are no such flags to be set. This list ends the specification of the walk region. And since the scene contains no further regions, a simple token indicates the end of the scene’s definition: |
| Room_end |
| Obviously, the only way to leave (short of quitting the game) is to walk forward to the scene defined in scenes\island1a\island1a.txt. |
...Keep in mind that you've just read a tiny extract of the entire Tutorial Document.
...the entire AGE Tutorial Document gives plenty of detail on how the scripts were built, with clear explanations that will allow you to incorporate the same functionality into your own game. The tutorial documents all other technical aspects of putting your game together, so that once you've read the tutorial, you'll have seen everything it takes to make your very own adventure game.
...25,800 words, 72 A4 pages of extensive and very well-written documentation. The Twilight Software Adventure Game Engine is a serious game engine, for serious game makers!