Multiplayer Game statistics PHP script

[lch]

Hi, I have coded a little PHP script which displays some turn statistics for Dom3 multiplayer servers, so your users don't have to connect every time to look who already did his turn and who is still missing. After a fair amount of testing I'll release it on the public domain here. Documentation follows.

Originally I planned to use a network sniffer and connect to the server to get the info, but I quickly came to the conclusion that it's too much of a hassle and I can get most of the info from the directory structure alone. The script therefore has some limitations and workarounds, but does not depend on the patch level of the game at all. It should be backwards compatible to Dom2 and maybe even Dom1, too. Now I have even a network-based solution, but I still like this one and I think it's easier to set up for most people, too.

If you have any suggestions, questions, problems, then write about them here. If you want to see the script in action, then have a look at my game server or BigBopper's game server.

Update 1.01: Added new nations from patch 3.08
Update 1.02: Support for Mod nations added
Update 1.03: Added new nations from patch 3.10, fixed a bug with anchor tags introduced in 1.02
Update 1.04: Reads turn numbers directly - no need for the "makecheck" feature anymore, fixed some more things
Update 1.05: Added new nations from patch 3.14
Update 1.06: Renamed Gath nations to their appropriate era names Hinnom, Ashdod, Gath

[lch]

Open bugs:
- none

[lch]

New functionality that should be added:
- I should add a switch that updates the filestamp for the ftherlnd file to the current time, or by +/- X hours/minutes if supplied as an argument

[lch]

Here are the README's contents:
Code:

---

============

INSTALLATION

============



What is this all about?



  This is the ReadMe for a script which provides game statistics for a server

  of a Dominions multiplayer game: who is playing, who has already played his

  turn, and how much time is left till the next turn begins.



What do I need to use it? Are there any requirements?



  PHP 4 or 5 and a webserver which supports PHP. You must be able to use

  the PHP executable from the command line aswell as from the web server.

  You can get PHP at http://www.php.net/ if you already have a webserver,

  otherwise I'd suggest using http://www.apachefriends.org/en/xampp.html

  You'll have to make sure that this stuff is set up correctly by yourself.



How do I set up a turn statistics page for my Dominions 3 multi player game?



  First, place the stats.php and the other files in your web directory. This

  script does all the work. Second, create a configuration file for your game.

  This is done from the command line. Navigate to the directory with the

  stats.php. Then call "php stats.php <DIRNAME>" where <DIRNAME> represents

  the directory name of your savegame directory for the multiplayer game.

  For example: 'php stats.php "~/dominions3/savedgames/MyGame"' or

  'php stats.php "C:\Programs\dominions3\savedgames\MyGame"'. If the script

  finds a valid Dominions savegame directory, it will then create a

  configuration file for this game. This would be named "dom3_MyGame.inc.php".

  If you now access the stats.php by your webserver you should see the game.



Can I use the script for more than one game at a time?



  You can have multiple configurations, one for each MP game that you are

  hosting, in the same directory as your stats.php file is and the script will

  be able to manage them all simultaneously. Actually, I'd even encourage it,

  instead of using several copies of the stats.php for a few different games.



==================

GAME CONFIGURATION

==================



