================================================================================
Voodoo Stats by myrddin & react
================================================================================

Voodoo Stats is a log analyzer for quake III arena. It can analyze both 
client side (qconsole.log) logs as well as server side (games.log) logs.
It reads the log files generated by quake III and displays various game stats 
in html format. 

Credits:
---------

             Lead Programming/Design : myrddin (myrdd1n@hotmail.com)
                         Programming : react   (r3act@hotmail.com)
Additional coding/suggestions/advise : phred   (greg@price.org)
 Additional testing/suggestions/p.r. : gouki   (gouki9@yahoo.com)

                             Website : http://www.clanavl.com/voodoo/
                                       http://www.clanavl.com
                                 Irc : #avalanche, #voodoopeople, #^oo^
                                       on irc.enterthegame.com

Thanks to:
----------
rhea and the osp team : For creating the best competition mod for quake3.
n8dawg                : For helping us out with ummm... stuff/code ;)
grunge                : For setting us up with a test server in linux.
lunk                  : For providing a linux shell account with mysql/php/www.
fia & hifi            : For helping me sort out browser compatiblities on macs.
all the peeps in avl  : Default Pimpage.

and anyone else i forgot to mention...

________________________________________________________________________________



================================================================================
Pimpage:
================================================================================

Clan Avalanche                    : http://www.clanavl.com
                                    #avalanche on irc.enterthegame.com
Orange Smoothie Productions (OSP) : http://www.orangesmoothie.com
                                    #osp on irc.enterthegame.com
Server Config Generator for OSP   : http://www.clanavl.com/OSPConfig
                                    Brought to you by phred ( greg@price.org )
Coderz                            : #coderz on irc.enterthegame.com

________________________________________________________________________________



================================================================================
About this document:
================================================================================

This ReadME is a generic document and contains information on all the different
releases of voodoostats (linux and windows), so ignore the information that does 
not refer to the release that you have downloaded.

This document is written from a windows/dos perspective, so linux users should 
use the equivalent commands/methods if its not the same.
ex: In windows directories are delimited by \
    In   linux directories are delimited by /

voodoostats(xx)-c and voodoostats(xx)-s
---------------------------------------
The (xx) here refers to the current version of voodoostats.
Ex: If you have downloaded voodoostats version 4.0, then
    voodoostats(xx)-c means voodoostats40-c and
    voodoostats(xx)-s means voodoostats40-s

voodoostats(xx)-c = analyzes log files and generates html stats.
voodoostats(xx)-s = analyzes log files and updates mysql database with stats.

________________________________________________________________________________



