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

Documentation Area

Document Path: /doc/room/search

Lfun:	search - define search actions everywhere

Synopsis:
	mixed search(string item);

Description:
	The search function is called through the search add_action of the
	player. Everything can be searched: room items, objects in the room
	and objects in the inventory of the player (see 'help search').

	To make an object searchable a function search has to be defined
	in the object.

	The single argument is the item to be searched. It has to be an
	ID (see 'man id') of the object. The object is identified by
	this ID. The IDs of a room are set via set_items in room2.h
	(see 'man set_items').

	If a pointer of object is returned, it is moved to the right
	environment and weight is added, if it is moved to the player's
	inventory.

	In this case full messaging is done by the obj/player: "You
	find an empty bottle." and "<Player> searches the <item> and
	finds <short>.".

	If 0 is returned, "You find nothing." and "<Player> searches
	the <item> but finds nothing." shown.

	If 1 is returned, the searched object has to do the messaging
	describing what happend.
	
	Also fully living object, monsters, can be made searchable.
	If 0 is returned (no function search defined, the default),
	"You can't do that." is displayed.

Return value:
	A pointer of object if searching is successfull and an object
	is found,
	or 1 if the search was "successful",
	or 0 if not successful.

Examples:
	status found;

	search(str) {
		if (str == "grass" && !found && !present("rope") {
			found = 1;
			return clone_object("lib/obj/rope");
		}
	}

	search(str) {
		if (str == "sign" || str == "signpost") {
			write("Hmmm, somebody has added a note on the "+
			  str+". Very tiny letters ...\n");
			say(this_player()->query_name()+" searches the "+str+
			  ". Hmm, looks like "+this_player()->query_pronoun()+
			" has found something.\n");
			return 1;
		}
	}

Note:
	Make sure players can only find a limited quantity of objects by
	storing the status in a global variable and reset it in reset().

	Numbered room items are also supported: <item 1> and <item 2>
	e.g. 2 notes in one room.

	For other possibilities of "searching" see 'man room/produce' and
	'man room/do_dig'.

See also:
helpdir/search
helpdir/numbering
room/set_items
lib/valid_id
living/find_id
room/produce
room/do_dig