Nightmare IV Intermediate Room Tutorial
		 written by Descartes of Borg 940901
			Last modified: 940901

You should understand how to write a room with simple exits,
descriptions, and item descriptions.  You should also understand how
to make a room indoors or outdoors, and to light the room
appropriately for a given situation.  If you are unclear in any of
these topics, review the Basic Room Tutorial first, then talk to a
mentor or arch, or mail borg@nightmare.imaginary.com.

I. Exits and enters
Our language intuitively captures a distinction in types of motion we
do not often make ourselves.  That is the distinction between motion
*into* something and motion *towards* something.  Because our language
makes this distinction, it is hard to capture the desires of a player
in a single command for motion (i.e. "go").  The Nightmare Mudlib thus
supports two types of commands to distinguish between these two types
of motion:  The command "enter" for motion into, and the command "go"
for motion towards".

You may or may not realize this, but all of your commands like "n",
"s", "e", "w", etc. are all aliases for motion commands, for example:
"go north", "go south", "go east", "go west", to match the examples
above.  All motion towards something is therefore down through the
command "go".

In addition, you can enter things, normally buildings.  To say "go
pub" is unnatural.  Therefore, Nightmare uses the command "enter" to
support motion into another object.  "enter pub", "enter church",
"enter cave", etc.

To distinguish between the two commands, Nightmare has two separate
functions for setting up exits: set_enters() and set_exits().  These
two functions differ only in the command a player uses to to move to
the room which they reference.

In fact, exit and enter handling functions come in the following
family:

set_exits();
add_exit();
remove_exit();
set_enters();
add_enter();
remove_enter();

To set all your exits at once:

    set_exits( ([ "north" : "/domains/standard/square",
      "south" : "/domains/standard/somewhere" ]) );

To set one exit at a time:

    add_exit("north", "/domains/standard/square");

And to remove an exit from the list:

    remove_exit("north");

All of the enters functions work exactly the same.

*************************************************************
II.  Dealing with properties

The Nightmare Mudlib has the concept of fleeting properties.  Things
about an object which do not last over time.  The actual meaning of
this is more clear if you understand the concept of a static variable,
however, this concept is at best inconsistently used in the mudlib.
Nevertheless, it is a legacy concept which is used.  This section
should describe its use in rooms.

There four property functions:
set_properties()
set_property()
add_property()
remove_property()

The first function allows you to set all properties at once:
    
    set_properties( ([ "light" : 2, "indoors" : 1 ]) );

the second allows you to set one at a time:

    set_property("no attack", 1);

the third allows you to add onto an already exiting property:

    add_property("light", 1);

the last allows you to delete a property

    remove_property("no magic");

Properties used in rooms:

light
The amount of light available to any generic observer in a room.  This
room is modified by other factors such as sun-glasses, torches, etc.
In addition, if the room is an outdoors room, the time of day affects
the amount of light.  The value you set is for day.  Things get darker
at night.

indoors
1 if the room is indoors
0 if the room is outdoors

no attack
1 if no one can fight in the room
0 is fighting is allows

no magic
1 if no magic is allows
0 if magic is allows

no teleport
1 if not allows to or from the room
0 if it is allowed

no steal
1 if stealing is not allowed
0 if stealing is allowed

allow estate
The number of residential estates for which your room is zoned.  Only
outdoor rooms should be zoned for estates, and they should be fairly
near to town.  In general, at most 2 estates should be allowed in a
given room.  Such rooms should be rare.  An estate is a high mortal
built home.  By setting this property, you are allowing immortals to
build homes.

********************************************************************
III. Senses
There are three sensory function calls which all behave in exactly the
same manner:

set_listen()
set_smell()
set_search()
remove_listen()
remove_smell()
remove_search()

Naturally, listen deals with things you hear, smell with things you
smell, and search for things you feel.  Items would fall in this list
as it is visual, however, the function calls are different.  There is
nothing for taste.

For players, when you have set something to have a smell, for example,
they see a message whenever they type "smell whatever".  You might do
something like:

set_smell("rose", "The rose stinks like rotten eggs!");

So when a player types:
> smell rose

They see:
The rose stinks like rotten eggs!

Basically, you just do:
set_smell(thing smelled, message seen);

If the room has a general smell about it, you can use the special
smell item "default" to set it for a general smell:

set_smell("default", "You smell a damp mildew about the area.");

When you do this, a player sees the smell as part of the description
of the room.  In addition, if they just type "smell", they will see
this description.

Listen and search work in exactly the same manner.

*******************************************************************
IV. Items
Items work much like smells, listens, and searches, with some minor
exceptions.  First of all, the set_items() function is a plural which
allows you to set multiple items at once.  Smells, listens, and
searches have no such function.  Second of all, you set a single item
through the add_item() function (which works exactly like the
set_smell(), set_search(), set_listen() function except there is no
default item).  The function list is like this:

set_items()
add_item()
remove_item()

set_items() takes a list of items and their descriptions in the form
of a mapping.  A mapping looks like this:

([ item1 : description1, item2 : description2, item3 : description3 ])

For example:
    set_items( ([ "rose" : "The rose is dying.",
      "door" : "The door is ugly.",
      "window" : "The window is dirty." ]) );

You can use add_item() to add these items all one at a time.  One
particularly useful implementation of this is to change the way a room
looks after a player does something.  For example, they pull a lever
opening a formerly hidden opening.  You can add that time add an item
describing the exit.  For example:

    add_item("opening", "It leads off into the darkness.");

Finally, if that opening gets hidden again:

    remove_item("opening");

*******************************************************************
V. Conclusion

If you have any question on details about how these fucntions work,
you can type "man functionname" and get help on that function.  For
example, if you did not fully understand set_items(), try using the
command "man set_items".  In addition, there is a file called
/doc/build/room/FunctionList to see a full list of functions which you
can use for a room.

You should now be able to write some very interesting rooms.  However,
there is still much more to room building.  The Advanced document will
detail such things as giving players commands which allow them to do
things, placing objects like monsters, weapons, armour, and money in
the room, and making all the functions you have learned so far do more
than simply display text.