================================================================================
Installation and Usage Instructions:
================================================================================

   
   Client Side version
   -------------------
   This version is mainly for players who just want to see stats of the games 
   they play online. The stats are generated from qconsole.log
   
   1. Extract the downloaded .zip file into a directory of your choice.
      Linux specific: You may have to do a "chmod u+x" on the following files:
   
        voodoostats(xx)-c
        vs-preparse
   
   2. To analyze a log file and generate html stats:
      Lets say your qconsole.log file is in c:\games\quake iii arena\baseq3\
      To analyze this file, go to the dir where you unzipped voodoostats and 
      type:
      
        voodoostats(xx)-c "c:\games\quake iii arena\baseq3\qconsole.log" <mycfg.cfg>

      NOTE: mycfg.cfg is optional. If you do not specify a cfg file then
            voodoostats will read all the info from c-default.cfg. You can make
            several different cfg files with different settings etc, and 
            tell voodoostats to read your preference from that cfg file.
            A description of what each setting mean in the cfg can be found
            in c-default.cfg
            Also, the config file must have .cfg as its extension.
            You need the double quotes if the directory path has spaces in it.

  
   Server Side version (includes client side as well)
   -------------------
   This version is mainly for q3 server admins who wants to generate stats
   for all the players that join their server and keep a cumulative record
   of the stats stored in a database. The stats are generated from games.log
   
   The server side version uses mysql and php to store and retrieve the stats, 
   so you need to install both mysql and php on your server/system.
   You may also need a webserver that is compatible with php if you dont 
   already have one.
   Both mysql and php can be downloaded and used for free.
   Download the latest version of the webserver, mysql and php.
   You can get a free webserver from http://www.xitami.com
   mysql can be downloaded from http://www.mysql.com
   php can be downloaded from http://www.php.net
   Install the webserver first. In windows, PHP can automatically detect the 
   webserver and configure it accordingly.
   Install mysql and php on your system.
   Check the installation instructions that comes with mysql and php.
   
   
   1. mysql setup
      -----------
   
   a. Add the mysql command path (c:\mysql\bin\ is the default) to your 
      evironment variable PATH.
      In windows 2000 you can specify the PATH in
      start->
        settings->
          control panel->
            system->
              advanced->
                environment variables->
                  user variables->
                    PATH
      In win9x versions, you can specify the PATH in autoexec.bat:
        Path=C:\Windows;C:\Windows\Command;c:\mysql\bin
      
      i.e, when you type mysql from the command prompt (from any directory), it
           should go to the mysql> prompt.
      Test it! Open up a dos window and from C:\ or any other directory, type 
      mysql and press enter. It should go to the mysql> prompt. type QUIT in the
      mysql> prompt to return to the command prompt.
      
   b. Read the section (section 4?) that deals with MySQL Database 
      Administration from the mysql manual which can be found C:\mysql\Docs
      This section deals with user priveleges and tells you how to make mysql
      more secure and add a new user etc.

      You need to setup a user AND a password in mysql. If you are planning
      to run mysql as user 'root' then you have to set up a password for user 
      'root' if it isnt already setup.
      
      The following is from the mysql documentation,
      
          The default privileges on Windows give all local users full 
          privileges to all databases. To make MySQL more secure, you should
          set a password for all users and remove the row in the mysql.user 
          table that has Host='localhost' and User=''. 

          You should also add a password for the root user. 
          (The following example starts by removing the anonymous user, that 
          allows anyone to access the 'test' database.): 
      
          C:\mysql\bin> mysql mysql
          mysql> DELETE FROM user WHERE Host='localhost' AND User='';
          mysql> QUIT
          C:\mysql\bin> mysqladmin reload
          C:\mysql\bin> mysqladmin -u root password your_password
      
      If you are running mysql as root, you *MUST* have a root password set up
      as indicated above, otherwise voodoostats will stall when updating
      the mysql database.
      
      Test to see if you can load up mysql with the username and the password
      you have set up as following:

        mysql -u Username -pPassword

      Note: Username = your username
            Password = your password
            There is no space between the -p and your password

      If it goes to the mysql> prompt, mysql is properly set up on your system.
      Quit mysql by typing QUIT in the mysql> prompt and that should return to the
      command prompt.
      
        mysql> QUIT
      
      Close the dos window.
 
   2. php setup
      ---------

   a. Make sure you have configured your webserver to intercept .php files.
      This should automatically be done by the php installation program. Read
      the ReadMe file that comes with php. You may have to configure some things
      manually depending on the webserver you have on your system.
      *WARNING* If php is not set up properly, your username/password for mysql
      may be compromised!
      There is a file called test.php in this distribution under the html 
      sub-folder. After setting up php, start your webserver and configure it
      to give public access to the html folder. Then load up the test.php file
      using your internet browser. If php is set up properly, you should see
      a whole lot of tables with variables and its values. If instead you see a
      line saying that "php is not set up properly" followed by "phpinfo();",
      then php is not set up properly!
  
   3. voodoostats setup
      -----------------
      
      If you installed mysql, php or a webserver or made any changes to your
      system configuration, its a good idea to reboot your system before you
      continue any further.

   a. Extract the downloaded .zip file to a directory of your choice.
      Linux specific: You may have to do a "chmod u+x" on the following files:

        voodoostats(xx)-s
        voodoostats(xx)-c
        vs-preparse
        DetectTags
      
   b. Open up the s-default.cfg file using a text editor and specify your
      mysql database username, password and other preferences. 
      Further decription of what each setting in the cfg file mean, can be
      found in s-default.cfg itself. These settings are used by voodoostats 
      to update the mysql database.
      
   c. Open up cfg-default.php under the html sub-folder using a text editor and
      specify your mysql database username, password and other preferences.
      Further decription of what each setting in the config file mean, can 
      be found in cfg-default.php itself. These settings are used by php to 
      retrieve the data from the mysql database.
      
   d. To analyze a log file and generate html stats:
      Lets say your games.log file is in c:\games\quake iii arena\osp\
      To analyze this file, go to the dir where you unzipped voodoostats 
      and type:

        voodoostats(xx)-s "c:\games\quake iii arena\osp\games.log" <mycfg.cfg>

      NOTE: mycfg.cfg is optional. If you do not specify a cfg file then
            voodoostats will read all the info from s-default.cfg. You can make
            several different cfg files with different database settings etc,
            and tell voodoostats to read your preference from that cfg file.
            Also, the config file must have .cfg as its extension.
            You need the double quotes if the directory path has spaces in it.
      
   e. If you want to access your stats from the www, give public access to the
      html subfolder including its sub-directories using your webserver.
      index.php is the main stats webpage. If no config file is specified,
      index.php reads cfg-default.php and uses the information in that to access
      the mysql stats database. You can make several different php config files
      with different database settings and other preferences and tell index.php
      to read your preferences from the specified config file.
      ex: If you have a config file called cfg-myconfig.php with your 
          preferences, then you can tell index.php to read from that config 
          file by accessing:
          
            index.php?config=cfg-myconfig.php
               
