Title    : fragstats
Filename : fs108_NT.zip, fs108_linux.tar.gz, fs108_solaris.tar.gz
Version  : 1.08
Date     : 19th July 1999
Author   : Chris Scarvell
Email    : chriss@pcug.org.au
WWW      : http://quake.tip.net.au/fragstats.html
Credits  : id software and the QuakeWorld team. Thanks to Nigel Haynes (Fanatic) 
           & Rohan McElwee (BigFoot) for help with the Linux port. Also thanks to:
           Hofkens Dale (ZZip) for help with the Quake extended character mapping.
           Marco Berri for the new Duel statistic.
           RooS for the alternative Skill statistic.
           Danny Whitesel (VaReBeL) for beta testing & suggestions.
           And thanks to the growing Fragstats user base out there for the constructive
           feedback!

Type of Mod
===========
Quake C    : No
Sound      : no
MDL        : no
C code     : Yes
HTML       : Yes
QuakeWorld : Yes
Quake 2    : Yes
O/S        : Win32, Linux 2.2.x, Solaris 2.51
Compiler   : MSVC++ 5.0 sp3 (Win32), GCC (UNIX)

Package
=======
fragstats.exe (fragstats)  Win32 (UNIX) Fragstats program
qplayer.exe (qplayer)      Win32 (UNIX) Query Player cgi program
scores.html                Sample scores page
fs.bat                     Sample batch file for automatic execution
fragstats.cfg              Sample config file
fragstats.txt              This file
version.txt                Version history
fs108.txt                  Upgrade instructions and version information
FAQ.txt                    Frequently asked questions
template.txt               The whys and wherefores of HTML templates
maintemp.html              Sample HTML template
top20temp.html             Sample HTML template
cgitemp.html               Sample HTML template for Qplayer
cgierrtemp.html            Sample HTML Error template for Qplayer
dm.cfg                     Sample database config file
ctf_templates              Directory
   ctf_cgitemp.html           Sample CTF HTML template for Qplayer
   ctf_maintemp.html          Sample CTF HTML template
   ctf_top20temp.html         Sample CTF HTML template
qwlog_templates            Directory
   cgitemp.html            Sample HTML template for Qplayer
   maintemp.html           Sample HTML template
   top20temp.html          Sample HTML template


What you need to have
=====================
. Administrative access to a system running the QuakeWorld/Quake2/TRIBES
  server

. Access to a Web Server running on this machine, or having network
  drive access to at least the directory containing the server log files.
  You will need to be able to write to a Web Server document directory
  and a Web Server CGI directory.

. I've tested fragstats sucessfully with Netscape FastTrack 2.01,
  Enterprise 2.01/3.51, MS Internet Information Server, MS Win95 personal
  webserver and Apache. This list is by no means exhaustive - fragstats
  should work happily with virtually any Web Server.

Description
===========
Fragstats replaces the much missed scoring system from the original
QuakeWorld 1.2x. The QuakeWorld team decided that centralised frag
logging was just too much and instead implemented local server frag
logging. This document assumes you are familiar with the deployment of
a Web Server.

Current versions of the QW server record frags in the frag_*.log
files under the qw directory. Q2 and TRIBES servers can also be made
to generate logs. These logs contain all the information, but need
processing to read anything meaningful from them. This is where
fragstats comes in!

Fragstats parses the frag logs, collating scores for each player.
From this data, fragstats generates html pages suitable for display
on any table capable browser and creates a database which can be
queried later by the cgi program qplayer.

For safety, fragstats does not alter the frag logs in any way.

Features
========
. To provide the scoring functionality of the original QuakeWorld Master.
  That's got to be the starting point, hasn't it? Fragstats records Frags,
  Deaths, Rank, Efficiency and Skill PLUS compiles lists of victims and
  deaths for each player.

