Birds Bot Manager (BBM) Bot Class Description --------------------- The Bot class encapsulates a bot and all its private data, including the edict_t * data created & used by the HL engine and the MOD. Movement-related methods ------------------------ Definitions: "yaw" Is an angle in degrees between 0 and 360, representing a horizontal rotation. Yaw increases in a clockwise direction. 0 degrees points in the +ve x direction. 90 degrees points in the +ve y direction. 180 degrees points in the -ve x direction. 270 degrees points in the -ve y direction. "pitch" is an angle between -90 (down) and +90 (up) representing a vertical angle. Three important directions: The direction that a bot is "facing" determines which way is forward and also the direction that the visible model will be facing. The direction that a bot is "looking" determines the field of view for calculating what the bot can "see". The direction that a bot is "moving" determines how the bots centre will move. void Face(float yaw, float pitch=0); Turn your bot to face in the given direction. "pitch" is an optional argument, and will be 0 if omitted. void Look(float yaw, float pitch=0) Set the direction that your bot is looking. This does not change the direction that it is Face()'ing. void MoveForward(float speed); void MoveLeft(float speed); void MoveUp(float speed); Sets the directional components for the bots movement. "speed" is a fractional value between -1.0 (max reverse speed) and 1.0 (max forward speed). These components are relative to the direction that the bot is facing. The three components will be scaled if needed so that the composite speed does not exceed 1.0 Vector Origin() Returns a 3D vector containing the (x,y,z) coords for the bot. float DistanceMoved() Returns a value between 0.0 and 1.0. This value is calculated as (actual_distance / expected_distance) for the bot and it can be used to check whether the bots movement is partially or completely blocked by something. This value is recalculated every 200ms. void MakeDirVectors(Vector *fwd, Vector *right, Vector *up) Generates unit vectors relative to the direction that the bot is currently facing. Using the Keyboard ------------------ void PressAndRelease(unsigned short bmask) Presses the buttons indicated in bmask and then releases them just before the next Think(). Definitions for buttons are in in_buttons.h There are 16 values, arranged as bits in an unsigned short value. void PressAndHold(unsigned short bmask) Press and hold down the named buttons. These buttons will remain down indefinitely, or until they are explicitly released via ReleaseButton(). void PressAndHold(unsigned short bmask, float duration) Press and hold down the named buttons. The buttons will stay down for the given duration (seconds). void ReleaseButtons(unsigned short bmask) Release the named buttons. void ReleaseButtons() Release all buttons that are currently held down. What the Bot can See -------------------- * See the section on "Bot Visibility management" for a thorough description of how visibility handling is done. BotClass *bc; void bc->InstallVisibilityTable( visibilitytable_t *vt ); Installs a new user-visibility table containing a collection of user-defined 3D points that the Bot might be interested in monitoring. This method is called off the BotClass ptr passed into BotCtl(). void b->AddVisible(int vis) Adds a Visible to the set that the Bot is monitoring. "vis" is either an offset into the current vt->list[], or it is an entity index supplied as (ent_index | IS_ENTITY). void b->AddVisible(char *classname) Adds all the system entities with this class name to the set that the bot is monitoring. void ClearVisible(int vis) void ClearVisible(char *classname) See the AddIndex() and AddVisible() methods for the semantic meanings of the parameters. These methods remove an entry from the set that the bot is monitoring. BOOL IsVisible(int vis) BOOL IsVisible(char *classname) See the AddIndex() and AddVisible() methods for the semantic meanings of the parameters. If the given Visible is actually visible to the Bot then the return value is TRUE, otherwise FALSE. void ClearVisibles() Clears all the entries in the Bot visibility table. The Bot will not receive any visibility messages after this. until new entries have been Add()ed. int CountVisibles() Count the number of monitored Visibles that are currently visible to the bot (within its field of view). int GetVisibles(int *list, int max) list[] is filled in with "vis" values for all the monitored Visibles that are visible to the bot. No more that "max" entries are filled in. GetVisibles() returns the actual number of entries filled in. int LookAtVisible(int vis, lookresult_t *res) If "vis" is visible to the bot, then *res is filled in with the actual coords for vis etc. BOOL VisibleFromLocation(int playernum, int vis); Returns TRUE if "playernum" refers to a player entity that is on the same team as the bot, and is visible from the visibilitytable_t entry "vis". Miscellaneous Methods --------------------- float b->Time() Returns the number of seconds that have elapsed since this level started. BOOL b->IsAlive() returns TRUE if the bot is currently alive. void b->Command(char *fmt, ...) Provides a mechanism for the bot to issue "console" commands. The arguments have the same semantics as printf(), with the final constructed string sent as a console command originating from the bot. MQueue *b->GetQueue(); Get the message queue associated with the bot. edict_t *b->GetEntity() Returns the edict_t (pEdict) associated with the bot. void b->TraceLines(traceresult_t *input, int count) Traces a bundle of "count" lines which originate at the (x,y) location of the bot. Each input specifies: yaw (0 to 360) relative to the direction that the bot is facing. pitch (-90 to 90) relative to the direction that the bot is facing. alt (-36 to +50) relative to the centre of the bot. (-36 is ground level, and +50 will be above head height) These three values, along with the current location of the Bot, determine a start point and direction for a TraceLine() command. The line that is traced is of length 255. dist Set by TraceLines() to the actual clear distance (0 to 255) visible (TRUE if the ray should be displayed for debugging) if "visible" is set, then the "ray" element should have these entries set: ray.r = RED component (0 - 255) ray.g = GREEN component (0 - 255) ray.b = BLUE component (0 - 255) ray.lifetime = lifetime in 0.1 second increments. The "ray.start" and "ray.end" vectors are ignored, and the actual start & end points of the ray are used. BOOL b->ShowMenu(char *title, char *options[16]) Opens a menu on the server. When the user has selected an option a message is sent to the Bots queue (type=BM_MESSAGE, id=MENUSELECT) with an Int component indicating which entry was selected (1 .. 16). Each of the 16 entries in options[] must point to a valid null-terminated string or be set to NULL. Each entry corresponds to a line in the menu. Entries that are NULL will leave their corresponding line blank. Only one Bot can have a menu open on the server at any time. If a bot tries to open a menu while one is already active then ShowMenu() will return FALSE. FILE b->OpenFile(char *fname, char *mode) Opens a file in a manner similar to fopen(). The supplied filename will be resolved relative to the bots data directory under bbm/, and must not start with "/" or contain "..". CfgFile * b->OpenConfigFile(char *fname) Opens and returns a CfgFile object for the given file. The file is resolved relative to the bots data directory in the same manner as OpenFile(). CfgFile files have a "windows .INI" file format with sections denoted by "[section-name]" and then free-form lines of data within each section. See the details on the CfgFile methods for parsing and rewriting these files.