WarWorld protocol

1. Introduction

The current client-server architecture is very thin-client. This implies lots of communications and very few client-side tasks.
The protocol is currently text based, for debugging reasons (it is easy to connect to the server with telnet and type commands by hand).
The server tick during the game is 0.1 seconds by default, so the clients should be done with any drawing in this time. However, there is a simple synchronization that allows clients to run a bit slower.
Data representation

The message parameter fields are separated by one whitespace character.

The messages terminate in newline character (not in \0). (The reason for this newline-termination is to make server-debugging with telnet or other text-based tools easier.) Many messages may be buffered and sent together in one packet. The socket protocol may break up messages to several input buffers, so the client should expect this and use internal buffering.

Coordinate values: 16 bits. Floating-point values are represented with 10 bits above the decimal point and 5 bits below (conversion is done simply with int(x*32) and x/32.0). The most significant bit is for the sign (we want to have negative coordinates for aeroplanes making curves and such). Thus we can have a 1024x1024 square map with 32x32 pixel map squares.

Angle values: an angle is represented as an integer value between 0 and 255. Winds counterclockwise from the x-axis. These values are not used in any translation calculations. The purpose is merely to give the engine information about how to draw units onto the screen.

Rough communication example.

2. Connection initialization and termination

2.1. Server-to-client messages

Connections are accepted any time during the game. A future option might be creating a lobby system for synchronized launching.

VER varsionid
Server version number; a dot-separated list ''major.minor''.

PLR playerid ipaddress name
This broadcast message tells clients about a (new) player with given playerid and IP address. Note that the message may be resent in a case where the player changes nickname.

playerid (integer) is a unique identifier for the player. It starts from 0. When a player leaves, the id will remain unused, but another connecting player may get the same identifier.

ipaddress (dot-separated string): IP adress or a resolved address.

name: a nickname with no space characters.

LCH

Notifies the clients that the game has started. Only player with playerid=0 (the first connecting player) can cause this by sending LCH command to the server (see below).

QIT playerid
Tells that the player has disconnected from the game.

2.2. Client-to-server messages

PLR name
Tells the player's nickname to the server. The client must send this message immediately after connecting to the server, and after that, a RDY command (see below).

LCH

Launches a game. Only player with playerid=0 (the first connecting player) can actually launch the game. If some other player does it, the server knows that the player is ready for launch.

QIT
The client wants to disconnect. The game doesn't crash if the client just disconnects, but this is a polite way.

3. Messages during the game

3.1. Server-to-client messages

INI
New game cycle. Not sent before the game launches.

END
End of data. Sent after all cycle data has been sent.

RES amount
Tells how much building resources the player has left (a floating-point value)

NEW playerid unitid classid
Tells that the given unit has moved or turned around, and reports the new location and orientation. Note that the unit can be an entirely new unit.

unitid (integer): a unit identifier.

classid is the unit class ID of the new unit. Currently they are hardcoded as: 0=Tank and 1=TankFactory.

POS unitid x y orientation [cannon_orientation]
Tells that the given unit has moved or turned around, and reports the new location and orientation. Note that the unit can be an entirely new unit.

x, y (float): current location of the vehicle measured as map grid units. The locations of the vehicles are measured at their center. A round value such as (4.0,8.0) would mean that a unit is at the center of a map square. Half-value (4.5,8.0) would mean that it is exactly between two squares.

orientation: (int 0..255) facing direction (0 = up)

cannon_orientation: (int 0..255) cannon direction (0 = same as unit direction). Not used currently (cannons use AIM).

Note: The classid is redundant. It might be more efficient to tell about new units and their unitclasses with a separate command.

WPT unitid x y
Tells client an estimated temporary waypoint for a unit. These are not necessarily actual waypoints commanded by player, but temporary short-range points calculated by the server.
WARNING: This information is a security risk.