. Maximum performance 
  The actual processing of the log files is quite intensive, and increases
  exponentially as the number of logs and players increases. Fragstats and
  the qplayer CGI program are optimised C code for just this reason.
  Optimised sorting and searching algorithms such as quick sorts, hash
  indexes and binary searches are used extensively. Fragstats has NO LIMIT
  to the number of players it can process (actually, the limit is MAXINT or
  2^31 - 1. Now if I had a 64 bit compiler... :)

. Access to generated stats via a web browser. 
  Almost a given these days. Fragstats can generates player lists sorted by
  any scoring type recorded in the logs.

. To provide a player lookup feature accessible via a web browser, rather
  than just a huge static list of players. At the time of writing we have
  over 2000 registered players on our Q2 server. There are other sites
  with over 6000 players. Finding an individual in this list is pretty
  hard. Fragstats supports (via the qplayer CGI program) lookup of additional
  player details such as victim and death lists. You can also lookup players
  by name.

Using Fragstats with Quake 2
============================
You will need to obtain a Quake 2 mod that generates logs files - Quake 2 out
of the box will *not* do this. Suggestions are:

. ServerConfig Mod by GutSpiller (pstepp@hotmail.com), available for win32 and
  Linux. It generates both QW and GS style logs. Obtain from:
  http://quake2.com/sconfig

. Lithium Mod by WhiteFang (matt@lithium.com), available for win32, Linux & Solaris.
  It generates GS style logs. Obtain from:
  http://www.planetquake.com/lithium/

. GS log mod by Mark "Grey" Davies, available for most platforms. It *only* generates
  GS style logs. Obtain from:
  http://www.planetquake.com/gslogmod

Mods like Capture the Flag and Rocket Arena can generate GS style logs as standard. 

Using Fragstats with TRIBES
===========================
You will need to obtain a tool from the D0gz Pack called Tribestats. This will
allow you to generate GS style logs from the TRIBES console output.
  Get it from:
  http://quake2.d0gz.net/

Installation
============
To install:

1. Unzip the package.
2. Copy fragstats to your qw directory or some other directory in
   your path.
3. Copy qplayer to a cgi directory.
4. Inspect the scores.html file, changing the "action=/cgi-bin/qplayer.exe" to
   the approprate URL mapped path for qplayer. Also check the "method=POST" and
   change to "method=GET" if your web server doesn't support POST. Copy the
   modified scores.html to a web server document directory.
5. Check the options set in the sample fragstats.cfg file, modify as required.
6. If using QuakeWorld, enable frag logging in your QuakeWorld server by toggling
   'fraglogfile' at the server console. From the QuakeWorld Server Console Commands
   document (Version: 1.1 Author: JakFrost
   <jakfrost@ultinet.net>):

   fraglogfile (T)

    Syntax: fraglogfile
    Default: off

    Toggles logging of kills to a file and reporting to external frag 
    polling programs.  The file name is frag_*.log.

   If you are using Quake 2 with a mod that provides logging, refer to the mod
   documentation for information on how to enable logging.

How to run
==========

Fragstats
---------
Fragstats requires the following arguments (they can be specified in the config file):

  logdir=<directory where the frag logs are found>
  htmldir=<directory to put the html pages - same as scores.html>
  cgidir=<explicit path to cgi directory>
  cgiurl=<URL mapped path to cgi directory>

If the CGI interface is disabled (see below), cgidir & cgiurl are not required.

Eg.
For UNIX:
  fragstats server=Megadeath logdir=/quake/qw htmldir=/webserver/docs cgidir=/webserver/cgi-bin cgiurl=/cgi-bin
For Win32:
  fragstats server=Megadeath logdir=c:\quake\qw htmldir=c:\InetPub\webroot cgidir=c:\Inetpub\scripts cgiurl=/scripts