What can I do with the configuration files?



  Open the configuration file with a text editor. You can assign a couple of

  options concerning your game. There is a short description about them in

  the configuration file, too. Here is a more detailed description about them:



 - The $dir variable is a reference to your MP game directory. This should be

   correct. Unless you move the game directory, you won't have to change it.



 - The $hostinterval tells the script how long your server waits for incoming

   turns from the players before it hosts automatically. If you have set a

   host interval, you can specify it here. Possible values are, for example:

   "15 minutes", "6 hours", "1 day" or "2 days" - or in short, anything that

   can be expressed like this. If you have not set a host interval then you

   should leave this option untouched and assign the empty string to it: ""



 - The $showaiplayers variable is a switch that controls if nations not under

   control of a human player, i.e. those that the AI was given control of and

   those that started under AI control, are included in the statistics or not.

   If this variable is set to 0, these nations won't be shown in the turn list

   anymore. If set to 1, they show up as "controlled by AI" in the statistics.

   The script can't differentiate between players that have lost the game and

   those where the controls have been given over to the AI, unless you use the

   --scoredump option for your game, see the next paragraph. If you don't, the

   script will take either as that nation being controlled by the AI. In any

   case, those nation don't have to submit their turns anymore. The script

   can't detect which nations have been played by the AI from the start, too.

   You'd have to add these nations manually. More about this shortly, below.



 - The $showdefeated variable is a switch that controls if nations which lost

   the game, i.e. are nowhere present on the map anymore, are included in the

   statistics or not. To detect this, it is required that you host your game

   with the --scoredump option. If $showdefeated is set to 0, those nations

   won't be shown in the turn list anymore. If set to 1, they will show up as

   "lost the game" in the statistics. This variable has no effect if you don't

   have a scores.html in the game folder, generated by the --scoredump option.



 - The $serveraddress variable, if set, shows the hostname/ip and port of

   your game server and even displays the client parameters for the Dominions

   executable to directly connect to your server on start, if you move your

   mouse over the address. If you use the Microsoft Internet Explorer, it will

   automatically copy this to your clipboard, too. Set it to "<host>:<port>"

   or to "" if you don't want this information to be displayed at all.



 - The $players variable assigns the names of the players to the nations that

   they are playing. The order in which the players appear in the statistics

   is determined by the order in which they appear in the array. It also tells

   the script which nations are present in the game. Most of the nations can

   be detected by the script upon creating the configuration file, but not all

   of them: Those that started as AI won't get detected at all. If there is a

   nation missing, you have to add it yourself. For the nation keys, look at

   the end of the stats.php file. There is a $nations array which lists the

   keys and the nations that they are representing. Notice that some nations

   appear multiple times, since their key depends on the age in which the

   game is set. Add the nations that are missing so that the entry looks like

   the others that are already present. Don't forget the comma at the end.



===============

TROUBLESHOOTING

===============



When I try to access the script I only see a blank page!



  Maybe you are getting PHP errors but don't see them because your error level

  is not high enough. Put "error_reporting(E_ALL ^ E_NOTICE);" directly after

  the "<?php" line at the top into your stats.php and access the page again.



When I try to access the script I get a download dialog / see the source code!



  Your webserver has not been properly configured to support PHP. Fix it.



I get PHP errors when I try to use the script!



  Please make sure that you are using PHP version 4 or 5 by calling "php -v".

  If the error is in one of your configuration files, try fixing it with the

  aid of the error message (it should tell you in which line the problem is),

  or delete the configuration file and redo it from scratch.



I restarted the server and the time counter has been reset, but the script

doesn't recognize this. How do I reset the time counter for the script, too?



  On Linux: "touch ftherlnd" in the savegame directory. On Windows, you prolly

  would have to copy the "ftherlnd" file in another directory and then copy it

  back to the game directory, overwriting the original file by this.



The script doesn't display all of the players that are in my game!



  Please read the information about configuring the $players variable, above.



Players show up as "controlled by AI", even though they're out of the game!



  That's true, as you can read in the information regarding the $showaiplayers

  variable. You'll have to remove those players by hand from the players list

  or use the --scoredump option to detect defeated players, see the info for

  the $showdefeated variable. Another workaround would be to rename the names

  by hand if you want to keep them: You could add a "(defeated)" behind it, or

  strike out their names by using HTML tags: "<strike>Playername</strike>".



When switching styles it shows "Loading new stylesheet" and nothing happens!



  The stylesheets are on external servers and must be loaded by your browser

  first. During this time the loading dialog shows up. If some of the external

  servers are inaccessible, then this loading process might not finish at all.

  Try the next style and maybe reload the page, or reset to the default one.



The "Loading new stylesheet" message vanished, but the page looks quite bleak!



  Some of the stylesheets make heavy use of images. Those images have to get

  loaded after the stylesheet, and that might take a while. Wait some time for

  the images to load, if nothing happens use the next stylesheet and reload.



While switching through the styles my browser gives me some Javascript error!



  Are you using the Microsoft Internet Explorer? That browser only supports up

  to 32 style sheets. The script tries to circumvent that by reloading the

  page after 30 style sheets have been loaded, but if you switch through the

  styles too fast, then it might be possible that this workaround fails. Try

  reloading the page manually or get a better browser, like Mozilla Firefox...



