Visibility Framework
--------------------

As bots move around a level, various points of interest move into and out of
their field of view. The Visibility Framework defines a programming interface
for the bot writer to access this information in a useful manner.

Field of View
-------------
The field of view is defined to be +/- 45 degrees from the direction that the
bot is Look()'ing. Entities (creatures, weapons, etc) do not block the field of view.

Visibles
--------
A "Visible" is either an entity (a hostage, player, gun-on-ground, etc) or it is
a user-defined 3D location that may be "of interest" to a Bot. Each bot maintains
an internal data structure indicating which Visibles it is monitoring,
and which ones are currently in view.

By default a bot is initialised to be monitoring all "entity" Visibles - i.e. all
Visibles that are predefined by Half-Life and the MOD. These are things such as
players, hostags, guns, the bomb, etc.

Defining Visibles
-----------------
There are two distinct stages to installing & monitoring Visibles. First, a global
data structure defining all non-entity Visibles must be installed and then individual
bots of that class can be allocated entries off this table to monitor.

Installing a Visibility Table
-----------------------------
All Bots belonging to the same class share a data structure called visibilitytable_t.

	typedef struct {

	   int nentries;	// Count of how many entries
	   Vector *list;	// Array of nentries vectors. Each vector (x,y,z)
				// represents a 3D location (a user-defined "Visible")
	   }
	   visibilitytable_t;

Calling (botclass->InstallVisibilityTable( visibilitytable_t *tbl)) informs the 
BotManager about the table, and makes the table available to other bots of this class
(your bots).

This table must contain all the user-defined Visibles that a bot of this class might 
want to track.  When the set of Visibles changes (e.g. when the map changes), this function 
can be called again to install a new table.

The BotManager assumes that memory management for this table is done in the Bot library.
The BotManager only holds a pointer to this table - it does not take a copy.

A side effect of calling this function is that all bots of this class have 
their user-defined Visible list cleared.

Allocating Visibility Entries
-----------------------------

To allocate or manage Visibles for a specific bot, use these Bot methods:

	BOOL b->AddVisible(int index);
	BOOL b->AddVisible(char *classname);

		"index" is either an index into a loaded visibilitytable,
			or it is (ent_index | IS_ENTITY) to indicate that it
			refers to a Half-Life entity.

		"entity" is an entity pointer.

		"classname" is the class name of an entity (e.g. "player")
		In this case you will get notification messages for all entities
		of this class.

		The return value indicates success of failure.

	void b->ClearVisibles(int which)

		Clears the entries for Visibles according to the value
		of "which" :

			USER_VISIBLES
			ENTITY_VISIBLES
			ALL_VISIBLES
		
	BOOL b->ClearVisible(int index);
	BOOL b->ClearVisible(char *classname)

		Removes entries for the specified Visible from the list for
		that bot.

	BOOL b->IsVisible(int index);
	BOOL b->IsVisible(char *classname)

		Returns TRUE if the Visible is currently in the F.O.V.

	count b->GetVisibles(int *list, int max);

		Fills in entries in list[] with "index" values for all Visibles
		that are within the bots field of view.

		"max" indicates the maximum number of entries that can fit into
		list[]. GetVisibles() returns the actual number of entries filled.
		
Visibility Notifications
------------------------
A Bot receives a message whenever a Visible that it is monitoring changes state.
The format of the message is:

	Message Type: 	BM_VISIBILITY
	Message Id:	The index of this Visible, combined with the following 
			flags:
				IS_VISIBLE		Visible is in F.O.V.
				IS_ENTITY		Visible is an entity
				
			The index can be extracted with this macro:

			int index = VISIBILITY_ENTRY( Message_Id );

If the IS_ENTITY bit is set, then the index is the entry in the Entity Index.

If the IS_ENTITY bit is not set, then "index" refers to an entry in the visibilitytable: