Getting Started Building with the Nightmare Mudlib
		     by Descartes of Borg 940901
			Last Modified: 940901

The object of this document is to get you started with the basic
things you need to know to build on Nightmare.  Whether you are an
experienced coder, are a newbie coder, you should read this document
to learn what utilities you have available to you on Nightmare.

If you have never coded LPC before, you will want to read the LPC
Textbooks in /doc/lpc.  They contan basic knowledge about the LPC
object building language which you will need for coding LPC on any
MUD.  Until you have read that, the other information in this document
may not be very meaningful to you.

I.  Where to get help
There are two help commands on Nightmare: "help" and "man".  "help"
gives you help on commands and topics.  Man gives you help on mudlib
and driver functions.  For help on any efun, SimulEfun, or lfun, type
"man <fun_name>", where fun_name is the name of the function (example:
"man this_player" gives you help on this_player() efun).  Before
running and asking a question on a topic, ask yourself if there
*might* be a help file for it.  Try using the help and man commands
*before* asking other people questions.

II.  What are efuns, lfuns, and SimulEfuns?
If you do not know what a function is by now, you should go read the
LPC textbooks.  If at that point you still do not understand, go ask
Descartes to explain them to you.  Functions are central to
understanding LPC.  An efun is a function which is defined for every
object in the game by the driver.  You do not need to write out the
code that says what it does.  You can simply use it wherever you like.
The term efun stands for external function, meaning it is defined
externally of the mudlib.
An lfun is just the opposite.  It is a function which has to be
written in the object in order to be used.  This does not mean you
have to define *every* lfun you use.  Sometimes, you get the
definition of an lfun into your object through inheritance.  In fact,
most functions you use are lfuns which have been defined inside your
object for you through inheritance.  lfun stands for local function.
A SimulEfun as an lfun in an object called the SimulEfun object.  Any
function defined in that object acts *as if* it were defined as an
efun in the driver.  Any object in the game can user a function
defined in the SimulEfun object.  SimulEfun stands for simulated
external function.

III.  Function pointers
You may notice that in a lot of places, the Nightmare Mudlib makes use
of a concept called a function pointer.  For example, in rooms, you
often might want to make what the room description says conditional
upon some set of circumstances being true.  The most common example is
wanting to give different descriptions for night time than from day
time.  Unfortunately, once you set_long(), you permanently set what
its long description is (You can change this value any time, but how
do you know when it becomes night?).
Nightmare, with set_long() and many other functions, has the ability
for you to specify a function to get called in order to create a
value.  In the example of set_long(), instead of setting a
description, you can specify a function which will get called every
time something wants to know what the long description is.  That way,
you can check what time of day it is each time something needs to know
the long description. 
Function names are specified through a special type of data called a
function pointer.  A function pointer is exactly that, a variable
which points to a function.  For example:

    set_long( (: special_long :) );

Points to the function special_long() which you write in that object.
You might write it something like this:

string special_long(string str) {
    if(query_night()) return "It is night outside.";
    else return "It is day outside.";
}

Thus, every time something wants to know what your long description
is, it calls your function special_long() to get the value.  Used
well, function pointers can be really powerful tools.

There are three different function pointer syntaxes:
    (: lfun :)
    (: efun :)
    (: objectvariable, "lfun" :)

The first one points to the function lfun() in your object.
The second one points to an efun.
The third points the the function lfun() in *another* object.  For
example (this is advanced coding here), if you have a very widely used
function, you could put it in a daemon object and have other objects
point to it to get their values.  An example of wuch a use might be
for weapon hit functions:
    set_hit( (: find_object("/realms/descartes/weap_daemon"), "hit" :) );

IV. How do I get started?
Start by building a room.  If you have no coding experience, copy some
room from somewhere else.  Make small changes to it, and see what
those changes do.  You will see how the long description changes when
you change the text in set_long().  You will see how the exits change
when you specify new rooms, etc.  If you have experience with coding,
sit down and read the room building documentation end-to-end.  It may
have some hidden secrets in it which could make you able to code
something quite awesome.
For newbies, once you have played around with a few rooms, then read
the room building documentation.  You will not notice all those
secrets to make you build something qutie awesome.  Instead, you
should be reading to understand what you did when you fooled around
with the rooms you did.

V. Is there an easier way to do this?
Yes, if you run Micro$#%^ Windows, I have written a room builder which
you can use to build rooms for the Nightmare Mudlib.  You can get it
through anonymous ftp to ftp.imaginary.com.