OLStats
Version 3.01
August 29, 2004

by Greg "Overload" Laabs

Overload@planetunreal.com
http://www.apartment167.com

OLStats uses El Muerte's LibHTTP2 tool, created for Unreal Tournament 2004.
See the "LibHTTP2_License.txt" file for the LibHTTP2 License.
http://ut2004.elmuerte.com/LibHTTP2

OLStats includes a modified version of El Muerte's ServQuery from ServerExt
105a, which I call OLServQuery. The only difference is the added ability to
get the unique stat identifiers of all the players in the server.
OLServQuery is released under the Open Unreal License:
http://wiki.beyondunreal.com/wiki/OpenUnrealModLicense

The Local OLStats Database is 100% based on and designed to look like
UTStatsDB, a php/mysql program for parsing and displaying stats for
UT2004. If you have a php and mysql server, I strongly suggest giving it
a try:
http://ut2003stats.sourceforge.net

Except for the OLServQuery class, you may not use OLStats as a base for
creating other mods or mutators without my express written permission. In
the future I will probably release OLStats under an open license, but this
is the way it is for now.

PLEASE REPORT BUGS AND FEATURE REQUESTS!
If you have a feature request, or found a bug in OLStats, please tell me!
Please create an account at http://www.apartment167.com/mantis to report
such things. I implement almost every feature request I receive, so there's
a good chance that you'll see your feature if you request it!

I welcome general feedback! Please drop me a note in my forums if you find
OLStats useful. Positive feedback is what keeps me coding!
http://www.apartment167.com/modules.php?name=Forums&file=viewforum&f=20

*******
*ABOUT*
*******

OLStats has two major functions:

The first, called the "Local OLStats Database" is full HTML logging of all
matches. After every game, OLStats exports an HTML log file of the match
you just played, as well as updates an "index" HTML file that holds tons of
overall stats, like career stats for each player, "career highs" showing
which player has the record in many different categories, and so forth.
This function is best for people who only play instant action games or host
games for their friends at LAN parties or something. Server admins of
public servers will want to use the raw game log function.

You can see a sample of what the output from OLStats looks like here:
http://www.apartment167.com/overload/showcase/OLStats/Stats_7777_2004_09_23_23_02_02.html


The second (and original) function is a greatly improved version of the
local stat logging feature found in UT2004. It outputs raw game logs that
can be imported in to UTStatsDB to generate the most complete stats
available for UT2004. Improvements over the built in stat logging include:
 * Optional bot logging
 * Chat logging
 * Pickup logging
 * Accuracy logging
 * Ping logging
 * Many (some huge) bug fixes
 * Monster logging for Invasion games
 * Proper scoring for Invasion and mutant games

If you would like an example of what a website running UTStatsDB + OLStats
looks like, go here: http://www.apartment167.com/ut2004stats/

Running OLStats will not remove your server from the standard server list!

OLStats 3.00 fully supports the ECE Bonus Pack, but does not require it.

Note that OLStats will NOT interfere will global stat logging! You server
will still be able to upload global stats like normal.


**************
*INSTALLATION*
**************

Unzip OLStats30.zip to your Unreal Tournament 2004 directory. It will place
all the files in the appropriate directories.

Then refer to the section below depending on what type of game you will be
playing.


LISTEN SERVER AND INSTANT ACTION
--------------------------------

To enable stat logging for a listen server or instant action game, simply add
the OLStats mutator to your game when you start it. No other configuration is
needed. Note that the OLStats mutator will NOT work for a dedicated server.

To change the OLStats options, click on "Configure Mutators" on the mutators
page. You may want to disable "Export Raw Logs" if you only plan on using the
HTML logging part of OLStats.


DEDICATED SERVER
----------------

**NOTE** If you are not going to use the HTML logging feature, TURN IT OFF.
It causes a huge lag burst at the very end of every match while it is
generating all the HTML pages.

To enable OLStats, open your UT2004.ini file and change the following line

  GameStatsClass=IpDrv.MasterServerGameStats

to this

  GameStatsClass=OLStats.OLGameStats

When you start up your dedicated server, add ?GameStats=True to the command
line.

You can configure the OLStats options by refering to the "ADVANCED
CONFIGURATION" section below. If you are not going to be using the HTML
logging feature, BE SURE to turn it off in your OLStats.ini file.

Now fire up a dedicated server (rememeber to add ?GameStats=True to the
commandline.) Log files will be created in your Unreal Tournament 2004 UserLogs
directory.

IMPORTNAT NOTE: If you are running UT2Vote, you need to edit your UT2Vote ini
file because UT2Vote overrides the commandline variables. Find the variable
called "ServerLine" in your UT2Vote ini file, and make sure it has
"?Gamestats=true" in it.


