OBJECT
	lamp


SYNOPSIS
	inherit "std/lamp";

	#include <properties.h>
	#include <lamp.h>
	#include <search.h>


LAST UPDATE
	Mateese, 11-Aug-1994, 21:15 MET


DESCRIPTION
	This is a generic lightsource. It's meant for all objects who shall
	be a lightsource with limited lifespan.

	The lamp is formed out of tho parts: the base and the fuel. The base
	is carrier of the fuel, with own weight and value. The fuel is the
	spirit needed for burning. It is measured in 'units', and weight/value
	are defined for one unit.

	When the lamp is lit, it burns down in discrete steps. The timelength
	of one step is customizable, default is 5 minutes.
	With each step, the amount of fuel is decremented, and if it falls
	below zero, the lamp goes dark (and of course can't be relit).

	Since the class 'lamp' includes a wide variety of objects (flashlights
	as well as torches), the /std/lamp can rarely be used by means of
	simple cloning - in most cases it'll be necessary to write an
	inheriting wrapper object (see /obj/torch for an example).

        The /std/lamp implements the commands 'light', 'unlight' and
	'extinguish'. It's not necessary that the player carries the lamp.

	The /std/lamp implements (besides the /std/thing properties) the 
	following builtin properties, defined in /sys/lamp.h,:

          P_BRIGHTNESS : the brightness of the lamp (default is 1).
          P_BURNING    : boolean state if its burning.
          P_BURN_STEP  : the timespan of on burn-step (default is 300 seconds).
          P_FUEL       : the current amount of fuel (in units).
          P_FUEL_MAX   : the max amount of fuel (in units).
          P_FUELTYPE   : the type of the fuel
          P_FUELVALUE  : the value of one fuel-unit.
          P_FUELWEIGHT : the weight of one fuel-unit.
          P_LAMPVALUE  : the value of the empty lamp.
          P_LAMPWEIGHT : the weight or the empty lamp.
          P_LAMP_MSG   : the messages needed for operation.

	Changing P_BURNING causes the lamp to light up/unlight,
	complete with messages!
	If on unlighting than the half of the time-span of the BurnUp has
	already elapsed, the amount of fuel is reduced by one.

        P_FUELTYPE is a string, defining the id of the needed fuel.
        /sys/lamp.h defines some values, but these are proposals.
        Only PFT_NONE is fixed: use this for non-refillable lamps.

	P_LAMP_MSG is an array of (mostly) strings, which are needed
	at various opportunities. All of these strings are
	process_string()ed before output.
	The array consists of the following PLM_MAX_MSGS strings (in given
	order): (I describe them by example)

	  PLM_IS_BURNING : "the lamp is already burning"
	  PLM_IS_DARK    : "the lamp isn't burning already"
	  PLM_NO_FUEL    : "the lamp is out of fuel - you cant light it"
	  PLM_LIGHT      : "your lamp lights up"
	  PLM_LIGHT_E    : "someones lamp lights up"
	  PLM_UNLIGHT    : "your lamp goes dark"
	  PLM_UNLIGHT_E  : "someones lamp goes dark"
	  PLM_BURNED_UP  : "your lamp used up all the fuel and goes dark"
	  PLM_BURNED_UP_E: "someones lamp used up all the fuel and goes dark"

	The ..._E messages may also set as arrays of two strings,
	according to the needs of the show() simul_efun.

	Alternatively, each entry may be set as a closure, which is
	executed on occasion (the index of the entry is then given as
	argument). The closure may return a string, which is then used
	as the string to output, or 0, so nothing (or a default) is output.

	The /std/thing-Properties P_WEIGHT and P_VALUE have been overlaid
	by builtin functions which return weight/value in respect to the
	current amount of fuel.

	For easier customization, the following functions are implemented:

	void SetLMsg (int index, string msg)
	  Sets the <index>ed P_LAMP_MSG to <msg>.

	void SetWeights (int lweight, int fweight)
	  Sets the lamp weight to <lweight>, and the weight of one fuel unit 
	  to <fweight>.

	void SetValues (int lvalue, int fvalue)
	  Sets the lamp value to <lvalue>, and the value of one fuel unit 
	  to <fvalue>.

	void SetFuelAmount (int current, int max)
	  Sets the <current> and the <max> fuel amount.
	  If <max> is 0, both are set to the same value <current>.

	void SetBrightness (int bness)
	  Sets the brightness of the _burning_ lamp to <bness>.
	  Do not mix this with SetBright(), which sets the _actual_
	  brightness of a thing.

	void SetBurnStep (int i)
	  Sets the timespan of one burn step to <i> seconds.


        int flight (string str, void|int where)
          This implements the 'light' command.
	  <where> determines where the lamp is searched, default is
	  SEARCH_ENV_INV. 

	int funlight (string str, void|int where)
          This implements the 'unlight', 'extinguish' command.
	  <where> determines where the lamp is searched, default is
	  SEARCH_ENV_INV. 

	int BurnUp()
	  This fun is called every P_BURN_STEP seconds to implement the
	  consumage of fuel.
	  It reduces the fuel by one and adjusts the carried weight of	
	  the environment (i.e.: gets lighter).
	  If the fuel falls <=0, the lamp will be unlighted by settint
	  P_BURNING to 0. If not, another BurnUp() is scheduled.

	string Pl_Name()
	string Pl_Pro()
	string Pl_Poss()
	string Pl_Obj()
	  For easier use of process_string() in the P_LAMP_MSGs, these funs
	  return the player's name, pronoun, objective and possessive.
	  E.g. "Araech", "it", "its", "him".

	string Pl_Owner()
  	  If the lamp is carried by a player 'name', it returns
  	  "name's", else just "A".


	These functions from /std/thing are redefined:

	void create()
	  Initialises the thing, and the lamp's properties.

	void init()
	  Adds the things commands, and 'light', 'unlight' and 'extinguish'.


INHERITANCE TREE
        lamp
	 `-thing
	     |-std/base
	     |-std/thing/moving
	     |-std/thing/properties
	     `-std/thing/description


SEE ALSO
	properties(C), light(C)