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
$Id: metaserver_protocol.txt 6599 2005-04-25 17:20:16Z jsalmon3 $
----------------------------------------------------------------------
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