Ptahhotep's Team Balancer (PTB) Version 1.7 BETA DATE: June 28, 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.7 ----------------------- o This version adds another feature to PTB, which scales down the the internally counted player scores. If the sum of kills and deaths for a player exceed PTB_MAXINCIDENTS, the scores are divided by PTB_SCALEDOWN. This insures, that consecutive kills or deaths of a player have a higher influence on his kills/deaths ratio. A single kill of a player with a 500/300 score would mean nothing. The new system insures, that this score would be represented by an equivalent 25/15 or similar and every consecutive kill or death would influence the ratio noticibly. That way the rating of a player is representing the player's current performance way better in long games (read: dust-only over 7 hours ...). o There reported some problems with servers running for 18 hours or more. PTB started reporting stack overflows (amx error 3) at each kill. This version should resolve these problems, since the source of the error (AdminMod's native function playerinfo) is now either not used anymore or feeded very carefully. If that doesn't help, it's possible to get rid of the stack overflow problem with an increase of the stack frame (change the according line in the script to #pragma dynamic 262144 and recompile). 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 (default: 0) - rounds after which teams limiting begins admin_ptb limitmin (default: 0) - minimum players for team limiting admin_ptb maxsize (default: 10) - maximum team size per team admin_ptb autorounds (default: 3) - initial rounds without free team choice admin_ptb maxdiff (default: 2) - maximum accepted team size difference admin_ptb wtjauto (default: 2) - WTJ tries for auto-join admin_ptb wtjkick (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 (default: 0) - rounds after which switching begins admin_ptb switchmin (default: 3) - minimum players on map for switching admin_ptb switchfreq (default: 1) - maximum team switching frequency admin_ptb playerfreq (default: 3) - maximum player switching frequency admin_ptb forceswitch (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 (default: 2) - maximum accepted team win streak admin_ptb maxscore (default: 2) - maximum accepted team score difference admin_ptb minrating (default: 1.5) - stronger team, if rating >= minrating admin_ptb maxrating (default: 2.0) - way stronger team, if rating >= maxrating admin_ptb superrating (default: 3.0) - overwhelming team strength, if rating >= superrating admin_ptb maxincidents (default: 50) - maximum incidents per player before scale down admin_ptb scaledown (default: 2) - scale down factor for player incidents (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 PTB_MAXINCIDENTS 50 PTB_SCALEDOWN 2 Latest Changes -------------- Version 1.7 + NEW: added player rating scale down (PTB_MAXINCIDENTS and PTB_SCALEDOWN) + FIXED: calls to playerinfo now feeded carefully 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 ------------------ - use last xxx kills as k/d stats - cut down kills and deaths, preserving the ratio (150/50 => 15/5) - ban instead of kick - 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_) - check, if switch/transfer really happened (anti-cheat against block of "kill" commands) (PTB 1.5 introduces new switching code, it remains to be seen, if this makes other potential changes obsolete)