OBJECT
	/obj/quest_control

SYNOPSIS
	#include <quests.h> 

	QUESTMASTER->lfun();


LAST UPDATE
	Loco 19 Jan 1997


DESCRIPTION
	The quest controller is the central server for all quest
	matters. It has the list of installed quests, and is the only
	object allowed to set a quest for a player. It is placed in
	the /obj directory so that every Archwizard has the access to
	it.


CONCEPT: Quest classes                 (flag value as defined in quests.h)

	1. Official quests		QT_OFFICIAL
	  These are official quests which are not restricted in the amount
	  of QP, stored in the questcontroller with verbose information.
	  The QP requirements for wizzing and getting HLP are calculated
	  only from the sum of QP for official quests.

	2. HLP quests			QT_HLP
	  These are harder quests intentionally meant for HLPs.
	  Technically same as official quests, but these are only shown to
	  HLPs. Their QP don't count for wizzing requirements.

	3. Miniquests			QT_MINI
	  Miniquests are stored only with their name, the responsible
	  creator and the number of QP and XP. 

 
BASIC PLAYER RELATED FUNCTIONS

	string *QueryPlayerQuests(object|string player)
	string *QueryPlayerQuests(object|string player, int types)
		Return an array of the names of the quests that the
		player already has solved. The structure of the
		player's quests variable is hidden in this and the
		next function. If player is a string, then you will
		get the quests of player even if he is logged out.
		If execution of this function failed an empty array
		will be returned.
		The optionally argument chooses the quest classes to
		display and defaults to QT_ALL.

	int QueryQuestSolved(string|int qname, object|string player)
		return non-zero if the player already solved quest qname.
		This function can and should be used to do the check in 
		a final quest object.
		if qname is an integer, this is the position in the 
		official questlist.

	int SetPlayerQuest(string qname, object player)
		Sets the quest in the player.
		Currently we allow setting of non-official quests,
		might be useful for guild-specific mini-quests.
		Unknown quests will just not be counted for quest
		points. Return 0 for failure, string of player's
		quests for success.
                Please note that this_player() and this_interactive()
                must both equal <player>, otherwise setting will be
                refused. Caution: This also means it is not possible
		to set a quest within of a call_out!

	int QueryQuestPoints (object|string player)
		Return the amount of collected qp for player. If player
		is a string then you will get the qp's even if the player
		is logged out.


DATA QUERY FUNCTIONS

	string ListQuests(object player)
	string ListQuests(object player,int shortflag)
		Return an string with all quest descriptions of official
		quests. If a pointer to a player is given, also give info
		if the player already has solved the quest.
		This function is very useful for guild offices.
		If shortflag is non-zero, a string with the short 
		descriptions of only those official quests the player 
		solved is returned.
		If the calling player is HLP or Wiz, also HLP quests are 
		listed.
		
	string QueryQuestLong(int n)
		Return the hint to a given quest. Also useful in guild
		offices. N is the number of the quest in the questlist.
		Only for official quests.
		Not anyone may query the long info, but only objects of 
		specific domain(s), normally the one where the quest is 
		located. The questlist flag therefor may have the values:
		  0 - may be queried by wizards only.
		  1 - anyone may query
		  a string - only objects from this domain (and wizards)
		  an array of strings - objects from all domains in the 
			array (and wizards) 
		Note also that the questlist starts counting quests for the
		number at 0, while the number prepended in the text returned
		by ListQuests starts at 1.

	string QueryQuestCreator(int | string q)
		return the creator of the quest with name q or position q
		in the official questlist. Only for official quests, will
		not work for miniquests.

	int QueryQuestQP (string qname)
		return the amount of QP given for quest qname

	int QueryQuestXP(string qname)
		Returns the XP given for a quest.

	string QueryQuestsWritten(string wizname)
	string QueryQuestsWritten(string wizname,int types)
		return an array with the quest strings of the quests
		the wizard wizname coded.
		The optional argument restricts to certain quest classes
		and defaults to QT_ALL.

	string *QueryQuestNames ()
	string *QueryQuestNames(int types)    
		Return the names of all valid official quests,
		in the (sorted) order they are in the questlist.
		The optional argument specifies the quest classes. Note:
		This function does not list miniquests.
		Default is QT_OFFICIAL.

	string *QueryAllQuestNames ()
	string *QueryAllQuestNames(int types) 
		return an array of all registered quests, also the 
		miniquests, but unsorted.
		The optional argument restricts to certain quest classes
		and defaults to QT_ALL.
		
	int QPointLevel (int level)
		Return the amount of qp associated with the given
		'general <level>'. (Level, as returned by
		RACEMASTER->XPtoLevel())

	int QueryTotalQuestPoints()
	int QueryTotalQuestPoints(int types)  
                Returns the sum of all possible questpoints.
		The optional argument specifies the quest classes to use.
		If given, the sum of QP for these classes are returned.
		Default is QT_ALL.

	int QueryOfficialQP()
	int QueryMiniQP()
	int QueryHLPQP()
		Return the appropriate slice of the QP sum.
		Obsolete since covered by QueryTotalQuestPoints(types).

	int QuerySeerQuestPoints()
                Returns the value of questpoints a player will need to
		become a seer.

	int QueryWizQuestPoints()
                Returns the value of questpoints a player will need to
		become a learner.


CONVENIENCE FUNCTIONS

	int QueryHLPQuests (object player)
	int QuerySeerQuests (object player)
		Return non-zero if <player> has enough questpoints to
		become seer/HLP.

	int QueryWizQuests (object player)
		Return non-zero if <player> has enough questpoints to
		become wizard.

	int QueryQuestFactor (object player)
		Returns 1 if <player> hasn't got enough questpoints
		for his/her amount of accumulated experience, else
		zero. Might be used by guilds, is not used by the
		RACEMASTER.

	int CheckAdvance (object player, string stat, int delta)
		Check if player has enough questpoints to advance its
		<stat> by <delta>. Return the amount of qp missing, or
		zero if advancing is ok.
	

OTHER FUNCTIONS

	void qshout(string text)
		This function is quite similar to the efun shout and sends
		text to all logged in players. Unlike shout it checks for
		earmuffs and does not send the string to wizards with 
		earmuffs !=0 (means negative earmuff values block also)


DEBUGGING FUNCTIONS

	mixed QueryQuests()
	mixed QueryAllQuests()
		Return the questlist arrays. Format may change just to
		bug you. Only for debugging. Please don't use.



FILES
	/obj/quest_control.c      program file
	/sys/quests.h             #define quest classes
	/obj/questctrl/*          data files


SEE ALSO
	racemaster(C)