-- sgDemo1.ala
--      a source-code example for a simple "Alan" interactive fiction game
--      by Stephen Griffiths
-- Modifications
-- September'10 : V0.4
-- 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. This first flavour contains
-- all the complete code for the sample game and is intended to give an
-- overview of the basic elements of an Alan program. The second flavour
-- demonstrates the useage of the Alan code library to simplify creation of
-- Alan games. The second flavour is more tasty but this first example is
-- a useful first introduction to the simplicity of Alan.

-- 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 five sections
-- Section 1 .... Game Control Commands
-- Section 2 .... Commands to interact with objects
-- Section 3 .... The Locked Room location and objects
-- Section 4 .... The Walled Garden location and objects
-- Section 5 .... The Game Start section

-- Section 1 .... Game Control Commands
-- basic 'game control' player commands (called "verbs" in Alan language)
-- ----------------------------------------------------------------------
-- note that words like 'quit' need to be written within single-quotes when
-- they're being defined as player commands to distinguish them from the
-- Alan language keywords like quit which actually tell the Alan program
-- to perform an operation like quitting from the game

-- there's three steps to defining a player command : syntax, synonyms & verbs

-- syntax statements define the words players can use in commands and what
-- actions (called verbs) those words will cause the game to carry out, this
-- first syntax defines a verb called 'quit' (on the left of the equals sign)
-- and the word the player types to enter this command which is, coincidentally,
-- also 'quit' (on the right of the equals sign)
syntax 'quit' = 'quit'.

-- synonyms define alternative words the player can type instead of the word(s)
-- defined in the syntax statements, in this case we're allowing the player to
-- type an abbreviation, 'q', when they want to quit from the game
synonyms q = 'quit'.

-- verb definitions define what the player commands actually do when the game
-- runs the commands, in the case of the 'quit' command, the game runs the
-- "score" action which displays the player's score on screen and runs the
-- 'quit' action which exits from the game and shuts down the program
verb 'quit'
    end verb.

-- The Score command shows the player's current game score, so we'll define
-- a verb to allow the player to check their current points score in the game
syntax 'score' = 'score'.

verb 'score'
    end verb.

-- let's define a help command that shows the player some information about the
-- game
syntax help = help.

-- note the $P text strings embedded in the text below, this tells Alan to start
-- a new paragraph of text (meaning insert a blank line.) There's other
-- formatting codes such as $N for a new line as well as some 'style' commands
-- like 'emphasize' for bold or italic text.
verb help
        "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 (in the plain-text file ""sgDemo1.alan"".)
        You can also download the source-code from Stephen's homepage at http:
        "$pThere's two versions of the source-code. this sgDemo1.alan contains
        the complete code for the sample game and is intended to give an
        overview of the 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 help.

--walkthru displays a list of commands to complete the game
--included to help out players who get stuck
syntax walkthru=walkthru.
synonyms walkthrough = walkthru.
verb walkthru
        "$$examine window
        $nopen window
        $nexamine gate
        $nopen gate
    end verb walkthru.

-- look re-displays the description of the player's current location
syntax 'look' = 'look'.

-- you can define one word to be equivalent to another  so that "L" can be used
-- as an abbreviation for "look" or "x" for "examine" or one word made
-- synonymous to another (e.g.: to make "get" interchangeable with "take")
synonyms l = 'look'.

verb 'look'
    end verb.

-- Section 2 .... Commands to interact with objects
-- commands that interact with objects have a different syntax to the "global
-- verb" defined in Section 1 because as well as the defining the player words,
-- the syntax also defines the type of things the verb can be used with (for
-- example locations, objects or actors.) In this game we'll only define verbs
-- that interact with objects

-- this typical verb syntax means the player types a command starting with the
-- word "open" and then the name of an object, e.g.: "open window". The Alan
-- game checks that the second word the player types is a valid name for an
-- object currently at the player's location and then processes the player
-- command

-- the object the player has named is represented in code for the verb by the
-- word in brackets in the syntax definition, in this case "obj".

-- This word in brackets is known as a "verb parameter". This feature of Alan
-- gives the flexibility for one verb definition to be executed for any object
-- the player mentions in their command
syntax open = open (obj)
    where obj isa object
        else "You can only open objects"

-- to make the new open command work with all objects in the game, we add a
-- basic definition of the 'open' verb to each and every object defined by the
-- game author and at the same time we add some 'attributes' to every object
-- which this verb changes. Manipulating object attributes is the magic which
-- allows the game's author to make the game's world appear alive and
-- interactive.

-- The 'add to every' feature lets the game author instantly define the same
-- attributes and verbs for every object in the game. Then within individual
-- objects, the author can re-define attributes and verb behaviours to customise
-- each object, as desired
add to every object
    is not openable. -- by default, all objects will not be 'openable' so the
    is closed.       -- open verb will just display "You can't open that"
    is not locked.

    verb open
        check obj is openable
            else "You can't open that!"
        and obj is closed
            else "It's already open."
        and obj is not locked
            else say the obj. "is locked tight, you can't open it."
            "You open the $1."
            make obj not closed.
        end verb open.
