A
          / \      _             Play Now                         Nemesis on 
          | |     | |  _______   _        _   _______    _______   _    _______
          | |\    | | |   ____| |  \    /  | |   ____|  /   ____| | |  /   ____|
 /-------/-------------------------------------------------------------------,
O= Home <=XX|  About  News  Pics  Adventurers  Wizards  Download  Connect     >
 \-------\-------------------------------------------------------------------'
          | |   \   | |  |____  | |      | | |  |____   ___ \  \  | |  ___ \  \
          | |     \_| |_______| |_|      |_| |_______| |_______/  |_| |_______/
          \ /
           V  

Documentation Area

Document Path: /doc/efun/add_action

Name: add_action - add a special command to a living

Synopsis:
	void add_action(string function, string command, int flag)

Description:
	The add_action efun adds a command to a living's list of commands.
	Commands are normally issued for a player by his input and for
	monsters by the 'command' efun.

	The command the first word of a users's input. Whenever the command
	matches an entry in the list of commands, function 'function' is
	called in the object that issued the add_action with the rest of the
	input as argument.

	You can see your current list of commands using the 'localcmd' command.
	Commands are checked in order of the list shown there. The order is 
	normally:

		- Commands from items in a room
		- Commands from the room
		- Commands from items in the inventory
		- Specific player commands

	For example a player has the player command 'smile'. An item in the
	player's inventory (eg. a curse) can overload the smile command.

	If the function returns 0 then the command was unsuccessful and the
	list of commands is searched on until the next matching command is
	found (or ends in an error message to the player that the command
	was not found). If it returns 1, the command was successful and the
	search is not continued.

	The object that issued the command has to check if the command is
	addressed to it, by parsing the the function argument (the rest of
	the input).
	
	For example, a player has a wand and a rod. Both object define 'wave'
	as an command. They both have to look if the argument is "wand" or
	"rod", to know if this object has to take action or the other one.
	If the argument is more complex you can use the sscanf efun to parse
	it.

	Always have add_action() called from an init() routine. This is the
	only right place to add commands for it makes sure that the object is
	present to the player and the action is removed again if the object
	is moved away from the player (or the other way round).

	If argument 'flag' is 1, then only the leading characters of the
	command has to match the verb 'command'.
	However this is a bitwise value with several options you can set.
	See /include/sentence.h for possible values.

	Never define an action that will call the function exit(), because it
	is a special function.

Return value: none

Examples:
	A wand that defines a 'wave' command.

	init() { add_action("wave_me", "wave"); }

	wave_me(str) {
		if (valid_id(str)) {
			write("You wave the wand.\n");
			say(this_player()->query_name()+" waves a wand.\n");
			return 1;
		}
		return 0;
	}

See also:
efun/query_verb
object/init
object/exit
w/localcmd
efun/sscanf
lib/valid_id