Reaperbot Improvement Protocol v0.11 (RIP v0.11)
by legion, the ubiquitous llama-killer

PART I

PREFACE

INTRODUCTION

COPYRIGHTS AND PERMISSIONS

PREREQUISITES





   1) Reaperbot v0.81

      - ftp.cdrom.com/pub/quake/quakec/bots/reaper



   2) btsk23.zip

      -ftp.cdrom.com/pub/quake/quakec/bots

      - contains norse_movetogoal as well as Alan Kivlin's QCBot ranking

      code

      - demos are included showing off the new movement code.  E-mail me

      at legion@keg.zymurgy.org if you think the Zeusbot's movement is

      better.  Provide an example (eg. a demo) proving your case



   3) ProQCC v1.52 or later

      - ftp.cdrom.com/pub/quake/quakec/utils



   4) v1.06 of QuakeC

      - many compilers come with v1.06 of QuakeC.  find one.

      - ftp.cdrom.com/pub/quake/quakec/utils



   5) knowledge of directory structure and installation of QuakeC patches

      - visit http://www.planetquake.com/qca for help in this area



   6) knowledge of QuakeC (not for the novice)

      - variable definitions are a must

      - modifying and creating functions

      - visit Inside3D, http://www.planetquake.com/iqc, for plenty of

        examples on this.  The tutorials are packed with examples of

        modifying functions.  Practically all the tutorials include at

        least one example of modifying existing or creating functions.

      - function prototypes are a must

      - understanding of IF block and IF-ELSE block

      - visit Inside 3D, http://www.planetquake.com/iqc, for examples

        on this.  Many of the tutorials contain IF blocks or IF-ELSE

        block statments for you to look at and understand.



   7) a text editor equipped with a cut-n-paste feature



   8) the ability to follow instructions





MAJOR CHANGES TO THE REAPERBOT



   1) bot will be able to walk on 'broken ground' and other good stuff.

      Watch the demos included in btsk23.zip for more examples of the

      added movement that the reaperbot now possess.



   2) thud sounds and splasing sounds are reduced.



   3) real players can be bounced around when hit by a rocket blast, now

      the reaperbot will mimic this as well.



   4) actual circle strafing is coded



   5) bot will no longer run away since the code is incompatible with the

      new movement code, norse_movetogoal.



   6) bot shows up on rankings



   7) monsters are active now, they can fight back.



   8) disappearing weapons bug removed







NOTE: If you thought that one original skill 3 reaperbot was easy to kill,

      you may find a modified skill 3 reaperbot more difficult to beat on

      some maps.  On other maps with certain terrains, the bot may be a

      little easier.  In short, you will have to learn the new attack

      patterns used by the reaperbot if you wish to win on a consistent

      basis.






 REAPERBOT BUGS 





This section contains a short list of bugs that were part of the ORIGINAL

reaperbot.  These bugs were not corrected.



   1) the "rebound" or "refire" bug causes the reaperbot to occasionally

   fire the weapon sooner than it should.  In other words, at times, the

   reaperbot can fire the rocket launcher at the same rate as a single-

   barrel shotgun.  THIS IS CHEATING.



   2) the firing rate for lightning gun/nails guns are not continuous

   sometimes.



   3) bot can fire at nearly 90 degrees angle up or down.  Human

   players can not do this but the reaperbot can.



   4) needs to scream the right pain sounds when drowning and it needs to

   blow bubbles, too.



   5) its line of sight code for items and waypoints needs to be improved.

   It still ignores items that is visible to it.  Therefore, it doesn't

   take advantage of the new movement code.  A perfect example is the yellow

   armor on E1M2.  With the new movement code, the reaperbot can now reach

   the yellow armor.  I have seen it do it once.  However, it failed many

   times.  It often quits after jumping two or three times.  The reaperbot

   actually didn't see the yellow armor, it was simply following the

   waypoints that were dynamically spawned.  If the waypoints were spawned

   too close to the edge, for instance, then obviously this would increase

   the failure rate.  And, of course, it quits too soon.









 GENERAL COMMENTS 





The reaperbot still uses much of its original programming.  Besides the AI,

the bot still use the same code for selecting and firing weapons.  (See the

list of bugs above).  The major changes that were introduced were in the

area of movement.  It is in the movement where you will see the improvements.

The reaperbot is actually an UNFINISHED product.  With this how-to guide,

it is possible that the Quake community can FINALLY improve the reaperbot so

that it is as human-like as possible.  So far, only its ability to "learn"

the map mimics human-like behavior.  All other aspects need to be improved