________________________________________________________________________________
             


================================================================================
Frequently Asked Questions (F.A.Q.)
================================================================================
Q. Where the can i find this so called "qconsole.log" file 

Quake III does not generate this file by default. You have to type 
"set logfile 1" in the quake III console inorder to get this file. It is a good 
idea to add that command to you "autoexec.cfg" file in "./baseq3/".  
The "qconsole.log" file is created in the ./baseq3/ folder by default.
If its not there, check the ./OSP/ folder
--------------------------------------------------------------------------------
Q. Where are all the html files generated by Voodoo Stats 

All the html files generated by Voodoo Stats can be found in the "html" 
sub-folder. 
--------------------------------------------------------------------------------
Q. Will the html files get over-written everytime the program runs? 

No. The html files generated will always have a unique filename based on the 
current time and date, so you dont have to worry about it getting over-written 
or deleted.  This also means that you will be incharge of manually deleting the 
html files if you dont need them. 
--------------------------------------------------------------------------------
Q. How come the accuracy stats dont display properly on client logs?

You have to enable dumping of accuracy stats by OSP. You can do this by setting
cg_autoaction "16" or adding 16 to your already existing cg_autoaction value.
This will enable automatic "/statsall" after the game ends.
--------------------------------------------------------------------------------
Q. How can I setup a shortcut for easy access to generate the stats?

Edit the voodoostats-c.bat file provided with voodoostats to match your settings.
and create a shortcut on your desktop to voodoostats-c.bat

Alternatively, You can create a batch file with the extension .bat with the 
voodoostats command in it.
Lets say your games.log file is in c:\games\quake iii arena\baseq3\
Open up any text editor (notepad etc.) and type the following:

  voodoostats(xx)-c "c:\games\quake iii arena\baseq3\qconsole.log" c-default.cfg

Save the file now as voodoostats.bat in the directory where you extracted 
voodoostats into.
Now create a shortcut on your desktop to point to voodoostats.bat
Now you can generate the stats by just clicking on the shortcut you made.

Obviously, you may have to replace c:\games\quake iii arena\baseq3\qconsole.log
with the pathname of where your qconsole.log is located and replace 
c-default.cfg with the custom cfg file name you are using.
--------------------------------------------------------------------------------
Q. Anything else ? 

A neat way of generating the stats is to create a batch file with the 
quake3 command followed by the VoodooStats command. This way, once you exit 
quake III, the html stats will be created from your latest "qconsole.log" 
--------------------------------------------------------------------------------

                       " feel da jungle vibe bebe! "

                           The Prodigy ownz all!
________________________________________________________________________________



================================================================================
History:
================================================================================

01 Oct 2001 - 4.0
-------------------

- Add: Server side stats using mysql/php! This ownz ;)
       If you use server side stats on your q3 server, let me know!
       I will put up a list of servers running voodoo stats on the webpage.
- Add: Support for Threewave mod. Full support will be added later with the 
       release of the next Threewave patch, hopefully.
- Add: More awards on the client side.
- Add: Displays weapon accuracy info and total damage given/recvd for all 
       players on the client side . This is only possible in OSP 0.99v4 and up.
       You have to add the /statsall command to the cg_autoaction bitmask
       cvar to enable this feature in OSP. cg_autoaction "16" should enable  
       this or add 16 to your existing cg_autoaction value.
- Add: Support for client side (qconsole.log) CA games.
- Add: TDM games are now supported.
- Add: A whole lot of map images.
- Add: Html is now generated using style sheets, so it should be 
       much more customizable now. Modify c-voodoo.css (default) to customize.
- Add: Random quotes for players (limited to 60 characters max for now).
- Add: Config file support for the html generator. You can specify certain 
       options in a .cfg file like file extension for the generated html, 
       the stylesheet to be used for the generated html, enable/disable 
       weapon stats generation, etc.
- Add: Header/Footer support for the generated html.