If these options are not set on the command line, fragstats will attempt
to find them in the config file. By default fragstats will look for
fragstats.cfg in the current directory. By using the 'config' option,
you can specify another location and name for the config file. Other
options you can specify are:

  server=<server name>
  config=<path to the config file>
  cgiqplayer=<name the qplayer program will be invoked as>
  text=<HTML text colour>
  bgcolor=<HTML background colour>
  link=<HTML link colour>
  vlink=<HTML visited link colour>
  alink=<HTML active link colour>
  lastscanned=<last scanned data file name>
  effthresh=<number of frags before a efficiency rating is given>
  duelthresh=<number of Wins required to sort higher>
  fphthresh=<number comnnect seconds required to sort higher>
  background=<HTML background image>
  mapchar=<character mapping>
  htmlout=<output directive>
  cgitemplate=<CGI template file>
  rawoutput=<raw output file> [extended|mapped]
  disablecgi=<yes or no>
  nameconvert=<yes or no>
  disablemapstats=<yes or no>
  logstyle=<QW or GS>
  alias=<alias definition>
  skilltype=<Original or Alternate>
  gslogname=<GS log filename>
  cgierr=<error template used by qplayer>
  dbcfg=<db config file>

'Htmlout' specifies HTML output. I've provided several sample templates which will
generate default output. I've also included some derivations of the defaults for CTF
support and others if you are using QW style logs. You can find these, respectively,
in the ctf_templates and qwlog_template directories.

Templates are described in detail in the template.txt file. If no 'htmlout' commands
are specified, Fragstats will generate default outputs of all players and the top 20
sorted by Frags, Deaths, Rank, Suicides, Efficiency and Skill. I would recommend using
templates where possible; they are much more flexible.

'Cgitemplate' specifies a template file for qplayer to use. See the template.txt
file for details.

'Cgierr' specifies an error template file for qplayer to use when it encounters some
errors. For example, it will get used when someone tries to look up a name that doesn't
exist. A sample error template 'cgierrtemp.html' has been provided.

'Rawoutput' specifies a file to which Fragstats will write the players database
contents in CSV format. You might find this useful for later anaylsis via a
spreadsheet or input to another program. You can optionally specify to output player
names using the Quake extended character set ('extended' option) or with character
mappings as per the 'mapchar' command ('mapped' option). If neither is specified, the
default is 'mapped'.

'Disablecgi' simply toggles the links to qplayer in the HTML output generated
by Fragstats.

'Nameconvert' toggles whether Fragstats will do a smart name conversion of
player's names. If this is switched off, 'Primevil [DLS]' WILL NOT be the same
as 'Primevil'. IMPORTANT NOTE: If you change this setting, you should delete the
last scanned data file (see the lastscanned option) and reprocess your
logs from scratch. This will ensure that all records in the logs are processed
with the same name conventions.

'Logstyle' allows you to specify Fragstats to parse QuakeWorld style logs (QW) or
GS log standard style logs (GS).

'Alias' allows you to define a list of aliases that a player is known by. This is
most useful when a player has changed names and would like to combine their old
scores under their new name.

'Skilltype' allows you to specify the type of skill calculation done. The default
calculation is the same as the one used by the original QuakeWorld Master server.
See above for deatils on how the alternate calculation works.

'Duelthresh' specifies the number of Wins you need to have to sort higher. For example,
if set to 10 , this would prevent someone with a Win/Loss ratio of 9/0 getting rated
higher than someone with 50/1.

'Disablemapstats' allows you to specify if you want to include map scoring as well
as overall scoring. Calculating map stats about doubles the work and hence memory
and CPU consumption of Fragstats. You also chew up more disk space. I've added this
option in case you don't want to crunch map stats. Of course, this option is
meaningless for QW style frag logs - there is no map data anyway.

'Gslogname' allows you to specify a specific filename that contains your GS logs.
If not specified, Fragstats will default to 'stdlog.log'. This option is of no use
whatsoever if you are using QW style logs.

'Dbcfg' allows you to specify a file located in the cgidir that contains the names of
the database files for that server. If this is not set (default), the database names
will be 'players.db' and 'victims.db'. If it is set the first line of the file must be
the name of the players database, the second the name of the victims database. See the
sample dm.cfg file for an example. Remember, the database config file *must* be located
in the directory specified by the 'cgidir' option. NOTE: If using the dbcfg option,
make sure you add the following line:

   <input type=hidden name=dbcfg value="<!--dbcfg-->">

