Nightmare IV Basic Room Tutorial
		 Written by Descartes of Borg 940901
			Last Modified: 940901

This document describes how to build a room under the Nightmare IV
Mudlib.  The document assumes that you have read LPC Basics and thus
have a basic understanding of what a function is and what a variable
is.  If you do not understand that much, please mail
borg@nightmare.imaginary.com with specific questions about what you do
not understand.

I.  The simplest room.
This is the simplest room you can actually get away with.  Note that
it is not the sort of room which actually should go into the game,
since it leads nowhere.

****
#include <std.h>

inherit ROOM;

void create() {
    room::create();
    set_short("an empty room");
    set_long("This is a very empty room!  You have nowhere to go!");
}
****

Yes.  If you write a file with only this in it (pretend it is
"/realms/descartes/test.c"), and then you type "goto /realms/descartes/test",
you will end up in a room with no exits and "This is a very empty
room!  You have nowhere to go!" as a description.  If you are in brief
mode, you will see "an empty room" for the description.

What does the most basic room consist of?  Well, the first line is
called a pre-processor directive.  It basically takes the file
"/adm/include/std.h" and dumps it right into your file at the line
where you included it.  Why would you do that?  Because std.h has a
pre-processor directive in it that looks like this:

#define ROOM    "/std/room"

When it sees that, it knows that everywhere it sees the expression
ROOM, it should replace it with the expression "/std/room".  You do
this in case the location of the standard room object should ever
change.  If I suddenly moved /std/room.c to /lib/room.c (which I might
do some day), then I would change the define in std.h  And your room
would never break!.

The third line:

inherit ROOM;

therefore looks like:

inherit "/std/room";

after the pre-processor is done with it (a more detailed explanation
of the LPMud pre-processor is in the intermediate textbook).  This
line is very important.  It is what makes a room a room.  Inside the
file /std/room.c are a bunch of files which do fun room things and
they are already written for you so that you do not have to write them
yourself just to make a stupid room.  When you "inherit" /std/room,
you are inheriting all of the functionality that /std/room has.

The final part of the room is a function you define called create().
create() gets called in every object the first time the object is
referenced in the game.  create() allows you to set the object up with
the values it needs to begin with.  In this case, the room needs to
have descriptions.  So you set it up with the descriptions (however
dull they are here) that it is to have.

Inside create(), you have three lines:
The first calls the function create() in /std/room.  That object you
inherited, has some business it needs to take care of as well when the
object is first loaded up.  But since you wrote your own create()
function, its create() function cannot be called, *unless* you
specifically reference it.  So:

    room::create();

says to call the function create() in the inherited object known as
room (objects are known by the last part of their file names).
The rest of the create() function sets up descriptions.  set_short()
is the description people see when they are in brief mode.  set_long()
sets the description they will see when in verbose mode.

Of course, all rooms are going to be more complicated than this.  You
will want to give people places to go and you will want to give them
things to do.  Not to mention adding other things in the room with
which they can interact.

II. A real room

At this point, you should understand the minimal components for any
room.  If you understand that well, it is time to dive into coding a
functioning room.  A minimal functioning room might look like this:

****
#include <std.h>

inherit ROOM

void create() {
    room::create();
    set_properties( ([ "light" : 2, "indoors" : 1 ]) );
    set_short("a cramped room");
    set_long("You are in a cramped room with no furnishings.
      "You see an exit to the north.");
    add_item("exit", "An open doorway without a door leading outside.");
    add_exit("north", "/realms/descartes/outside");
}
****

Notice that this room has barely anything the simple room does not,
yet it is infinitely better.  Why?  Because a player can actually *do*
things inside the room.  First of all, you have the line:

    set_properties( ([ "light" : 2, "indoors" : 1 ]) );

This sets the basic values for your room's properties.  In this case,
your room has a light value of 2 and an indoors value of 1, meaning
that the room is in fact an indoors room.  Light values can extend
between +5 for utterly way-too brightm to -5 meaning supernaturally
dark.  2 is average indoor lighting.  Indoor property simply is 1 if
the room is indoors, or 0 if it is an outdoors room.

The next different thing is a tedious, yet perhaps the most important
part of good room building.  Placing items for people to look at to
get visual representations of the room.  In this example, any time a
player types "look at exit", they will see the description "An open
doorway without a door leading outside.".  It is very important to
describe anything which might be in view in the room.  A good general
rule is to describe every noun you use.

Finally, this room has an exit.  Any time a player in the room types
"go north", they will move to the room "/realms/descartes/outside",
and thus no longer be in this room.

That is all there is to building your basic room.  Of course, you
cannot get away with building an entire area consisting only of rooms
with nice descriptions, items, and other places to go.  If you
understand everything presented in here, then perform the following
tasks as a check, then move on to the IntermediateRooms document.

III. Exercises
Build a garden room which has an exit to the north that leads to
Krasna Square (/domains/standard/square).  You should describe flowers
and vegitables in the garden both in the long description and
specifically in the items.  Naturally the room is outdoors.

If you feel you have created a realistic room given the knowledge
presented in this document, then move on to the Intermediate document.