- Fix: Fixed selector names in css to conform to standard naming format.
       i.e., no underscodes are used in the selectors anymore.
- Fix: Score calculations were wrong if there were any team kills.
       TeleFragging your own team-mate in CTF can cause this.
       Hopefully it is fixed now with OSP 0.99v1 and later since
       it adds team join messages to the console so teams are now
       detected in the beginning of the game itself rather than 
       waiting till a ctf event occurs.
- Fix: Fixed assist award to count capture assists rather than FC defends.
- Fix: Fixed lots of html formatting errors.
- Fix: Erroneous calculations due to a variable that was not
       initialized.
- Fix: Fixed up some suicides being missed because of a period in it.
       killed itself. melted itself. etc.
- Fix: Fixed up some MAJOR memory leaks which eluded me in all the 
       previous releases. gg me!. Anyways, the program shouldn't be
       much of a resource hog anymore and should run much faster.
- Fix: A whole lot of other crap i dont remember.

- Mod: The generated files are named using only alphanumeric characters
       and underscode(_). This is to ensure compatibility over database
       apps since some of them may have trouble with non-alphanumeric 
       characters.
- Mod: For team games, players on unknown teams are not displayed by 
       default. You can enable this in the .cfg file.
- Mod: Removed full names of maps. The reason for this was that the 
       full map names were hard-coded and it meant that everytime a 
       new map was added, i had to update the code with the name of the map.
       I know a better way to support this by having a text file with
       map names and its full name and reading from that. I may implement
       this some time in the future if i have time.
       Now its also possible to add other custom map images yourself.
       Just save a .jpg file with the short map name in ./html/images/maps/
       and it will load the map image for that map.
       ex: If there is a new map with short name q3ctf8, you can save a 
           screenshot of the map as q3ctf8.jpg in ./html/images/maps/
- Mod: Removed every trace of the map guessing feature (based on location).


09 Jun 2001 - 3.5
------------------ 

- Fix: Fixed a nasty bug that happened when using certain logs files.
       It was caused by CARRIAGE RETURN characters.
       Thanks to React for finding it!
       ASIDE: React is busy workin on server logs!
              I'm trying to get the database going.
              So what does that mean? 
              Voodoo Stats server side is in the works!
- Fix: Now detects suicides strings based on drowning under water.
       'sank like a rock.'
- Fix: Now detects suicides strings based on deaths in the slime.
       'melted.'
- Fix: Fixed OSP warmup detection bug when player is ready! and is kicked
       out of server before game starts.

- Mod: Skill point for flag hold kills has been reduced from 2.0 to 1.8
- Mod: Map guessing has been disabled.


02 Jun 2001 - 3.4
-------------------

- Add: Support for regular id dm and tourney maps, and threewave compilation 
       pack 1 maps.
- Add: OSP map detection. OSP version 0.99u and later prints out the map
       names onto the console so detection is trivial now. Thanks to Rhea!

- Fix: Fixed printing of map name without an image for that map.
- Fix: Score calculation is finally accurate! Hopefully...

- Mod: Changed the map image dimensions.


19 May 2001 - 3.3
-------------------

- Fix: Certain Player-name merges that was missed in the previous releases 
       is fixed now.
- Fix: Fixed tag detection bug that occured when player-names were merged.


14 May 2001 - 3.2
-------------------

- Add: Detects player disconnects that happens when 'Lost reliable commands'

- Fix: Fixed Player merges and Player disconnect issues that was broken
       in the 3.1 release.
- Fix: Fixed image for crewctf map which was missing in previous releases.
- Fix: Fixed erroneous 'Flag Hold Kills'.

- Mod: Players are now added based on their color coded name. So for example,
       A playername in RED color is now different from the same playername in
       a different color.


13 May 2001 - 3.1
-------------------

- Add: "Guess-timates" teams for left-over players in CTF games.
       Players who are assigned teams in this way are marked with a '~'

- Fix: Fixed problem when log file had the ascii character 27 (one of the
       fun name characters). Woo this was one annoying bug!
       Thanks to KI|N8_Dawg!
- Fix: Clicking on the main player name in the weapon stats goes back to the
       main stats properly now. The link was broken in the previous release.
- Fix: Bugs in the markers (Disconnects, Team Changes and Playername Merges)
       are fixed now, hopefully.
- Fix: Multiple games in the same log file which are incomplete games are
       detected properly now.
- Fix: Server changes/reconnects are detected now. If a server change is
       detected, the stats will be generated upto the point where server
       was changed.