upon.



 
   BEGIN GUIDE: Part I 





 MAKING A COMPILABLE REAPERBOT SOURCE 





   1) follow the instructions that came with the reaperbot patch.  That is,

   create the reaperbot directory like you normally would when you want

   to play the patch.  I will assume you will call this directory, rpbot.

   You are free to use any other name that you like.



   2) In the rpbot directory, make a sub-directory called "src".  So the

   directory tree should look something like the following:



 [quake]

      - [id1]

         - pak0.pak

         - pak1.pak

      - [some other patch1]

         - some other patch1's progs.dat

         - [maps]

      - [some other patch2]

         -pak0.pak

      - [some other patch3]

         - some other patch3's progs.dat

         - [progs]

            - player.mdl

      - [rpbot]

         - progs.dat

         - [src]

      - [some other patch4]

         ...



  The "[]" signifies a directory.  This is just an EXAMPLE.  You may have

   only one patch, the reaperbot.  I included other patches in the directory

   structure above.



   Visit the QuakeC Archives (http://www.planetquake.com/qca) for additional

   help in this area.



   3) copy the progs.dat found in the rpbot directory into the src

   sub-directory.  Copy proqcc.exe into the src sub-directory.  There should

   be two files in the src sub-directory at this point: progs.dat and

   proqcc.exe.  Then go to this sub-directory by typing "cd\quake\rpbot\src"

   at the DOS prompt.



   4) type "proqcc -dec" at the DOS prompt without the damn quotes, of

   course.  Notice the use of CAPS.   "What caps?", you ask.  Well, I mention

   this because many people like to type parameters like this "proqcc -DeC"

   or "q95 -GaME rpBoT" or "q95 -GAMe rpbot" and the like.  Then they go to

   the newsgroups and wonder why the reaperbot is not loaded.  The caps lock

   key and the shift key obviously needs to be removed from these people's

   keyboard, followed by a smack on the head with an aluminum bat (not a

   wooden bat since wood breaks).



   - after the decompilation process, you will find a large list of

      files in the src sub-directory with an extension *.qc and one file

      with an extension *.src.  Any other file (if any) should be ignored.



 5) Open progs.src using your favorite text editor.  On the first line,

   you should see "./progs.dat".  The single period tells the compiler that

   the compiled progs.dat should be placed in the current directory.  A

   double-period tells the compiler that the compiled progs.dat be placed in

   the directory above it.  In this case, the directory one level above it is

   the rpbot directory (see directory structure provided above).  When Quake

   loads a patch, it is assumed that the progs.dat is in the rpbot directory

   and NOT in one of its sub-directories.  So change "./progs.dat" to

   "../progs.dat".

      a) now save the changes by closing progs.src



   6) now type "proqcc" at the DOS prompt to compile the source

      a) you should see some errors

      b) YOU will now correct these errors



   7) Open botit_th.qc using your favorite text editor.  (I use edit.com).

      a) you will see a bunch of lines that end with a semi-colon.  Most

      statements MUST end with a semi-colon.

      b) The following is an example of a function PROTOTYPE.





void (entity targ, entity inflictor, entity attacker, float damage) T_Damage;



      This function prototype tells the compiler that a function called

      T_Damage is defined somewhere in the code.  Like everything else, the

      name is CASE sensitive so the function called T_DAmaGE is not the same

      as T_Damage.



      BEFORE you execute any function, you must do one of two things: either

      declare the function by using a function prototype like above OR

      you define the function.



      Notice that you don't see any code telling you what the T_Damage

      function does.  The actual code that DEFINES the function (the code that

      tells you what the function does) can be found in combat.qc.  When

      you look into the combat.qc file and search for the T_Damage function,

      you will notice that the first line in a function definition is almost

      the same as a function prototype.  The only difference is that the

      semi-colon used in the function prototype has been replaced by an

      equal sign ("=").



      In other words, the function definition for T_Damage is the following:



