# $Id: Head,v 1.3 2006/11/02 00:25:14 mike Exp $ # Tutorial.pm - reference manual for the Scott Adams adventure compiler package Games::ScottAdams::Tutorial; use strict; =head1 NAME Games::ScottAdams::Tutorial - The Scott Adams Adventure Compiler Tutorial =head1 INTRODUCTION This document walks you through the process of creating a small but complete and playable game with six rooms, seven items including a single treasure, and a couple of puzzles. It makes no attempt to be complete: you need the reference manual for that. But by the time you've worked your way through this tutorial you should be familiar with rooms, items, actions and occurrences, and you'll be ready to start writing your own games. =head1 STAGE 1 This is the minimal playable game, consisting of rooms only - and only two of them. This stage is built entirely using the C<%room> and C<%exit> directives. =head2 Stage 1 Map Chamber---------Dungeon =head2 Stage 1 Source %room chamber square chamber %exit e dungeon %room dungeon gloomy dungeon %exit w chamber =head1 STAGE 2 This stage introduces the first items: one portable (the coin) and one not (the sign). This stage uses the directives from the previous stage, plus C<%item> and C<%getdrop>. =head2 Stage 2 Map Chamber---------Dungeon [sign] | | | Cell [*coin*] =head2 Stage 2 Source %room chamber square chamber %exit e dungeon %item sign Sign says: leave treasure here, then say SCORE %room dungeon gloomy dungeon %exit w chamber %exit s cell %room cell dungeon cell %exit n dungeon %item coin *Gold coin* %getdrop coin =head1 STAGE 3 Here we introduce the first explicitly-coded actions - the previous stages' movement between locations and ability to pick up and drop items are ``intrinsics'' provided by the interpreter. The new action provides the first puzzle: the player needs to unlock the cell door entering the cell to obtain the coin. The key is necessary in order to open the door. This stage uses the directives from the previous stage, plus C<%nowhere>, C<%at>, C<%action> and C<%result>. =head2 Stage 3 Map Chamber---------Dungeon [sign, key] [door] = | Cell [*coin*] =head2 Stage 3 Source %action score %result score %action inventory %result inventory %room chamber square chamber %exit e dungeon %item sign Sign says: leave treasure here, then say SCORE %room dungeon gloomy dungeon %exit w chamber %item door Locked door %item key Brass key %getdrop key %at chamber %item door2 Open door leads south %nowhere %action open door here door !accessible key %result msg It's locked. %action open door here door %result swap door door2 msg OK %action go door here door2 %result moveto cell %room cell dungeon cell %exit n dungeon %item coin *Gold coin* %getdrop coin =head1 STAGE 4 This stage introduces automatic actions, which occur without the player needing to do anything. In effect, they happen I<to> him rather than being done I<by> him. It also uses inline documentation in the form of an action comment (though why you'd want to do this is beyond me) and specifies the start and treasury rooms explicitly. This stage uses the directives from the previous stage, plus C<%occur>, C<%comment>, C<%start> and C<%treasury>. =head2 Stage 4 Map Throne Room Crypt [sign] [vampire, key] | | | | Chamber---------Dungeon [cross] [door] = | Cell [*coin*] =head2 Stage 4 Source %start dungeon %treasury throne %action score %result score %action inventory %result inventory %room throne gorgeously decorated throne room %exit s chamber %item sign Sign says: leave treasure here, then say SCORE %room chamber square chamber %exit e dungeon %exit n throne %item cross Wooden cross %getdrop cross %room dungeon gloomy dungeon %exit w chamber %exit n crypt %item door Locked door %item key Brass key %getdrop key %at crypt %item door2 Open door leads south %nowhere %action open door here door !accessible key %result msg It's locked. %action open door here door %result swap door door2 msg OK %action go door here door2 %result moveto cell %room cell dungeon cell %exit n dungeon %item coin *Gold coin* %getdrop coin %room crypt damp, dismal crypt %exit s dungeon %item vampire Vampire %occur here vampire !carried cross %result msg Vampire bites me! I'm dead! game_over %comment vampire attacks unless cross is carried %occur here vampire carried cross %result msg Vampire cowers away from the cross! =head1 STAGE 5 This stage adds a light source (and darkness), a random occurrence and aliases for both verbs and nouns. This stage uses the directives from the previous stage, plus C<%lightsource>, C<%occur> with an argument, C<%nalias> and C<%valias>. =head2 Stage 5 Map Throne Room Crypt [sign, lamp] [vampire, key] | | | | Cave Mouth------Chamber---------Dungeon [cross] [door] = | Cell [*coin*] =head2 Stage 5 Source %start cave %treasury throne %action score %result score %action inventory %result inventory %room cave cave mouth %exit e chamber %room throne gorgeously decorated throne room %exit s chamber %item sign Sign says: leave treasure here, then say SCORE %item lamp old-fashioned brass lamp %getdrop lamp %lightsource lamp %room chamber square chamber %exit e dungeon %exit n throne %exit w cave %occur at chamber %result clear_dark look %item cross Wooden cross %getdrop cross %room dungeon gloomy dungeon %exit w chamber %exit n crypt %occur at dungeon %result set_dark look %occur 25 at dungeon %result msg I smell something rotting to the north. %item door Locked door %item key Brass key %getdrop key %at crypt %item door2 Open door leads south %nowhere %action open door here door !accessible key %result msg It's locked. %action open door here door %result swap door door2 msg OK %action go door here door2 %result moveto cell %room cell dungeon cell %exit n dungeon %item coin *Gold coin* %getdrop coin %room crypt damp, dismal crypt %exit s dungeon %item vampire Vampire %occur here vampire !carried cross %result msg Vampire bites me! I'm dead! game_over %comment vampire attacks unless cross is carried %occur here vampire carried cross %result msg Vampire cowers away from the cross! %valias take get %valias leave drop %nalias lantern lamp =head1 SEE ALSO The reference manual, C<Games::ScottAdams::Manual>. =head1 BUGS Bugs in the tutorial, that is, not bugs in the program ... The following directives are not yet discussed: C<%ident>, C<%version>, C<%wordlen>, C<%maxload>, C<%lighttime> and C<%include>. There is not yet any discussion of flags, counters and location stores. Some discussion of what makes a good game design may be appropriate. =head1 AUTHOR Mike Taylor E<lt>mike@miketaylor.org.ukE<gt> First version Thursday 29th November 2001. =cut 1;