SHT unitid x y
The given unit shoots at the given coordinates. The client is expected to display a shoot-animation. The client should expect that the unit can do something else in the next game tick (after approx. 0.1 seconds), so whatever animations it does, they should take this into account. Note that the target coordinates may be outside the screen.

HIT unitid hits_remaining

Unit has been damaged. hits_remaining is value 0-100 percentage of hit points remaining.
If hits_remaining is 0, the unit is destroyed. The client may display explosion animation and deallocate the unitid.
NOTE: The unit ID can be reallocated by the server immediately after this message, so the client should not rely on the unit ID any longer. (This behaviour could be eased somehow, if it causes trouble.)

SCR playerid0 score0 died0 playerid1 score1 died1 playerid2 score2 ...
Reports the current kill-score situation for each player.

score# (integer): number of units destroyed by the player #.

died# (integer): number of units destroyed from the player #.

SEL playerid unitid1 unitid2 unitid3 ...

Tells what units a player has currently selected.
NOTE: This is temporary feature for implementing the interactive cannon-aiming. It should be replaced by some smart mechanism later.

AIM playerid x y
Tells the client where a player is currently pointing with mouse.
The command is currently relayed to other clients so that they could turn the cannons of the selected units at the mouse location. THIS IS UNSECURE FEATURE! It has to be implemented more securely in future versions of the game.

SAY playerid message
A text message sent by another player.
NOTE: Client doesn't really have to implement this yet.

ERR num message
Tells an error message to the client. Client might, for example, like to write it to a message box, or whatever.

num: error number

message: free-formatted error message in English

3.2. Client-to-server messages

RDY

A syncronization message that tells the server that the client is ready for the next game cycle. The client should send it after it has finished all drawing for the current game cycle.
(not in use yet: timeout for synchronization is 5 seconds. If some client in the game doesn't report to be ready during this time, it is dropped out of the game.)

SEL unitid1 unitid2 unitid3 ...

Creates a unit group. The client creates such a group typically when making a group-selection with the mouse. Moving such a group, instead in individual units, might be coordinated in some way, and perhaps even use formations, but such behaviour is not currently implemented.
Currently the server maintains internally group objects that control common commands for a group. The client does not, however, have to care about these internal groups.
NOTE: In future there would need to be named, external groups. Currently the client could implement client-side named grouping (typical Alt+1-key-style group selection), but server-side named groups could be used for more elaborate command structures.
NOTE2: The selection list for one client is currently relayed to other clients for the use of AIM. THIS IS UNSECURE FEATURE! It has to be implemented more securely in future versions of the game.

unitid1, unitid1, unitid1, ...: unit identifiers.

AIM x y
Tells the server where the player is currently pointing with mouse. The location is used as parameter for various unit commands (MOV,SHT).
The command is currently relayed to other clients so that they could turn the cannons of the selected units at the mouse location. THIS IS UNSECURE FEATURE! It has to be implemented more securely in future versions of the game.

MOV queue_cmd

Add movement order to unit's command queue.

queue_cmd (0 or 1): tells whether to enqueue the command (1), or to clear the command queue and enqueue the command as the first entry (0).

x, y (float): waypoint coordinates

SHT queue_cmd n
Add fire order to unit's command queue. Units can currently aim only at ground coordinates, not at units.

queue_cmd (0 or 1): as above.

x, y (float): target coordinates

n = number of shots; n=-1 permanent fire command

BLD classnid queue_cmd n
Add building order to the command queue of a factory unit.
NOTE: unitid of the factory is taken from selection!!!!

classid (string): unit class ID of the units to be built (0=Tank, 1=TankFactory).

queue_cmd (0 or 1): as above.

n = number of such units to be built

Notes

Playerids and unitids are currently in the same number space. However, ids 0-15 are reserved solely for player objects. (This numbering has some far-fetched reasons.)

References

Earlier protocol propositions:

Last modified: Tue Feb 1 10:20:53 EET 2000