Dominate:ProtocolFrom WackyWikiDominate:Protocol
COMMUNICATION BETWEEN THE DOMINATEGAME SERVER AND DOMINATEGAME CLIENTS IntroductionThis document describes the way the DominateGame.com game-server communicates with its clients. At the current moment there is only one client: the Java applet that is on-line available at http://www.dominategame.com. This document should make it possible for application developers to create their own DominateGame clients, like end-user programs like the applet, and robots.
Future changesBoth this document, and the protocol it describes, may be altered in the future. Because of these future changes clients that are based on this document may become incompatible with the server.
Approval for new clientsNew clients need the approval of the maintainer of the DominateGame.com website before they are allowed to connect with the server. It is not allowed to make and/or distribute DominateGame.com applications without this approval. Clients without approval can be banned from the DominateGame.com server either by banning the client's IP-address or by changes to the communication protocol that is described in this document. Such changes would make the client useless.
Internet address of the serverThe DominateGame.com server runs at www.dominategame.com, port 8822. The client and the server communicate over a TCP/IP connection that is initiated by the client.
Format of messagesWhen a TCP/IP connection is established between the client and the server, they start to communicate using binary messages. A message is a structure that contains data that is transfered from the client to the server, or from the server to the client. A message contains zero or more message-elements. The number of elements is stored in a numeric value in the first four bytes of a message. This numeric value is stored in network-byte-order. The following example shows a message with three elements. The first four bytes contain the value "3" in network byte order. +--------+--------+--------+--------+ | NUMBER OF ELEMENTS (4 bytes) | +--------+--------+--------+--------+ / / / ELEMENT 1 (variable size) / / / +-----------------------------------+ / / / ELEMENT 2 (variable size) / / / +-----------------------------------+ / / / ELEMENT 3 (variable size) / / / +-----------------------------------+
Type 0 - Numeric message-element Type 1 - String message-element Type 2 - Binary message-element
+--------+--------+--------+--------+--------+ | 0 | 7 in network byte order | +--------+--------+--------+--------+--------+ String and binary elements differ from numeric elements. The next four bytes of string and binary elements contain the length of the string or the size of the binary buffer. A string is made up of byte-sized characters. There is no support for unicode characters. The final byte of a string must be a null character. The size or length is stored in the next four bytes in network byte order. After these four bytes the actual string or buffer is stored. The following example shows a message-element with the string "HELLO": +--------+--------+--------+--------+--------+ | 1 | 6 in network byte order | +--------+--------+--------+--------+--------+ | H | E | L | L | O | +--------+--------+--------+--------+--------+ | null | +--------+
+--------+--------+--------+--------+--------+ | 2 | 3 in network byte order | +--------+--------+--------+--------+--------+ | x | x | x | +--------+--------+--------+
Thus, a message starts with four bytes in which the total number of elements is stored. Each element starts with a byte containing the element-type. Numeric elements then have four bytes for the actual value of the element, while string and binary elements use four bytes to store the size of the buffer followed by a variable sized buffer. The first message-element is ALWAYS a numeric value containing the "opcode" of the message. After the opcode the message contains a variable number of elements with relevant data. The remainder of this document describes the format of the different messages. This document uses keywords for opcodes like LOGIN and COUNTRY. The actual numeric value of these keywords can be found in an appendix.
Loggin onWhen the connection to the server is established, the server sends a START message. The client should respond with a LOGIN message in which the login information is sent. After this message the server sends either a FAILURE or SUCCESS message. Message from: Server
Opcode: START
Description: Connection is established, the client should send a LOGIN
message.
Message from: Client
Opcode: LOGIN
Parameter: Username [string]
Parameter: Password [string]
Parameter: Version [numeric]
Description: This message is sent after a START message is received. The
supplied username and password must have been registered and
activated at www.dominategame.com. The version is a numeric
value containing the release of the communication protocol.
The current release-version is 2. This number will be
increased when the protocol that is described in this
document is changed.
Message from: Server
Opcode: SUCCESS
Parameter: Nickname [string]
Description: The login attempt was successfull. The nickname should be
stored by the client as the actual nickname. It's possible
that this nickname differs from the nickname that was sent
with the LOGIN message, because the server automatically
repairs nicknames with invalid characters like spaces.
After the SUCCESS message a lot of other messages are sent
by the server to initialize the client. These messages are
described in other sections of this document. The
initialization is over when a NEWUSER message for the client
itself is sent.
Message from: Server
Opcode: FAILURE
Parameter: Reason [numeric]
Description: The login attempt was not successfull. The reason parameter
explains what went wrong:
0 - An invalid nickname was entered.
1 - There is already someone with this nickname logged on.
2 - The nickname already exists in the database (not used).
3 - You are banned.
4 - The nickname could not be registered (not used).
5 - Wrong password entered.
Reasons 2 and 4 are used for on-line registration via the
server. This is not implemented, users should register via
http://www.dominategame.com.
The client is allowed to re-send a LOGIN message after this
message.
Message from: Server
Opcode: UPGRADE
Description: It would have been better if this message was part of the
FAILURE message. It is sent when the client could not log
on because it supplied an invalid version-number.
Keeping the connection aliveOnce in a while the server checks if all connected clients are still alive by sending "PING" messages. The clients should respond with a "PING" message. Message from: Server
Opcode: PING
Description: The server checks if the client is still alive. The client
should answer this message with a PONG message. If it fails
to answer this message before a certain time, the client is
disconnected from the server.
Message from: Client
Opcode: PING
Description: Answer to PING message from server.
Some "technical" messagesSome messages cannot be placed in other categories: Message from: Server
Opcode: CLOSED
Description: The server is closing down, no new games can be started
by the client. The client should disconnect from the server
and make a new connection for new games.
Message from: Server
Opcode: QUEUE
Parameter: Position in the queue [numeric]
Description: When there are too many connections to the server, new
clients are places in a queue. When someone else logs off,
he or she is replaced by the first client from the queue.
The parameter specifies the position in the queue.
The user databaseThe DominateGame server keeps track of all users who are logged on. This information is shared with the clients so that the clients can also display the list of people who are on-line Message from: Server
Opcode: NEWUSER
Parameter: Nickname [string]
Parameter: Hostname [string]
Description: A new user logs on. The nickname and hostname of the user
are supplied in the parameters. This message is only sent
once for each user right after the user logs on, or right
after the client has logged on and the server is
initializing the client. When a NEWUSER message is received
with the nickname of the client itself, the initialisation
is over.
Message from: Server
Opcode: USER
Parameter: Nickname [string]
Parameter: Rating [numeric]
Parameter: Number of games [numeric]
Parameter: ID of the game in which the user is a player [numeric]
Parameter: ID of the game in which the user is an observer [numeric]
Parameter: Is this user a member? [numeric]
Parameter: Smilie [string]
Parameter: Unknown, needs reverse engineering. So far the value has always been 0 [numeric]
Parameter: Unknown, needs reverse engineering. So far the value has always been 0 [numeric]
Parameter: The level of the user [numeric]
Description: This message is sent every time something changes with the
state of a user. Only one of the game-parameters can be
valid. A valid game-ID always refers to an existing game.
Message from: Server Opcode: ENDUSER Parameter: Nickname [string] Description: This message is sent when a user logs off. The game databaseThe server also keeps the client informed about all existing games. These are games that are running, waiting for players or that are already finished. Message from: Server
Opcode: NEWGAME
Parameter: Unique ID [numeric]
Parameter: ID of the map [numeric]
Parameter: Name of the map [string]
Parameter: Nickname of the creator of the map [string]
Parameter: Place before attack? [numeric]
Parameter: Capitals? [numeric]
Parameter: Timeout in seconds [numeric]
Parameter: Allow players with same hostname? [numeric]
Parameter: Replace lost players with robots? [numeric]
Parameter: Increasing value for cards? [numeric]
Parameter: Hide cards for other users? [numeric]
Parameter: Disable whispering? [numeric]
Parameter: Blind map? [numeric]
Parameter: Min. number of humans [numeric]
Parameter: Min. rating [numeric]
Parameter: Max. rating [numeric]
Parameter: Allow gifts? [numeric]
Parameter: Receive cards of defeated players? [numeric]
Parameter: When timer expires [numeric] 0=kick, 1=kick if player was inactive, 2=end turn
Parameter: Only players of the same level? [numeric]
Parameter: No robots in the game? [numeric]
Description: This message is sent when a new game is created, or when
the client is initializing. It contains all information
about a game.
Message from: Server
Opcode: GAME
Parameter: Unique ID [numeric]
Parameter: Nickname of operator [string]
Parameter: Is the game running? [numeric]
Parameter: Number of connected clients [numeric]
Parameter: Number of players [numeric]
Parameter: Number of robots [numeric]
Parameter: Number of disconnected players (ghosts) [numeric]
Description: This message is sent when the current state of a game
changes. The unique ID always refers to a game for which
a NEWGAME message was already sent.
Message from: Server
Opcode: ENDGAME
Parameter: Unique ID [numeric]
Description: A game is removed from the server, because all players have
left the game.
Chatbox communicationThere are three different chatboxes and it is also possible to send private messages to other users. This section describes the format of the relevant messages Message from: Server
Opcode: GLOBCHAT
Parameter: Nickname [string]
Parameter: Message [string]
Description: The user with the specified nickname sends a message to the
global chatbox.
Message from: Server
Opcode: GAMECHAT
Parameter: Nickname [string]
Parameter: Message [string]
Description: The user with the specified nickname sends a message to the
chatbox of the client's current game.
Message from: Server
Opcode: MEMBERCHAT
Parameter: Nickname [string]
Parameter: Message [string]
Description: The user with the specified nickname sends a message to the
chatbox of the members.
Message from: Server
Opcode: WHISPER
Parameter: Nickname [string]
Parameter: Message [string]
Description: The user with the specified nickname sends a private message
to the client.
Friend- and enemylistsMembers can maintain their own friend- and enemylists. This section describes the messages that are sent between the client and server to initialize those lists and to add and remove entries in the lists. Message from: Server
Opcode: MASK
Parameter: Mask [string]
Parameter: Type [string]
Description: When the client is initializing, the server sends the
friend- and enemylist. Mask is the literal mask that was
entered by the user on an earlier occasion. Type is either
"friend" or "enemy".
Game communicationThe client can be in one game at a time. Apart from the information the server sends in the NEWGAME and GAME messages, additional information about the state of the client's current game is sent. This section describes all communication that is relevant for the game-play. A game has up to six players. The players are numbered 0 to 5. Messages about players always include the ID of a player. This ID is thus in the 0 to 5 range. Message from: Client
Opcode: WATCH
Parameter: Game ID [numeric]
Description: This message is sent to inform the server that this client
wants to watch this game. The server will then send the client
all messages about this game.
Message from: Client
Opcode: PART
Description: This message is sent to inform the server that this client
wants to stop watching the current game. A client has to send
this message before being able to watch another game.
Message from: Server
Opcode: PLAYER
Parameter: Player ID [numeric]
Parameter: Robot player? [numeric]
Parameter: Nickname [string]
Description: This message is sent to inform the client that a certain
position is occupied by a certain player. When the robot
parameter is not 0, the robot player with the supplied
nickname has entered the game. Otherwise a normal client
enters the game on the supplied position.
Message from: Server
Opcode: REPLACE
Parameter: Player ID [numeric]
Parameter: Nickname [string]
Description: A human player has left the game and is replaced by a robot
player. The nickname parameter specifies the nickname of the
new robot.
Message from: Server Opcode: ENDPLAYER Parameter: Player ID [numeric] Description: A player leaves the game or is defeated. Message from: Server
Opcode: COUNTRY
Parameter: Country ID [numeric]
Parameter: Player ID [numeric]
Parameter: Number of armies [numeric]
Description: The current state of the map has changed. The new owner and
the number of armies is specified in the parameters. The
playerID can be invalid in blind-map games. In that case the
owner of the country and the number of armies is unknown to
the client.
Message from: Server
Opcode: INIT
Parameter: Number of armies [numeric]
Description: The game has just started and all players should pick their
capital and place initial armies. The number of armies each
player is allowed to have is specified in the parameter.
In case of a capital game, the client first needs to place
it's capital. The client should answer with a CAPITAL
message and a number of PLACE messages.
Message from: Server
Opcode: DECIDE
Parameter: Player ID [numeric]
Description: The turn for the specified player starts and it's not a
place-before-attack game. The player needs to decide if he
wants to place additional armies or that he wants to
perform an attack. The appropriate client should reply with
PLACE messages or an ATTACK message.
Message from: Server
Opcode: MORE
Parameter: Player ID [numeric]
Description: It's the turn of the player with the specified ID and he
already has performed an attack. Now he should decide if he
wants to perform another attack, move armies or finish his
turn. The appropriate client should reply with an ATTACK
message, a MOVE message or an END message.
Message from: Server
Opcode: PLACE
Parameter: Player ID [numeric]
Parameter: Number of armies [numeric]
Description: The specified player should place the specified number of
armies. The appropriate client should reply with PLACE
messages.
Message from: Server
Opcode: ATTACK
Parameter: From country ID [numeric]
Parameter: To country ID [numeric]
Parameter: Number of dice [numeric]
Description: An attack is performed. The specified from-country attacks
the to-country with the supplied number of dice.
Message from: Server
Opcode: DEFEND
Description: This message is sent right after the attack message. The
client should tell the server in a DEFEND message the number
of dice it wants to use in the attack.
Message from: Server
Opcode: DICE
Parameter: Player ID of attacker [numeric]
Parameter: Value of attack-die 1 [numeric]
Parameter: Value of attack-die 2 [numeric]
Parameter: Value of attack-die 3 [numeric]
Parameter: Player ID of defender [numeric]
Parameter: Value of defend-die 1 [numeric]
Parameter: Value of defend-die 2 [numeric]
Description: The values of the dice that are used in the ATTACK message
that was just sent.
Message from: Server
Opcode: TAKE
Parameter: From coutry ID [numeric]
Parameter: To country ID [numeric]
Parameter: Min. number of armies [numeric]
Description: When a country is captured, the conquerer should specify
the number of armies he wants to move to the captured
country. The appropriate client should replace with a TAKE
message.
Message from: Server
Opcode: CARD
Parameter: Card ID [numeric]
Description: The client receives a card because it has captured one or
more countries during it's turn. The possible values for
card ID are:
0 - Cavalry
1 - Artillery
2 - Infantry
3 - Wildcard
When the client has three different or three the same cards,
he can exchange them with the EXCHANGE message. A wildcard
can be used to complete a set, only one wildcard can be
exchanged at a time. No more than five cards can be posessed
by a player.
Message from: Server Opcode: WINNER Parameter: Player ID [numeric] Description: The supplied player has won the game! Message from: Server
Opcode: EXCHANGE
Parameter: Player ID [numeric]
Description: The supplied player MUST exchange cards because he has 5 or
more cards at the start of his game. The appropriate client
should reply with an EXCHANGE message.
Message from: Server
Opcode: EXCHANGED
Parameter: Player ID [numeric]
Parameter: Number of armies [numeric]
Description: The specified player has exchanged cards and now received
extra armies.
Message from: Server
Opcode: CARDCOUNT
Parameter: Player ID [numeric]
Parameter: Number of cards [numeric]
Description: The server tells each client how many cards the other
players have.
Message from: Server
Opcode: END
Description: The current turn has ended. It's nobody's turn now. The
clients should wait for additional instructions from the
server.
Message from: Server
Opcode: CLOCK
Parameter: Number of seconds [numeric]
Description: At the start of the turn the server tells all clients how
many seconds the has to complete it's turn.
Storing and loading flexible mapsDominateGame.com uses flexible maps. The maps are stored on the server and loaded by the clients when a client enters a game. Message from: Server
Opcode: SLOT
Parameter: Personal slot? [numeric]
Parameter: Slotnumber [numeric]
Parameter: Map ID [numeric]
Parameter: Name of the map [string]
Parameter: Nickname of the creator of the map [string]
Description: All users can store a list of 5 favourite maps. Based on
these lists, the server calculates the 5 most popular maps.
This message is sent to tell a client his 5 favourite maps,
when the client has just logged on and is initializing, and
to keep the client informed about the most popular maps.
The first parameter tells if this message is about a
personal favorite (parameter=1) or about a most popular map
amongst all users (parameter=0). There are two lists of
slots: slot 0, 1, 2, 3 and 4 for personal favourites and
slot 0, 1, 2, 3 and 4 for the most popular slots. Each map
has a unique ID, and a name and a creator.
Message from: Client
Opcode: SLOT
Parameter: Slotnumber [numeric]
Description: To store the current loaded map into one of the personal
favourites, the client can send this message to the server.
The slotnumber contains a number in the range from 0 to 4
that specifies the slotnumber to save the map in.
Message from: Server
Opcode: STARTMAP
Parameter: Map ID [numeric]
Parameter: Name [string]
Parameter: Nickname of the creator [string]
Parameter: Source [string]
Parameter: Index [binary]
Description: This message is sent when the server starts transfering a
map to a client. Each map has a unique ID, a name and a
creator. A map is also based on a source: world, europe or
africa. The index is a binary representation of the borders
on the map. A description of the syntax of the index is not
yet available. The messages that follow this message are
also relevant for transfering a map to a client. When the
entire map is sent, the ENDMAP message is sent.
Message from: Server
Opcode: CONTINENTMAP
Parameter: Continent ID [numeric]
Parameter: Name [string]
Parameter: Bonus [numeric]
Description: During a transfer of a map, the server sends CONTINENTMAP
messages to inform the client about the continents on the
map. Each continent has a unique ID and a name. The number
of bonusarmies one receives when he holds the continent at
the start of his turn is supplied as well. This message is
only sent during a map transfer.
Message from: Server
Opcode: COUNTRYMAP
Parameter: Country ID [numeric]
Parameter: Name [string]
Parameter: Continent ID [numeric]
Parameter: Text X coordinate [numeric]
Parameter: Text Y coordinate [numeric]
Parameter: Bounding box X [numeric]
Parameter: Bounding box Y [numeric]
Parameter: Bounding box width [numeric]
Parameter: Bounding box height [numeric]
Description: During a transfer of a map, the server sends COUNTRYMAP
messages to inform the client about the countries on the
map. Each country has a unique ID and a name. A country
always belongs to a continent. The continent it refers to
should already be sent by the server in a CONTINENTMAP
message. The X and Y coordinates for the text-position on
the map are sent and the coordinates and sizes of a
bounding box are sent as well.
Message from: Server
Opcode: NEIGHBOURMAP
Parameter: Country ID 1 [numeric]
Parameter: Country ID 2 [numeric]
Description: Sent during the transfer of a map to inform the client that
two countries are eachother's neighbours.
Message from: Server
Opcode: LINEMAP
Parameter: Start X coordinate [numeric]
Parameter: Start Y coordinate [numeric]
Parameter: End X coordinate [numeric]
Parameter: End Y coordinate [numeric]
Description: A map contains white (useless, but for the readability
sometimes essential) lines. The coordindates of the lines
are sent using LINEMAP messages.
Message from: Server Opcode: ENDMAP Description: The transfer of a map has completed Message from: Client
Opcode: STARTMAP
Parameter: Source [string]
Parameter: Name [string]
Parameter: Index [binary]
Description: When a client has created a new map, it can be stored on
the server. The transfer of a map to the server starts with
a STARTMAP message, and ends with an ENDMAP message. In
between a number of other messages can be sent.
Robot managementMessage from: Server Opcode: ROBOT Parameter: Nickname [string] Parameter: Nickname of creator [string] Parameter: Rating [numeric] Parameter: Number of games [numeric] Message from: Server Opcode: ERROR Parameter: Nickname [string] Parameter: Error message [string] The opcodesThe first element of a message is always an opcode. These are the valid opcodes: START = 0; LOGIN = 1; REGISTER = 2; SUCCESS = 3; FAILURE = 4; NEWUSER = 5; USER = 6; ENDUSER = 7; NEWGAME = 8; GAME = 9; ENDGAME = 10; GLOBCHAT = 11; GAMECHAT = 12; WHISPER = 13; PLAYER = 14; JOIN = 15; WATCH = 16; PART = 17; COUNTRY = 18; ROBOT = 19; INIT = 20; MASK = 21; MORE = 22; DECIDE = 23; PLACE = 24; ATTACK = 25; DICE = 26; TAKE = 27; CARD = 28; WINNER = 29; UPGRADE = 30; EXCHANGE = 31; EXCHANGED = 32; END = 33; ARMIES = 34; STARTGAME = 35; ALL = 36; CAPITAL = 37; DEFEND = 38; MOVE = 39; PING = 40; CLOCK = 41; CLOSED = 42; REJECT = 43; MEMBERCHAT = 44; REPLACE = 45; CARDCOUNT = 46; ENDPLAYER = 47; ADDMASK = 48; REMOVEMASK = 49; QUEUE = 50; STARTMAP = 51; CONTINENTMAP = 52; COUNTRYMAP = 53; NEIGHBOURMAP = 54; LINEMAP = 55; ENDMAP = 56; SLOT = 57; ERROR = 58; YOU = 59; OPTION = 60; |