PROTOCOL Purpose This document describes the protocol for the Galax game ("Galax protocol"). Version The current version of the Galax protocol is 0.3. This protocol is quite incompatible with protocol versions prior to 0.3. General All commands consist of four letters and a space-separated list of arguments. Each command is terminated by the sequence \r\n (carriage return, newline). Handshake Protocol version is an ASCII string, and protocol versions may be lexically compared (e.g. "1.0a" > "1.0" and "1.1" > "1.05"). and are strings which may contain spaces, because they are always the last arguments on a line. The strings are not delimited in any way. Arguments There are two types of arguments: tagged arguments, which are of the form `=', where the names of the properties are command-specific; and separate arguments, which have free form. Separate arguments are currently only used for messages, descriptions, etc. Common properties The following property-names are used often where they are rather unambiguous: g for the id of the game which the command concerns; p for player (but currently there is nothing you can do on somebody other's account); and i for planet-id. Extensibility Unknown commands and arguments should be ignored. Separate arguments intermixed with tagged arguments should be ignored. A protocol that will break client behaviour even if it honours these rules will be given a new next-to-major version (0.4 or higher). Handshake (independent of the protocol version) Client Server ------ ------ Makes a TCP connection to port 42529. Establishes connection. <-"GSRV

" "GCLT

"-> Continues according to . Multi-protocol clients should choose the highest protocol version not higher than that of the server. Protocol phases Client Server Explanation ------ ------ ----------- -- Initialisation < CLOK Tells that the handshake is OK. < BGML Tags the beginning of game listing. < GAME This is sent for every open (joinable) game. < CFLD This is sent for every field the game contains. < EGML Tags the end of game listing. < SLCT Prompt for client to select game. Even after the SLCT prompt, new games are broadcasted to those who have not yet joined. JOIN > < OKAY The client tells which game it wants to join and what it should be called in that game. If no such game exists, a new one is created. < GOWN Tells the owner of the joined game. Also tells the id of the game in case it is newly created. < PLYR Gives information about the players in the game. Upon joining, a list of these is generated; after that, whenever a player joins the game, a PLYR is generated. < PLNT Because each joining player causes a new planet on the map, these are broadcasted whenever a player joins. FILD > < OKAY If the owner wants to alter field parameters. The protocol remains in this state until the game owner starts the game. PGAM > < OKAY < TIME This tags the beginning of time(tm). < GFLD Gives the final field parameters for each field. < PLNT For each planet. -- Beginning of a turn < TIME Tags the time to which the following stats apply. < PIND < PSHP These are sent for each known planet. < YEAR < BRND These tell that it is okay to begin making moves. -- Move phase MESG > < SAID Optional. To send broadcast messages. SUIC > < PKIL Optional. To quit playing but remain watching. QUIT > < KILL Optional. To quit playing and break connection. < WINN Sent if there is only one player left. MOVE > < OKAY For every move the player wishes to make. < MVOK DONE > < OKAY When the player is done with the moves. < PDON Sent for every player that is already done. < ERND Tags the end of move phase. -- Battle phase These are sent for every battle on a known planet: < TIME Tags the time when the battle takes place. < BATT Tells battle parameters. < BSHP Tells the number of ships on both sides. < ATTK Send for battle participants for each attack. < BSHP Battle statistics - number of ships. < BWIN < PLNT Broadcasted to tell about the possible change of ownership to every player. < PKIL Sent if the player has no planets nor ships left. < WINN Sent if there is only one player left. These are sent for every fortification: < TIME Tags the time of the fortification < FORT Fortification parameters. After these events, the usual turn-start information is sent. -- Error messages < ERRC Sent if the command syntax is incorrect. < ERRP If the operation is not permitted. < ERRS If there's a server-side reason for the error. Command parameters Client-side JOIN g: the id of the game to join. name: what the client wants to be called in this game. Separate arguments: Long description for the client. FILD g: the id of the game which contains the field to alter. x: requested width of the field. y: requested height of the field. pl: requested number of additional planets for the field. PGAM g: the id of the game the state of which will be changed. type: "S" for starting, "C" for closing. MESG Separate arguments: the message to send to others. SUIC Separate arguments: reason(tm) for the suicide. MOVE from: the planet from which the player sends the ships. to: the planet towards which the ships are destined. s: the number of ships the player wishes to send. Server-side OKAY cmd: describes the command for which this OKAY is sent ERR_ cmd: same as in OKAY Separate arguments: explanation of the error PDON, KILL, WINN p: the id of the player GOWN g: the id of the game p: the id of the owner PLYR p: the id of the player name: the name of the player Separate arguments: the description of the player GAME g: the id of the game owner: the id of the owner name: the name of the game(tm) Separate arguments: description of the game (player list) YEAR, TIME y: the time in years, with 3 decimal places PKIL p: the id of the player Separate arguments: explanation for the death CFLD g: the id of the game in which the field resides x: the width of the field y: the height of the field name: the name of the field (usually empty) pl: number of planets in the field GFLD same as CFLD. PLNT i: the planet id owner: the id of the owning player (0 for independent) x: the location on the horizontal axis y: the location on the vertical axis PIND i: the planet id indust: the industry level of the planet PSHP i: the planet id : number of that player's ships on the planet MVOK remain: the number of ships remaining on the planet eta: time of arrival, in years, with 2 decimal places SAID sayer: the id of the player saying the message Separate arguments: the message of the player BATT i: the id of the planet where the battle takes place att: the id of the attacker def: the id of the defender surprise: whether the attack is a surprise attack BSHP i: the id of the planet where the ships are : the number of ships for that player ATTK who: whether the original attacker or defender shoots change: number of ships shot BWIN i: the id of the planet winner: the id of the victorious player FORT i: the id of the planet where the fortification happens new: the number of new ships on the planet : number of that player's ships on the planet