	Ptahhotep's Team Balancer (PTB)
	Version 1.6

	DATE: May 11, 2002
	FILE: plugin_logd_cs_ptb.sma
	AUTHOR: Ptahhotep (ptahhotep@planethalflife.com)
	CONTRIBUTIONS: 
	o NtroP started some new team switching code for PTB 1.5,
	  choosing the switch/transfer which balances team strengths best.
	TESTERS: all the great guys at http://www.concarne.org

	Thanks to all those who reported bugs and sent in suggestions!
	Special thanks go to Innocence from http://www.seth.dk, who maintains
	a small PTB FAQ.

	Comments On Version 1.6
	-----------------------
	o This version adds another 8 new configuration options to PTB.
	o Setting the new max team size setting to a number smaller than half
	  the number of maximum players on the server effectively forces the
	  remaining players into spectator mode.
	o I put some real work into the admin_ptb command. Please check out
	  the "admin_ptb" and "admin_ptb status" commands from the CS console.
	o PTB now limits the frequency of switches of individual players,
	  which should help getting rid of complaints about frequent switching.
	o PTB 1.6 uses the AdminMod playercount() function to determine
	  the current number of players in the game. The number returned by
	  that function is not always correct. Please keep that in mind when
	  using the new PTB_SWITCHMIN and PTB_LIMITMIN settings. You can
	  monitor the value returned by playerinfo() by typing admin_ptb in
	  the console. I also tried to track the number of connections and
	  disconnections, but that gives even worse results, since AdminMod
	  doesn't seem to generate either enough disconnect or more than
	  enough connect events.
	o The new commands "admin_ptb save" and "admin_ptb load" let you
	  save and restore changes in the settings made from the console.
	  That way you can experiment with the PTB settings in-game and
	  make them permanent without editing any files by hand.
	o The new PTB_SUPERRATING setting adds a new winning team condition,
	  that effectively limits the maximum allowed team strength for the
	  losing team. Before version 1.6 PTB allowed a team to be as strong
	  as it gets, as long as it didn't have either a winning streak or
	  a score advantage or both. See the Details section for details.
	o The new commands "admin_ptb list" and "admin_ptb help" both give
	  you a brief overview of available PTB commands.

	Comments On Version 1.5
	-----------------------
	This verion of PTB is tested with AdminMod 2.50.26a, Metamod 1.12
	and LogD 1.00.3 (Wraith's version ...).
	This version improves PTB in a lot of ways:
	o Most important is the new team switching code, which looks
	  for the best possible switch to execute. If there is no switch
	  that makes any difference in team balance, no switching happens.
	  Thanks go to NtroP for pushing me to finish his team
	  switching code for version 1.5 of PTB.
	o Also new is an improved team strength calculation method,
	  providing better indication of team strength. A detailed
	  description is given in the Details section.
	o Players will not be allowed to choose their team in the first
	  3 rounds, instead they will be auto-joined.
	o PTB will now try to keep the differences in team size below 3
	  when auto-joining players.
	o Forcing a switch (switching alive) is now configurable. You
	  can set the number of unsuccessful tries, after which PTB
	  does a switch of living players (killing them in the process).
	o Default settings for wtj auto-joining and kicking are much
	  more strict now. Try wtjing a second time and PTB will auto-
	  join you, try it a third time and you get kicked.
	o There is now an option to disable typesays completely.
	o All the things above are configurable through "vault.ini" -
	  another new feature of PTB 1.5.
	o Finally some bugs were fixed and some additional changes might
	  have happened that I forgot to note.
	See the latest changes notes below and the new section about
	vault.ini for more details.

	Introduction
	------------
	PTB is an Adminmod plugin (http://www.adminmod.org).
	LogD (http://logd.sourceforge.net) is required to run PTB.
	PTB is a Counter-Strike (CS) specific plugin.

	To run PTB with its default settings, simply compile it
	for your operating system, include it into plugin.ini
	and change the map on your CS server.

	PTB detects situations, in which one team rules over the other.
	It looks at the current team scores, current team win streaks
	and the current team ratings and decides on actions with the
	help of these values.
	
	Additionally PTB completely controls team joining actions of
	players and prevents unbalancing team joins. PTB auto-joins
	and even kicks obvious winning team joiners.

	Features
	--------
	o team strength evaluation based on scores, streaks, kills, deaths and size
	o search for best balancing switch or transfer
	o automatic dead only team switches
	o automatic dead only team transfers
	o announcement of team balance status
	o display of WTJ attempts
	o prevention, auto-join and kick for WTJing
	o "safe auto-join" - overriden auto-join function, that is always
	  choosing the right team and prevents joining of the same or
	  winning or bigger team, using auto-team never kills a player,
	  if he can't switch teams, and never gives WTJ counts
	o controllable with 33 console commands
	o configurable with 26 configuration options
	o configurable through vault.ini
	o much more ...

	Details
	-------
	The most important thing PTB evaluates is team strength. PTB calculates
	a single number as an indicator of team strength.

	In PTB 1.5 the team strength calculation changed. In earlier versions,
	team strength was calculated as the sum of total kills per team over the
	sum of total deaths per team times the number of players per team
	(strength = kills/deaths * players). The method didn't always work well,
	since a very good player (20:1) and a very bad player (1:20) made no
	difference to 2 mediocre players (5:5 and 6:6).
	
	The new method calculates a separate kills/deaths ratio per player, sums
	the ratios up per team and multiplies them with team size
	(strength = players * (sum of kills/deaths per player)).

	 Example:
	 CT team: A (6:5), B (2:3)
	 T team: C (1:1), D (4:3), E (1:4)
	 CT strength: 2 * (6/5 + 2/3) = 3.73
	 T strength: 3 * (1/1 + 4/3 + 1/4) = 7.75

	To compare the team strengths against each other, a rating is calculated
	per team by dividing the team's	strength by the opposing team's strength
	(rating = ownStrength / opposingStrength).

	 Example (continued):
	 CT rating: 3.73/7.75 = 0.48
	 T rating: 7.75/3.73 = 2.08

	Just in case you want to know: the old ratings would have been 0.88 for
	the CT team and 1.125 for the T team. Just imagine to add player F (0:10)
	to the CT team and look what happens to the old and new ratings. I found
	the new ratings to represent the teams much better.

	But team rating is not all. Even the best team might fail. That's why PTB
	doesn't limit itself to those kill/death ratios. PTB also compares the number
	of team wins and notes the number of consecutive rounds one by a team as
	additional indicators for team efficiency.
	
	To decide, if there if there is a winning team situation, PTB then evaluates
	the following equations:

	o team rating >= PTB_MINRATING (stronger team) and score > PTB_MAXDIFF
	o team rating >= PTB_MINRATING (stronger team) and streak > PTB_MAXSTREAK
	o team rating >= PTB_MINRATING (stronger team) and more players
	o team rating >= PTB_MAXRATING (way stronger team)
	o team rating >= PTB_SUPERRATING (overwhelming team strength)

	If any TWO of these criteria hold for one team, it is considered to
	be the winning team and actions are taken as appropriate.

	Note: Teams with a rating below PTB_MINRATING are considered as of equal
	or very similar strength. If team strengths are very similar, streaks
	and	scores are ignored. As soon as a team gets noticibly stronger
	than it's opposing team, scores, streaks and team size are checked.
	
	PTB balances the teams in one of two ways. If the losing team is smaller,
	PTB transfers a player from the winning to the losing team. Else two players
	are exchanged (switched) with each other. Valid targets for switches and
	transfers are dead players and players, who didn't change teams already
	this round. These limitations origin from the fact, that it's not possible
	to switch a living player with the help of console commands without killing
	him. Additionally CS currently does allow only one team change per round.
	Since PTB 1.5 all possible transfers or switches are evaluated for the
	switch or tranfer, that balances the teams the most. If no switch or transfer
	would improve team balance, switching or transfering is skipped.

	Configuration
	-------------
	PTB Required Variable Settings:
	allow_client_exec 1 - needed to switch players' teams
	admin_balance_teams 0 - switch other team balancing methods off
	mp_autoteambalance 0 - switch off inbuild CS team balancing
	mp_limitteams 10 - enable any team size difference

	PTB Commands:

	// misc
	admin_ptb - show PTB statistics (ACCESS_ALL)
	admin_ptb status - show all current settings (ACCESS_ALL)
	admin_ptb list - list of ptb commands (ACCESS_ALL)
	admin_ptb help - same as "list" (ACCESS_ALL)
	admin_ptb on - enable all options
	admin_ptb off - disable all options
	admin_ptb save - save all settings to vault.ini
	admin_ptb load - load all settings from vault.ini

	// team selection control
	admin_ptb limitjoin on|off (default: on) - team join control
	admin_ptb limitafter <value> (default: 0) - rounds after which teams limiting begins
	admin_ptb limitmin <value> (default: 0) - minimum players for team limiting
	admin_ptb maxsize <value> (default: 10) - maximum team size per team
	admin_ptb autorounds <value> (default: 3) - initial rounds without free team choice
	admin_ptb maxdiff <value> (default: 2) - maximum accepted team size difference
	admin_ptb wtjauto <value> (default: 2) - WTJ tries for auto-join
	admin_ptb wtjkick <value> (default: 3) - WTJ tries for kick
	admin_ptb kick on|off (default: on) - WTJ kicking
	admin_ptb savewtj on|off (default: off) - wtj.log writing

	// team balancing actions
	admin_ptb switch on|off (default: on) - team switching and transfers
	admin_ptb switchafter <value> (default: 0) - rounds after which switching begins
	admin_ptb switchmin <value> (default: 3) - minimum players on map for switching
	admin_ptb switchfreq <value> (default: 1) - maximum team switching frequency
	admin_ptb playerfreq <value> (default: 3) - maximum player switching frequency
	admin_ptb forceswitch <value> (default: 3) - forced switch delay (switching alive, if neccessary)
	admin_ptb deadonly on|off (default: on) - switch dead only or alive, too

	// messages
	admin_ptb tellwtj on|off (default: on) - tell about wtj tries
	admin_ptb announce on|off (default: on) - announcements
	admin_ptb sayok on|off (default: on) - "no action required" message
	admin_ptb typesay on|off (default: on) - globally switch use of typesay

	// team strength limits
	admin_ptb maxstreak <value> (default: 2) - maximum accepted team win streak
	admin_ptb maxscore <value> (default: 2) - maximum accepted team score difference
	admin_ptb minrating <value> (default: 1.5) - stronger team, if rating >= minrating
	admin_ptb maxrating <value> (default: 2.0) - way stronger team, if rating >= maxrating
	admin_ptb superrating <value> (default: 3.0) - overwhelming team strength, if rating >= superrating
	 (don't play with these, if you don't fully understand, what they mean)

	Configuration Using "vault.ini"
	-------------------------------
	PTB options can be set by manipulating the "option_..." variables at
	the top of the code, or by setting variables in AdminMod's vault.ini
	file. If you want to do the latter, these are the default settings
	as they should appear in the file (each option should stand at the
	beginning of a new line). Look at the comments besides the corresponding
	"options_..." code to find out what the options do. Atlernatively you can
	type "admin_ptb status" in the console of a running CS server to get some
	info on the settings.
	
	// team selection control
	PTB_LIMITJOIN    on
	PTB_LIMITAFTER   0
	PTB_LIMITMIN     0
	PTB_MAXSIZE      10
	PTB_MAXDIFF      2
	PTB_AUTOROUNDS   3
	PTB_WTJAUTO      2
	PTB WTJKICK      3
	PTB_KICK         on
	PTB_SAVEWTJ      off

	// team balancing actions
	PTB_SWITCH       on
	PTB_SWITCHAFTER  0
	PTB_SWITCHMIN    3
	PTB_SWITCHFREQ   1
	PTB_PLAYERFREQ   3
	PTB_FORCESWITCH  3
	PTB_DEADONLY     on

	// messages
	PTB_TELLWTJ      on
	PTB_ANNOUNCE     on
	PTB_SAYOK        on
	PTB_TYPESAY      on

	// team strength limits
	PTB_MAXSTREAK    2
	PTB_MAXSCORE     2
	PTB_MINRATING    1.5
	PTB_MAXRATING    2.0
	PTB_SUPERRATING  3.0

	Latest Changes
	--------------
	Version 1.6
	+ NEW: added new winning team condition (PTB_SUPERRATING)
	+ NEW: new console commands "admin_ptb list" and "admin_ptb help"
	+ NEW: new console command "admin_ptb save" saves settings to "vault.ini"
	+ NEW: new console command "admin_ptb load" loads settings from "vault.ini"
	+ NEW: grouped settings and added missing console commands
	+ NEW: rounds before team limiting setting (PTB_LIMITAFTER, default: 0)
	+ NEW: minimum players for team limiting setting (PTB_LIMITMIN, default: 0)
	+ NEW: maximum team size setting (PTB_MAXSIZE, default: 10)
	+ NEW: rounds before switching setting (PTB_SWITCHAFTER, default: 0)
	+ NEW: minimum players for switching setting (PTB_SWITCHMIN, default: 3)
	+ NEW: maximum switch frequency setting (PTB_SWITCHFREQ, default: 1)
	+ NEW: tell about WTJ tries setting (PTB_TELLWTJ, default: on)
	+ NEW: maximum player switch frequency setting (PTB_PLAYERFREQ, default: 3)
	+ CHANGED: replaced all option_ identifiers with their PTB_ counterparts
	+ CHANGED: further code cleaning
	+ FIXED: hopefully improved the "negative result on fdiv" workaround

	Version 1.5
	+ NEW: new team rating calculation method with much improved strength indication
	+ NEW: much improved team switching code, choosing best balancing switch/transfer
	  (thanks to NtroP for providing part of the code for this)
	+ NEW: reading configuration options from vault.ini (see section about vault.ini)
	+ NEW: option to globally disable typesay messages (PTB_TYPESAY, default: 1)
	+ NEW: wtj tries for autojoin setting (PTB_WTJAUTO, default: 2)
	+ NEW: wtj tries for kick setting (PTB_WTJKICK, default: 3)
	+ NEW: max team size difference setting (PTB_MAXDIFF, default: 2)
	+ NEW: auto join only in the first x rounds setting (PTB_AUTOROUNDS, default: 3)
	+ NEW: force switch after x unsuccessful tries setting (PTB_FORCESWITCH, default: 3)
	+ CHANGED: changed file name to plugin_logd_cs_ptb.sma
	+ CHANGED: added new documentation topics and updated the old ones
	+ REMOVED: removed option_maxrandom, as there is no random switching anymore
	+ FIXED: didn't catch all win conditions (e. g. Bomb_Defused was not counted)

	Version 1.4a (never published intermediate version)
	+ FIXED: Some semicolons missed, causing problems with AdminMod 2.50.26 (Metamod 1.12 version)

	Version 1.4
	+ FIXED: PTB didn't work the first time a player chooses a team
	+ NEW: PTB sets team strength to team size, if team has no single kill yet
	  (fix for team inbalance in the first rounds of a map)
	+ NEW: switching/transfering alive, if dead only is not possible repeatedly

	Version 1.3
	+ NEW: announcing team switch/transfer failures as typesay message
	+ NEW: added "sayok" option
	+ FIXED: completely reworked the options interface, which didn't work at all
	+ WORKAROUND: retrying calculation for negative results on division of 2 positive numbers
	+ REMOVED: command admin_ptb_stats no longer exists

	Version 1.2a
	+ FIXED: compile error with Adminmod 2.50.26 (plugin_connect syntax change in Adminmod?)

	Version 1.2
	+ NEW: display WTJ count
	+ NEW: kick for WTJ count 10 or greater
	+ NEW: force players into losing/smaller team for WTJ count > 3
	+ NEW: save player name and WONID in wtj.log for WTJ count > 3
	+ NEW: changed rating to incorporate team sizes
	+ NEW: added switch dead only mode
	+ NEW: added lots of configuration variables
	+ NEW: added team advantage announcements
	+ FIXED: trying to switch player that had already changed teams in the same round

	KNOWN BUGS
	----------
	- sometimes dividing 2 positive fixed numbers yields a negative number,
	  the chosen workaround might not always do it
	- playercount() doesn't always give the correct number
	- playerinfo() doesn't always give correct team

	SUGGESTIONS & TODO
	------------------
	- keep spectators out of PTB_LIMITMIN and PTB_SWITCHMIN
	- configurable colors
	- configurable/translatable text messages
	- modified ying-yang logo
	- invent map type factors (de_, cs_, as_)
	(PTB 1.5 introduces new switching code, it remains to be seen,
	if this makes other potential changes obsolete)
