
									J A C K   B O T   f o r   K i n g p i n
									       "You're Gonna Need a Bigger Bot"

	'' INTRODUCTION ''

	JackBot is built on the Quake II ACE Bot version 1.0 by Steve Yeager code base; but it's not "yet another fork of ACE": only the spawning and server updating functions remain intact, almost everything else has been rewritten or scrapped entirely. The goal is to provide heavily customizable bots with smoother, more believable reactions.

	These bots have a set of skills and behaviors that can be completely modified via simple text files: they have weapon preferences, different reaction time, different line of sight, different goals, different combat skills and spatial awareness... also, they do not cheat and won't start shooting in your direction as soon as you invade their personal space: they need to SEE you (setting them on fire affects their ability to see).

	They will do their best to keep the appropriate distance when using weapons; they will rush you down if they only have a melee weapon left, will back off to a reasonable distance if they are using a rocket launcher, will switch to a safer weapon when they're cornered, reload their guns when they are not in combat... They have their own prefered weapons too: how interested they are in certain pickups and what weapon they are more likely to use depending on the situation directly depends on their weapon preferences and how much ammo they have for it.

	They jump and crouch when necessary, they can also climb ladders, ride elevators and use teleporters.

	IMPORANT: THIS IS A SUPER DIRTY RELEASE. I HAVEN'T BEEN WORKING ON THIS PROJECT FOR THE PAST FOUR MONTHS AND LAST TIME I CHECKED, I THINK I BROKE THE ELEVATOR WAITING CODE AND ANOTHER DIRTY BUG APPEARED BECAUSE OF USER-ENFORCED NODE LINKING. IF I EVER REWRITE THE CODE AS I INTEND AND FUTURE .WAY FILES BECOME INCOMPATIBLE WITH THIS VERSION'S, I WILL PROVIDE A CONVERSION TOOL.


	'' I WANT TO PLAY ''
	Make sure the mod directory is called "jackbots". You can start a game by using one of the "go_x.bat" files located in the "jackbots" directory. "!RUN_X.BAT" files are shorthands for setting up a game, running them won't load any map.


	'' LIST FILES ''

	Bots are populating maps automatically according to a list, a simple text file with the ".lst" extension. The list is located in "maps/". Each line starts with the game mode, followed by the name of the bot to load on map start. Use "BOT_DEATHMATCH" for deathmatch games and "BOT_TEAM1" or "BOT_TEAM2" for team-based games. Note that a same file can contain both BOT_DEATHMATCH and BOT_TEAM# (the proper bots will be loaded according to the server's game mode). Spacing, tabs and double-dash comments can be used to format the text.


	'' SCRIPT FILES ''

	Script files are located in "bots/", they are simple text files with the ".bot" extension. This is where each bot obtains its own characteristics, skills, and preferences. Spacing, tabs and double-dash comments can be used to shape the script. Here's a list of the attributes, their effect and the expected values.

	CHARACTERISTICS
		This set of attributes defines how the bot looks and their line of sight.

		BOT_NAME <name>
			Name of the bot, as displayed in-game; This may or may not be the same name as the bot file. The same bot cannot appear twice in the same server.
		BOT_MODEL_SKIN <skin>
			Standard Kingpin skin string: <gender>_<model>/<head> <torso> <legs>; for instance, it could be: male_thug/009 019 017
		BOT_MODEL_SKIN_TEAM1 <skin>
			Skin for team-based games (used when bot is in team 1 - Dragons): <gender>_<model>/<head> <torso> <legs>. The torso and legs should be, for female: 057 031, for runt: 055 032, for thug: 056 032.
		BOT_MODEL_SKIN_TEAM2 <skin>
			Skin for team-based games (used when bot is in team 2 - Nikki's Boyz): <gender>_<model>/<head> <torso> <legs>. The torso and legs should be, for female: 031 032, for runt: 031 030, for thug: 035 030.
		BOT_MODEL_EXTRA <integer>
			Sub-model value for extra bits like cigar and hats. This value depends on the model.
		BOT_FIELD_OF_VIEW <integer>
			How wide the view cone is for this bot.
		BOT_VIEW_DISTANCE <integer>
			How far the bot can see.
		BOT_HANDEDNESS <hand>
			Defines if the bot is left-handed, right-handed or center-handed; Use "left", "right" or "center".

	SKILLS
		SKILL_DODGE <percent>
			How good at dodging things the bot is, also impacts their perception of other's "danger cone" (how close they are from the crosshair).
		SKILL_JUMPER <percent>
			How addicted to bunny-jumping the bot is. A value of 100 will turn it into a kid with too much sugar in the blood stream, 0 will make them stick to the floor (unless, of course, a jump is required for navigation). This attribute is affected by SKILL_DODGE.
		SKILL_CROUCHER <percent>
			How likely the bot is to crouch to avoid attack. This attribute is affected by SKILL_DODGE.
		SKILL_JITTERY <percent>
			How jerky bot movements are. A value of 100 will make them behave pretty much like kids overdosing on sugar, a value of 0 makes their movements much smoother.
		SKILL_ACCURACY <percent>
			How accurately the bot can aim. A value of 100 will make the bot a sharpshooter, a value of 0 will turn them into bumbling blind puppies... with a gun.
		SKILL_RELOADER <percent>
			How likely bots are to reload their guns out of combat.
		SKILL_NAVIGATION <percent>
			How good the bot is at moving around, how well they "know" the map, etc. A value of 0 turns them into clueless kittens, a value of 100 makes them very efficient at moving around.
		SKILL_SPATIAL_AWARENESS <percent>
			How good the bot is at estimating distances when dodging and moving in combat.
		SKILL_SELF_PRESERVATION <percent>
			How much the bot craves for health and armor, how confident they are in trespassing danger zones (get in range of other's weapon), and how likely it is for them to flee a fight when damaged. A value of 0 will turn them into berzerk kamikaze ready to get deep-fried by your flamethrower, a value of 100 will make them cower in fear, would they even eat a knuckle sandwich.
		SKILL_REACTION_TIME <float>
			How long (in seconds) the bot takes to react to damage, dodge rockets, notice someone in its line of sight, etc.

	WEAPON PREFERENCES
		This set of attributes defines how much the bot likes a specific weapon. A value between 0 (don't like it, don't want it) to 100 (absolute favorite, must have) is expected. Those values impact how much a bot wants a specific weapon pickup, how much they crave ammunition for that weapon, and how likely they are to use this specific weapon if it suits the situation (note that even if the bot REALLY loves the rocket launcher, it will not use it in close-range combat). When the weapon is already owned, they are processed like ammunition.

		W_PIPE <percent>
		W_CROWBAR <percent>
		W_PISTOL <percent>
		W_SHOTGUN <percent>
		W_TOMMYGUN <percent>
		W_HMG <percent>
		W_GRENADELAUNCHER <percent>
		W_ROCKETLAUNCHER <percent>
		W_FLAMETHROWER <percent>

	DEBUG SPECIAL
		For script and route testing only, should always be set to 0.

		AI_HOLSTER <0|1>
			Force bot to holster weapons (never seek enemies, never shoot). Note: if sv_cheats is enabled, you may use the "notarget" command to make yourself invisible from bots (useful to observe their behavior when playing together).

		AI_SLAVE <0|1>
			Prevent bot from roaming and looking for items. They will still move if ellicited (noticing someone).

		AI_NOREACTION <0|1>
			Completely braindead, will not react to anything.

		AI_THINK <0|1>
			Prints in console what this bot is thinking about, also displays the path it is currently following.


	'' NAVIGATION FILES ''

	Loaded automatically on map load. These files are located in "maps/". You can find the format specifications in the joined document.


	'' CONSOLE COMMANDS ''

	== BOTS
	SV BotSpawn <name> <team>
		Add bot <name> to the game, <name> is a .bot file located in "bots/". If <team> is specified (either 1 or 2), the bot will join the team.

	SV BotRemove <name|"all">
		Remove bot <name> from the game.

	SV BotKill <name|"all">
		Kill bot <name>.

	SV BotGive <name|"all"> <what>
		Refill <name>'s inventory with all sorts of goodies, works like the "give" cheat code.

	SV BotScript <name|"all"> <attribute> <value>
		Change, for bot <name>, the specified <attribute> to <value>. If <value> is unspecified, the current value of <attribute> is returned instead. If <attribute> is unspecified, the whole set of attributes and their value is displayed. Refer to "SCRIPT FILES" for the list of attribute and their expected values.

	SV SaveBotScript <name|"all">
		Save bot script for <name>.

	SV SaveBotList
		Save bot list for current map. Important: the list will depend on the current game mode, if the original file contained information for team-based games and free-for-all, some information will be lost.

	SV BotGoal <name|"all"> <node>
		Forces bot <name> to go to node number <node>, regardless of its current objectives. Super useful for path debuging, especially with AI_THINK and AI_SLAVE enabled.

	SV BotFind <name>
		Teleport to bot <name>.


	== NODES
	SV SaveNodes
		Create node network, solve paths and save nodes for current map.

	SV NodeItem
		Create and associate a node for every item or special entity that has none.

	NodeFind <index>
		Teleport to node <index>. Very useful to debug paths.

	LinkAdd <source> <target> <mode>
		Create a link between two nodes, overrides the automatic linking process. Source and target are valid node numbers. If the two specified nodes are already linked, the link is updated (useful to change mode). Mode is "walk" (default if mode is omitted), "jump" or "duck". This command is very useful if the automated process cannot link two nodes together because there's a door standing in-between, or if you want to force the connection between two nodes that are too far apart.

	NodeAdd <type>
		Create a node at current location, type can be: ndMove, ndLadder, ndItem, ndTeleport, ndPlatform, ndJump. If <type> is omitted, the best type of node is used.

	NodeRemove <index>
		Remove the specified node. If <index> is omitted, the closest node is removed. <index> also supports "all".

	SV EditRoute
		Route creation. This displays nodes, provides link information, etc.; this switch needs to be ON to create routes and manipulate nodes.

	SV PathSolve
		Create node network (direct connection of nodes) and solve paths (connections by proxy).

	PathShow <from> <to>
	PathShow <to>
		Show the complete path from node <from> to node <to>, or from the closest node to node <to>. A value out of boundaries (below 0 or higher than the number of nodes) disables the line display.

	NodeArea
		Use this command once to start drawing a rectangle on the floor, use it again to fill the area with nodes.


	== DEBUG
	SV DebugLog
		Save bot debug messages in botlog.txt


	'' CONSOLE VARIABLES ''

	ROUTE EDITION MODE
		The following cvars and commands have no effect outside route edition mode.

		Dummy node display:
			bot_nodeviewdist (cvar/default: 320)
				Nodes within this range are perfectly visible. If you get the infamous "sz_getspace: overflow" error, try a smaller value.

			bot_nodeviewfade (cvar/default: 192)
				Distance before nodes vanish completely. This variable is meant to provide a smoother experience by preventing dummy nodes from suddenly popping in and out, it also hints when a node is about to dissapear from your sight. If you get the infamous "sz_getspace: overflow" error, try a smaller value.

			bot_nodeviewupdate (cvar/default: 0.10)
				How often (in seconds) nodes are being updated. Dummy nodes rotation should give you a good idea of how often nodes are being updated. If you experience serious slow downs, increase this value.

			bot_nodeviewtest (cvar/default: 1)
				This parameter allows you to turn off optimizations for dummy node displays. By default, dummy nodes that are likely outside your line of sight are not displayed, this optimization may force nodes to pop in if you suddenly turn around. Turn the variable off if it's annoying to you.

			bot_nodeviewlinks (cvar/default: 1)
				Display all the connections for the closest node.

		Node edition:
			bot_nodetrail (cvar/default: 0)
				Enables the automatic node creation.

			bot_nodeshrink (cvar/default: 1)
				Allows different types of compression whenever appliable: 0 to disable compression completely, 1 to enable RLE-W (super fast, provide a solid compression), 2 to enable Word Repeat (slow, but super efficient), 3 to enable both RLE-W and WR (faster than WR alone, sometime produces files that are slightly larger or slightly smaller than WR alone). Null or negative-gain compressions are discarded; fully compressed files (using WR) are about 10% the size of uncompressed files.

			bot_nodesound  (cvar/default: 1)
				Enables sound when placing, deleting, and moving nodes.

			bot_nodeautosave (cvar/default: 60)
				How often (in seconds) the route file is automatically saved. Set to 0 to disable, values below 30 are set to 30. Autosaved roadmaps have a ".tmp" extension and are uncompressed.


	== SZ_GETSPACE: OVERFLOW
		Basically, this error appears when the engine was unable to stuff all the information needed within the reserved memory segment. Even when playing offline, the Quake engine sets up a local server to handle clients (ie. the player). Many packages of information are sent from the client to the server, so the server can process what's going on: network updates, demo recording, interactive entities, collisions, etc. This error will more often show up when too many objects are being drawn at once (internally, models are described as a set of OpenGL commands, which means very complex or poorly optimized models can rapidly fill the memory stack, resulting in "sz_getspace: overflow")

	'' SPECIAL THANKS ''

	Sylacs LOL        - For converting Kingpin's SDK to Visual C++ Express Edition 2008.
		Vertigo Team    - [Sylacs wanted to thank them, but I'm not sure what they were involved in].
		Greg            - For his Quake 2 Visual C 9 mod.
	Steve Yeager      - For programming (and sharing!) the ACE Quake II Bot Base Code.
		John Cricket    - For ideas and swapping code.
		Ryan Feltrin    - For ideas and swapping code.
		SABIN           - For showing how to do true client based movement.
		BotEpidemic     - For keeping us up to date.
		Telefragged.com - For giving ACE a home.
		Microsoft       - For giving us such a wonderful crash free OS.
		id              - Need I say more.
	MrDamage          - For managing the Kingpin forums, the mailing list and the Kingpin website for the past 20 years! (that's dedication)
	Hypov8            - For pointing out some of ACE "oddities", therefore confirming I was not taking crazy pills.
	Xatrix            - For Kingpin. Also for the well-commented source.


	'' DIFFERENCES FROM KRAZE/ACE ''
	- Routes are rebuilt automatically according to node's type and location
	- Since jumping and crouching are means to travel from point A to B, those actions are handled through connectivity instead of a special node type.
	- Each bot has its own favorite weapons and has its own set of skills and perception; they do not cheat.
	- Bots tend to manage their time better: they reload when they are not in combat, never commit suicide when they get stuck, revise their plan if the goal they seek is no longer available (for instance, they notice the item they wanted is missing).
	- Bots can be configured on-the-fly, and the new script can be saved again after modification.
	- The route edition mode features tons of visual aid and information to ease the placement of nodes and the debugging of routes.
	- Bots are properly jumping and using ladders, they are no longer carried by velocity hacks. Their movement and aiming are dissociated, making the much more mobile.
	- Autosave feature when working on routes.


	'' EXTRA FEATURES ''
	- Bots are automatically loaded along with the map (includes map change, and re-match of the same map).
	- Bots can be added or removed from the map, and the list can be saved again.
	- If no WAY file is found in "maps/", JackBot will attempt to load Kraze Bot's KPR files version 3 (they might need some tweaking and a clean route made from scratch will probably work better, but hey, you do you).
	- The WAY file format supports data compression.


	'' ISSUES ''
	- The code became a mess with the introduction of TeamPlay, will work on that.
	- The automated node linking system is having serious issues when entities are breaking links (for instance, a door located between two nodes will prevent these two nodes from being connected to each other).
	- The chat system is not flexible enough and looks dirty in bot files; will have to revise that.
	- Bots are unable to use rocket jumping.


	'' TROUBLESHOOTING ''
	Always make sure the game has been started properly. The following command line would cause issues (notice that the map is loaded before the deathmatch cvar is set):
	kingpin.exe +game bots +map %~n1 +deathmatch 1 +fraglimit 30 +timelimit 30 +set cheats 1 +set maxclients 8 +exec editnode.cfg
	This command line will produce the proper effect:
	kingpin.exe +game bots +deathmatch 1 +fraglimit 30 +timelimit 30 +set maxclients 8 +map %~n1 +exec editnode.cfg
	To start team deathmatch:
	kingpin.exe +game bots +deathmatch 1 +set teamplay 4 +fraglimit 30 +timelimit 30 +set maxclients 10 +map %~n1 +exec editnode.cfg
	To start a map in bagman:
	kingpin.exe +game bots +deathmatch 1 +set teamplay 1 +fraglimit 30 +timelimit 30 +set maxclients 10 +map %~n1 +exec editnode.cfg


	'' ACKNOWLEDGEMENT (STRAIGHT FROM ACEBOT SOURCE CODE) ''

	The ACE Bot is a product of Steve Yeager, and is available from the ACE Bot homepage, at http://www.axionfx.com/ace. This program is a modification of the ACE Bot, and is therefore in NO WAY supported by Steve Yeager. This program MUST NOT be sold in ANY form. If you have paid for this product, you should contact Steve Yeager immediately, via the ACE Bot homepage.

	Have fun.
	- AliasConradColdwood