Gobligine/doc/metaserver_protocol.txt

This document describes the protocol used by Stratagus to communicate with 
the metaserver.


(c) Copyright 2005 by Jimmy Salmon

Distributed under the GNU General Public License


----------------------------------------------------------------------
LOGIN
----------------------------------------------------------------------


USER username password gamename gamever

Immediately after connecting you must either log in as an existing user or 
REGISTER a new account.

Replies:
ERR_NOUSER           The username does not exist
ERR_BADPASSWORD      Incorrect password for the username
ERR_BADPARAMETER     Too many parameters, not enough parameters, or a badly 
                     formed parameter was sent
ERR_ALREADYLOGGEDIN  Already logged in
USER_OK              Login successful



REGISTER username password gamename gamever

Immediately after connecting you must either log in as an existing user or 
REGISTER a new account.

Replies:
ERR_USEREXISTS       The username already exists
ERR_BADPARAMETER     Too many parameters, not enough parameters, or a badly 
                     formed parameter was sent
ERR_ALREADYLOGGEDIN  Already logged in
REGISTER_OK          Login successful


----------------------------------------------------------------------
HOSTING GAMES
----------------------------------------------------------------------


CREATEGAME description map players ip port [password]

Create a new game.  A user may only have one created game at a time.  If the 
description or map includes spaces it must be enclosed in quotation marks.  
Players is the number of player slots (human or computer), ip is the user's 
ip address, and port is the udp port number that the engine is listening on.
An optional password may be used.

Replies:
ERR_GAMECREATED   The user already has an open created game
ERR_BADPARAMETER  Too many parameters, not enough parameters, or a badly 
                  formed parameter was sent
CREATEGAME_OK     The game was created



CANCELGAME

Cancel the created game.

Replies:
ERR_NOGAMECREATED  The user does not have a created game
ERR_GAMESTARTED    The game has already started
ERR_BADPARAMETER   Too many parameters, not enough parameters, or a badly 
                   formed parameter was sent
CANCELGAME_OK      The game was cancelled



STARTGAME

The game is starting.

Replies:
ERR_NOGAMECREATED  The user does not have a created game
ERR_BADPARAMETER   Too many parameters, not enough parameters, or a badly 
                   formed parameter was sent
STARTGAME_OK       Received the start message


----------------------------------------------------------------------
JOINING GAMES
----------------------------------------------------------------------


LISTGAMES

Get a list of all created games.  The server will send a series of LISTGAMES 
responses for all currently open games and as new games are created.  The 
LISTGAMES parameters are a unique game id used by JOINGAME, the game 
description, map, number of open player slots, total number of players (human 
and computer), game creator user name, ip address, and the udp port number the 
engine is listening on.  The server will continue sending LISTGAMES until 
LISTGAMESEND is called or the user joins a game.

Replies:
ERR_BADPARAMETER   Too many parameters, not enough parameters, or a badly 
                   formed parameter was sent
LISTGAMES id "description" "map" open_players players creator ip port


LISTGAMESEND

Stop the server from sending LISTGAMES.

Replies:
ERR_NOTLISTINGGAMES  The server is not currently sending LISTGAMES
ERR_BADPARAMETER     Too many parameters, not enough parameters, or a badly 
                     formed parameter was sent
LISTGAMESEND_OK      Message received


JOINGAME id [password]

Join a game.  The id is obtained from LISTGAMES.  The password must be sent
when joining games created with a password.

Replies:
ERR_GAMEFULL       There are no empty player slots
ERR_ALREADYINGAME  The user is already in a game 
ERR_NEEDPASSWORD   The game requires a password to join
ERR_BADPASSWORD    The password is incorrect
ERR_BADPARAMETER   Too many parameters, not enough parameters, or a badly 
                   formed parameter was sent
JOINGAME_OK        The player joined the game


PARTGAME

Leave a game.

Replies:
ERR_GAMESTARTED   The game has already started
ERR_NOTINGAME     The user is not currently in a game
ERR_BADPARAMETER  Too many parameters, not enough parameters, or a badly 
                  formed parameter was sent
PARTGAME_OK       The player left the game


----------------------------------------------------------------------
ENDING GAMES
----------------------------------------------------------------------


ENDGAME result

End a game with a result of win, lose, or draw.  TODO: find a way to prevent
cheating.

Replies:
ERR_NOTINGAME     The user is not currently in a game
ERR_BADPARAMETER  Too many parameters, not enough parameters, or a badly 
                  formed parameter was sent
ENDGAME_OK        Received the end game message


----------------------------------------------------------------------
CHATTING
----------------------------------------------------------------------


MSG message

Send a message.

Replies:
None