Coding Light Sources Using the Nightmare IV Mudlib
                             Descartes of Borg
                                  940428

This document details how to build light sources using the standard light
source object.  Any light source should inherit and make use of the
features of this object, as other objects on the MUD depend on these
features being in light source type objects.  A light source type
object is something like a torch or a lamp or a match which may be used
to change the lighting of a room or area.

The standard light source object is /std/light.c.  Examples of two such
objects are /d/Examples/etc/torch.c and /d/Examples/etc/match.c.  More
than anything else, these examples should help you come to understand what
the standard light object is doing.

***************************************************************************

Part I: Required Calls
----------------------

/std/light.c inherits /std/weapon.c which inherits /std/Object.c.  Thus,
any object inheriting light.c needs to make all of the needed function
calls of any object, as well as those of a weapon (if you do not disable
the weapon functionality of the light object).  The standard Object
function calls which are mandatory:

set_name("torch");
set_id( ({ "torch", "a wooden torch" }) );
set_adjectives( ({ "a", "small", "wooden" }) );
set_short("a small wooden torch");
set_long("This wooden torch will only last so long you imagine.");
set_mass(70);
set_value(50);

If you are allowing the object to funcion as a weapon, it needs these
function calls as well:

set_type("blunt");
set_wc(2);
set_ac(1);

And, of course, there are function calls you always must make for the light
item itself:

varargs void set_light(int strength, string cmd_light, string cmd_ext);
Example: set_light(2, "light", "extinguish");

This sets up the light object.  The first argument is how strong the light
is.  Consult the table of light values in the room document directory as
well as any relevant balance documents.  The second argument is the command
a player uses in order to light the object.  The third argument is the
command the player uses to extinguish the object.  The second and third
arguments are optional.  If they are not given, then the default commands
are "light" and "extinguish".  You may also disable commands from being
used to light or extinguish the light object, but more on that later.

void set_fuel_required(int x);
Example: set_fuel_required(1);

Sets whether or not the object needs fuel in order to burn.  1 means that
fuel is required.  0 means it is not required.  You must set_burnt_value() 
if your light object requires fuel.

void set_fuel(int x);
Example: set_fuel(300);

Sets how much fuel the light object has.  Only needed if you require
fuel.  The value is how long in seconds the object can stay lit.

void set_source_required(int x);
Example: set_source_required(1);

Sets whether or not an external, burning light source is needed in order
to light this one.  For example, you might need a match burning in order
to light a torch.  A value of 1 means you need soemthing elsewith which
to light it.  A value of 0 means it can be lit on its own.

void set_fire(int x);
Example: set_fire(1);

Sets whether or not the light object is on fire (like a torch) or
simply glowing (like a lamp).

That is all a light object requires!

************************************************************************

Part II: Optional Functionality
-------------------------------

The following functions help add interesting features to your light
source, but they are not required in order to make a light source
work:

void set_burnt_value(int x);
Example: set_burnt_value(10);

Sets the value an object will have after its fuel is exhausted.  Required
for any object that requires fuel.

void set_disable_weapon(int x);
Example: set_disable_weapon(1);

If you pass 1, then a player cannot use the light source as a weapon.
If you do not call this function, or if you pass 0, then the light
source may be used as a weapon and you must make sure to make the 
minimal weapon calls as listed above.

void set_disable_commands(int x);
Example: set_disable_commands(1);

If you pass 1, then no player commands may be used to light the
light source.  Useful for magical light sources and such.  If you
do not call this function, or if 0 is passed, then player commands
as you set up in set_light() will work.

void set_light_function(function f);
Example: set_light_function( (: this_object(), "check_indoors" :) );

Sets up a function which gets called any time a player tries
to use the lighting command to light the object.  If that function
returns 1, then the object can be lit.  If it returns 0, then the
object will not be allowed to be lit.  Any object being used to light
the object is passed to your function.  So your function should
look like:

int check_indoors(object ob) {
    if((int)environment(this_player())->query_property("indoors")) {
        write("You cannot light that indoors!");
        return 0;
    }
    else {
        write("You light the torch.");
        say((string)this_player()->query_cap_name()+" lights the torch.");
        return 1;
    }
}

void set_extinguish_function(function f);
Example: set_extinguish_function( (: this_object(), "check_indoors" :) );

Exactly the same as set_light_function(), except it gets called