# MAXstats

### From Q4MAX

# General Information

Author: Hannes "panni" Tismer
Version: 1.0.3.1
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"

# 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.)

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
"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.3.1:
- fixed XML view error for teamgames
- probably fixed colorcodes with "+" or "-" for fading

MAXStats 1.0.3:
- 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:
- improved compatibility, output and errorhandling
- included single match-file view into SERVERside component
- first public release

MAXStats 1.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.