diff --git a/docs/cube_bot-readme.txt b/docs/cube_bot-readme.txt new file mode 100644 index 00000000..384553a1 --- /dev/null +++ b/docs/cube_bot-readme.txt @@ -0,0 +1,481 @@ +Official 'Cube with Bots' readme. + +Current version: 0.32 + + +AUTHOR: + +Rick Helmus +E-Mail: rickhelmus@gmail.com +MSN: rick_helmus8@hotmail.com +ICQ: 224332897 +AIM: rickakame + + + + +CONTENT + +1. Features +2. Installing & Uninstalling + 2.1 Installing + 2.2 Uninstalling +3. Starting a game +4. Bot settings + 4.1 Bot names & teams + 4.2 Bot skills + 4.3 Bot configuration file +5. Bot commands & CVARS + 5.1 How to execute a command + 5.2 List of all server side commands + 5.3 List of all client side commands + 5.4 How to change a bot CVAR + 5.5 List of all bot CVARS + 5.6 List of all waypoint commands +6. Waypoints + 6.1 What are waypoints? + 6.2 When should I make my own waypoints? + 6.3 List of all waypoint commands + 6.4 How to use & Tips +7. Dedicated servers +8. Source code +9. Credits +10. Questions, suggestions, comments etc + + + + +1. FEATURES: + +See the file 'changelog.txt' in your cube/bot folder. + + + + +2. INSTALLATION & UNSTALLATION + + +2.1 Installing + +Extract all the files to your cube folder. +Don't worry it won't overwrite any cube specific files. + +Note: Since the file structure changed a bit, it might be handy to uninstall previous cube bot versions first. + +2.2 Uninstalling + +If you want for some reason uninstall the bots you have to delete these files: +- The bot folder, +- bin/cubebot.exe +- 'cube_bot_linux', +- 'cube_bot_fbsd', +- 'cube_bot_win.bat', +- 'cube_bot_linux-ded', +- 'cube_bot_fbsd-ded', +- 'cube_bot_win-ded.bat' +- This file + + + + +3. STARTING A GAME + +Run either cube_bot_win.bat (for windows users), cube_bot_fbsd(for FreeBSD users) or cube_bot_lin (for linux users). + +For linux/unix users: if you have problems with running cube, you might want to 'chmod it'. +Type this in a console in your cube directory: +chmod +x ./cube_bot_lin + +To add a bot you can simply open the main menu(esc) and open the bot menu, from there +you can add a bot in a team or change the default bot skill. +You can also use the addbot command(see section 6) to add a bot. + +Bots work for every singleplayer and multiplayer mode. In singleplayer they will help you to fight monsters and finish a level. +In multiplayer they try to kill you instead ;-) + +For dedicated servers see section 7. + + + +4. BOT SETTINGS + +4.1 Bot names and teams + +When you add a bot and don't specifiy a name, the bot will pick a name from the file +'bot_names.txt' in the folder cube/bot. This is a plain text file, you can modify existing names +and add up to 150 names. Note that names in cube can't contain more than 16 characters. +When you add a bot and don't specify his team, it will pick one from the file 'bot_teams.txt' +found in the cube/bot folder. This file can contain 20 different team names with a maximal +length of 5 characters. + +4.2 Bot skills + +There are 5 skills for the bots. The skill for a bot can be specified from the menu or via the console(see section 6). +Each skill can be modified by editing the file 'bot_skills.txt' found in the bot folder. +4.3 Bot configuration file + + +5. BOT COMMANDS + +5.1 How to execute a bot command + +There are 2 ways to execute a (bot)command: +- Hit the chat key(default t) and type / +- Hit the console key(default ~) and type the command. + + +5.2 List of all server side bot commands + +Server side commands(works if your the host, otherwise people have to vote for it): + +addbot +Adds a bot in the current game. Command arguments: + +: Specifies the team for the bot, when you leave it blank or + use "random" as team the bot will choose a team from the file + 'bot/bot_teams.txt'. +: The skill of the bot; can be best, good, medium, worse, bad, default or random. + When blank or "default" is used as skill, the bot will use skill good. When "random" is used, + the bot will use a random skill. +: The name for this bot. When blank the bot will pick a name from the + file 'bot/bot_names.txt' + +Examples: +To add a bot with a random team, default skill(good) and a random name: +addbot +To add a bot in team red, default skill with the name Joe: +addbot red default Joe + + +addnbot +Adds multiple bots to the game. Command arguments: + +: Number of bots to add. +: Specifies the team for the bots, when you leave it blank or + use "random" as team the bot will choose a team from the file + 'bot/bot_teams.txt'. +: The skill of the bot; can be best, good, medium, worse, bad, default or random. + When blank or "default" is used as skill, the bot will use skill good. When "random" is used, + the bot will use a random skill. + + +kickbot +Will kick the bot with the name from the server. + +Example: To kick bot Joe from the server: +kickbot Joe + + +kickallbots +Will kick all bots from the server + + +botskill +Will change the skill of the bot with the name to . + can be best, good, medium, worse or bad. + +Example: +To change the skill of the bot Joe to best: +botskill Joe best + + +botskillall +Will change the bot skill and the default skill to . + can be best, good, medium, worse or bad. + + +5.3 List of all client side commands(Works if you're a host or joined a server): + + +drawbeamtobots +Will draw some particles(same as the rifle) to all bots. This more used for +debugging to see where the bots are :-) + + +togglegrap +Will toggle the focus of the mouse in game. Normally you can use your mouse to look around, +when you type this command your mouse cursor is visible and can be used as normally. This is only +usefull when you run cube windowed ofcourse. + + +togglebotview +When used you will see what the bot with the name sees. Type it again +(with or without name) to return to the game(you will respawn). + + +5.4 How to change a bot cvar + +This works like bot commands: First open the console (with the chat key or the console key), +then just type the variabele name and put the desired value after it. + + +5.5 List of all bot CVARS (Server side variabels, host only) + +botsshoot 1|0 +Enables or disables bot shooting. 1 is enabled, 0 is disabled. Default is 1. + + +idlebots 1|0 +When enabled, all bots are idle(they won't 'think'). 1 is enabled, 0 is disabled. Default is 0. + + +maxbots 0-50 +Specifies how many bots can be in a game. Ranges from 0 to 50, default is 7. +Note that there cannot be more bots than maxclients-1(so atleast one human can be in the game). + + +allowaddbotvotes 1|0 +When enabled, clients are able to add bots through voting. 1 is enabled, 0 is disabled. Default is 1. + + +allowbotskillvotes 1|0 +When enabled, clients are able to change the bots skill through voting. 1 is enabled, 0 is disabled. +Default is 1. + + +allowkickbotvotes 1|0 +When enabled, clients are able to kick bots through voting. 1 is enabled, 0 is disabled. +Default is 1. + + +monstersperbot 1-25 +Specifies how with how much the total monster count should be increased in DMSP mode. This number also depends on the skill: + +nr of monsters = monster skill x monstersperbot cvar. + +So for example, if monstersperbot is 7(default) and the monster skill is 8, the total monster count will be 7x8=56. + + +monsterspawnmillis 1-2000 +Specifies the delay in milliseconds for when new monsters should be added in DMSP mode. The default is 1000(=1 second). +Decrease this value if you want a monster war :) You should use it with caution though, since many monsters at the same time will +be very CPU intensive. +Note: The formula for the number of new monsters per spawn is: 1 + 1/3 of the number of bots ingame. +So for example, if monsterspawnmillis is 1000 and there are 3 bots ingame, there will be +1 + 1 (1/3 of 3 = 1) = 2 monsters that will spawn every second. + + + + +6. WAYPOINTS + +6.1 What are waypoints? + +Waypoints are used by bots to help them navigate through a map. A waypoint +is simply a spot in a map, by connecting them with other waypoints bots know how to +move from waypoint to waypoint. Note that waypoints can be connected 1 way or 2 way, +if a waypoint is connected 1 way this means that waypoint A can be connected with B, but +B is NOT connected to A. +The waypoints are stored in the directory bot/waypoints in your cube directory. + +When waypoint viewing is enabled(see the 'wpvisible' command below) you can view all the waypoints +in the current map. Jump waypoints are red lines, the nearest normal waypoint +is a green line and all the others are blue lines. Connections between waypoints are +white lines. If a waypoint has a yaw(see the 'setwpyaw' command below) a short red line from the waypoint +in the direction taken from the yaw will be drawed. + +6.2 When should I make my own waypoints? + +If a map is loaded and no waypoints exist for this map, it will be flooded with waypoints(Automatically waypointed). +For most of the multiplayer maps this is enough(except complex maps like '32') but for SP(Single Player) maps +its better to make your own waypoints. This because these maps are generally more complex and there are one or more goals. + +However the following SP maps are already waypointed by me or can be played without custom made waypoints: +- cruel01 & cruel02 +- kksp1 +- nsp2 +- wsg1 & wsg2 & wsg3 +- mpsp4 + +6.3 Waypoint commands + +addwp +Adds a waypoint at the place where you are, all nearby waypoints will be connected with it. + + +delwp +Deletes the nearest waypoint. + + +wpsave +Saves the waypoints to a file. + + +wpload +Loads waypoints from a file, only handy when you want to undo your changes.(Waypoints will +be loaded automaticly when a map is started). + + +wpclear +Will clear all waypoints from the map. You usually want to use this to clear all automaticly generated +waypoints when you start making your own waypoints. + + +wpvisble 1|0 +When enabled(1) you can view all the waypoint in the current map, 0 will +disable this. (Waypoints will be automaticly visible when you use any +waypoint command). Jump waypoints are red lines, the nearest normal waypoint +is a green line and others are blue lines. Connections between waypoints are +white lines. + + +autowp 1|0 +Enables(1) or disables(0) autowaypointing. When enabled you will drop waypoints while +you walk around in the map. + + +wpinfo 1|0 +If enabled(1)(disabled=0) you can view info(such as waypoint property flags, trigger numbers, yaw etc) from +a nearby waypoint. + + +addtelewps +Adds waypoints on all teleporters and their destination in the current map and connects +the waypoints at a teleporter with the waypoint at its destination. + + +addtriggerwps +Adds waypoints at all triggers(such as carrots and switches) in the current map. + + +setwptriggernr +Assigns a number to the nearest waypoint. This is only used for trigger waypoints, so that the bots go to triggers in the +right order. If you don't do this bots will search for every trigger, even when they are not reachable yet. + + +setwpyaw +Sets the yaw of this waypoint. If a bot reaches a waypoint with a given yaw, it equalize his yaw with the one from +the waypoint. This is usefull for very narrow spaces or jump waypoints. +The yaw is taken from the yaw of the player. + + +addpath1way1 +Selects first waypoint to connect with another waypoint. + + +addpath1way2 +Will connect the waypoint you selected with the command 'addpath1way1' with the +nearest waypoint. + + +addpath2way1, addpath2way2 +Same as above, though it will connect both waypoints +with each other(that is there is a connection between the one +you select with 'addpath2way1' and the nearest waypoint AND there +is a connection between the nearest waypoint and the one you +selected with 'addpath1way1'). + + +delpath1way1, delpath1way2, delpath2way1, delpath2way2 +Same as above, but will remove connections between waypoints. + + +setjumpwp +Makes the nearest waypoint a "jump waypoint" this simply means that a bot will +jump when it reaches this waypoint(usefull when the bot has to jump over an obstacle +for example). + + +unsetjumpwp +Removes the jump flag from the nearest waypoint. + + +startflood +Starts flooding the map with waypoints. This is normally done when the game starts and no waypoints exist for the current map. + + +6.4 How to use & Tips + +6.4.1 Simple howto + +Lets say you want to make waypoints for map 'foo'. This map is a singleplayer map you found on Quadropolis(http://cube.snieb.com/). + +Here are some simple steps to waypoint the map: +- Start the game(see section 3) and load the map. Since its a singleplayer map it may be better to load it in + multiplayer mode, so you won't get killed during waypointing ;) +- Now since the map is automaticly waypointed, the best thing todo is to clear these waypoints first. + Simply type 'wpclear' in the console to remove them. +- Map foo has several teleporters, therefore its handy to put some waypoints on them and their destination. Luckely there is a + command which does that and will even connect the waypoint on the teleporter with the waypoint on the teleport-destination. + Simply type 'addtelewps' in the console to add them. +- Like most maps, foo has several triggers to open doors, unlock monsters etc. The command 'addtriggerwps' will put waypoints on all + the triggers for you. +- Now you can actually start waypointing. On simple, not complex places you can type 'autowp 1' so it will drop + waypoints (within a certain radius) where you walk and connect them(2 way) with each other. However on more complex places + (for example a place where you have to climb up) its better to place them manually with the command 'addwp'. +- After thats its a good thing to givbe the 'trigger waypoints' a number. Bots will go to the trigger with the + lowest number(except 0) first, then go to the next one and the next one etc etc. First type 'wpinfo 1' so you can see which + waypoints are trigger waypoints and which not. Now go to the trigger waypoint which should be triggered first and type + 'setwptriggernr 1'. Then go to the next trigger waypoint and type 'setwptriggernr 2' and continue like that untill you're done. + Note: If the order doesn't matter(very rare) you can skip this step. +- When you're done type 'wpsave' to save the waypoints, reload the map and add some bots to check if they can finish the map by + their selves :-) + +6.4.2 Waypoint tips + +- If you start with new waypoints, its mostly better to type 'wpclear' in the console to remove the waypoints which where automaticly + generated. If, however, you just want to make some minor modifications you can leave them. +- When you waypint a singleplayer map, its better to load the map in multiplayer mode so you the monsters won't annoy you. +- On narrow spaces its better to manually waypoint with 'addwp' and disable autowaypointing('autowp 0'). +- Always check if every waypoint is connected with the right waypoints. Waypoints can be connected with to + much waypoints or not connected at all. The following commands can be used to solve this: addpath1way1, addpath1way2, addpath2way1, + addpath2way2, delpath1way1, delpath1way2, delpath2way1 and delpath2way2. +- If a bot should jump somewhere you can set the jump flag with the command 'setjumpwp'. Its handy to set the direction to where + the bot should jump to with the command 'setwpyaw'. + + + + +7. DEDICATED SERVERS + +As of release 0.3 there is dedicated support! :) Though the standalone server binary is less light than the one +for cube. It also needs some additional directories/files: +- The bot folder +- The packages folder, however it only needs the map files so you can remove all the sounds and textures. +- Server script file + +If you want to configure bot cvars, add a few bots on startup etc. You should edit the bot.cfg file in the bot folder. +Explanation can be found in the file itself. + +You can start a server by executing on of the following scripts: +cube_bot_linux-ded (linux) +or +cube_bot_fbsd-server (FreeBSD) +or +cube_bot_win-ded.bat (Windows) + + + + +8. SOURCE CODE + +You can find the modified source in the "bot/bot_src" directory. Atleast 90% off all the changes are +marked by me with comments(mostly something like 'added by Rick'). + + + + +9. CREDITS + +Wouter van Oortmerssen aka Aardappel and all the other people +that made cube as what it is now(see the cube readme). + +Pierre-Marie Baty (PMB): for most of the current navigation code and other misc. code. +Check out his RACC bot for half-life at racc.bots-united.com + +Botman : 'The father of all half-life bots'. He created the HPB bot(hpb-bot.bots-united.com) which +is the base for almost all half-life bots. A lot of ideas are inspired by him. + +arghvark : Fix for ATI based gfx cards on linux. + +Internet Nightmare : Optimizing waypoint file reading/writing + +People at bots-united forums and cube forums: For feedback, suggestions, reporting bugs +and bot names :) + + + +10. Questions, suggestions, comments etc + +Feel free to send them to me :) (check top of file for contact info) +You can also visit the forums: http://forums.bots-united.com/forumdisplay.php?f=77