-- sgDemo2.alan
--      a sample Alan Version 3 game
--      by Stephen Griffiths
--      to illustrate programming with the New ALAN Library
-- Modification History
-- September'10 : V0.2 
-- NOTE: lines like this one starting with two hyphens (--) are comment lines
-- providing information  and explanations to the human reader. These lines
-- are just ignored by the Alan program when it compiles the game code.

-- this coding sample comes in two flavours. The first flavour contains
-- the complete code for the sample game and is intended to give an
-- overview of the basic elements of an Alan program. This second flavour
-- demonstrates the useage of the Alan code library to simplify creation of
-- Alan games.

-- The first version of this demo shows the basic principles of Alan but using
-- all the pre-built coding in the Alan library is the more advanced and
-- productive way to write an Alan game. So it is this second version of this
-- demo game that illustrates the way you would really program a game using the
-- Alan IF authoring system.

-- If you have not programmed with Alan before, please study the first example
-- before using this second example. The first example introduces basic Alan
-- concepts that this second example glosses over. The focus of the explanations
-- in this second example is on using the library features.

-- This game contains only a few elements of Alan -- objects, locations &
-- verbs. There's many more features of Alan that I haven't included as I
-- wanted to write a little game with just enough source code to give
-- beginning Alan authors a straight-forward introduction to the language.

-- This game source code is organised into four sections
-- Section 1 .... including the library code in your game
-- Section 2 .... The Locked Room location and objects
-- Section 3 .... The Walled Garden location and objects
-- Section 4 .... The Game Start section

-- Section 1 .... including the library code in your game

-- In sgDemo1 we defined a 'help' verb to display some explanatory text to the
-- player. In the library, however, 'help' is a synonym for the standard 'about'
-- command.  We want our own game-specific help text displayed so we should edit
-- the 'about' verb in the library's "verbs.i" file. However, to keep this
-- example all in one file, I've done a little trick by including our own custom
-- 'about' command here BEFORE the commands to import the library code into our
-- game. This means that our 'about' command definition is used in the game and
-- a warning message is displayed by the Alan compiler that it's found a second
-- version of the 'about' verb in the library and it's going to be ignored.
verb about
        "This is just a little sample game. There's very few commands you can
        try so just try them all on everything. Use compass directions like
        north and east to move from place to place, try to open things (eg
        ""open window""), you can examine things to get more information (eg
        ""look at gate""), use quit to exit from the game, there's also save,
        restore and score commands."
        "$pIf you're really stuck, try the command walkthru, which will display
        the handful of steps you need to play the whole game."
        "$PThis game was written by Stephen Griffiths as a little programming
        example for people learning to write text adventure games using the
        'Alan' programming language. It's not intended to be taken seriously as
        a game -- reading the source-code to learn about 'Alan' programming is
        more the point!"
        "$pThe 'Alan' programming language is developed by Thomas Nilsson who
        has an Internet homepage at http://www.alanif.se"
        "$pThe source-code for this game should've been included with what
        you've downloaded to play it (the plain-text file ""sgDemo2.alan"".) You
        can also download the source-code from Stephen's homepage at http:
        "$pThere's two versions of the source-code. sgDemo1.alan contains the
        complete code for the sample game and is intended to give an overview of
        basics of 'Alan' programming. The second flavour, sgDemo2.alan,
        demonstrates the useage of the Alan code library to simplify creation of
        Alan games."
    end verb about.

-- these four import statements add into this game the Alan source-code from the
-- four files that make up the library.  The imported source-code is treated by
-- the compiler just as if it was typed directly into our game's file
-- the library sourcecode contains many comments about how the library works, so
-- reading the files is important, perhaps even printing out paper copies to
-- study might be worthwhile
-- if you want to change anything in these files, go ahead -- take a copy of the
-- library files, make changes and use your version in your game. And if you
-- think of good ideas, make suggestions back to the Library maintainer.
-- Feedback and suggested improvements are very welcome!

import 'classes.i'.
import 'verbs.i'.
import 'locations.i'.
import 'messages.i'.

-- the library doesn't contain a 'walkthrough' verb so we define our own syntax,
-- synonyms and verb just as if we weren't using the library
syntax walkthru=walkthru.
synonyms walkthrough = walkthru.
verb walkthru
        "$$examine window
        $nopen window
        $nexamine gate
        $nopen gate
    end verb walkthru.