=====================

FURTHER MODIFICATIONS

=====================



Can I add things like email addresses to the player names? Or avatar images?



  You can use full HTML for the player names. You could for example set it to

  something like this: "<a href='mailto:someone@there.com'>Player Name</a>".

  Make sure that you escape quotation marks (use \" instead of "), though.



Can I change the layout of the game statistics tables?



  It should be pretty straight-forward if you know how to use CSS (Cascading

  Style Sheets). There is one sample stylesheet being distributed with the

  stats.php file. I got the style "Revolucao etc" from the CSS Table Gallery

  at http://icant.co.uk/csstablegallery/ and just fixed some display problems.

  Have a look at the other styles, then you should be able to do your own one.



Some of the style sheets look weird in my browser. How can I fix them?



  If you know how to fix the styles, then you can add a fix to your stats.php

  file. Look at it, I already added a fix for the "Matrix?" style in there.

  You should add a new style element and put the rules that fix the display in

  there. The title has to be the same as the title of the stylesheet you want

  to fix, prepended by "(fix) ". If you find a new and working fix for one of

  the styles from the list, then please tell me. My contact info is below.



Can I disable the style sheet switcher ?



  I used to have a script named "stats-fixed.php" around which didn't use any

  other styles and was missing the code for the style switcher. However, since

  it didn't see any use by others, I discountinued it for sake of simplicity.



Can I have my turn status displayed for all games that I am participating in?



  You could create your own page which uses frames or iframes to display the

  status from multiple games in one window. The stats script sets HTML anchor

  tags for each nation: the statistics for nation Ulm can be accessed by

  adding an "#Ulm" to the URL, for example. If you set up your frames/iframes

  correctly, then you should be able to only display the one column on a page

  which is relevant for your nation and crop stuff that doesn't interest you.



=======

CONTACT

=======



I have an idea for a new feature, could you add it to the script?



  You have the source code, so you can implement it yourself. If you come up

  with something good or if you think that others would really benefit alot

  from something, then you could drop by the Shrapnel forums and write about

  it in the thread for this script or send me a forum PM.



I have a question and read through all this, but it hasn't been answered yet.



  See above: Post it in the thread on Shrapnel forums, or write me an email.



Your script rocks! I want to have your babies!



  I'm pleased to hear it. If you want to tell me about it, feel free to do so.

---

[Argitoth]

uhh... no replys?

I think this is frikkin awesome.

[Randvek]

Yeah, he's had this script running on one of the games we're both playing in, and it's pretty slick.

[sansanjuan]

Ich,
Nice work indeed!
-SSJ

[lch]

Well, yeah, this script was my very first and certainly most rewarding dom3-related programming experience so far. But it just so happens that just now I find the following switch in the Dom3 game help: Code:

---

--statfile      Create a player info file after each turn (stats.txt)

---

Was that always in there? That would have made the initial programming a little easier, I think.

Here's the easily parseable contents of one such stats.txt file: Code:

---

Statistics for game 'Test' turn 45



Arcoscephale is computer controlled

Ermor played this turn

T'ien Ch'i didn't play this turn

C'tis played this turn

Agartha played this turn

Helheim played this turn

Niefelheim didn't play this turn

---

The script now surpasses the functionality offered by this file. But to think that I could have just used this instead of reading from the file system and interpreting the results... and to think that I found the --scoresdump switch, but not this one... hehe

Maybe I will put this inside to be able to tell AI opponents and so on in a later version. This needs a rehaul, anyway.

[AStott]

Ich, thanks for this script. It's perfect for me. I did make one tweak that I thought I'd pass on as a feature suggestion.

I altered the script so that you can add an extra "player" parameter. When this is specified on the main page that lists all the games, it adds an extra column that indicates whether or not the specified player has a new turn available. The cell will be blank if that player is not in that particular game.

This is nice for when a player is in multiple games, because it means they can check whether or not they have a turn up without having to go and check each of the individual game pages.

I'd send you my code change, but frankly I kind of hacked it in, and I'm sure you'd implement it more cleanly than I.

[hunt11]

This makes checking out who has not played their turn, and how much time until the next turn starts makes checking the status of games really easy. Great job Ich