XLRstats Plugin Documentation
About
XLRstats is a plugin for the B3 game bot, that will collect statistics of the people playing on your game server. Also, some server-wide statistics are kept.
Contents
Setup
Requirements
A fully installed and configured B3 bot, with associated requirements.
Install
Download the latest version of b3 here.
It comes with a pre-installed xlrstats!
Create the extra tables in the database also used by B3, using the 'xlrstats.sql' script that you can find here. (You will need command line access or direct access to your database with a tool like eg. phpMyAdmin)
Initial configuration
Copy the sample configuration file 'xlrstats.xml' to your configuration directory ('@b3/extplugins/conf/').
This configuration file is mostly empty, because the plugin will use default values in absence of explicitly configured values.
Edit your B3 configuration file ('conf/b3.xml') so that B3 will use the new plugin: In the 'plugins' section of this file, uncomment the line:
<plugin name="xlrstats" config="@b3/extplugins/conf/xlrstats.xml"></plugin>
(Note that the previous priority setting is no longer needed when using B3 1.3.2+)
Detailed configuration
Besides a detailed tallying of kills and deaths, XLRstats also calculates a skill score for players. Most of the configuration options are related to this skill calculation, so before the options are explained, first some more about the skill formula. You do only need to understand it if you wish to experiment with the associated configuration settings.
Skill score calculation
The skill score as calculated by XLRstats is based on the ELO rating system, commonly used for games like chess, go and Magic: The Gathering.
A central point in this system is that points gained or lost in a confrontation are not absolute, but depend on the skill of both adversaries. Or to be more precise, on their difference in skill.
First, the chance for both players for winning are determined. As in ELO, this is done using the Logistic function. The configuration option steepness influences this function because it corresponds to the variable tau from the Logistic function. It is a bit different from what you might expect though: a bigger steepness value makes the slope actually less steep. So a bigger steepness value means that even with a bigger difference in skill score, the winning chance for both players will be closer together.
Next, for each player the difference between the real outcome (kill/win or death/loss) and the winning chance is determined. For a kill this will be positive, while for a death this will be negative. Before adding or subtracting this single score from the player's skill, a multiplication factor is usually applied (or in the case of XLRstats, possibly more than one).
One target of the factor is to speed up reaching the skill a player should have. The bigger it is, the faster a player's skill score will converge to the value it should have. Too big, and there will be a lot of noise around a player's average skill score. For this reason, XLRstats uses 2 distinct values for this so-called K-factor. For relatively new players, Kfactor_high is used, ensuring the player's skill is adjusted very fast, starting from the skill score of defaultskill the player got assigned when first entering. After reaching a certain threshold number of kills (Kswitch_kills), a player will be judged using Kfactor_low.
Other, extra factors can take effect in XLRstats. Most notably, applying to both killer and target, is the weapon factor. Some weapons are more difficult to handle, and can therefore warrant an extra increase (and decrease) in skill.
The other is kill_bonus. Because some leakage of skill points occurs on suicides and teamkills, it is a good idea to inject a limited amount of points into the system. This is done in the form of an extra multiplication factor for the killer, as an extra bonus.
Events like teamkills and suicides are not evaluated using the bove system, but just subtract a percentage from your skill score.
Configuration options
[settings] Section
[settings]
<set name="minplayers">3</set>
<set name="suicide_penalty_percent">0.05</set>
<set name="tk_penalty_percent">0.1</set>
<set name="defaultskill">1000</set>
<set name="steepness">600</set>
<set name="Kfactor_high">16</set>
<set name="Kfactor_low">4</set>
<set name="Kswitch_kills">100</set>
<set name="prematch_maxtime">70</set>
<set name="minlevel">1</set>
<set name="onemaponly">False</set>
<set name="keep_history">False</set>
; minplayers: Minimum number of players required in the server for plugin to start collecting player stats.
; Default 3
; suicide_penalty_percent: Percentage that is subtracted from a player's skill on suicide.
; Default 0.05
; tk_penalty_percent: Percentage that is subtracted from a player's skill on teamkill
; Default 0.1
; defaultskill: The default skill score a player starts out with.
; Default 1000
; steepness: Steepness of the Logistical function.
; Default 600
; Kfactor_high: Initial multiplication factor for skill calculation
; Default 16
; Kfactor_low: Multiplication factor for skill calculation for more experienced players
; Default 4
; Kswitch_kills: Number of kills after which a player is switched to Kfactor_low
; Default 100
; kill_bonus: Extra multiplication factor for skill calculation, applies only to the killer.
; Default 1.2
; prematch_maxtime: The time of prematch duration on the server, plus a small safety margin. Needed to keep the rounds played in order.
; Default 70
; minlevel: Minimum user level a player needs to have his stats recorded. Good so the stats database doesn't become too big with one-time visitors. Default setting is everyone who cares enough to register with the bot.
; Default 1
; onemaponly: Used on servers that have one map 24/7. It changes the way maps/rounds are counted.
; Default False
The names for the tables used by the XLRstats plugin are configurable.
[tables] Section
[tables]
; playerstats: Player specific stats
; Default xlr_playerstats
; weaponstats: Weapons and their overall stats
; Default xlr_weaponstats
; bodyparts: Bodyparts (hitzones) and their overall stats
; Default xlr_bodyparts
; mapstats: Maps and their overall stats
; Default xlr_mapstats
; opponents: Player vs. player stats
; Default xlr_opponents
; weaponusage: How every player uses (or gets hit by) the various weapons
; Default xlr_weaponusage
; playerbody: The bodyparts every player hits or is hit at?
; Default xlr_playerbody
; playermaps: Player's achievements in the various maps
; Default xlr_playermaps
<settings name="tables">
<set name="playerstats">xlr_playerstats</set>
<set name="weaponstats">xlr_weaponstats</set>
<set name="bodyparts">xlr_bodyparts</set>
<set name="mapstats">xlr_mapstats</set>
<set name="opponents">xlr_opponents</set>
<set name="weaponusage">xlr_weaponusage</set>
<set name="playerbody">xlr_playerbody</set>
<set name="playermaps">xlr_playermaps</set>
</settings>
[weapons] Section
[weapons]
Here weapons modifiers are stored. Weapons modifiers are just like the K-factors, but usually close to 1. Bigger than 1 gives an extra bonus (for a difficult weapon), smaller than 1 makes a killer gain less points. (Smaller than 0 would not make sense). A few examples:
<settings name="weapons">
<set name="bar_mp">1.00</set>
<set name="bar_slow_mp">1.15</set>
<set name="bren_mp">1.10</set>
</settings>
Weapons not specified in this section automatically get a modifier of 1.00.
Usage
Viewing the stats will mainly be done from a web front-end. Example code for such a front-end can be found in our download section.
Command reference
These are the commands available from within the game
- !xlrstats
- Tells a player his basic stats (kills, deaths, teamkills, ratio, skill)
- !xlrhide
- Hides a player from the stats
- !xlrtopstats
- Shows top players in the stats
- To enable the commands, this section must exist in the config. If it doesn't exist, the commands will not work.
<settings name="commands">
<set name="xlrstats">1</set>
<set name="xlrtopstats">2</set>
<set name="xlrhide">60</set>
</settings>
FAQ
What is XLRstats?
XLRstats is a plugin for the B3 game bot that will collect statistics of the people playing on your game server. Also, some server-wide statistics are kept.
Why would I want to collect statistics?
Collection of in game statistics made available to users will create friendly competition between users and increase the general skill level of the player base. Ideal for clans who need to pick a starting line up, or communities looking to increase friendly competition.
What is the maximum number of skill points I can get?
There is no cap, you could have two thousand kills, no deaths and have a very large skill number. The reality of this is slim however, so it's best to just play to a realistic goal you can attain for yourself. Also, when your skill is high, you will only gain significant amounts of gain by killing other strong players.
What would be a realistic goal to set?
This is completely dependant upon your playing abilities. A 1.0 or better ratio is a good place to start, although it's not really related to skill. Play for 2 weeks with the stats on to see where you're at and make a decision from there. If you're at 1200 skill points, maybe think about reaching for 1250.
What can I do to get more skill points?
Since skill points are based on a kill to death ratio, the best thing to do is get more kills and die less. There are variables to the score to be taken into consideration as well, but the principal of fewer deaths more kills remains true. Killing better "skilled" players will also earn you more skill and conversly getting killed by better players will lose less skill.
What kind of variables changes my score?
Different weapons will change your modifier when you get a kill. Some weapons are more difficult to handle, and can therefore warrant an extra increase (or decrease) in skill; additionally how you use the weapon can come into play. Team kills and suicides are also taken into consideration, subtracting a percentage from your skill score; obviously you want to avoid these things.
Who you kill will also have an effect on your score; killing a new player vs. killing a seasoned player affects your score differently.
In the future, targeting may play a part as well - where you get hit, where you hit them, however hit statistics are not calculated per hit, only on a death. Headshots are of course hard to get and create a larger modifier.
What do I need to use XLRstats?
A fully installed and configured B3 bot, with associated requirements. See www.bigbrotherbot.com for an installation procedure. For all the plugin's files please see our download section.
Rate this page +1 at Google Search
BigBrotherBot
"Develop with pleasure"