-- Section 2 .... The Locked Room location and objects
-- the library includes more specific sub-classes of locations for interior
-- (rooms) and outdoor locations, so by defining this location as a 'room'
-- rather than a generic 'location' we automatically get walls, floor and
-- ceiling defined and available for the player to examine, etc
the prison isa room
    name bare room

    description "You are in a small bare room, nothing here but a bare wooden
    floor, and bare walls, painted pale cream that glow coldly in the moonlight
    coming through the small window. This cold, dismal room is a long way from
    your normal happy life, this is a place of depression and slow death."

    exit west to prison
        check "The door is locked, there seems to be no way for you to open it."
        end exit.

    exit north, up to garden
        check prison_window is not closed
            else "The window is closed."
            "You clamber through the open window and let yourself down quietly
            into the garden. "
        end exit.
    end the prison.

-- in sgdemo1 this object was called 'the window'. But the library code defines
-- 'window' as a class of objects in the 'classes.i' file. So our window object
-- must  have a different but unique name ('prison_window'). We give it a
-- player-usable name of just 'window' though (with the 'name window' clause.)
-- More importantly, we also declare our window object to be not a generic
-- 'object' but a 'window' which means all the standard features of a window are
-- already coded for us in the library such as open, close and look-through
-- verbs
the prison_window isa window at prison
    name window
    is not examined.
    description "There is a small window set at about head height in the cold
    north-facing wall. Sounds of music and laughter can be heard through the

    -- in sgdemo1.alan we defined a look_at verb and made 'examine' an
    -- alternative syntax for 'look_at', in the library it's done the other way
    -- around -- 'look_at' is an alternative syntax for 'examine'. So references
    -- to the look_at/examine verb in sgDemo2 are made using 'examine' as the
    -- keyword
    verb examine
        does only -- 'only' means just this action is done overriding the 'does'
                  -- in the verb's main definition in the verb.i file
            if prison_window is closed then
                "The window is not properly closed. Seems like you could
                open it easily."
                if prison_window is not examined then
                    "Perhaps one of the servents has secretly provided a way for
                    you to escape after all."
                    make prison_window examined.
                end if.
                "The window is open providing you an exit to the north from the
                room in which you have been trapped."
            end if.
        end verb examine.

    -- when the player opens the window this extra code for 'open' is run, as
    -- well as the standard 'open' verb code from verbs.i file. This extra code
    -- provides a nice description of the action, some player points and makes
    -- the 'window' object at the garden location also 'open' to keep it
    -- synchronised
    verb open
            if prison_window is not examined then
                "The window was not properly closed! Perhaps one of the servents
                had secretly provided a way for you to escape after all."
                make prison_window examined.
            end if.
            "The noise of the party now sounds louder. The party-goers seem so
            close but hopefully no-one can see you or the open window as you are
            shielded by the trees and bushes of the dark garden. You can see an
            exit, a quiet doorway, in the high stone wall on the eastern side of
            the garden."
            score 10.
            make garden_window not closed.--the other side is opened now too
    end verb open.

    verb close
            make garden_window closed.
    end verb close.

    end the prison_window.

-- 'door' is a class of objects defined in the classes.i library file. Looking
-- at the comments at the top of that file, shows that a door is set to be
-- unlocked  by default, so we need to set this particular door to be locked but
-- don't need to specify the other attributes like 'closed', etc because the
-- default values of library's "door" class are just what we want for this
-- particular door.
the prison_door isa door at prison
    name door
    is locked.

    description "There is a closed door in the western wall."

    verb examine
        does only
            "It's a big strong wooden door built from very solid-looking planks
            of thick wood."
        end verb examine.

    end the prison_Door.

-- Section 3 .... The Walled Garden location and objects
the garden isa location
    "Straight north across the garden are the large lit windows of the ballroom.
    From there you can hear the sounds of the party celebrating your imminent
    wedding -- the wedding you made such a scene about that you were locked away
    to save embarrassment to your father and fiance. $pA path leads west and
    east, east leads to the garden wall where you can escape onto the road to
    the harbour, while west is the main entrance to the chateau living quarters.
    $pThe window back to the little room in which you were locked is to the

    exit south to prison
        check "You wouldn't want to go back in there!"
        end exit south.

    exit west to west_garden.

    exit east to garden_wall.

    exit north to garden
        check "You wouldn't want to join the party -- the evil fiance is in
        end exit north.

    end the Garden.

