Building object with the Nightmare Mudlib

You may or may not understand the concept of inheritance.  If you do,
then understanding it will help you understand the way the mud works
as a whole much better.  If you do not, you might want to check out
the chapter called "Basic Inheritance" in the basic LPC textbook found
in /doc/lpc/basic.  But you can get through it all without this knowledge,
it just might take a little more thought.

This document is intended to tell you how to build any object in the
mudlib, but not in detail.  The other documents in this directory give
you detailed information on each type of object.  The intent of this document
is to show how the very different objects of the mud interact, and what
things must be set *no matter what* kind of object you are coding.

Part 1: The basic object /std/Object
Mudlib objects use a property of LPC called inheritance. Let's say that
object A inherits object B.  In object A, you would see at least the
following code:

inherit <file name of B>;

At this point, object A and object B do *exactly* the same things.  All
the code that was written into object B by its creator becomes written
into object A through inheritance.  In addition, this inheritance in no
way affects object B.  Practically speaking, this allows you to use all
the functionality already coded for objects of a certain type (say, weapons)
while adding special functionality unique to your own object (say a special
function which allows the weapon to have a magic spell attatched to it).

In the process of coding things, you will often inherit a bunch of different
files: /std/weapon for weapons, /std/armour for armours, /std/monster for
monsters, /std/room for rooms, etc.  All of these objects inherit at
some point a file called /std/Object.

Part 2: What the standard object does
The standard object provides functions needed for any object to interact
with any other object on the mud.  It has the following important functions:

void remove()
This gets called to destruct an object.  This is important since any
object that gets destructed needs some cleaning up before it gets
destructed.  For example, a player is carrying a heavy sword and uses
its magic spell coded into it which has it disappear after it is cast.
If the sword was simply destructed, the player object would still register
that the player was wielding the sword AND that the player object was
carrying something heavy even though there is nothing there.  The 
remove() function adjusts the carry information of the object carrying it
and it unequips it, among other things.

void clean_up()
This function is called after the object has not been referenced after a 
while.  It checks the object to see if it is ok to delete it from memory
to save some memory.

int allow_get()
This tells other objects whether or not the object can be gotten.

int allow_drop()
Allows an object carrying this object to drop (or prevents) this object.

Part 3: Things you need to worry about
All objects inheriting another objects also have the following functions
defined for them:
void init()
void create()
void reset()

Nevertheless, in able to be able to do anything useful with your objects,
you need to be able to write your own create(), and sometimes also
init() and reset().  So, in your code, when you write a create() function,
that becomes the function create() in that object, *overriding* the
version it inherited.  Unfortunatley, that create() in the object you
are inheriting is there for a reason.  But you can access that create()
by using the :: operator to reference it.  Therefore any create(), init(),
or reset() function should have as the first executed line a ::
call to the function it is overriding.  It looks something like this:

void create() {
    ::create();
    reset fo code for create
}

OR

void create() {
    variable declarations

    ::create();
    rest of create code
}

You must set the following information in any object you create.  Every
object inherits the following functions through /std/Object

void set_short("any old string description");
This will set a short description that people will notice whenever they
encounter the object.  Exception: rooms, where they will see the short
only if they are in brief mode.

void set_long(
    "A very long bunch of descriptions.  Note that here, "
    "like in all Nightmare Mudlib strings, you do not put in the special "
    "carriage return character '\n'.  Also, you do not put in + signs to "
    "join multiple strings.  To strings put side by side will automatically "
    "be added together in a faster way than using string addition. Only "
    "useful for string constants though :).");
Sets a very verbose description of an object.  Note that the mudlib will
automatically wrap any text to fit the screen of a user.  Players see
this when they use the "look" command.

void set_id(({ "an", "array", "of possible", "ids" }))
This sets up all the names which a given object will respond to by
commands like "look" and "get" and that efuns like present() use.  The
exception to this is rooms.  Rooms get their id's set in a special way
through a room function called set_item_descriptions() which you will
read about in the rooms tutorial.

Functions not meaningful in rooms:

set_value(50);
This will set the value of an object to 50 gold coins.

set_mass(100)
This will make an object have a mass of 100 units.

set_name("whatever")
Sets a primary id for the object which will be what is used for reporting
what is done with the object in the game.

Other special functions inherited through the standard object:
set_property("property", value);  query_property("property");
Allows you to set and query values in an object which will not
be saved over time.  These things are called object properties.
Some common object properties are:
light
indoors
no attack
no magic
no castle
And more (check the /doc/build/etc/properties file for a full list).

set_properties(([ "property1" : value1, "property2" : value2 ]));
Allows you to set multiple properties at once.

add_property("property", value);
Adds to the value of a property.

set_read("message")
set_read((: "function" :))
If you pass a string, that string will be read whenever a player types:
"read name_of_this_object".  If you pass a function, instead that function gets called.

set_prevent_get("message")
set_prevent_get((: "function" :))
If a string is passed, any time a player tries to get the object, they will
not be able to get it, but will instead see this message.
If a function is passed, the function will get called.  If the function
returns 1, the player can get the object.  If 0, the player cannot.

set_prevent_drop("message")
set_prevent_drop((: "function" :))
Just like set_prevent_get(), except for people trying to drop the item.