OBJECT
	/std/base


LAST UPDATE
	Mateese, 20-Aug-96 20:00 MET


SYNOPSIS
	inherit "/std/base";


DESCRIPTION
	This object contains the 'core' of all things used in
	OSB.
	It provides a gerneral purpose property mechanism and
	functions to remove the object.

	Each property consists of a name and a value of type mixed.
	That means that properties can be of arbitrarily type.
	Properties provide a flexible way of adding new aspects of an
	object. You are nevertheless advised to use only approved
	properties when designing new objects. See the discussion in
	concepts/properties for further information about inventing
	and approving new properties.

	Normally properties are a direct assignment between value and
	property name. There are, however, cases where a more direct
	control about the values of a property is necessary. There is
	a mechanism that lets the programmer specify functions that are
	called instead of the built-in mechanismus. See the discussion
	about properties in concepts/properties.

	Properties can be manipulated in the following ways:

	  mixed Set(string property_name, mixed value, void|int sc)
	  mixed SetProp(string property_name, mixed value, void|int sc)
	    Assigns the value <value> to the property <property_name>
	    and returns the new setting.
	    If <sc> is non-zero, always the 'soft property' of the
	    given name is set.

	  mixed Query(string property_name, void|int sc)
	  mixed QueryProp(string property_name, void|int sc)
	    Retrieves the value of property <property_name>.
	    If <sc> is non-zero, always the 'soft property' of the
	    given name is queried.

	  int Exists(string property_name, void|int sc)
	  int ExistsProp(string property_name, void|int sc)
	    Checks if property <property_name> is defined for this
	    object and returns 1 if it is the case.
	    If <sc> is non-zero, only the 'soft property' of the given
	    name is searched.
	
	  mapping SetProperties (mapping props)
	    Sets _all_ properties from the mapping <props> and returns
	    the new setting.

	  mapping QueryProperties (void)
	    Returns a mapping of all properties defined in this
	    object.

	SetProp(), QueryProp() and ExistsProp() exist for compatibility
	reasons and should not be used anymore (they are clumsier too
	type anyway).
	
	Destruction of an object may happen in two ways: deliberately
	on demand of an other other, or liberately due to the fact
	that it is not 'in the game' any more.

	Deliberate destruction is commanded by:

	  int remove()
	    Notify the environment (if existing) about the object's
	    leave, then destruct the object.
	    Result is 1.

	Liberate destruction due to unnecessarity is a bit more
	complex. Everytime the gamedriver suspects an object of being
	unused (which happens after 2 hours idleness), it calls the
	lfun clean_up() with an integer 'ref' as parameter. The 'ref'
	has these meaning:

	  ref < 0: our environment calls us to clean up.
	  ref = 0: we are a clone.
	  ref = 1: we are a swapped blueprint or one with ref count 1.
	  ref > 1: we are a non swapped blueprint with a ref count >1.

	If the lfun returns 0, the object either destructed itself, or
	it resisted to clean_up and doesn't want to be asked again.
	Else the object didn't destruct itself, but would like to be
	asked again the next round.

	  int clean_up (int ref)
	    Try to destruct this object and return 0 if success; else 1.

	clean_up() queries a non-builtin property:

	  mixed P_CLEAN_UP  "Cleanup"
            If non-zero, the object may cleanup, else a cleanup is
	    disabled. Default setting is 1.


        Sometimes an object just consists of a create() function, all
	other functions are inherited. In this case a replacement of
	the objects program by the inherited program can save a lot of
	memory.

	  string replace_pgm ()
	    Try to replace this objects program by the program of a
	    parent.
	    Return the object_name() of the parent on success, else 0.
	    This functions MUST NOT be called for blueprints, from
	    which multiple clones are to be created, inheritance
	    parents, or clones themselves!


	There are some informational read-only-properties:

	  string P_CREATOR  "Creator"
	    The object_name() of that object which loaded this object.

	  string P_ICREATOR  "ICreator"
	    The object_name() of that interactive user which caused the
	    load of this object.

	  int P_CREATION_TIME "CreationTime"
	    The time() when this object was created (loaded resp.
	    cloned).

	  int P_CLONED  "Cloned"
	    Set to a negative number in a blueprint if clones have been made
	    from this blueprint. It is also set to a positive number 
	    for cloned objects themselves.
	    Beware: there may be objects for which this doesn't hold!

	  int P_INHERITED  "Inherited"
	    Set to non-zero if the object was loaded by being
	    inherited.
	    If it was inherited after loading, the setting is
	    indeterminated.

	  int P_IS_VIRTUAL  "IsVirtual"
	    The value of this property is non-zero if the object is a
	    'virtual object'.


	Shadowing of objects is possible, but needs to be controlled
	such that at least the standard objects can not be shadowed.
	For this, the master queries this function:

	  int prevent_shadow (object shadower)
	    Return 0 if this object may be shadowed by <shadower>,
	    non-zero if not.

	/std/base allows shadowing on every clone, and on blueprints
	outside of /std, /obj, /lib, /room, /secure.
	This means that player and domain objects have to prevent
	their shadowing on their own.

	When inherited, the initialization of /std/object must be
	assured by a call to
	
	  void create (void)
	    Initializes the object core.


	To change the rate of refresh (modulo the granularity given
	by the gamedriver), set this non-builtin property:

	  int P_RESET_INTERVAL  "ResetInterval"
	    Holds the time in seconds to elapse between to refreshes.
	    If 0, the gamedrivers default interval is used.

	The time of the last refresh can be queried in the non-builtin
	property

	  int P_LAST_RESET  "LastReset"
	    Holds the time in seconds of the last reset().


	To support virtual objects, the call to compile_object() may
	be redirected from the object to a master object using the
	non-builtin property

	  object|string P_VMASTER  "VMaster"
	    The value is the master object of a group of virtual objects.

BUGS
	Maybe the clean_up() should implement the elaborate handling
	  now in std/thing/moving to provide a better failsafe against
	  GD and wizard 'features'.
	Shadowing is yet deactivated in the master.


INHERITANCE TREE
	base


SEE ALSO
	properties(C), virtual(C), thing(S)