FILE
        sequence.c - make monsters execute a sequence of commands
 
INHERITS
        Nothing 
 
SETUP FUNCTIONS
        add_sequence
	start_sequence
	set_sequence_state
 
OTHER FUNCTIONS
	do_sequence
	clear_sequence
	stop_sequence
        
QUERY FUNCTIONS
	query_sequence
	query_stack
	query_seq_state
 
DESCRIPTION
        A sequence is a series of commands that will be executed
	by the monster with some time interval between. This is
	useful when you want to let a monster walk around in your
	area along a specified path, or when you want a monster
	to do certain commands as a response. A sequence can be
	set with the add_sequence function when the monster is
	created and then be executed when a player enters the
	room, and then it continues that sequence in a loop for
	some time. Or a sequence can be executed once with the
	do_sequence function. The time between each command can
	either be immediate, random or specified time. The
	commands can also be simple strings that is sent to std/msg.

=======================================================================
NAME
        add_sequence - add a sequence line to the monster
 
SYNTAX
	void add_sequence(string command, mixed time)
	or
	void add_sequence(mixed *command)
 
DESCRIPTION
	This function adds either a command and a time, or a list of
	commands to the monsters sequence. The command can be one of
	the following:

	"text" -     which will be sent to std/msg and written when executed.
	"!command" - the command is done by the monster
	"@func()" -  the function is sent to eval, and the return value
		     is executed. That value can be a new list which will
		     be executed as if sent to do_sequence.
	({"!north",0,"!south",1}) - a list of commands and times

	The time can be one of the following:

	0    	  - the command will be executed after a random time set
		    with the start_sequence function.
	1    	  - the command will be executed immediately
	  - time is specified
	"@func()" - time is returned by the function

	This function sets the monsters base sequence which will be
	executed when any player enters the room, and after that will
	loop over the commands until the timeout has been reached.
	This sequence of commands will always stay in the monster,
	unless the clear_sequence() function is called.

EXAMPLES
	add_sequence("!north");    /* time 0 is not needed */
	add_sequence("\bPRON jumps around.\n",1);
	add_sequence(({"!north",0,"!south",1}),"@random_function()");

=======================================================================
NAME
	start_sequence - starts a sequence
 
SYNTAX
	void start_sequence(int rand, int timeout)

DESCRIPTION
	Only when this function is called the monster will start the
	sequence when a player enters the room. The parameter rand is
	the average random time between each command, and it defaults
	to 200 seconds. The timeout parameter is the total time the
	sequence will loop after a player left the room, and defaults
	to rand*10.

=======================================================================
NAME
	set_sequence_state - sets the state of the current sequence

SYNTAX
	void set_sequence_state(int state)

DESCRIPTION
	This function sets a new state of the current sequence. If
	the parameter state is greater than the current sequence size
	it ends the loop and restart it, unless it was a temporary
	sequence.

=======================================================================
NAME
	do_sequence - run a temporary sequence

SYNTAX
	void do_sequence(mixed *seq, int rand, int timeout, int lowprior)

DESCRIPTION
	Executes the command sequence 'seq' in the monster once. This
	function normally interrupts any old running sequence and put
	that on a stack for later execution, but if the lowprior flag
	is set, it will run 'seq' after every old sequence. But not 
	after the original sequence added with add_sequence().
	After execution the sequence is removed.

EXAMPLE
	monster->do_sequence(({"!smile",5,"!laugh",5}));
	monster->do_sequence(({"!hmm",5}));
	monster->do_sequence(({"!twiddle",5}),0,0,1);

	Will do the commands in the following order:
	  hmm, smile, laugh, twiddle

NOTA BENE
	Do not call this function in reset(), because it won't be
	executed at that time anyway, and it messes up the rest of
	the add_sequence().

=======================================================================
NAME
	stop_sequence - stops an ongoing sequence

SYNTAX
	void stop_sequence()

DESCRIPTION
	This function stops all sequences running in the monster.
	It actually clears the timeout and randomtime variables.

=======================================================================
NAME
	clear_sequence - clears all sequences

SYNTAX
	void clear_sequence()

DESCRIPTION
	This function clears and removes all sequences in the monster,
	including any stacked sequences. A stop_sequence() and a 
	clear_sequence() resets and blanks the monster completely.

=======================================================================
NAME
	query_seq_state - returns current state
	query_sequence - returns current running sequence
	query_stack - returns stacked sequences

SYNTAX
	int query_seq_state()
	mixed query_sequence()
	mixed query_stack()

DESCRIPTION
	These functions returns various information about sequences.

Help topics available:

board.doc	box.doc	door.doc	hidden_door.doc	lib.doc
remote	sequence.doc	simple_armour.doc	simple_container.doc	simple_weapon.doc