SUBJECT:
==============================

This small "snippet" like thing can be used to create graphical graphs of
how many players that are online the game for your website.

It displays 4 different graphs:

- Daily' Graph (5 Minute Average)
- Weekly' Graph (30 Minute Average)
- Monthly' Graph (2 Hour Average)
- Yearly' Graph (1 Day Average)

This snippet should probably NOT be used by complete newbie mud coders.
You should know atleast something about programming and knowing your way
around your mud before trying to install this.

There are not fully instructions on how to get this to work. Some of the
instructions are in "pseudo" code, which means you have to implement it
yourself into your game's codebase.


REQUIREMENTS:
==============================
- You must have the mrtg tool on your server. Mrtg can be downloaded
  from:

  http://people.ee.ethz.ch/~oetiker/webtools/mrtg/

  To check if your server has the mrtg tools installed you can simply
  type "mrtg" in your shell (should work if it is in your path...). Otherwise
  you must check in all the /sbin and /usr/local/bin  directories etc for the
  mrtg executable and add it into the path of the user that is running your
  mud.

- You also need to have access to a webpage on the same server as your
  mud is running, else this will not work.


CREDITS:
==============================
You don't need to give credits for using any of the following material,
except if MRTG has some credit licence on their own...

HOwever, it would be fun if you could send a small mail to hephos@sharune.com
with a link to your game's graphs.

Also, if you figure out a better way to accomplish the same graphs through
mrtg or any other graphing system, please let us know.

/Emil Nilimaa aka "Hephos" (www.sharune.com)


HOW IT WORKS
==============================
Your game writes the number of players to a file (player_stats). Then it runs the
mrtg command with the system("") function. Mrtg will take care of the rest. The
mrtg tool will use the mrtg_player_stats compiled binary script to open the 
player_stats file and read the amount of players that is online.

The mrtg_player_stats file has been compiled from the mrtg_player_stats.c source file.
If you need to do any changes, just modify it as you wish and recompile it.


HOWTO
==============================

1. Make sure you have the mrtg tool installed on your server.
   If it is not installed you can download it from:
   http://people.ee.ethz.ch/~oetiker/webtools/mrtg/

2. In this step you will copy some files to some directory in
   your game's libraries.
   
   Suppose your mud is residing in the directory:
      
      /home/yourmud/

   Perhaps your mud has a lib/ directory. It would be good
   to set all the files needed for the mrtg graphs under this
   directory (but you can place it anywhere you want, just remember where :P).

   Create the following directory (/mrtg somewhere inside your game).

      /home/yourmud/lib/mrtg/

   Now copy all the files included in the mrtg_graph.zip into that dir.
   They are:
   
      mrtg.cfg
      mrtg_player_stats.c
      mrtg_player_stats
      player_stats

3. Open the mrtg.cfg file.

   Change the first line which looks something like this:
      
      WorkDir: /var/www/html/mrtg_stats
   
   To a directory that suits your webserver. This is the directory
   where all the mrtg html and image files will be created. If the directory
   does not exist, you must also create it.

   Now look at the second line, which looks something like this:

      Target[players]: `/home/yourmud/lib/mrtg/mrtg_player_stats`

   Here you must change the path to the correct path pointing to the
   mrtg_player_stats script inside your mud libs.

   You can then look at all the other lines in the file and change them to
   what seems to suit your game and webpages.

4. Now you need to modify some code in your game. You need to add a loop
   that counts the number of players online your game into your game's
   "heartbeat". You need to create a function that is executed every 5 minutes
   from the heartbeat.

   The function should do the following (notice that this is not real code, you
   need to write your own code for this).

   void mrtg_update()
   =======================================================
   FILE fp;
   int online = 0;
   
   loop through all your online players{
     online++;
   }
   
   if (!(fp = fopen("/home/yourmud/lib/mrtg/player_stats", "w"))) {
       log("SYSERR: MRTG: Can't write to the temp player_stats.");
       return;
   }
   
   fprintf(fp, "#%d", online); // write number of players online.
   fclose(fp);

   // start mrtg... and update the stuff
   system("mrtg /home/yourmud/lib/mrtg/mrtg.cfg &");
   =======================================================

5. You should be done... :P Try run your game.

   Notice that you need to be able to use the mrtg command from the
   shell for this to work. It must be in the path (which it should after
   it has been installed).

   You can also test if this works by simply using the command from the shell:

   > mrtg /home/yourmud/lib/mrtg/mrtg.cfg &



Have fun!

Emil Nilimaa aka "Hephos" <hephos@sharune.com>
http://www.sharune.com
http://www.mythicscape.com