1. NAME

Games::ScottAdams::Tutorial - The Scott Adams Adventure Compiler Tutorial


2. 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.


3. STAGE 1

This is the minimal playable game, consisting of rooms only - and only two of them.

This stage is built entirely using the %room and %exit directives.

3.1. Stage 1 Map

        Chamber---------Dungeon

3.2. Stage 1 Source

        %room chamber
        square chamber
        %exit e dungeon
        
        %room dungeon
        gloomy dungeon
        %exit w chamber


4. 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 %item and %getdrop.

4.1. Stage 2 Map

        Chamber---------Dungeon
        [sign]          |
                        |
                        |
                        Cell
                        [*coin*]

4.2. 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


5. 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 %nowhere, %at, %action and %result.

5.1. Stage 3 Map

        Chamber---------Dungeon
        [sign, key]     [door]
                        =
                        |
                        Cell
                        [*coin*]

5.2. 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


6. STAGE 4

This stage introduces automatic actions, which occur without the player needing to do anything. In effect, they happen to him rather than being done 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 %occur, %comment, %start and %treasury.

6.1. Stage 4 Map

        Throne Room     Crypt
        [sign]          [vampire, key]
        |               |
        |               |
        Chamber---------Dungeon
        [cross]         [door]
                        =
                        |
                        Cell
                        [*coin*]

6.2. 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!


7. 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 %lightsource, %occur with an argument, %nalias and %valias.

7.1. Stage 5 Map

                        Throne Room     Crypt
                        [sign, lamp]    [vampire, key]
                        |               |
                        |               |
        Cave Mouth------Chamber---------Dungeon
                        [cross]         [door]
                                        =
                                        |
                                        Cell
                                        [*coin*]

7.2. 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


8. SEE ALSO

The reference manual, Games::ScottAdams::Manual.


9. BUGS

Bugs in the tutorial, that is, not bugs in the program ...

The following directives are not yet discussed: %ident, %version, %wordlen, %maxload, %lighttime and %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.


10. AUTHOR

Mike Taylor <mike@miketaylor.org.uk>

First version Thursday 29th November 2001.

Feedback to <mike@miketaylor.org.uk> is welcome!