view release on metacpan or  search on metacpan

lib/Games/ScottAdams/Manual.pod  view on Meta::CPAN

things that reside in a room, and in some cases can be picked up,
carried around and left in other rooms.  Typically, some of the items
are ``objects'' like axes and keys, while others are ``scenery'' like
trees, signs, I<etc.>

As with rooms, each item in a C<sac> file is identified by a unique
name - typically a short, alphanumeric-plus-underscores name.  Because
the concepts of room and item are so distinct in the Scott Adams
model, it's OK for a room and an item to share the same name.  In fact
this is often the obvious thing to do - for example, consider a
situtation where the player can see a tunnel, then type C<ENTER
TUNNEL> to move inside the tunnel.  In this case, it's natural for
both the tunnel item and the tunnel room to have the name C<tunnel>.

Apart from its name, an item is defined by its location and possibly
by a ``getdrop'' name - see below.

=head2 %item

	%item rubies
	*Pot of RUBIES*

Creates a new item whose name is the word immediately after the
C<%item> directive, on the same line.  The following line is the
description of this item, which is what the player sees.  (The name is
used only as an identifying tag.)

=over 4

=item *

I<Should we allow multi-line object descriptions by reading up to but
not including the next directive line as with room descriptions?>

=back

If the item name begins with an asterisk (C<*>) then it is considered
to be a treasure: it, along with any other treasures, must be
deposited in the treasury (see below) in order to win the game.  The
asterisk is displayed to the user; traditionally, another asterisk
appears at the end of treasure descriptions, but this is not enforced.

=head2 %at

	%at chamber

By default, each item starts the game in the last room defined before
its C<%item> directive; this means that sequences like the following
do The Right Thing:

	%room lake
	*I'm on the shore of a lake
	%item water
	water
	%item fish
	*GOLDEN FISH*

However, in some cases, it may be convenient to define items at some
other point in a C<sac> file - for example, some authors may prefer to
list all rooms together, then all items together.  In such cases,
an item may be relocated to its correct starting room by providing a
C<%at> directive followed by the name of that room:

	%room lake
	*I'm on the shore of a lake
	%room meadow
	sunny meadow
	%item water
	water
	%at lake

Items defined earlier in the C<sac> file than the first C<%room>
directive are by default not in the game when it starts (though they
may subsequently be brought into the game by DROP actions or similar -
see below.)  This can of course be changed with C<%at> directives,
since here as everywhere else, forward references to rooms that have
not yet been defined are OK.

=head2 %nowhere

	%nowhere

Conversely, when defining an item that should not initially be in
play, it may be convenient to place the definition at a point in the
C<sac> file that places it in a room.  In this case, the C<%nowhere>
directive can be used to start it off out of play.  This is
particularly useful if, for example, an item initially in play is
later to be replaced by one that is initially absent:

	%room stump
	damp hollow stump in the swamp
	%item wbottle
	Water in bottle
	%item ebottle
	Empty bottle
	%nowhere
	# will come into play when water is drunk

(Actually, C<%at> and C<%nowhere> are synonyms, so it's possible to
include commands like ``C<%at>'' alone to start an item out of play,
and ``C<%nowhere stump>'' to start it in the room called C<stump>, but
this would be a bit perverse, now, wouldn't it?)

=head2 %getdrop

	%getdrop lamp

Some of the items in a game - those described above as ``objects''
rather than ``scenery'' - can be picked up and dropped.  Rather than
laboriously coding these actions by hand, it's possible to have the
game automatically handle the GET and DROP actions.  In order to do
this, it needs to know the word the user will use to specify the item,
and this is what the C<%getdrop> directive provides:

	%item lamp
	Old fashioned brass lamp
	%getdrop lamp

If no C<%getdrop> name is provided, then it will not be possible for
the player to pick up or drop the item unless explicit actions are
coded to make this possible.