# $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;