***********************
*VIEWING THE HTML LOGS*
***********************

After at least one match has been logged with OLStats, you can view your stats
by opening up the "OLStatsIndex.html" file inside your UserLogs directory.
The UserLogs directory is located directly in your Unreal Tournament 2004
directory. If you want, you could make a shortcut to the OLStatsIndex.html, or
mark it as a favorite so that you can easily get to your stats. From the index
page you can get to every match logged.


*******************************************
*AUTOMATIC UTStatsDB UPLOADING AND PARSING*
*******************************************


OLStats now has the ability to automagically upload raw log files to your
UTStatsDB server, as well as run the parser each time a new match begins.

OLStats is distributed with a file called OLSendLog.php. You will need to place
this file in the UTStatsDB directory of your webserver. It is the script that
OLStats communicates with to upload the logs. You can find OLSendLog.php in your
UT2004/OLStats/Other/ directory.

To turn on and configure these features, you need to modify your OLStats.ini file.
These are the options related to automatic UTStatsDB uploading and parsing:

PARSING
-------
bRunUTStatsDBParser=[true|false]
ParserURL=http://myserver.com/logs.php
ParserPass=updatepass

New in v2.50
These options control the automatic UTStatsDB parsing feature of OLStats. If
bRunUTStatsDBParser is set to true, then the URL in ParserURL will be executed every
time a new match starts. Set it to the location of your logs.php file on your UTStatsDB
server. You need to set ParserPass to the password required to run the parser.
(UpdatePass in statsdb.inc.php)
Details about how many matches were parsed, and any possible errors are outputted in
to your server's .log file.

UPLOADING
---------
bUploadLogs=False
UploadURL=http://myserver.com/OLSendLog.php
UploadPass=adminpass

New in v2.50
These options control the automatic UTStatsDB uploading feature of OLStats. If
bUploadLogs is set to true, then the raw logfile for the match will be uploaded to the
location given in UploadURL. Set it to the location of the OLSendLog.php file on your
UTStatsDB server. You need to set UploadPass to the ADMIN password of your UTStatsDB
installation. (AdminPass in statsdb.inc.php)


*******************
*USING OLSERVQUERY*
*******************

