From the NannyMUD documentation

LAST CHANGE

2004-05-28

FUNCTION

NAME
        move_player - move a living object to a new location


LOCATION
	/obj/living_functions.c

SYNTAX
	varargs int move_player(string destdir, mixed optdest, int moveflags);

DESCRIPTION
	This is the standard method of moving monsters and players
	to new rooms.  It may be referenced in the following ways:

	  ob->move_player(string+"#"+string);

	where the first string is the direction ("north", "south", etc.)
	and the second string is the file name of the room to be moved to.

	  ob->move_player(string, string)

	Like above, except the direction and the destination are 
	passed as separate arguments instead of one separated by a "#"

	  ob->move_player(string, object)

	The first argument is the direction, the second an object 
	pointer to the destination.

	There is a special direction, "X", which means the living is leaving
	magically.  In this case the 'magic' exit message is printed out
	(normally "leaves in a puff of smoke").

	If you want your own enter and exit messages, you can separate
	them with \b and put them in the destdir string. For example
	ob->move_player("You enter the closet\b$M\b$M into the closet",
	"/room/closet"); will give one message to the player, one to
	the entered room and one in the exited room. The $M is replaced
	with the players normal enter/exit message.

	You can also supply three different flags to move_player as
	third argument. The flags are specified in /include/move_flags.h.
	If you wish to use more then one flag just '+' them together.


RETURN VALUES
	Gets a 1 if object moved is an NPC, or a 0 if object is
	a player (either way, almost completely useless).


NOTE
        Any paths given, must be full paths.


NOTE
	This function is preferable to moving players with move_object or
	transfer as it handles automatically the printing of messages,
	the automatic 'look-around' a player does when entering a room, etc.


SEE ALSO
        move_object in efun/object_related/move_object