From the NannyMUD documentation

LAST CHANGE

2000-12-16

NAME

        sequence.c - Make monsters execute a sequence of commands.

FUNCTIONS

SETUP FUNCTIONS

	add_sequence
	start_sequence
	force_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.

FUNCTION

NAME
        add_sequence - Add a sequence line to the monster.


SYNTAX
	void add_sequence(string command, mixed time)
	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.


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




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.




FUNCTION

NAME
        force_start_sequence - Force a start of a sequence.


SYNTAX
	void force_start_sequence(int rand, int timeout)

DESCRIPTION
	This function forces the sequence to start even if no player
	is present in the room. Otherwise it works as start_sequence().




FUNCTION

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.




FUNCTION

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


NOTE
	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().




FUNCTION

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.




FUNCTION

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.




FUNCTION

NAME
        query_seq_state - returns current state


SYNTAX
	int query_seq_state()

DESCRIPTION
	This function returns various information about sequences.




FUNCTION

NAME
        query_sequence - Return the current running sequence.


SYNTAX
	mixed query_sequence()

DESCRIPTION
	This function returns various information about sequences.




FUNCTION

NAME
        query_stack - Returns stacked sequences.


SYNTAX
	mixed query_stack()

DESCRIPTION
	This function returns various information about sequences.