Difference between revisions of "MultiplayerServerWML"

From The Battle for Wesnoth Wiki
(The login procedure)
(36 intermediate revisions by 14 users not shown)
Line 1: Line 1:
= Multiplayer Server WML =
+
This page describes the [[WML]] used to communicate with the multiplayer server for Wesnoth, [[wesnothd]].
This page describes the WML used to communicate with the multiplayer server (wesnothd).
+
 
 +
== The handshake ==
 +
 
 +
The client sends four bytes, then the server replies with four bytes. To get a new connection number, the client will send these four bytes: 0x00 0x00 0x00 0x00. The server then sends back the connection number (wesnothd calls this number the "socket number"). Since 1.13+ the server no longer is using socket numbers to keep track of clients and always sends the same number to them all. If the handshake is successful, the server will be the first to send a data package. All packages are in [http://en.wikipedia.org/wiki/Gzip gzip] format and are preceded by four bytes that specify the size of the package to come in big-endian. Below you'll find information about what data the (unzipped) packages contain. Unpacked WML uses utf-8 charset.
  
 
== The login procedure ==
 
== The login procedure ==
Line 10: Line 13:
 
** '''[version]'''
 
** '''[version]'''
 
*** '''version''': The client's version string.
 
*** '''version''': The client's version string.
 +
 +
* server response (if the server does not accept this version)
 +
** '''[redirect]'''
 +
*** '''host''': The host you should connect to.
 +
*** '''port''': The port you should connect to.
 +
*** '''version''': A comma-separated list of globs that this server should accept (e.g. "1.0*,1.2*,1.4*,1.7*,1.8*")
 +
** or '''[reject]''' (if the version is unknown)
 +
*** '''accepted_versions''': A comma-separated list of globs that this server does accept
  
 
* server request
 
* server request
Line 18: Line 29:
 
*** '''username''': The username the client would like to have.
 
*** '''username''': The username the client would like to have.
 
*** '''password_reminder''': If "yes" the client requests the server to send a password reminder for the provided username.
 
*** '''password_reminder''': If "yes" the client requests the server to send a password reminder for the provided username.
*** '''password''': The hashed password, created from the username, the password and salt received from the server.
+
*** '''password''': The hashed password, created from the password and salt received from the server. More information about how this password is being generated, including a real world example, can be found in the file [http://forum.wesnoth.org/download/file.php?id=41145 HashedPasswords.pdf] (885 KiB).
  
 
* server response
 
* server response
** '''[join_lobby]'''
+
** '''[join_lobby]''' or
** or
 
 
** '''[error]'''
 
** '''[error]'''
 
*** '''message''': The error message.
 
*** '''message''': The error message.
*** '''password_request''': If not empty the server asks the client to provide a password for its desired username
+
*** '''password_request''': If not empty the server asks the client to provide a password for its desired username.
 +
*** '''phpbb_encryption''': If "yes" the client will encrypt the password using phpbb's algorithm.
 
*** '''random_salt''': Random salt sent to the client for mixing with the password hash.
 
*** '''random_salt''': Random salt sent to the client for mixing with the password hash.
 
*** '''hash_seed''': Salt generated from the original hash that is required to recreate it.
 
*** '''hash_seed''': Salt generated from the original hash that is required to recreate it.
 
*** '''salt''': Salt generated from the original hash that is required to recreate it.
 
*** '''salt''': Salt generated from the original hash that is required to recreate it.
 +
*** '''force_confirmation''': Display an ok/cancel dialog with the content of the 'message' key.
  
 
* server response
 
* server response
Line 37: Line 49:
 
**** '''mp_scenario''': The id of the scenario.
 
**** '''mp_scenario''': The id of the scenario.
 
**** '''mp_era''': The id of the used era.
 
**** '''mp_era''': The id of the used era.
**** ''mp_use_map_settings''': Does the game use the map settings specified in the scenario.
+
**** '''mp_use_map_settings''': Does the game use the map settings specified in the scenario.
 
**** '''mp_fog''': Does the game use fog.
 
**** '''mp_fog''': Does the game use fog.
 
**** '''mp_shroud''': Does the game use shroud.
 
**** '''mp_shroud''': Does the game use shroud.
Line 47: Line 59:
 
**** '''mp_countdown_action_bonus''': Time bonus per action.
 
**** '''mp_countdown_action_bonus''': Time bonus per action.
 
**** '''mp_countdown_turn_bonus''': Time bonus per turn.
 
**** '''mp_countdown_turn_bonus''': Time bonus per turn.
**** '''map_data''': The map data.
+
**** '''map_data''': The map data. ''Notice: not sent to lobby if the game uses shroud''
 
**** '''hash''': The hash value of the map_data.
 
**** '''hash''': The hash value of the map_data.
 
**** '''observer''': Are observers allowed or not.
 
**** '''observer''': Are observers allowed or not.
Line 55: Line 67:
 
** '''[user]''' (repeated)
 
** '''[user]''' (repeated)
 
*** '''name''': The username of the player.
 
*** '''name''': The username of the player.
*** '''game_id''': The ID of the game the player is in (version 1.3.7+svn).
+
*** '''game_id''': The ID of the game the player is in.
 
*** '''location''': The name of the game the player is in.
 
*** '''location''': The name of the game the player is in.
 
*** '''available''': "yes" if the player is in the lobby; "no" if in a game.
 
*** '''available''': "yes" if the player is in the lobby; "no" if in a game.
Line 70: Line 82:
 
** '''sender''': (optional - filled by the server) The sender of the message.
 
** '''sender''': (optional - filled by the server) The sender of the message.
 
** '''message''': The message itself.
 
** '''message''': The message itself.
 +
** '''room''': The room the message is from/to
 
* '''[whisper]'''
 
* '''[whisper]'''
 
** '''receiver''': The receiver of the whisper
 
** '''receiver''': The receiver of the whisper
 
** '''sender''': (optional - filled by the server) The sender of the whisper.
 
** '''sender''': (optional - filled by the server) The sender of the whisper.
 
** '''message''': The message itself.
 
** '''message''': The message itself.
 +
 +
== Room commands ==
 +
Note: the room commands are in general and are subject to change. Room commands are not implemented on 1.13+ servers.
 +
* '''[room_join]'''
 +
** '''room''': The room name to join
 +
** '''player''': (filled by server in response message sent to all room members) the player that joins the room
 +
** '''[members]''': member list sent to the player that joined
 +
*** '''[member]''': (repeated) members
 +
**** '''name''': This member's name
 +
* '''[room_part]'''
 +
** '''room''': The room name to part (leave). Leaving the lobby is not allowed.
 +
** '''player''': (filled by server in response message sent to all room members) the player that leaves the room
 +
* '''[room_query]''': specific room-related queries.
 +
** '''[rooms]''': List rooms created on the server, or
 +
** '''[names]''': List members of a given room
 +
*** '''room''': The room name (if applicable)
 +
** '''[persist]''': Check or set room persistance
 +
*** '''value''': (optional) set room persistance to this value (yes/no)
 +
* '''[room_query_response]''': contains specific response to a room_query.
 +
** '''message''': optional text message response
 +
** '''room''': room name (if applicable)
 +
** '''[rooms]''': room list
 +
*** '''[room]''': (repeated) rooms
 +
**** '''name''': This room's name
 +
** '''[members]''': member list
 +
*** '''[member]''': (repeated) members
 +
**** '''name''': This member's name
 +
 +
== Nickname registration related commands (lobby and in-game) ==
 +
 +
* '''[nickserv]'''
 +
** '''[info]''': Request info about another username.
 +
*** '''name''': The username.
  
 
== Updating the lobby state ==
 
== Updating the lobby state ==
  
* '''[gamelist_diff]''': server message - basically a diff from two [gamelist]s; the keys listed are the ones that actually occure in practice
+
* '''[gamelist_diff]''': server message - basically a [[DiffWML|diff]] from two gamelists, which also includes the user list.
** '''index''': The index of a user.
 
** '''[insert_child]''' A new user logged on.
 
*** '''[user]'''
 
**** '''name''': The name of the user.
 
**** ''available'' "yes"
 
*** '''[delete_child]''' A user logged off.
 
** '''[change_child]'''
 
*** '''[user]'''
 
**** '''[insert]''': A user joined/left a game.
 
***** '''available''': "yes" when the user left a game. "no" when the user joined a game
 
***** '''location''': The name of the game the user joined.
 
**** '''[delete]'''
 
***** '''location''': "x" when a game was left.
 
*** '''[gamelist]'''
 
**** '''index''': Index of the game in question.
 
**** '''[insert_child]''': A game started.
 
***** '''[game]''' All the usual keys of [game] possible, see above.
 
**** '''[delete_child]''': A game ended.
 
***** '''[game]'''
 
**** '''[change_child]''': Something changed in a game.
 
***** '''[game]'''
 
****** '''[insert]'''
 
******* '''slots''': The number of free slots in the form: free/max slots
 
******* '''turn''': The turn number in the form: current turn/max turns
 
****** '''[delete]'''
 
******* '''map''': "x" comes with every ''turn'' or ''slots'' change for games with shroud
 
******* '''mp_scenario''': "x" comes with ''turn'' and ''slots'' changes for games with no scenario id
 
  
 
* '''[observer]''' or '''[observer_quit]''': server message - players joining([observer_quit] - quitting the lobby "game")/quitting([observer] - joining the lobby "game") a game
 
* '''[observer]''' or '''[observer_quit]''': server message - players joining([observer_quit] - quitting the lobby "game")/quitting([observer] - joining the lobby "game") a game
Line 120: Line 139:
 
** '''observe''': Join the game as an observer.
 
** '''observe''': Join the game as an observer.
  
* '''[scenario_diff]''': [[ScenarioWML]] diff (side changes, etc.)
+
* '''[scenario_diff]''': [[DiffWML|diff]] of the [[ScenarioWML]] (side changes, etc.)
  
 
* '''[start_game]''': sent by the host to start a game
 
* '''[start_game]''': sent by the host to start a game
Line 128: Line 147:
  
 
* '''[store_next_scenario]''': sent by the host - the scenario data (see [[ScenarioWML]]) to advance to the next scenario
 
* '''[store_next_scenario]''': sent by the host - the scenario data (see [[ScenarioWML]]) to advance to the next scenario
 +
* '''[notify_next_scenario]''': sent by the server to tell players that the data for the next scenario is available
 
* '''[load_next_scenario]''': sent by the client to request the data for the next scenario
 
* '''[load_next_scenario]''': sent by the client to request the data for the next scenario
 
* '''[next_scenario]''': data for the next scenario (see [[ScenarioWML]]), sent by the server on request
 
* '''[next_scenario]''': data for the next scenario (see [[ScenarioWML]]), sent by the server on request
Line 135: Line 155:
 
** '''condition''': the termination reason
 
** '''condition''': the termination reason
  
* '''[change_controller]''': a player gives away one of his sides
+
* '''[change_controller]''': a player (un)droids one of his sides or assigns control to someone else (The host can assign control for any side.)
 
** '''side''': the side to change controller
 
** '''side''': the side to change controller
** '''player''': the nick of the player to take control
+
** '''player''': the nickname of the player to take control
 +
** '''controller''': the new controller: "human" or "human_ai"
 
** '''own_side''': "yes"
 
** '''own_side''': "yes"
  
 
If a player leaves this is sent to the host for all sides he owned.
 
If a player leaves this is sent to the host for all sides he owned.
 
* '''side_drop''': The number of a side that dropped because a player left.
 
* '''side_drop''': The number of a side that dropped because a player left.
* '''controller''': The controller of that side. ("human", "ai", "network", "none")
+
* '''controller''': The controller of that side. ("ai", "network")
  
 
* '''[muteall]''': the host mutes/unmutes all observers - toggles
 
* '''[muteall]''': the host mutes/unmutes all observers - toggles
Line 154: Line 175:
 
*** '''[speak]'''
 
*** '''[speak]'''
 
**** '''message''': text of the message
 
**** '''message''': text of the message
**** '''description''': the sender (in 1.4 and earlier; later replaced by '''id''')
+
**** '''id''': the sender
**** '''id''': the sender {{DevFeature}}
 
 
**** '''team_name''': the name of the team the message is for - empty if it's a public message
 
**** '''team_name''': the name of the team the message is for - empty if it's a public message
  
Line 161: Line 181:
 
* '''[query]'''
 
* '''[query]'''
 
** '''type''': The type of query. See [[ServerAdministration]] for details.
 
** '''type''': The type of query. See [[ServerAdministration]] for details.
 +
 +
== See also ==
 +
[[MultiplayerServerBots]]
  
 
[[Category:WML Reference]]
 
[[Category:WML Reference]]
 +
[[Category:Server Documentation]]

Revision as of 22:04, 23 November 2019

This page describes the WML used to communicate with the multiplayer server for Wesnoth, wesnothd.

The handshake

The client sends four bytes, then the server replies with four bytes. To get a new connection number, the client will send these four bytes: 0x00 0x00 0x00 0x00. The server then sends back the connection number (wesnothd calls this number the "socket number"). Since 1.13+ the server no longer is using socket numbers to keep track of clients and always sends the same number to them all. If the handshake is successful, the server will be the first to send a data package. All packages are in gzip format and are preceded by four bytes that specify the size of the package to come in big-endian. Below you'll find information about what data the (unzipped) packages contain. Unpacked WML uses utf-8 charset.

The login procedure

  • server request (optional)
    • [version]
  • client response
    • [version]
      • version: The client's version string.
  • server response (if the server does not accept this version)
    • [redirect]
      • host: The host you should connect to.
      • port: The port you should connect to.
      • version: A comma-separated list of globs that this server should accept (e.g. "1.0*,1.2*,1.4*,1.7*,1.8*")
    • or [reject] (if the version is unknown)
      • accepted_versions: A comma-separated list of globs that this server does accept
  • server request
    • [mustlogin]
  • client response
    • [login]
      • username: The username the client would like to have.
      • password_reminder: If "yes" the client requests the server to send a password reminder for the provided username.
      • password: The hashed password, created from the password and salt received from the server. More information about how this password is being generated, including a real world example, can be found in the file HashedPasswords.pdf (885 KiB).
  • server response
    • [join_lobby] or
    • [error]
      • message: The error message.
      • password_request: If not empty the server asks the client to provide a password for its desired username.
      • phpbb_encryption: If "yes" the client will encrypt the password using phpbb's algorithm.
      • random_salt: Random salt sent to the client for mixing with the password hash.
      • hash_seed: Salt generated from the original hash that is required to recreate it.
      • salt: Salt generated from the original hash that is required to recreate it.
      • force_confirmation: Display an ok/cancel dialog with the content of the 'message' key.
  • server response
    • [gamelist]
      • [game] (repeated)
        • id: A unique id of the game.
        • name: The title of the game.
        • mp_scenario: The id of the scenario.
        • mp_era: The id of the used era.
        • mp_use_map_settings: Does the game use the map settings specified in the scenario.
        • mp_fog: Does the game use fog.
        • mp_shroud: Does the game use shroud.
        • mp_village_gold: The number of gold per village.
        • experience_modifier: The experience setting.
        • mp_countdown: Does the game use a timer.
        • mp_countdown_reservoir_time: Upper limit of the possibly available time.
        • mp_countdown_init_time: Initial time.
        • mp_countdown_action_bonus: Time bonus per action.
        • mp_countdown_turn_bonus: Time bonus per turn.
        • map_data: The map data. Notice: not sent to lobby if the game uses shroud
        • hash: The hash value of the map_data.
        • observer: Are observers allowed or not.
        • human_sides: The number of sides played by humans.
        • slots: The number of vacant/max slots.
        • turn: The current turn/max turn.
    • [user] (repeated)
      • name: The username of the player.
      • game_id: The ID of the game the player is in.
      • location: The name of the game the player is in.
      • available: "yes" if the player is in the lobby; "no" if in a game.

Many of the keys under [game] are described more indepth on the ScenarioWML page.

Error messages

  • [error]
    • message: The error message.

Chat (lobby and in-game)

  • [message]
    • sender: (optional - filled by the server) The sender of the message.
    • message: The message itself.
    • room: The room the message is from/to
  • [whisper]
    • receiver: The receiver of the whisper
    • sender: (optional - filled by the server) The sender of the whisper.
    • message: The message itself.

Room commands

Note: the room commands are in general and are subject to change. Room commands are not implemented on 1.13+ servers.

  • [room_join]
    • room: The room name to join
    • player: (filled by server in response message sent to all room members) the player that joins the room
    • [members]: member list sent to the player that joined
      • [member]: (repeated) members
        • name: This member's name
  • [room_part]
    • room: The room name to part (leave). Leaving the lobby is not allowed.
    • player: (filled by server in response message sent to all room members) the player that leaves the room
  • [room_query]: specific room-related queries.
    • [rooms]: List rooms created on the server, or
    • [names]: List members of a given room
      • room: The room name (if applicable)
    • [persist]: Check or set room persistance
      • value: (optional) set room persistance to this value (yes/no)
  • [room_query_response]: contains specific response to a room_query.
    • message: optional text message response
    • room: room name (if applicable)
    • [rooms]: room list
      • [room]: (repeated) rooms
        • name: This room's name
    • [members]: member list
      • [member]: (repeated) members
        • name: This member's name

Nickname registration related commands (lobby and in-game)

  • [nickserv]
    • [info]: Request info about another username.
      • name: The username.

Updating the lobby state

  • [gamelist_diff]: server message - basically a diff from two gamelists, which also includes the user list.
  • [observer] or [observer_quit]: server message - players joining([observer_quit] - quitting the lobby "game")/quitting([observer] - joining the lobby "game") a game
    • name: Username of the player/observer.

Game setup (the phase from creation to start)

To create a game the client sends:

  • [create_game]
    • name: The title of the game.

followed by a message with the scenario options as under [game] (see above) plus the scenario data ([time], [era], [side], etc. see ScenarioWML)

  • [join]
    • id: The id of the game.
    • observe: Join the game as an observer.
  • [start_game]: sent by the host to start a game
  • [leave_game]: sent by the client when it leaves a game; sent by the server to make a client leave a game

In-game communication

  • [store_next_scenario]: sent by the host - the scenario data (see ScenarioWML) to advance to the next scenario
  • [notify_next_scenario]: sent by the server to tell players that the data for the next scenario is available
  • [load_next_scenario]: sent by the client to request the data for the next scenario
  • [next_scenario]: data for the next scenario (see ScenarioWML), sent by the server on request
  • [info]: sent by the host on game end - info about the game state
    • type: "termination"
    • condition: the termination reason
  • [change_controller]: a player (un)droids one of his sides or assigns control to someone else (The host can assign control for any side.)
    • side: the side to change controller
    • player: the nickname of the player to take control
    • controller: the new controller: "human" or "human_ai"
    • own_side: "yes"

If a player leaves this is sent to the host for all sides he owned.

  • side_drop: The number of a side that dropped because a player left.
  • controller: The controller of that side. ("ai", "network")
  • [muteall]: the host mutes/unmutes all observers - toggles
  • [mute]: the host mutes an observer - toggles
    • username: the username of the observer - if not specified the servers returns a list of muted usernames
  • [kick] or [ban]: the host kicks/bans a player/observer
    • username: the username of the player/observer
  • [turn]
    • [command]: (repeated) can contain all the tags you can find in a replay: [recruit], [move], [end_turn], etc.
      • [speak]
        • message: text of the message
        • id: the sender
        • team_name: the name of the team the message is for - empty if it's a public message

Administrative commands

See also

MultiplayerServerBots