Title    : fragstats
Filename : fs106b_NT.zip, fs106b_linux.tar.gz, fs106b_solaris.tar.gz
Version  : 1.06b
Date     : 12th October 1998
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.0.x, Solaris 2.51
Compiler   : MSVC++ 5.0 sp3 (Win32), GCC 2.7.2.1 (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
fs106.txt                  Upgrade instructions
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
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

Whats new in 1.06
=================
. User Defined Tags (UDT's) for use in templates. See the templates.txt and fragstats.cfg
  files for details.

. Support for Quake 2 mods such as CTF, HeadHunters, etc via UDT's. User defined tags
  let you specify what special bonus scores are recorded and logged. The user defined
  tags can be used in all template files. Some sample CTF templates have been included
  in the distribution.

. Team statistics for GS log users. Fragstats can generate a complete list of teams and
  total scores for the Overall Stats and each map, Qplayer can display the Players team
  name and total score.

. Map based statistics for GS log users with the option to switch them off if you want.
  As before, HTML pages for 'Overall Stats' will be generated in the 'htmldir' directory.
  If map stats are enabled (the default if using GS style logs), a subdirectory will
  be created for each map under the directory specified by 'htmldir'. A complete set
  of HTML pages as specified by the 'htmlout' commands will be generated in each
  subdirectory. You can also use 'htmlout' and the new tags (see below) to help generate
  a custom scores.html for each map. check out the sample fragstats.cfg and scores.html
  files for details.

. Weapon based statistics for GS log users. These are only visible for indiviuals via
  Qplayer.

. Added 'Duelthresh' option to provide fairer Duel sorting.

. Specify the GS log name via the 'gslogname' option. Previously, Fragstats forced you
  rename the GS log to "stdlog.log". Now you can just set the name in the config file.

. Added comparative frag count to victim lists in Qplayer. This makes it easier to compare
  frag counts with your buddy/enemy, especially if you have lots of frags.

. Added optional Error template for Qplayer. You can alter this template to the look & feel
  of your site. Errors that are caused by bad user input (eg. lookup by name of someone
  who doesn't exist) will use this template to display an error message.

. Fixed bug with last line processing of cfg file.

. Tighter log parsing code; malformed frag log entries are now always rejected.

. Added new template tags for support of team, weapon & map statistics:
          team name
      team name padded to 32 chars
   total score for team
    total score for team padded to 8 chars
           map name
     number of players recorded for that map (Fragstats only)
       number of frags recorded for that map (Fragstats only)
           subdirectory containing the stats for
                          that map
       Encoded link to Qplayer with map name and player name (Qplayer
                          only)
          name of the HTML page being written (Fragstats only)
          weapon name (Qplayer only)
         kills by that weapon (Qplayer only)
        deaths by that weapon (Qplayer only)

  There are also new embed tags,  for Fragstats, 
  for Fragstat and Qplayer, and  for Qplayer.

. New sample template files which show the usage of the new tags.

Whats's new in v1.05
====================
. GS log support. Note that initially I'm only using info from the
  stdlog.log which is compatible with the 1.04b of Fragstats, ie. Kills
  and Suicides. No other score types or general log information is used
  at this time.
. Bug fixes (mainly with the smart name conversion). If after stripping
  clan designations, etc. the player name is shorter than 3 characters, the
  name is left as-is.
. Changed Deaths so it doesn't include Suicides.
. Alias option. This allows the admin to define aliases for players that
  have changed names, so their scores get combined into one.
. Duel statistic. This shows a count of how many players you outfrag and
  how many outfrag you to. Draws are not shown. This statistic is limited
  to those players you have frags against or have been fragged by.
. Alternative Skill statistic. A modified skill calculation. Enabled using
  the 'Skilltype' option (see below).

  Currently, the skill calculation formula taken from QW Master Servers
  doesn't take the killer's Skill into consideration. This means that a
  master player gains exactly the same number of points for fragging
  "John_Rambo", as a newbie would.

  The new skill calcuation works like this:

  Killers skill = Killers skill + ((Killees skill / Killers skill) * 10)

  and correspondingly:

  Killees skill = Killees skill - ((Killees skill / Killers skill) * 10)

  The alternative skill calculation is added Killer's skill, and subtracted
  from the from the Killee's skill.

  Some examples: 
  1)
  Killer: a very good player with skill 3500
  Killee: a good player with skill 2500

  Killer = Killer + 2500/3500 * 10
  Killee = Killee - 2500/3500 * 10

  Killer has now 3507 points, Killee 2493

  2)
  Killer: a very good player with skill 3500
  Killee: a newbie with skill 1200

  Killer = Killer + 1200/3500 * 10
  Killee = Killee - 1200/3500 * 10

  Killer has now 3503 points, Killee 1197

  3)
  Killer: a newbie with skill 1200
  Killee: a good player with skill 2500

  Killer = Killer + 2500/1200 * 10
  Killee = killee - 2500/1200 * 10

  Killer has now 1220 points, Killee 2480
  Note the integer rounding in this case.

  If a player suicides, the player gets their alternative skill adjusted
  like so:

  Killer = Killer - (Killer skill / 1000)

  This is a significant penalty to those who like to keep their skill high
  by topping themselves when in a bad position.

  Note that is a an alternative statistic; it replaces the old skill when used.

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

. Access to a Web Server running on this machine, or having network
  drive access to at least the qw directory belonging to the QuakeWorld
  server. 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. This being said,
  there is a known problem with Website and the qplayer program on NT.

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 server record frags in the frag_*.log
files under the qw directory. 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
  Frags, Deaths, Rank, Efficiency, Suicides, Skill and Duel.

. 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 3000 registered players on our QuakeWorld 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. 

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
   ):

   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=
  htmldir=
  cgidir=
  cgiurl=

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=
  config=
  cgiqplayer=
  text=
  bgcolor=
  link=
  vlink=
  alink=
  lastscanned=
  effthresh=
  duelthresh=
  background=
  mapchar=
  htmlout=

  cgitemplate=
  rawoutput= [extended|mapped]
  disablecgi=
  nameconvert=
  disablemapstats=
  logstyle=
  alias=
  skilltype=

New in v1.06 are the following settings:
  gslogname=
  cgierr=

'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.

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" as defined by the GNU public licence, with
the exception that source code is not provided. 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.