OLStats comes with OLServQuery, a modified version of El Muerte's ServQuery.
If you would like to be able to get the unique stat identifiers of the players in your
server through a server query (which would allow the front page of UTStatsDB to
directly link to each player's career page) then you'll need to configure it as follows:

In UT2004.ini, add OLStats.OLSQMSUplink to your list of Server Actors:
[Engine.GameEngine]
ServerActors=OLStats.OLSQMSUplink

Be sure to REMOVE IpDrv.MasterServerUplink and ServerExt.SQMSUplink if they exist.


OLServQuery can be configured by adding this to your server's ini file:

[OLStats.OLServQuery]
bVerbose=false
sReplyTo="TASGMEBHO"
ePType=PT_None
iTimeframe=60
iMaxQueryPerFrame=180
iMaxQueryPerHostPerFrame=10
sPassword=

For a description of the different config values, see the ServQuery readme:
http://ut2004.elmuerte.com/ServerExt#servquery

The only addition in OLServQuery is in the sReplyTo variable:
    O	\olstatsids\

Which allows the following query:
\olstatsids\
Returns the players' unique stat identifiers
Reply for each player: \psidname_<id>\<player name>\pstatsid_<id>\<player stats id>


************************
*ADVANCED CONFIGURATION*
************************
There are several options you can configure by modifying your OLStats.ini file.
Note that almost all of these options only affect the raw stat logging part of
OLStats, so people just using the HTML logging do not need to worry about this
section.

        [OLStats.MutOLGameStats]
        bExportRawLog=true
        bExportHTMLLogs=true
        KeepBotRecords=false
        bMasterServerStats=true
        bLogBots=true
        bLogChat=true
        bLogPickups=true
        bLogVehicleDeaths=true
        bLogSecurityInfo=true
        bLogPings=true
        bLogAccuracy=true
        bAdvancedVoteLogging=false
        
        bRunUTStatsDBParser=False
        ParserURL=http://myserver.com/logs.php
        ParserPass=updatepass
        bUploadLogs=False
        UploadURL=http://myserver.com/OLSendLog.php
        UploadPass=adminpass

Here are each of the options explained:

[OLStats.MutOLGameStats]

bExportRawLog=true=[true|false]
New in v3.00
If true, OLStats will output raw log files for every match played. Previous to
version 3.00, this was the only type of logging available. True by default.

bExportHTMLLogs=[true|false]
New in v3.00
If true, OLStats will export HTML log file for every match played, as well as
an index file that displays totals and a history of all matches played. If you
are not going to use the HTML logs, be sure to turn this option off, as it uses
unnecessary system resources.

KeepBotRecords=true=[true|false]
New in v3.00
This option only affects HTML logging. If true, all bots' career stats will be
stored. They will have a chance to be in the Career and Match Highs sections.

bMasterServerStats[true|false]
New in v3.00
If true, stats will be uploaded to the Epic Master Server, if it's up and running.

bLogBots=[true|false]
Set to false to not log bots at all. (This is the behaviour of the built in stat
logger) True by default.

bLogChat=[true|false]
Set to false to not log any chat. True by default.

bLogPickups[true|false]
Set to false to not log item pickups. True by default.

bLogVehicleDeaths=[true|false]
New in v1.90
Set to true to have OLStats report the vehicle a player is in when he dies.
Normally, the built in statlogger reports the weapon that the player is holding.
I think that if the player is in a vehicle, the stats shouldn't care what weapon
he's holding.  The vehicle is much more interesting.  This way, you will be able
to tell how many of each vehicle a player has killed, and what weapons are used
to kill which vehicles. True by default.

bLogSecurityInfo=[true|false]
New in v2.00
Set to true to have OLStats report every player's IP address and netspeed when
they connect. True by default.

bLogPings=[true|false]
New in v2.00
Set to true to have OLStats report every player's ping every 30 seconds. True by
default.

bLogAccuracy=[true|false]
New in v2.00
Set to true to have OLStats log the accuracy of every player. When a player
disconnects or the match ends, the number of shots fired, hit, and damage dealt
for each weapon will be reported. True by default.

bAdvancedVoteLogging=[true|false]
New in v2.20
Turns on "advanced vote logging."  When this is set to FALSE, vote logging is
done simply by reporting the chat that the voting generates, like "Overload has
placed 5 votes for dm-gael."  When this is set to TRUE, vote logging is done via
unique events.  The advantage of this is that they could be used to generate more
interesting vote statistics. However, if you simply want the votes represented in
the chat log, leave this false. False by default.

IMPORTANT: If you turn on advanced vote logging you need to make one change to
your UT2004.ini file. This occurs because in order to log voting, the voting
handler must be changed with a unique OLStats version, which then requires its own
configuration section in the ini. Its an unfortunate side effect, and is why
advanced vote logging is off by default.

Find the line with the following text:
  [xVoting.xVotingHandler]
And replace it with this:
  [OLStats.OLStatsVotingHandler]
NOTE: If you are running a mod that replaces the voting handler (such as UT2Vote)
      then setting this to TRUE will cause voting not to be logged at all. If your
      custom vote mod handles logging itself, then you should set this to true to
      make OLStats not log voting.

*****************
*TROUBLESHOOTING*
*****************

Please note:
The HTML files that OLStats creates are not meant to be viewed over
the web. You can, but the pages will take forever to load on anything less
than broadband. If you would like a future version of OLStats to have an
option to output web-friendly HTML files, please tell me. If there's enough
of a demand, I'll implement it.

PROBLEM 1
OLStats says that my UTStatsDB parser is returning unknown data, but the
database is getting updated anyway!

ANSWER 1
OLStats does its best to handle what the UTStatsDB parser returns, but it
is not perfect. If you're getting an error message, but when you view your
UTStatsDB page it looks fine, then just ignore the error and be happy it works.


PROBLEM 2
Same as Q1 but for the stat uploader.

ANSWER 2
Same as A1 but for the stat uploader. :P

************
*CHANGE LOG*
************

For changes between different beta versions, visit
http://www.apartment167.com/mantis

3.01
= Fixed a problem where debug mode was on by default.

3.00
+ Added the "Local OLStats Database" feature, also called HTML Logging. One
  line in the changelog hardly does this feature justice.
+ Added OLServQuery, a modified version of El Muerte's ServQuery that allows
  the unique stat identifiers of the players in the server to be requested
  through a servquery.
= Removed several options from the in-game mutator options. They can still be
  set in the OLStats.ini file.
= Fixed a bug that caused incompatability with certain chat-related mods
  (again) - Thanks ProAsm!
= Made it so that OLStats is compatable with global stat logging. Running
  OLStats will not interfere with global stat logging.

2.50
+ OLStats now requires LibHTTP2, which is included in the OLStats
  distribution.
+ Added the ability to have OLStats run a UTStatsDB parser every time a match
  is started, that way it will parse the match that just completed. See the
  configuration section below.
+ Added a feature that will upload the stats of a game to a utstatsdb server
  at the end of a game. Good for people who don't want utstatsdb to FTP in to
  the game server. See the configuration section below.
= Moved the change log to the bottom of the readme file.

2.20
+ Added special support for Mutant. Now all the mutant scores are reported
  correctly. For some reason, Epic reports only one point for each kill, but
  in mutant it's actually done very differently. OLStats now overrides it
  with the proper scoring.
+ Added super-special support for UT2004RPG.  Now all RPG weapons will
  report the actual weapon you're holding instead of the generic "RPGWeapon"
+ Added advanced vote logging. Now all votes for maps and kicks are logged.
  When a player is kicked due to voting, or a map changes due to voting, that
  is logged too.
+ Made it so chat messages from the WebAdmin interface are logged. They are
  reported as player -1.
+ Added the server's "shortname" to the list of server variables reported
  in the ServerInfo (SI) event. The variable name is "shortname"
= Fixed a bug that causes spectators who later join the game as players to not
  be assigned a team.
= Made it so that pickups are not logged during assault warmup rounds.
= Made it so that if a player fired 0 shots from a weapon, the accuracy data
  is not reported.  This prevents reporting bad data when the "shots fired"
  can't be determined, such as in Instagib.
= Fixed the "out of bounds" error that was occuring a lot. Someone should shoot
  me for the way I coded it originally. (Although it WAS a tad faster...)
= Fixed an accessed none warning in LogChat().
= Reformatted the readme to be printer compatable.
= Fixed an issue that caused OLStats not to be compatable with some other
  mods and mutators that needed their own broadcasthandler. (UTAdminmod in
  particular) Now OLStats plays nice with others.
= Fixed a major bug that occured if a monster appeared in a game that isn't
  invasion, which can happen if you're running UT2004RPG. (Or other mods)

2.11
= Applied a fix so that servers running OLStats can still be considered
  "standard" (No mutators)

2.10
+ Added the CDKey hashes to the Player Security event. The hash reported is
  the same one reported in the web admin, and in mods such as UT2004RPG.
+ Added server difficulty logging. There is now an extra variable reported
  in the serverinfo event that shows the default bot skill. This is especially
  useful to know for Invasion matches.
+ Added bot skill logging. When bots connect, all their skill variables
  are reported.
= Fixed the "phantom player" bug. This bug existed in Epic's code. Now I keep
  track of all players in the game, and force a connect event if a phantom
  player shows up.
= Fixed some access none bugs in the AccuracyHandler
= Fixed some access none bugs in the LogChat function
= Fixed a bug that made bots not appear in the "mini scoreboard" during the
  endgame event
= Time is now reported in centiseconds instead of whole seconds.
= Removed the space from the readme filename :P

2.00
+ Added accuracy logging! Every player's accuracy for each weapon is now
  reported at the end of game, or when the player disconnects. Can be turned
  off in ini file. Note that accuracy logging will not function in Invasion
  games due to forces out of my control.
+ Added all the invasion scoring events. Now the stats will report the team
  and individual scores correctly.
+ Added special invasion specific events. Stats now track player-kills-monster
  and monster-kills-player events.
+ Added a game event that shows when a new invasion wave has begun
+ Added player security logging. Logs every player's IP and netspeed on
  connect. Can be turned off in ini file.
+ Added ping logging. Every 30 seconds, every player's ping is reported.
  Can be turned off in ini file.
+ Implemented a fix for the Epic bug where the damagetype of the Leviathan
  driver's primary fire is incorrect. It now reports the fake damagetype
  "DamTypeMASRocket"
= Fixed bug where it wouldn't log anything after the game ends (like chat)
= Fixed bug that caused stats to report the unique vehicle name in a kill
  instead of the generic classname. It happened for stationary turrets.
= Fixed a major bug in the bot tracking that occured if a bot disconnected,
  and a bot with the same name returned later.
- Removed the Ignore Turret Suicides option, as the latest version of
  UStatsDB now handles it.

1.91
= Made it no longer necessary to put bLocalLog=true in your ut2004.ini file.

1.90
+ Added the OLStats Mutator, so that people can statlog Instant Action
  games.
+ Added the mutator menu for the OLStats Mutator, allowing you to configure
  the OLStats option from inside the game. Intended for when hosting Listen
  or Instant Action games.
= Fixed "accessed none" bug in the CheckBot function when trying to access
  the "team" variable in a non-team game.
= Fixed "accessed none" bug in the BroadcastHandler and the GameRules that
  occured at the beginning and end of some games

1.60
+ Made it so that if you die in a vehicle, the weapon you are reported
  to be carrying is the vehicle itself. This allows you to see how many
  times someone blew up a particular vehicle. Configurable in ini file.

1.50
+ Added ability to turn off bot logging
+ Added ability to turn off chat logging
+ Added ability to turn off pickup logging
+ Added feature to ignore kills from automated turrets found in some
  assault levels. (Normally they register as suicides)
  REMOVED IN LATER VERSIONS

1.00
+ Added pickup logging
+ Added bot logging
+ Added chat logging