the garden_window isa window at garden
    name window -- name clause lets you give a 'display name' that the player
                -- sees which is different to the object's real name used
                -- in the game's source code

    -- blank desctiption because window is mentioned in room's description

    -- can customise the definition of a verb by adding a verb clause inside an
    -- object's definition.
    verb examine
        does only -- 'only' means just this action is done overriding the 'does'
                    -- in the verb's main definition in verbs.i library file
            if garden_window is closed then
                "The window is not properly closed. Seems like you could open it
                "The window is open providing you an exit to the south, back to
                the room in which you were trapped."
            end if.
        end verb examine.

    -- this extra code for 'open' synchronises the view of the window from the
    -- inside so that it opens when this window opens.  The 'open' verb code
    -- from verbs.i file is also run (because we use 'does' in our verb
    -- definition, not 'does only')
    verb open
            make prison_window not closed.
    end verb open.

    verb close
            make prison_window closed.
    end verb close.

    end the garden_Window.

the west_garden isa location
    name courtyard
    description "An arched entranceway leads west from a tiled courtyard into
    the chateau living quarters. Across the garden, to the east, you can just
    see a shadowed doorway in the eastern wall."
    exit east to garden.
    exit west to garden
        check "Very risky, don't go there. Most of the servants are on your side
        but if the butler or the gamekeeper see you they'll raise the alarm."
        end exit west.
    end the west_garden.

the garden_wall isa location
    name east side of garden
    is openable.
    is closed.
    is not locked.
    "You are on the east side of the garden, separated from the freedom of the
    road outside only by a high and unclimbable wall of grey stone."

    exit west to garden.
    exit east to garden
        check walldoor is not closed
            else "The door is closed."
            score 10.
            "You slip through the archway and onto the dark, deserted road
            outside. You have successfully escaped, avoided your unhappy fate
            and won the game!$pCongratulations!"
            quit. -- 'quit' command finishes the game
        end exit.
    end the garden_wall.

-- an object can be given more than one name, in this example the player can
-- call door in the gateway either "door" or "gate"
the walldoor isa door at garden_wall
    name door
    name gate
        if walldoor is closed then
            "A strong wooden door covers a small gateway in the wall."
            "An open wooden door allows you access through a small archway
            leading east to the road outside."
        end if.

    verb examine
        does only
            if walldoor is closed then
                "A strongly-built wooden door covers the archway. The door is
                currently closed."
                "The wooden door hangs open allowing you access through the
                small archway leading east to the road outside."
            end if.
        end verb examine.

    end the walldoor.

-- Section 4 .... The Game Start section
start at prison.
"A n  $t$t A d v e n t u r e $t$t  B e g i n s
$n$tby Stephen Griffiths
$p$t(an introduction to a swashbuckling tale
$n$tand an introductory source-code example
$n$tfor new Alan game writers. Try the help
$n$tcommand within the game for more
"$PThis could be your last night of freedom, locked in this little room. At
least being locked in a room is better than being locked into a marriage to a
cruel man you do not, and could not ever, love. And that will be your state
tomorrow unless you can escape from this room tonight and get away from the
count's chateau before your wedding ceremony tomorrow morning."
"$pThe door leading out of the room is locked tight. You've already tried to
open it many times, hoping irrationally that it will give up and open purely
from your persistance but it hasn't happened and despite all your banging and
crying no-one has come to release you. Your hope that some of the servants might
furtively help you seems to have been disappointed. Perhaps no-one can hear you
with all the noise from the pre-wedding banquet your bridegroom, the young count,
is hosting in the ballroom across the large garden courtyard from your little

    --========== text highlighting scheme ==========--
    garden          -- the names, objects and other items of this game
    "game text"     -- double-quoted string (text displayed to the game player)
    'myfile'        -- single-quoted string such as a filename
    location        -- Alan programming language keyword
    lockable        -- Alan standard code library keyword
    -- comments     -- explanatory notes embedded in the sourcecode
    --========== ------------------------ ==========--