end add to.

-- now we define a 'close' command which reverses the results of 'open'
syntax close = close (obj)
    where obj isa object
        else "You can only open objects"
synonyms shut = close.

add to every object
    verb close
        check obj is openable
            else "You can't close" say an obj. "!"
        and obj is not closed
            else "It's not open."
            "You close the $1."
            make obj closed.
    end verb close.
end add to.

-- you can define more than one syntax for the same verb so the player
-- can specify a command  with alternative phrases which offers more
-- flexibility than the synonym feature which only matches one word
-- to another (eg: "x" as an abbreviation for "examine"). With multiple syntax's
-- for a verb the commands can have words in a different order or a longer
-- phrase that means the same as a shorter one (e.g.: "look at object" as an
-- alternative to "examine object")
-- here we define syntax look_at twice with different command phrases for the
-- player to use (on the right of the equals sign)
syntax look_at  = 'look' 'at' (obj)
    where obj isa object
        else "You can't examine that."

syntax look_at = examine (obj).

synonyms x = examine.

add to every object
    verb look_at
            "There's nothing special about"
            say the (obj).
    end verb look_at.
end add to.

-- Section 3 .... The Locked Room location and objects
-- locations are the basic places in an Alan game, the player can move
-- between locations via the defined 'exits' in order to explore the game
-- world

the prison isa location
    -- by default, the location's title (ie 'prison') is displayed to the
    -- player, if you want something more descriptive add a 'name' clause to
    -- the location's properties
    name bare room

    -- the text of a location's description is displayed to the player when they
    -- arrive at a location
    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."

    -- an 'exit' that does nothing but display a message when you attempt
    -- to go west out of the room
    exit west to prison
        check "The door is locked, there seems to be no way for you to open it."
        end exit.

    -- an 'exit' that first confirms conditions are met (window is open) and
    -- then displays a message as you move to the new location
    exit north to garden
        check 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.

the window isa object at prison
    is openable.
    is closed.
    is not locked.
    is not examined. -- to track whether player has already looked at window, we
                    -- add a custom attribute defined just for this object.
                    -- the game displays more information the first time the
                    -- window is examined.

    -- by default, the objects at a location are listed after the location's
    -- description (e.g.: "There is a window here.") but you can provide a more
    -- elaborate description
    description "The small window is set at about head height in the cold north-
    facing wall. Sounds of music and laughter can be heard through the window."

    -- can customise the definition of a verb by adding a verb clause inside an
    -- object's definition. Normally the actions in the object's verb will be
    -- run after the verb's standard actions as defined in the verb's "add to
    -- every object" definition. But the author can specify "does only" or "does
    -- before" phrases in an object's verb definition
    verb look_at
        -- 'only' means just this action is done, replacing the
        -- actions defined in this verb's main definition
        does only
            if window is closed then
                "The window is not properly closed! It seems like you could
                open the window easily."
                if window is not examined then
                    "Perhaps one of the servents has secretly provided a way for
                    you to escape after all."
                    make 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 look_at.

    -- when the player opens the window this extra code for 'open' is run, as
    -- well as the standard 'open' verb code. (Notice this local verb is defined
    -- with 'does' rather than 'does only' so this code is run as well as the
    -- standard 'open' verb code)
    -- 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
            -- in case player randomly tries to open window without knowing it
            -- would work by previously examining the window, we had this extra
            -- text to provide an explanation why the window does open
            if 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 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. -- player given 10 points when this command  first run
            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 Window.

the door isa object at prison
    is openable.
    is closed.
    is locked.

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

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

    end the Door.

-- Section 4 .... 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 object 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 ("garden_window")

    -- blank desctiption because window is mentioned in room description and we
    -- don't want the default text "There is a window here" added to the room
    -- description text as well!

    is openable.
    is closed.
    is not locked.

    verb look_at
        does only
            if garden_window is closed then
                "The window is not properly closed. Seems like you could
                open it easily"
                "The window is open providing you an exit to the south,back to
                the room in which you were trapped."
            end if.
        end verb look_at.

    -- this extra code for 'open' synchronises the view of the window from the
    -- inside so that it opens when this window opens.
    verb open
            make window not closed.
    end verb open.

    verb close
            make 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 garden wall
    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!"
            score.  -- 'score' command with no following number displays players
                    -- current score
            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 object 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.
    is openable.
    is closed.
    is not locked.

    verb look_at
        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 look_at.

    end the walldoor.


-- define abbreviations the player can use for the directional commands

-- Section 5 .... The Game Start section
-- every Alan game must have a Start section where the first location which the
-- player starts the game is specified. Some text introducing the game is
-- usually written here, such as the game's title, author, etc, as well as some
-- scene-setting description.

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
    -- comments     -- explanatory notes embedded in the sourcecode
    --========== ------------------------ ==========--