After the hidden mapname input line, or search by name will not work.

'FPHthresh' is used to ensure players with a low connect time and a few frags
don't get sorted higher than someone with longer connect time. Setting this
specifies the minimum number of connect seconds required for a top FPH position.
Someone with less connect time will always sort lower than someone with more
connect time than FPHthresh.

All of these (except for config) can be specified in the config file.
Options are specified in the config file without the '=', eg.

server	Megadeath
htmldir	/webserver/docs
rawoutput /tmp/stats.csv extended

Check out the included fragstats.cfg file for details.

What it does
------------
Fragstats will parse all the frag logs starting from frag_0.log going
to frag_N.log sequentially. If you are parsing GS style logs, Fragstats will
look in the log directory for the 'stdlog.log' file.

Fragstats tries to be a little smart about how it processes player
names. For comparison purposes, player names are case insensitive,
spaces are removed and clan designations enclosed in [], (), {}, <> and
-- are ignored. For example, 'PrimEvil [DLS]' is considered to be the
same player as 'primevil'. If the 'nameconvert' option is set to 'no',
this smart name comparison will not occur, and players will have to have
identical names to be considered the same.

For complete name changes, you can define the old name(s) as aliases of the
new name.

The Quake extended character set is fully supported via the 'mapchar'
command'. All those funky names you see in QuakeWorld are translated
automatically into displayable ASCII characters!

Once the logs are scanned, fragstats will generate web pages as instructed
via the 'htmlout' commands (or if no 'htmlout' commands are specified, via
internal defaults), and the player database and the victims database.

The player and victims database end up in the cgidir along with qplayer.

The default HTML pages contain complete and top 20 lists of players, sorted by
rank, frags, deaths, suicides, efficiency and skill. The players and victims
databases are accessed by the cgi executable, qplayer.

Fragstats saves the last log number and file pointer position in the
last scanned data file. The next time you run fragstats, it will reload
the database and start scanning from this position. This can save a lot
of time for subsequent runs. If you want to rescan the logs from
scratch, delete the last scanned data file or change the contents to "0 0 0".

Did it work?
------------
Fragstats will generate some output which you should check to verify
a successful run. If you see an 'Error parsing' message, don't worry.
It indicates that an incomplete frag record was found in a frag log.

The 'Error parsing' message indicates that an incomplete frag record
was found. When fragstats encounters an incomplete record, it ignores
it and gets the next record. In my experience, incomplete records can
occur in two situations:

1. The server has crashed, and so hasn't flushed the last record(s) to
   the frag log.
2. The server is still writing that particular frag log (this doesn't
   seem to happen much, but is possible).

In case 1, frags that hadn't been flushed to the logs will be lost.
Sorry.

In case 2, the frags will be flushed eventually, so the data is OK,
just temporarily unavailable.

Fragstats can produce other error messages. For example, you haven't
provided the required command arguments, specified an invalid directory,
you've run out of disk space, etc.

Running fragstats automatically
-------------------------------
Fragstats was designed to be run as a batch job maybe once or twice a
day. A good reason for this is that it is fairly CPU intensive. Running
this at the same time as a full on frag fest is likely to result in a
few seconds of poor performance. Also, the frag logs are flushed fairly
infrequently by the server. Fragstats is not a real time reporting
tool!

With this in mind, it is quite easy to set up a job via the NT
scheduler or UNIX cron command to execute fragstats periodically.

With NT, enable the Scheduler service and run fragstats with the 'at'
command. For example:

   at 3:00 /every:monday,tuesday,wednesday,thursday,friday,saturday,sunday c:\quake\qw\fs.bat

The fs.bat file simply invokes fragstats and redirects standard output
to a text file for later perusal.

With UNIX (Linux, Solaris) run fragstats via cron. I won't go into a
discussion on the usage of cron - the man pages should cover this.

