Winbolo.net Source Code

From WinBolo

The Winbolo.net source code is available under the GNU GPL version 2 and available to download via Google code.

Contents 1 Authors 2 Requirements 3 Design 3.1 Website 3.2 WBN Server 4 Protocol 4.1 Request Format 4.2 Response Format 4.3 Message Types 5 Trivia

Authors

Winbolo.net was created by

• John Morrison.
• Andrew Roth - Testing and addition functionality.
• Min - Testing and additional functionality.
• Killjoy - Website design.
• Wonka - Additional functionality.
• Adam Karas (aka Sheeps) - Additional functionality.
• Mettler - 3D tank renders.
• Matt - Logo's.
• Kirsty - Original Website design and ideas.

The forums use PHPBB version 2.0 (included)

Requirements

The requirements for running WBN are:

• PHP 4.3+
• Mysql 3.2+
• For log file uploads a small C application is required. See bin/splitter.c and www/wbn/zip.php
• For email aliases you must have access to created and deleting email aliases.

Design

The directories structure and purpose of each is as as following:

Path	Purpose
bin/	Email alias scripts and log file splitter helper program.
loguploads/	Destination for uploaded log files. Configurable in www/wbn/log.php
php/	Website includes and functionality. Typically stored outside the webserver document root.
www/	Website files
www/forum	PHP BB forum files
www/wbn	WBN Server files

The mysql database import file can be located in the root directory. The database import file contains the schema only and no data. For phpBB to work correctly an anonymous user of user_id -1 must be created. The news forum_id must match 5 to appear on the front page or recent news side bar. This can be changed by editing the inc/functions.php but it is hard coded in the SQL queries.

Website

The WBN website is built around phpBB.

phpBB provides the user session authentication and forums.

The site has additional tables containing statistics and game logs.

The majority of functions are located in the file php/functions.php

Map collection functions are located in the file php/mapcollectionfunctions.php

The design is that is as little code in the www directory as possible and it is included from the php/ directory. E.g. The playerinfo.php page:

$html_title="WinBolo.net: Player Statistics";
require "../php/header.php";
include "$BASE_FILES/inc_top.php";

$name = $HTTP_GET_VARS['name'];
$name = str_replace("\\", "", $name);

$pid = getPid($name);
if ($pid == 0 || $name == "Administrator" || $name == "Anonymous") {
        $error_body = "Player does not exist.";
        require "$BASE_FILES/inc_error.php";
} else {
        $player = getPlayerClass($name);
        $map = getPlayerMap($player->getId());
        include "$BASE_FILES/inc_playerdetails.php";
}
require "$BASE_FILES/inc_bottom.php";
?>

WBN Server

The WBN server is a set of PHP scripts located in the www/wbn directory. The wbn.php file is the main entry point to the application. It must live off the document root of the domain. The hostname or IP address of the server can be set in the winbolo.ini file. It is the "Host" parameter in the [winbolo.net] section.

The two important items for a game are the server_key which is a site unique key for identifying the game. Clients are identified by the player key. The purpose of the player key was to increase security of the players passwords. See the protocol section below.

The tables used by active games are:

• game_server - Details of each game include, host port, number of players. Similar data to an Information Packet The primary key to the table is the server_key
• active_player - Details each player in an active game linking the user table to their player key.
• game_event - Detail each event that happens in a game. If the player is not a WBN participant the client_key is set to NULL.
• active_team - A helper table for storing who is in what team at the end of the game. Used to determine if it is a valid team game and to assign points.

Upon completion of the game (or a timeout of not receiving any more data) the script wbn-gameend.php is called to calculate scores and move the game_server game_event to the archived_game_server and archived_game_event tables. The player key is replaced by the players user_id from the users table. The data is then removed from the game_event, active_player, active_team and game_server tables. The game_diary table will linked to the game via the game_diary table. The tables are split for performance purposes.

The log file may then be uploaded via the log.php file. You can saving log uploads by uncommenting three lines near the top of the log.php file.

Protocol

The protocol between sever/clients and WBN is via HTTP GET. The messages are sent as a URL encoded GET string to the wbn.php script that processes the request. For example

Request GET /wbn.php?data=0x010x000x000x01

The data is transmitted between the client/server and WBN is without encryption so all passwords are sent in clear text. For security purposes players passwords are never never transmitted to game servers and only to WBN. This is modelled off the 3rd party security model. The process for this is as follows:

1. Game server requests a server key from WBN on game start.
2. Client joins a game that has WBN participation and receives copy of the server key.
3. Client requests a unique player key for this game server key using the server key, user name and password from WBN.
4. Client sends player name and WBN player key to game server.
5. Game server validates player key with WBN before accepting they are a valid WBN player.

Request Format

All messages are formatted as follows:

• First byte - WBN major version number
• Second byte - WBN minor version number
• Third byte - WBN revision number
• Fourth byte - Message type
• Additional bytes - Message data

Response Format

The message responses are either:

1. Success - 0x01 byte immediately followed by the relevant data
2. Failure - 0x00 byte immediately by the error text

All HTTP headers sent back are ignored.

Message Types

The message types are defined in winbolo/wbn/winbolonet.h and are as follows:

Message	Origin	Purpose
WINBOLO_NET_MESSAGE_VERSION	Both	Version check and service availability.
WINBOLO_NET_MESSAGE_SERVERKEY_REQ	Server	Generates a server key to identify this game.
WINBOLO_NET_MESSAGE_CLIENTKEY_REQ	Client	Generates a game unique client key.
WINBOLO_NET_MESSAGE_VERIFYCLIENTKEY_REQ	Server	Verify the generated client key is valid for this game (server key).
WINBOLO_NET_MESSAGE_CLIENTLEAVE_REQ	Server	A game client (client key) has left this game.
WINBOLO_NET_MESSAGE_SERVERQUIT_REQ	Server	This server is shutting down.
WINBOLO_NET_MESSAGE_SERVERUPDATE_REQ	Server	Provides a list of events that have happened recently in this game. E.g. Pillbox capture
WINBOLO_NET_MESSAGE_TEAMS	Server	Provides a list of which players are allied. Sent just prior to a server win event.
WINBOLO_NET_VERSION	Server	Unusused.
WINBOLO_NET_LOCK	Server	The server has either become locked or unlocked to new players.

For more information on the content of any message see winbolo/wbn/winbolonet.c

Trivia

• WBN was modelled off Bungie Software's bungie.net match making and ranking portal created for the real time strategy game Myth: The fallen lords. (Bonus Bungie trivia: In the Marathon Trilogy special boxed set that included the map making contest results there was a Quicktime video hidden on the extra CD of maps. The video is of the developers working on the original Marathon game towards the end of the release cycle. Halfway through the video two of the developers take a break from debugging and play a game of bolo. One of them says: "We should just buy this game instead")
• This was my first PHP application. That's why its not layed out very well.