MAXstats
From Q4MAX
General Information
Author: Hannes "panni" Tismer
Version: 1.0.4.0
Purpose: Client- and serverside match- and general statistics
Contact: #fac.vae, #Q4MAX, hannes@tismer.com
Thanks to alba for providing the neat basic-template!
Another big thank-you goes to SpOOnman for his XSL basis.
Download: Current version is included in your Q4MAX release.
MAXStats is the evolved symbiosis of the clientside q4mXSL and the serverside q4mXML (former q4maxXML).
It provides statistics and details about matches played by a clan or player - serverside (webserver) and clientside (localhost).
When index.html is opened, it detects how it was launched and boots up the corresponding statistics-view.
Generally the output of MAXStats on a webserver (with PHP >4.0.x) includes a way more detailed statistics-view as well as the features of the clientside version (detailed single-match stats).
If index.html is launched locally, the clientside view is enabled whereas on a webserver the serverside version will be viewed.
All features of q4mXSL and q4mXML have been collected and improved on a high level.
License Information
While MAXStats was designed for the usage of the Q4MAX-mod it is NOT to be used for any other mod or extension. Because of its modularity it can be extended and improved - all rights/licenses under GPL.
Configuration
DON'T USE ANY OTHER SYMBOLS THAN "/" OR QUOTES. NO QUOTES IN VARIABLE-DATA!
Base-config: "config_clientside.html" - CLIENTside
Information: The config_clientside.html holds the value for the relative path of your "Q4MAX_DIR/stats" folder. E.g. if MAXStats's config_clientside.html is located in "Q4MAX_DIR/MAXStats/configs" the folder value would have to be "../../stats".
Values: ../relative/path/to/stats/folder
Example (Default): ../../stats
Base-config: "config.ini" - SERVERside
Section [STATFOLDERS]
Information
A folder variable isn't fixed to any name. It must contain a relative or absolute path to the Q4MAX /stats folder. If the section has more than one folder specified the system will merge all stats found in those folders. Currently a folder variable can ONLY contain relative or absolute paths (even symlinks) of the same server. No external links are supported.
The given folders have to be in Q4MAX-stat-style, like "../q4max/stats", containing the following structure: /yearname/monthname/dayname/*.xml
Please make sure the folder variables don't end with a "/".
Values
folderX = "/path/to/q4max/stats/folder"
Example
folder1 = "../../q4max/stats"
folder2 = "/an/absolute/path"
wrong = "http://www.bla.org/my/folder" // This currently WON'T work!
Section [GENERAL]
Information
This section contains general settings for output and stat-generation.
Values
servername = "your server's name"
- Default: ""
Sets the servername which will be displayed on the stats-page.
---------------
reparse_stats = NUMERIC_VALUE
- Default: 120
This is the internal value for a full timestamp-based reparse of all collected stats, in seconds. It will reinclude all previously parsed information of the internal "parsed.ini", with looking for new, unprocessed XML files.
---------------
skip_awards = "award-name-list, seperated, by, commas"
Default: empty
This list contains award-names not to be shown/processed by the engine; mainly bug-based setting, normally not to be used. To-be-used award-names can be found by looking for the image-names in the "/img/awards" subfolder.
---------------
skip_weapons = "weapon-name-list, separated, by, commas"
Default: "Dark Matter Gun"
Look at "skip_awards" for information.
---------------
top_count = NUMERIC_VALUE
- Default: 10
This setting determines how many players and clans are to be shown in the "Top-XX-Players/Clans"-Section in MAXStats' generated output.
---------------
dump_stats = 0/1
- Default: 1
By setting dump_stats to 1 the system will dump all collected statistics into the internal "parsed.ini" which improves the script's loadtime by the factor of 10. This setting is defaulted to 1 and highly recommended.
---------------
snip_tags = NUMERIC_VALUE
- Default: 30
This variable contains the maximum-length for playernames and clantags. Names/tags having a bigger length than "snip_tags"
will get truncated.
---------------
tp_snip_tags = NUMERIC_VALUE
- Default: 15
This variable contains the maximum-length for playernames and clantags for the "Top-Players"-section in stat-output. Names/tags having a bigger length than "tp_snip_tags" will get truncated.
---------------
crop_servername = NUMERIC_VALUE
- Default: 90
The server-name set by "servername"-setting will be cut down to that value if its length is higher.
---------------
pdeterm_guid = 0/1
- Default: 1
This setting forces the system to assign a generated, nick-based GuID to every player without a valid GuID set (e.g. for players
without valid CDKey) - leaving it at "1" is suggested
---------------
tpdeterm_type = "overall_eff" | "player_eff" | "kills" | "deaths" | "dnet"
- Default: "dnet"
Set this setting to one of the options above - it directly affects the way of the "Top-Players"-ordering.
---------------
tcdeterm_type = "avg_playereff" | "kills" | "deaths"
- Default: "avg_playereff"
Set this setting to one of the options above - it directly affects the way of the "Top-Clans"-ordering.
Examples
- servername = "Fragstore - official #Q4MAX public server - www.fragstore.net"
- reparse_stats = 120
- skip_awards = "holy_shit, impressive"
- skip_weapons = "Dark Matter Gun, Railgun"
- top_count = 10
- dump_stats = 1
- snip_tags = 30
- tp_snip_tags = 15
- crop_servername = 90
- pdeterm_guid = 1
- tpdeterm_type = "dnet"
- tcdeterm_type = "avg_playereff"
Section [FILTERS]
Information:
This section defines the filtering for different attributes not to be shown or to be skipped constantly, in a "lazy" style. Values to be skipped have to be separated by |||. The skiplist uses a lazy search mechanism, so for example skipping a playername like "booboo" would skip player "666BooBOO", too.
Values:
ignoredplayernames = "keel|||sorlag" - Default: "keel|||sorlag" Which playernames to skip when parsing XML data.
ignoredweapons = "Dark Matter Gun|||Gauntlet" - Default: "Dark Matter Gun|||Gauntlet" Which weapons to skip when parsing XML data.
ignoredawards = "impressive" - Default: "" Which awards to skip when parsing XML data.
Usage / Installation
CLIENTside
For MAXStats on clientside you just need to edit "configs/config_clientside.html" and fill in the relative path to your /stats folder. After launching up MAXStats_root/index.html then, the clientside view should pop-up.
NOTICE: Currently only Firefox and IE >5 are supported in clientside-view!
SERVERside
All files included in MAXStats' package are to be placed inside a folder accessible by HTTP. After configuring the system (have a look at the config-section) please make sure that "import/parsed.ini" is available and chmodded "777".
With having set-up the system like described above you should be able to immediately access "http://your.server.or.ip/MAXStatsfolder/" or alternatively "http://your.server.or.ip/MAXStatsfolder/index.html".
The whole script can work as a standalone OR included version. It uses an own session-infiltrating technique to work with clanpage-CMS's.
Basic Page (no parameters given)
"Top X Players | Top X Clans | All " ?detail=X / ?clandetail=X / ?showall
- Switchable list of players/clans, ordered descending by player-efficiency or average- player-efficiency. By clicking
the non-active option the list will be refreshed to clan or player-view. Clan and nicknames are clickable for further
information and stats.
- If "showall" parameter given (link "All") or "Expand ..." , "top_count" config setting will be ignored and all collected entries will be shown.
"Force reparse of all data" ?reparse
Reparses a previously dumped "parsed.ini" file containing detailed stats about players and/or clans. This option is triggered automatically and periodically by the system. Its update-interval is determined by the config-setting eparse_stats". If newer undumped XML stat-files are available in given stat-folders they will be collected and added to previously collected data of "parsed.ini".
"Kill all dumped stats" ?killall
Removes the previously created "parsed.ini" and regathers all available XML files. This option should only be used when experiencing a bug or when the stat-folder setting has been changed. This option may consume a very high loadtime depending on the XML-filecount in specified stat-folders.
"Debug-mode" ?debug
Forces a "killall" and displays detailed debug-information if anything went wrong (e.g. information about rights-based errors when trying to read out of jailed webfolders etc.)
"DumpDebug-mode" ?dumpdebug
Doesn't force a "killall" over the dumped stats as ?debug does, but displays PHP errors, notices and warnings, too.
To prevent a high HDD-overhead and/or CPU-load, don't make this option clickable for public.
Player-Information (?detail=X)
Basic Information
"Name" - holding the player's nickname
"Clan" - holding the player's last used clantag
"GuID" - quake4-internal stat-guid, set by quake4 itself - used for identifying users on the server
"Kills" - summarized kills
"Deaths" - summarized deaths
"Suicides" - summarized suicides
"Thaws" - summarized thaws of freezetag games
"Score" - quake4-internal score value (should be kills - suicides - teamkills)
"Damage given" - summarized damage given to enemies
"Damage recieved" - summarized damage taken by enemies (should include teamdamage)
"DNET" - "Damage Netto": Damage given value substracted by Damage recieved
"Best weapon" - weapon with the best average accuracy
"Most played map" - map which was played most often by the player
"Best map" - map with highest average efficiency of player
"Awards earned" - count of all ingame and endgame-awards earned by the player
"Player efficiency" - efficiency value determined by overall kill/death stats
"Overall efficiency" - player efficiency together with average weapon accuracy
"Nick History" - history of all alternative nicks used by the player
"Clantag History" - history of all previously used alternative clantags
"Internal plID" - hash of GuID, internal value
Weapon Information
Detailed information about every previously used weapon, including kills, hits and accuracy.
Awards Information
List of all ingame and endgame awards earned, together with the count.
Map Information
List of all maps played by the player, including a play-counter, score, deaths and a per-map-efficiency value.
Clan-Information (?clandetail=X)
Basic Information
"Name" - holding the clanname
"Members" - count of all recorded members of the clan
"Team stats" - show recorded win/loss-summary of all played team-matches
"Kills" - all kills of all recorded clan-members
"Deaths" - all deaths of all recorded clan-members
"Suicides" - all suicides of all recorded clan-members
"Damage given" - summarized damage-given value of all clan-members
"Damage recieved" - summarized damage-taken value of all clan-members
"Best weapon" - clan-averaged weapon with highest per-player accuracy
"Best map" - clan-averaged map with highest per-player efficiency
Player Information
List of all clanmembers with basic information like best weapon, overall and kill/death efficiency, kills and deaths.
Footer-Details
The footer of a MAXStats-page contains detailed information about the script's recent behaviour:
"Script loaded in 0.xxxxxs, dumped, realtime using MAXStats 0.x.x XX" - This information show us the basic loadtime of the script, along with the word "dumped", which means that the data shown has not been taken out of the user's session-space but was "realtime" parsed out of "parsed.ini". If there have been any changes to the stat-folder's data (e.g. new XML files found or new date-folders created) this phrase also implements, that new data may have been parsed out of new XML files. -> second fast load-behaviour
"Script loaded in 0.0xxxxs, dump cached, reparsing in xxxs using MAXStats 0.x.x XX " - This phrase gives us the info that no locally-saved file has been processed - all data has been taken out of the user's session-space. "Reparsing in xxxs" holds the value in seconds for the time the next reparse of "parsed.ini" will occur, as well as a filesystem-check will be done to gather new XML files. -> fastest load-behaviour
"Script loaded in x.xxxxxs, realtime, for xx XML files using MAXStats 0.x.x XX" - As you can see this phrase doesn't contain "dump" anywhere but "realtime" as well as a XML-filecount. This ONLY happens after a "?killall" has been processed - e.g. if the user clicks on "Kill all dumped stats". The system has deleted "parsed.ini" completely and regathered all stat-information out of all existing XML-files. -> slowest load-behaviour, with a XML-filecount over 250 it may take a while to compute the stats
Efficiency and Accuracy calculations described
The player-efficiency is being calculated like it was in Q3OSP's scoreboard. It provides an efficiency-percentage which has a max-value of 100%. The following formula is used for it: (playerkills * 100 / (playerkills + playerdeaths)). Weapon-accuracy is being calculated with (hits * 100 / shots), the very basic percentage-formula. The overall-efficiency is the average percentage of player-efficiency and the average weapon-accuracy: ((player-efficiency + avg-weapon-accuracy) / 2)
Performance
CLIENTside
MAXStats' CLIENTside mode's performance depends on the browser you are using and the speed of your HDD. Because the /stats folder has to be indexed on boot-up of MAXStats, it may take some time to index all match-files contained in /stats, depending on how many files you have got in there.
SERVERside
MAXStats' SERVERside mode uses three different types of content-handling. The fastest one uses data stored in the user's session-space for the page-output. This mode is the fastest of all three. The second fastest mode is the dumper- mode which doesn't use the user's session-space at all, but information out of "parsed.ini", containing previously dumped data. If new XML files found, that are unprocessed in "parsed.ini" it will gather all new informations and merge them up with the dumped ones. The slowest mode is a debug-one. It's forked by the parameter "?killall", which deletes the "parsed.ini" and reparses all information inside all configured stat-folders. This can take up a hell of loadtime and should only be used and being made available to admins.
The basic data-lifecycle is:
- page request
1. collect data out of XML files
2. summarize and average information about players and clans
3. dump collected data into "parsed.ini"
4. temporarily store collected data into user's session-space for page-browsing, until next reparse is done
- next page request (without reparse)
1. output data carried by user's session-space
- next page request (with reparse)
1. get summarized data out of "parsed.ini", as well as XML-dump-stat informations
2. search for new XML files based on [PREVPARSED]-section in "parsed.ini"
(3.) if needed, parse collected XML files into local class-instances
(4.) if new data has been collected, resave "parsed.ini"
5. temporarily store collected data into user's session-space for page-browsing, until next reparse is done
Basically the dumper function for "parsed.ini" only is 4 times slower than the internal cached session-space, but more than 20 times faster than realtime-parsing of all XML files.
A realtime-parse of thirty found XML files takes about 0,25seconds on a 2,4ghz Pentium 4 Prescott with 1024MB of RAM. A dumped-parse using "parsed.ini" takes about 0,0208seconds for the dumped data of thirty XML files inside. The fastest mode which is mainly used when browsing MAXStats only takes about 0,005seconds for a session-dump with high award-, weapon- and map-count.
Without the need of any database-engines MAXStats is one of the fastest stat-parsers available.
Templating
Additionally the whole MAXStats SERVERside output can be customized by editing the template-files located in the "/template"-directory. "index.tpl" holds the basic layout of the page-output; all files ending with "basic" are static pages with basic information for the requested section (e.g. "clan_details_basic.tpl" holds the basic layout for the "?clandetail=X" parameter). All files ending with "repeat" are files containing sub-HTML table-structures for repeated, dynamic output like "Weapon Information" of the parameter "?detail=X".
Every important HTML tag has been shipped with a class-name, defined in "index.css".
The MAXStats CLIENTside output can be customized by editing styl.xsl and styl.css (in /stats/basics folder).
Bugs
Currently known bugs using an appropriate configuration:
- gauntlet stats don't get counted, sv_logXMLstats issue
- on SERVERside view we had some issues with Firefox 1.5.0.1 crashing randomly on selecting a match-file for XSL view
- Opera browser doesn't support optical javascript helper functions -> nick/clan colorcodes/qcodes won't be stripped
Bug-Reports go to panni (#fac.vae, #q4max, hannes@tismer.com)
Upcoming
Planned changes/updates for upcoming versions:
- IRC-Bot for live-stats
- support for distant www-stat folders not on the same machine as the system is
Changelog
Changes made:
MAXStats 1.0.4.0
- fixed compatibility problems with current CPMA and Q4MAX XML data structures; old XML format should still be supported but is deprecated
- added "FILTERING" section to config for lazily skipping awards, players or weaponnames
- fixed big reparsing bug of "DNET" and "Thaws" of dumped data
- fixed some internals
- removed unecessary datetime javascript filtering for xsl
MAXStats 1.0.3.2
- added Freezetag statistics support ("thaws")
MAXStats 1.0.3.1
- fixed XML view error for teamgames
- probably fixed colorcodes with "+" or "-" for fading
MAXStats 1.0.3.0
- comprehensive player/clan-search function added
- damagegiven/damagetaken -> DNET for SERVERside (currently only on CLIENTside or matchview)
- added "DNET" as topplayers ordering-option (now default: dnet)
- Opera 9 support for CLIENT and SERVERside
- optimized XML output
- optimized SERVERside output
- optimized javascript helper functions
- fixed some award pictures
- fixed general parser bug, improved performance
- added filter for empty colorcode-filtered or HTML-tag looking values
- added expand/contract link to top-players/clans (equals "all")
- improved color/qcode filter for names/clans
MAXStats 1.0.2.0
- improved compatibility, output and errorhandling
- included single match-file view into SERVERside componen
- first public release
MAXStats 1.0.0.0
- redesigned folders for higher simplicity and supermerged q4mXSL and q4mXML into MAXStats
Suggestions
Suggestions and tips are very appreciated and welcome. The easiest way to make suggestions for further releases available for the developers is to message panni on quakenet, #q4max, E-Mail him to hannes@tismer.com or go to the forums.