void (entity targ, entity inflictor, entity attacker, float damage) T_Damage = {



   [ lots of code ]



};





 Every function definition has an opening left brace and a closing right

      brace.  The right brace is followed by a semi-colon.  You can view the

      braces as something that 'collects' statements that belong together or

      view the braces and the code inside it as a BLOCK of code that belongs

      together.



      So the format of a function prototype is the following:



      return_type (parameter list and types) function_name;



      The format of a function definition is the following:



      return_type (parameter list and types) function_name =

      {

         [ lots of code ]

      };





 NOTE: In C++, the equal sign is NOT used in making function

      definitions.



      So you must either DECLARE or DEFINE it first BEFORE you actually use

      the function.  That is why there is a bunch of function prototypes

      in botit_th.qc.  The file also contains a few function definitions

      as well.  When you finish with this tutorial, botit_th.qc will have

      more prototypes and more definitions than before.



      You can declare the function as often as you want as long as each

      declaration (each function prototype) is identical and that they match

      with the function definition.  You can only define a function ONCE.

      I was told that there is one exception to this rule, however.  You can

      redefine builtin functions of Quake but you can only define QuakeC

      functions ONCE.



      You will ONLY need to specify one function prototype for each

      function definition.  It is required BEFORE you actually execute the

      function, remember.  There is no need to provide multiple function

      prototypes for one function even though you can.



   8)  In decompiling, ProQCC has a problem decompiling certain types of

   function prototypes and definitions.  In botit_th.qc, search for the lines

   ".void() th_weight;" and ".void() th_cache;".  These are incorrect.

   Notice that there are periods (".") in front of the function prototypes.

   That is not the problem, the periods belong there.  To make a long story

   short, the periods tell Quake that each entity has its own th_weight and

   th_cache function.  That is, the th_weight function for one bot can be

   different from the th_weight function of another bot.



   The word "void" in the function prototype tells Quake that the function

   does not return any value.  Functions can return values which can be a

   number (ie. "float"), a vector, or an entity.  However, th_weight and

   th_cache are not void functions, these functions are supposed to return

   a value.



   Additionally, the function prototypes state that the function does not

   have any parameters.  Look at the T_Damage function above.  There are

   a bunch of variables in between the parenthesis.  This means that the

   T_Damage function takes in parameters.  The function prototypes for

   th_weight and th_cache says they don't.  This is wrong, too.



   Now the problem is what kind of values does these function return and

   what type of parameters, if any, do these functions take?



   9) Look into botgoal.qc.  Search for the line "weight = e.th_weight (e);".

   This code is in the "thingweight" function definition.



   Right off the bat, this should tell you that the th_weight function

   returns a value and that it takes one parameter.  So look around in this

   "thingweight" function for clues that tell you what type of variable is

   "e" and what type of variable is "weight".  You will find that e is

   a variable of type entity and that weight is a variable of type float.



   (Hint: like functions, you have to DECLARE the variables before using

   them.  So search for things like "local float weight" and the like.  In

   QuakeC terminology, declaring a variable is called "defining" a variable.

   The keyword 'local' is used WITHIN a function definition.  Outside the

   function definition, the word 'local' is NOT used.)





   From these two pieces of information, the correct function prototype for

   th_weight should be:



   .float(entity e) th_weight;



   So replace the ".void() th_weight" line in botit_th.qc with the correct

   function prototype above.



   You can follow a similar method with th_cache by looking into botroute.qc

   file and searching for th_cache.  Unfortunately, there's nothing in

   botroute.qc that tells you what kind of values the function returns.  You

   can determine what the parameters are, however, but that is not enough.

   So you need to do more searching.  In botspawn.qc, you will find the line

   "self.th_cache = cacheenemy;" in the PutBotInServer function definition.

   This means that the th_cache function for the bot is the cacheenemy

   function.  So search for this function.



   You will find the cacheenemy function in botit_th.qc.  Since this function

   is the SAME as the th_cache function, then this means that the th_cache

   function returns the same type of value and takes in the same parameters.

   Thus, the function prototype for th_cache should look like cacheenemy.

   In short, the function prototype for th_cache is the following:



   .float(entity node, float len, entity item) th_cache;



   So replace the ".void() th_cache" line in botit_th.qc with the correct

   function prototype above.



   Now save the changes you made in botit_th.qc.



   10) open misc.qc.  You should see the following at the bottom of the

   misc_fireball function definition.





/* Begin code */

   if ( !self.speed ) {





   }

/* End code */







The above code is given the label, "the IF block", since it is a block

   of code that should be executed whenever the conditions in the IF

   line is true.  If there is only one statement in the IF block, then the

   braces are not necessary.  The braces are only necessary if the block

   contains more than one statement (and, of course, each statement

   ends with a semi-colon).



   Examples of correct if-blocks are the following:



if (!self.health) {



      self.speed = 3;

      self.health = 20;

      self.button0 = FALSE;

   }



   if (self.search_time < time)

      self.search_time = time + 3;



   if (self.flags & FL_ONGROUND)

   {

      self.flags = self.flags - FL_ONGROUND;

   }



 Each statement inside the block ends with a semi-colon.  There is NO

   semi-colon after the closing right brace.



   The above code from misc.qc checks to see if self.speed (where self is the

   fireball) has zero velocity.  If the fireball has zero velocity, then it

   is supposed to execute any statements between the two braces.  As you can

   see, there is nothing in between the two braces.  Hence, there is missing

   code.



   The compiler will see two braces with nothing in it.  The braces are the

   one that confuses the compiler.  Braces are not only used in IF blocks,

   but these are also used in function definitions.  If there is nothing in

   the braces, you'll end up with a "not a name" error when compiling.  You

   can either delete the braces (and leave the IF line alone), put back the

   missing code or delete the whole IF block.  Putting back the missing code

   is the better choice.



   Now why do you have missing code in the decompiled source?



   Well, the problems comes from iD's original QuakeC code.  Originally, the

   code is this:



/* Begin code */

   if (!self.speed)

      self.speed == 1000;

/* End code */



When Polge compiled his code, the compiler correctly compiled the line

   "if (!self.speed)" but the next line causes problems.  The line is

   supposed to set the value of speed to 1000 but instead, it assigns a

   value of 1000 by "checking" to see if self.speed is equal to 1000.  This

   is meaningless.   You don't assign a variable a value by checking to see

   if it is equal to it. The result is that the compiler "left it blank"

   so to speak since it doesn't understand that line of code.  The progs.dat,

   then, contains "missing code".  Additionally, the compiler/decompiler

   always include the opening and closing braces for all IF statements even

   if there is only one statement in the IF block itself.



   When you decompiled the progs.dat, you will see that you have missing

   code.  Your only recourse is to find a compiler/decompiler that attempts

   to make sense of the mess or look at the original code.  I happen to know

   what the missing code should be.  So in misc.qc, insert the line



  self.speed = 1000;



   between the two braces of the IF block.



   Save your changes by closing misc.qc.



   11) Open botgoal.qc.  Look for this following lines of code:



/* Begin code */

   self.search_time = (self.search_time - 0.400);

   if ( (botTarget.goalentity == botTarget) ) {





   }

/* End code */



 You should find the above snippet of code in the ai_botseek function.



   Yes, this is the same problem found in misc.qc.  But this is different.

   Why?  Because I don't have a copy of the original botgoal.qc file used

   by Steven Polge.  So now, what do you do?  Well, I was lucky.  Decker

   in rec.games.computer.quake.quake-c newsgroup said that a decompiler

   provided this bit of code:



      self.search_time = time;



   So insert the above missing lines of code in between the braces.



   Save the changes made to botgoal.qc.



   12) now zip up all the *.qc files and progs.src.  You now have a

   compilable reaperbot source code.  Compile it by typing "proqcc" at

   the DOS prompt and enjoy.



   13) In preparation for your next lesson, create a file called

   func.qc.  This file will contain a list of function prototypes.



   14) Open progs.src, and insert "func.qc" AFTER defs.qc.



   15) Open buttons.qc.  Search the entire file for function prototypes of

   functions used by the reaperbot.  You should find one prototype in this

   file.  It is "void(entity bot) bot_triggered;".



   16) open func.qc.

      a) add the following:



/* Begin code */



// found in buttons.qc



void(entity bot) bot_triggered;

/* End code */



   b) save changes made to func.qc.



 17) open client.qc.  Search entire file for function prototypes of

   functions used by the reaperbot.  I found nine.  You are going to move

   these function prototypes to func.qc just like you did with the prototype

   found in buttons.qc.



   18) open func.qc.

      a) add the following:



/* Begin code*/

// found in client.qc

void(entity killer, entity killed) countkill;

void() initscore;

void(entity ply, float n) removeTeamBots;

void(entity ply, float n) addTeamBots;

void(entity e, float newskin) skinChange;

void() NewCarriedPath;

void() initBotLevel;

float() CheckDropPath;

void() DropBotPath;

/* End code */



      b) save changes made to func.qc.



   19) Continue the search for other function prototypes in EVERY file.



   20) open func.qc.

      a) add the following:



/* Begin code */

// found in combat.qc

float() BotFoundTarget;

void(entity en2) secondEnemy;

void() endEnemy;



// found in doors.qc

void() bot_touched;

void() enemy_touched;



// found in items.qc

void(entity node, entity targ, float len, entity item) cacheRoute;

void() bot_toucheditem;



// found in triggers.qc

void(entity a, entity b) addTarget;



// found in weapons.qc

vector() botaim;

void() botImpulseCommand;



// found in world.qc

void () setBotGravity;

