CONCEPTS
	moving

UPDATE
	Mateese, 10-Oct-94 21:30 MET

DESRIPTION
	In native mode an objects may only be mved by itself by
	the efun move_object(). If another object wants to move object
	<ob>, it has to call move() in the object it wants to move.

	Object may want to restrict their movement. An optional parameter
	<methods> can be given to move(), defining the method of this move.
	If you dont give any methods, a default action will be taken
	by the object which normally is very restrictive about its
	movement. Nevertheless, move() without any method should be
	the rule if your object doesnt want to do something very
	specific with the other object.

	If an object just doesn't want to be dropped, taken by or
	given to, this can be achieved by setting the object's
	properties P_NODROP, P_NOGET or P_NOGIVE to non-zero.
	If their value is a string, it is used as failure message,
	else a default message is given to the player. It is task of
	the interactive command code to check this properties, though.

	For some very special moves, an optional third parameter
	<extras> can be given. The interpretation of this parameter is
	completely up to the object being moved/checked/notified in
	respect to the <method>.

	move() returns a code specifying the success/failure of the
	move.

	int move (object|string dest, void|int method, void|mixed extra)
	  Move the defining object to <dest> using <method>.
	  Before the move, and if <method> != M_NOCHECK, call
	  prevent_leave() in the current env, and allow_enter() in <dest>.
	  After a successful move, call notify_leave() in the former
	  env, and notify_enter() in <dest> alias the new env.
	  Also, a MSG_MOVE is issued to both new and old environment.

	int remove()
	  This function should be called if the defining object is to be
	  destructed. If the remove() is ok, the object has to
	  self-destruct and return non-zero, else it has to return zero.
	  If the object has an environment, it calls prior to the
	  self-destruct the env's 'prevent_leave (0, M_DESTRUCT, 0)',
	  and on success also 'notify_leave (0, M_DESTRUCT, 0)'.
	  If 'prevent_leave()' failed, remove() will be aborted
	  returning zero.

	int prevent_leave (object|string dest, int method, void|mixed extra)
	  This is called to check if previous_object() may leave the
	  defining object for a move to <dest> using <method>.
	  Return zero if it's allowed, else a decent error code.
	  The error code will then be returned by the calling move().

	int allow_enter (int method, void|mixed extra)
	  This is called to check if previous_object() may enter the
	  defining object from a move from its old env using <method>.
	  Return ME_OK if it's allowed, else a decent error-code or 0.
	  The error code (or ME_NO_ENTER if it's 0) will be returned
	  by the calling move().

	void notify_leave (object|string dest, int method, void|mixed extra)
	  This is called to notify that previous_object() has left the
	  defining object while moving to <dest> using <method>.

	void notify_enter (object|string oldenv, int method, void|mixed extra)
	  This is called to notify that previous_object() has enterd the
	  defining object while moving from <oldenv> using <method>.
	  Note that <oldenv> may be zero.

	The semantics of the checks/notifies allow that simple things
	(solid, need not be notified) easily may omit these funs.

	The actions performed in these funs are object specific. Refer
	to the approbiate documentation.

	Standard move methods and error codes are defined in <moving.h>.
	The methods and their <extra> are:

	  M_SILENT  : do a silent move but with all checks.
	  M_NOCHECK : don't do any checks just inform the environment.
	  M_GO	    : a walks into <dest>.
	  M_TELEPORT: a teleports into <dest>.
	    The difference between M_GO and M_TELEPORT are the
	    differing movement messages the others will see.
	    If <extra> is given, it replaces the default teleport
	    messages just as if it were a M_SPECIAL move.
	  M_SPECIAL : be creative!

	  M_PUT     : thing is put (living -> container)
	  M_DROP    : thing is dropped (living -> room)
	  M_TAKE    : thing is taken (room/container -> living)
	    If <extra> is non-zero for M_DROP und M_TAKE, the room
	    generates no messages.

	  M_DESTRUCT: thing shall be destructed.
	    This is no actual move-method, but to check/notify the
	    environment before the actual destruction.
	    <dest> is set to 0.

	The errors are:
	  ME_NO_MOVE	    : general error, also default if move() is
			      not defined.
	  ME_OK 	    : move succeeded.
	  ME_DESTRUCTED_SELF: object was destructed while moving.
	  ME_NO_LEAVE	    : was not allowed to leave current env.
	  ME_NO_ENTER	    : was denied entering for unknown reason.
	  ME_TOO_HEAVY	    : dest cannot carry us.
	  ME_NO_DROP	    : can't drop
	  ME_NO_GET	    : can't take
	  ME_NO_GIVE	    : can't give

	  ME_CAUGHT_ERR     : a runtime error occured during the move


	Moved objects also generate a message after the move, which is
	delivered to the old and new environment:

	  MSG_MOVE <origin> <dest> <method> <extra>

	<origin> and <dest> here are both object values.

SEE ALSO
	messages(C), move(L)