Pubserver Internals

This page is for discussion on everything needed to make the pubserver (in particular the Freeciv Pubserver) work how we
want it.
Note: there is now a fairly complete document to describe the present pubserver software, written by Reinier.
So keep the design and planning here, and the details of present states of affairs there.
Included here are server/pubserver protocols, things needed for a useful pubserver, things needed for a useful authserver, and anything else that anyone can think of. See Publite for details on a redesign of the basic scripts and server modifications necessary to run a pubserver. This page is dedicated to a useful pubserver rather than a functional one.
The main problems now are authentication, ranking, and post-game statistics.
=== Authentication ===
Most of what is needed for auth is done. Certain changes need to be made in order to have a robust authentication system. First, a webpage must be set up to changing passwords and contact information as well as resetting statistics. Second, the server and client need to be changed. The client GUI needs to be revamped to make it easier to create new users (and an additional email address field) and the server needs to be able to transmit a field to the client to display the URL of the website. Also, an option is to remove the flat-file database from the server and put the mysql code directly into CVS. Accompanying this must be a HOWTO on installing and running mysql.
Put a detailed list of client/server changes here:
* email address field in client
* website URL over network and displayed in client
* website URL shouldn't be compiled into server, but read in from commandline or by -r
=== Ranking ===
The glue between the actual system for ranking and what the server needs to record is specified here. The principal question which must be answered is: what is the relationship between a player and a user (the entity who is ranked)? A player in a game can have multiple users. A user may start a game with a particular player and then change players or leave and let the AI take over. What follows are the proposed conditions for ranking:
* For a game to be counted (the users involved are ranked), it must be completed. This means that there must be a victory condition of some sort. There has been much discussion about Allied Wins, but the conclusion is that one player must be alive and the rest are dead, or in the case of a team game, at least one member of a team is alive and the rest of the players on the other teams are all dead. 
* The game must have lasted a certain number of turns. This is arbitrary, but 25 is a good number.
* The first user attached to a player for X turns will be the user who is ranked according to how the player ends the game, where X is 10 (we will call such a user associated with that player).
* Although, it trends onto the actual system for ranking, it is important for the specific information which must be transmitted to the ranking program: only the fact of being alive or dead (being a winner or loser) matters in the ranking. Other factors such as civscore for a particular player, or whether a player launched to Alpha Centauri, or whatever else that happened in the game matters not a bit in the relative number of points that a user will receive from the game being ranked. (There is one exception which is dealt with next.)
* At most, only one player --- that is considered to be played by an AI --- will be counted among winners or losers. A player will only be considered to be an AI if no user was attached to the player long enough to be ranked (see above). This means that users cannot increase their ranking by beating lots of AI.
The third point is vitally important in determining the amount of information needed to actually rank. Once the decision is made, we can't go back and add additional ranking conditions and rerank all played games...
If the above conditions are accepted, then the minimum amount of information for a ranking script is:
* The number of turns a game lasted.
* A list of winners. These will be names of users associated with each winning player. AI players will be given a privileged name.
* A list of losers. These will also be names of users associated with each losing player. AI players will be given a privileged name.
An example flat file that might be output by the server to be parsed by the ranker:
 turns: 136
 winners: krakatoa
 losers: bob, joe, Karno, merlin, Unassigned, George, Unnassigned
There is implicit policy (with respect to ranking) in the server with this scheme: the file should be zero bytes, or not exist if the was not completed (in the interested of ranking, a draw would not be considered completed). Alternatively, another field could be added:
 completed: yes|no
Also, the lack of any other information means that this is all the ranking script needs to do the ranking. To compile a list of users, the policy of "number of turns needed to associate a user with a player" would have to reside in the server. In the proposed case, though, not all of the policy is determined in the server. The ranking script would determine if the requisite number of turns has been played (25) and would also remove all but one AI from each winner and loser list.
N.B. Also, we have implicit policy regarding user naming. In this example, the comma (,) would have to be forbidden in usernames as it is the record separator.
A way to do this would be to add fields to the player struct: player.ranked_user which would be initialized to ANON_USER_NAME and player.ranked_user_turns initialized to 0, then on each turn:
 players_iterate(pplayer) {
 if (pplayer->ranked_user_turns++ > TURNS_NEEDED_TO_RANK 
 && strcmp(pplayer->ranked_user, ANON_USER_NAME) == 0) {
 sz_strlcpy(pplayer->ranked_user, pplayer->username);
 pplayer->ranked_user_turns = 0;
 }
 } players_iterate_end;
 
 where
 
 #define TURNS_NEEDED_TO_RANK 10
 
 also pplayer->ranked_user_turns must be reset whenever another user takes over control of the player
=== Post-Game Statistics ===
Games played on pubserver can be reviewed and "replayed". Currently this can be done via http://pubserver.freeciv.org/viewgame.phtml.
In order to accomplish this, certain data need to be saved postgame for processing. Currently the gamelog, scorelog, timeoutlog, and savegames once a turn are necessary to create the data displayed.
The current system of post-processing a game on pubserver is [overly] complex and perhaps not worthwhile to explore. What we want is a list of statistics and such that would be useful/nice to have and simplify the machinery on pubserver to accomplish it. The machinery now is quite fragile.
Things that we want for game review:
* a game replay (animated gif of map)
* a set of graphs that give a good idea of game progression.
Also, currently, there is an HTML rendering of the gamelog which has tech and wonder progression for each player. This author thinks that we could dump that.
In order to get a game replay, we would need a set of savegames (or semi-processed map data) for each turn. Currently, a C program based on server code parses the set of savegames and outputs for each turn a .ppm [image] file where each player is given a color for his cities and units and land and ocean are given the colors black and blue. A set of scripts then transforms the ppm into an animated gif suitable for viewing. This part of post-processing is the most fragile, and consumes a large amount of processor time and disk space. The server itself should be modified to do some or most of this postprocessing. At the minimum, it should output the set of .ppm files. That removes the requirement of creating a separate savegame on each turn. I haven't looked at it recently, but the color selection process is also a bit complicated. This could definitely be simplified.
For the set of graphs, we need a file that has game data for each player for each turn. Example game data: amount land within borders, population, number of units or cities or techs, etc. It would also be nice to see when a particular player changed controllers. A possible file format might look like:
 <turn number>
 # Player User CivScore LandArea Cities Units Techs Population
 <plrname0>, <username0>, <int>, <int>, <int>, <int>, <int>, <int>
 <plrname1>, <username1>, <int>, <int>, <int>, <int>, <int>, <int> 
 <plrname2>, <username2>, <int>, <int>, <int>, <int>, <int>, <int>
 ...
 
 <next turn number>
 # Player User CivScore LandArea Cities Units Techs Population
 <plrname0>, <username0>, <int>, <int>, <int>, <int>, <int>, <int>
 <plrname1>, <username1>, <int>, <int>, <int>, <int>, <int>, <int> 
 <plrname2>, <username2>, <int>, <int>, <int>, <int>, <int>, <int>
 ...
which would be easily parseable. This flat file would replace the gamelog and scorelog and be called the gamelog.
Category:Pubserver