- Fix: Score calculation has been fixed a little bit, still not 100% accurate.
- Fix: Fixed OSP warm-up detection bug when player readys up, disconnects,
       reconnects and then readys up again, before game starts.
- Fix: Fixed display of player names that ended with '^'.
- Fix: Player names with just spaces or invisible characters in them are
       clickable now. The player names of such "k3wl" people are marked with 
       a '_' to make them "unk3wl" like the rest of us.

- Mod: 'Frags' is replaced with 'Score'
- Mod: 'Score' is now displayed on the main player listing in CTF games.
       Its still not 100% accurate, but close enough?.
- Mod: Made the BLUE color a little brighter so its easier to read.


03 May 2001 - 3.0
-------------------

- Add: Complete stats for DM games. Lookin good!
- Add: Bloodlust award given to the player with most kill streak.
       For da horde!
- Add: Clan tag detection! The html files will now be named according to the
       clan tags in the player names.
- Add: Markers.
       Players that disconnected before the game ended are marked with x
       Players that were merged due to identical names are marked with +
       Players that rejoined a game are marked with a number beside name
- Add: Error warning for improper termination of program due to the fun-name
       ascii character 27 (Dont use that fun-name character!) in player name.
       If you need to generate the stats for a log file with this fun-name,
       then open the log file using a decent text editor and do a 'replace all'
       on that player name with something else, and run voodoo stats again.
       
- Fix: The last character in certain player names is displayed properly now.
- Fix: Map played is properly detected now.
- Fix: Better team detection for players in CTF.
- Fix: Fixed player name detection issues that occured in certain lines.
- Fix: Fixed points that were not calculated properly before due to suicides.
- Fix: Fixed errors that occured when total number of players exceeded MAX.
- Fix: Detects "was squished." and "does a back flip into the lava." as
       suicides now.

- Mod: The stats filename format has been changed to include date, time,
       game-id, mod-type, team-name, game-type.
- Mod: The executable name now includes the version number.
- Mod: Initial assumption of easiest prey and worst enemy is the player
       itself rather than the first player.
- Mod: Merged players with almost identical names.
       This is really an issue with the q3 log file, qconsole.log.
       This is a partial work-around which seems to be working so far.
- Mod: Stats are now generated in two seperate files. The weapon stats
       tends to get considerably large for big pub games and dm games. 
       Now the main stats is generated in a seperate html to reduce 
       download time. Weapon stats are still available on demand.
       This also introduces a problem. If you decide to rename the html
       stat files, then the links within the main stats html that point
       to the weapon stats html, will get broken. Hrms...
       If you do decide to rename the html files then you have to update 
       the html links manually to point to the renamed files.


24 Apr 2001 - 2.2
-------------------

- Fix: Kill Streak and Death Streak is fixed now, hopefully.

- Add: Alternate Stats for DM games (alpha).

- Mod: Generate html only if there are at least 2 players in game.
- Mod: Deadliness Points System tweaked.


22 Apr 2001 - 2.1
-------------------

- Bug: If a player name uses the 'fun-name' ascii character 27 (escape key),
       then the log file cannot be read properly. 

- Fix: Better OSP Warm-up time detection.
- Fix: Fixed a bug that occured when player name had the letters "ate" in it.
- Fix: detects BFG lines properly now. This was a bug that was introduced in
       the 2.0 release when i did a 'search and replace'.
       
- Mod: Skill Points System tweaked.


17 Apr 2001 - 2.0
-------------------

- Bug: Frags are still not calculated accurately. 
       The problem might be that Q3/OSP does not log all the defense/assist 
       points in client log.

- Fix: Various bugs in version 1.0

- Add: Map Detection based on player team chat messages.
       Supported maps - id ctf, threewave ctf, threewave compilation (selected 
       maps)

- Mod: Skill Points System tweaked.
- Mod: Ignore Stats Generation during OSP warm-up.
- Mod: Force Stats Generation for incomplete games.


13 Apr 2001 - 1.0
-------------------

- Initial Public Release


30 Mar 2001 - beta
-------------------

- Initial Public Beta

________________________________________________________________________________



================================================================================
Disclaimer/Legal mumbo jumbo:
================================================================================

Use this program at your own risk. Absolutely no warranty what-so-ever.
This program is free as long as its not for commercial use.
If you use this program for a sponsored/commercial event/website, you have to 
get consent from the author (myrdd1n@hotmail.com). Just let me know that you 
are going to use it, it should still be free ;).

________________________________________________________________________________