/* End code */



       b) save changes made to func.qc.



 21) Compile and enjoy.



   22) I already outlined the problems that ProQCC had in decompiling certain

   function prototypes but I haven't gone over any problems it may have for

   function definitions.



   open botmove.qc.  In the Bot_tryjump function definition, you have the

   following:



float /* Warning: Could not determine return type */ (float vz, float dist, float imagine) Bot_tryjump = {



   Notice the warning in between the comments. (In QuakeC you can insert

   any statements between the "/*" and "*/".  The compiler will ignore every

   line between the "/*" and the "*/".)



   The decompiler had problems trying to determine what type of value the

   Bot_tryjump function returns.  It guessed that the function returns a

   number (ie. a "float").  It guessed right.  In fact, ProQCC made several

   such guesses throughout the source code.  All of them happened to be

   correct.  That is why I didn't go over this.  So now I will.



   Suppose you are decompiling the Zeusbot or some other patch.



   Suppose the first line of the function definition look like this:



float /* Warning: Could not determine return type */ (entity ent) ZEUS_StaticOrigin = {



   When you compile the source, you get an error somewhere saying something

   like "type mismatch for =" for a line code different from the line of

   code that the above line was taken.  That is, the error didn't come from

   the above quoted code, the function definition above.  The error was

   someplace else.



   The error came from something that look like this:



   entity_org = ZEUS_StaticOrigin (ent);



   Now let us forget for the moment, that the name of the variable

   "entity_org" makes it obvious that the function ZEUS_StaticOrigin returns

   a value that is a vector, not a float.  How do you determine what value

   the function returns?



   You look into the ZEUS_StaticOrigin function itself and look for clues

   that tell you what its return type is.  Well, in the return line of this

   particular function it uses the variables .absmin and .absmax.  If you

   look in the defs.qc file for these two variables, you will discover that

   .absmin and .absmax are both VECTORS.  So the ZEUS_StaticOrigin function

   returns a vector.  To correct the error, simply change the first line

   of the function definition to this:



   vector(entity ent) ZEUS_StaticOrigin = {



   You will have to go through every "type mismatch" errors involving

   functions and correct the problem.  Don't be surprised if more than one

   function has this problem.



   Alternatively, you can look through all the variable declarations and

   search for the variable "entity_org".  In particular, you will be looking

   for either "local xxx entity_org" or "xxx entity_org" where xxx stands

   for float, vector, or entity.  The variable type for "entity_org" will

   then be the return type for ZEUS_StaticOrigin.



   23) In addition to the above decompiling problems, ProQCC also has

   problems with strings.  In particular, those strings used in the sprint

   builtin function sometimes give ProQCC problems.  In the decompiled code,

   you might find lines looking like the following:



/* Begin code */

   /* Warning: No local name with offset 15762 */

   /* Warning: No local name with offset 15763 */

   /* Warning: No local name with offset 15764 */

   local "Maximum of 15 bots allowed!\n";

   /* Warning: No local name with offset 15766 */

   /* Warning: No local name with offset 15767 */

   /* Warning: No local name with offset 15768 */

/* End code */



   Simply delete all these lines.  In particular, notice above that there

   is the line "local..."  This line will cause problems in compiling.  This

   has to be deleted before compiling.  All the other lines are simply

   comments and will be ignored anyway.



   24) This completes the lesson for decompiling the reaperbot patch.  The

   lessons learned here can be applied to other patches as well.  This

   assumes that the progs.dat for the patches were not scrambled.  You

   will need to find an unscrambler before you decompile the progs.dat.  I

   don't have an unscrambler.



   You are now finished with Part I, stay tuned for Part II.



   Each part builds on the knowledge gained from the previous part.  So don't

   assume that other parts would be as detailed as this.  See you next week.



 


SUMMARY OF STEPS 



   1) create the rpbot directory

   2) create the src subdirectory under the rpbot directory

   3) copy the reaperbot progs.dat and proqcc.exe into the src subdirectory

   4) decompile the progs.dat by typing "proqcc -dec"

   5) open up progs.src and change the line that says "./progs.dat" to

      "../progs.dat".

   6) open up botit_th.qc.

      a) replace ".void() th_weight;" with ".float(entity e) th_weight;"

      b) replace ".void() th_cache;" with

         ".float(entity node, float len, entity item) th_cache;"

   7) open up misc.qc

      a) insert "self.speed = 1000;" inside the IF block in the misc_fireball

      function definition

   8) open up botgoal.qc

      a) search for the IF block that checks for goalentity being equal to

         botTarget in the ai_botseek function definition.

      b) insert "self.search_time = time;" inside this IF block

   9) compile the code by typing "proqcc".