Aliases
-------
Fragstats allows you to set up alias definitions for mapping of old
names to new ones. Use this when a player has used more than one name
and would like to combine the scores.

The format is:
  alias name with aliasname ...

Example:
  alias "Stoo [GE]" with Stoo Stoo.[GE] Stoo.{ge} stoo "Stoo [DLS]"

will combine the scores of Stoo, Stoo.[GE], Stoo.{ge}, stoo and
Stoo [DLS] into one player called Stoo [GE]. note I've used double
quotes to ensure Stoo [DLS] and Stoo [GE] are considered to be
single player names.

Alias names are case sensitive.

If you add or change alias definitions, delete the last.dat file to force
Fragstats to reparse the logs. Otherwise, data stored in the databases
will not be updated.

Extended character support
--------------------------
Fragstats will automatically convert extended Quake characters to
standard ASCII characters suitable for display. Mapping of characters
is done via the 'mapchar' option.

The format is:
  mapchar c to n n n n n ...

Example:
  mapchar ! to 61

Would cause every instance of = (ASCII 61) to be replaced with a !
You can specify numbers as well as characters.

Example:
  mapchar 34 to + # 64

Would cause every instance of +, # or @ (ASCII 64) to be changed to
double quotes. Single digit numbers are assumed to be a character.

Example:
  mapchar 1 to 147

is the same as:
  mapchar 49 to 147

while:
  mapchar 01 to 147

is the same as:
  mapchar 001 to 147

Lastly, you don't need to map a character to it's valid ASCII position.

If this sounds all a bit too hard, don't worry - the sample fragstats.cfg
file has all the mappings required for the Quake extended character set.
Feel free to have modify these mappings. I deliberately went to the effort
to make these mappings customisable so you're not just stuck with my
interpretation of "best fit".

If you find a problem or figure out a better mapping, let me know.

IMPORTANT NOTE: If you change the mappings, you should delete the
last scanned data file (see the lastscanned option) and reprocess your
logs from scratch. This will ensure that all players in the database
are processed with the same mappings.

Qplayer
-------
Qplayer gets invoked when you click on a player in the generated
pages. It will query the databases and returns stats for that player.
You will have to set up the web server to recognise the cgidir as a
cgi directory if you haven't already. The stats returned include the
frags, deaths, rank, efficiency and skill of that player, along with a
list of that players victims and a list of who has killed that player.

Qplayer support both HTML GET and POST methods. So if name lookup in
scores.html isn't invoking qplayer correctly, try changing the method.

To Test
=======
. Setup your web server cgi directory and mapping if you haven't
  already.

. Make sure fragstats is in your path.

. Make sure scores.html has been copied to the html directory you will
  provide as an argument to fragstats.

. Make sure you've enabled fraglogfile as described above and ensure
  there are some frag logs written.

. Run fragstats via the command line, providing the log directory,
  html directory, cgi directory and cgi URL mapping as arguments.
  Alternately, set the options in the fragstats.cfg file and run
  fragstats without any command line options.

. Check to see that some html pages have been created in the html
  directory you specified to fragstats (these are the default pages
  produced if you don't specify any htmlout commands):
  Rank.html
  Frags.html
  Deaths.html
  Efficiency.html
  Skill.html
  Suicides.html
  Rank-top20.html
  Frags-top20.html
  Deaths-top20.html
  Efficiency-top20.html
  Skill-top20.html
  Suicides-top20.html

. Check to see that the players.db and victims.db have been created in
  the cgi directory you specified to fragstats.

. Send your browser to scores.html and see if it worked! You can compare
  your output with that found at http://quake.tip.net.au/scores.html

If something is not working right, check out out the FAQ.txt file.

Disclaimer
==========
This software is "Freeware" which means that is offered at no cost. 
No warranty of any kind is offered or given with this software.
The software is provided on an "as is" basis. No liability is offered
or accepted by the use or misuse of this software.
