Difference between revisions of "MultiplayerServerWML"

From The Battle for Wesnoth Wiki
m (Game setup (the phase from creation to start))
(Highlight tags and attributes.)
Line 9: Line 9:
 
* client response
 
* client response
 
** '''[version]'''
 
** '''[version]'''
*** ''version'' The client's version string.
+
*** '''version''': The client's version string.
  
 
* server request
 
* server request
Line 16: Line 16:
 
* client response
 
* client response
 
** '''[login]'''
 
** '''[login]'''
*** ''username'' The username the client would like to have.
+
*** '''username''': The username the client would like to have.
  
 
* server response
 
* server response
Line 24: Line 24:
 
** '''[gamelist]'''
 
** '''[gamelist]'''
 
*** '''[game]''' (repeated)
 
*** '''[game]''' (repeated)
**** ''id'' A unique id of the game.
+
**** '''id''': A unique id of the game.
**** ''name'' The title of the game.
+
**** '''name''': The title of the game.
**** ''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.
**** ''mp_village_gold'' The number of gold per village.
+
**** '''mp_village_gold''': The number of gold per village.
**** ''experience_modifier'' The experience setting.
+
**** '''experience_modifier''': The experience setting.
**** ''mp_countdown'' Does the game use a timer.
+
**** '''mp_countdown''': Does the game use a timer.
**** ''mp_countdown_reservoir_time'' Upper limit of the possibly available time.
+
**** '''mp_countdown_reservoir_time''': Upper limit of the possibly available time.
**** ''mp_countdown_init_time'' Initial time.
+
**** '''mp_countdown_init_time''': Initial time.
**** ''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.
**** ''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.
**** ''human_sides'' The number of sides played by humans.
+
**** '''human_sides''': The number of sides played by humans.
**** ''slots'' The number of vacant/max slots.
+
**** '''slots''': The number of vacant/max slots.
**** ''turn'' The current turn/max turn.
+
**** '''turn''': The current turn/max turn.
 
** '''[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 (version 1.3.7+svn).
*** ''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.
 
Many of the keys under [game] are described more indepth on the [[ScenarioWML]] page.
 
Many of the keys under [game] are described more indepth on the [[ScenarioWML]] page.
  
Line 54: Line 54:
  
 
* '''[error]'''
 
* '''[error]'''
** ''message'' The error message.
+
** '''message''': The error message.
  
 
== Chat (lobby and in-game) ==
 
== Chat (lobby and in-game) ==
  
 
* '''[message]'''
 
* '''[message]'''
** ''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.
 
* '''[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.
  
 
== 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 diff from two [gamelist]s; the keys listed are the ones that actually occure in practice
** ''index'' The index of a user.
+
** '''index''': The index of a user.
 
** '''[insert_child]''' A new user logged on.
 
** '''[insert_child]''' A new user logged on.
 
*** '''[user]'''
 
*** '''[user]'''
**** ''name'' The name of the user.
+
**** '''name''': The name of the user.
 
**** ''available'' "yes"
 
**** ''available'' "yes"
 
*** '''[delete_child]''' A user logged off.
 
*** '''[delete_child]''' A user logged off.
 
** '''[change_child]'''
 
** '''[change_child]'''
 
*** '''[user]'''
 
*** '''[user]'''
**** '''[insert]''' A user joined/left a game.
+
**** '''[insert]''': A user joined/left a game.
***** ''available'' "yes" when the user left a game. "no" when the user joined 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.
+
***** '''location''': The name of the game the user joined.
 
**** '''[delete]'''
 
**** '''[delete]'''
***** ''location'' "x" when a game was left.
+
***** '''location''': "x" when a game was left.
 
*** '''[gamelist]'''
 
*** '''[gamelist]'''
**** ''index'' Index of the game in question.
+
**** '''index''': Index of the game in question.
**** '''[insert_child]''' A game started.
+
**** '''[insert_child]''': A game started.
 
***** '''[game]''' All the usual keys of [game] possible, see above.
 
***** '''[game]''' All the usual keys of [game] possible, see above.
**** '''[delete_child]''' A game ended.
+
**** '''[delete_child]''': A game ended.
 
***** '''[game]'''
 
***** '''[game]'''
**** '''[change_child]''' Something changed in a game.
+
**** '''[change_child]''': Something changed in a game.
 
***** '''[game]'''
 
***** '''[game]'''
 
****** '''[insert]'''
 
****** '''[insert]'''
******* ''slots'' The number of free slots in the form: free/max slots
+
******* '''slots''': The number of free slots in the form: free/max slots
******* ''turn'' The turn number in the form: current turn/max turns
+
******* '''turn''': The turn number in the form: current turn/max turns
 
****** '''[delete]'''
 
****** '''[delete]'''
******* ''map'' "x" comes with every ''turn'' or ''slots'' change for games with shroud
+
******* '''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
+
******* '''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
** ''name'' Username of the player/observer.
+
** '''name''': Username of the player/observer.
  
 
== Game setup (the phase from creation to start) ==
 
== Game setup (the phase from creation to start) ==
 
To create a game the client sends:
 
To create a game the client sends:
 
* '''[create_game]'''
 
* '''[create_game]'''
** ''name'' The title of the game.
+
** '''name''': The title of the game.
** ''human_sides'' (obsolete) The number of sides played by humans.
+
** '''human_sides''': (obsolete) The number of sides played by humans.
  
 
followed by a message with the scenario options as under [game] (see above) plus the scenario data ([time], [era], [side], etc. see [[ScenarioWML]])
 
followed by a message with the scenario options as under [game] (see above) plus the scenario data ([time], [era], [side], etc. see [[ScenarioWML]])
  
 
* '''[join]'''
 
* '''[join]'''
** ''id'' The id of the game.
+
** '''id''': The id of the game.
** ''observe'' Join the game as an observer.
+
** '''observe''': Join the game as an observer.
  
* '''[side_secured]'''(obsolete) server response upon successfully taking a side by a player
+
* '''[scenario_diff]''': [[ScenarioWML]] diff (side changes, etc.)
* '''[failed]'''(obsolete) server response upon an unsuccessful try of taking a side by a player
 
  
* '''[scenario_diff]''' [[ScenarioWML]] diff (side changes, etc.)
+
* '''[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
* '''[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 ==
 
== In-game communication ==
  
* '''[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
* '''[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
  
* '''[info]''' sent by the host on game end - info about the game state
+
* '''[info]''': sent by the host on game end - info about the game state
** ''type'' "termination"  
+
** '''type''': "termination"  
** ''condition'' the termination reason
+
** '''condition''': the termination reason
  
* '''[change_controller]''' a player gives away one of his sides
+
* '''[change_controller]''': a player gives away one of his sides
** ''side'' the side to change controller
+
** '''side''': the side to change controller
** ''player'' the nick of the player to take control
+
** '''player''': the nick of the player to take control
** ''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. ("human", "ai", "network", "none")
  
* '''[muteall]''' the host mutes/unmutes all observers - toggles
+
* '''[muteall]''': the host mutes/unmutes all observers - toggles
* '''[mute]''' the host mutes an observer - 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
+
** '''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
+
* '''[kick]''' or '''[ban]''': the host kicks/bans a player/observer
** ''username'' the username of the player/observer
+
** '''username''': the username of the player/observer
  
 
* '''[turn]'''
 
* '''[turn]'''
** '''[command]''' (repeated) can contain all the tags you can find in a replay: [recruit], [move], [end_turn], etc.
+
** '''[command]''': (repeated) can contain all the tags you can find in a replay: [recruit], [move], [end_turn], etc.
 
*** '''[speak]'''
 
*** '''[speak]'''
**** ''message''
+
**** '''message''': text of the message
**** ''description'' the sender
+
**** '''description''': the sender
**** ''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
  
 
== Administrative commands ==
 
== Administrative commands ==
 
* '''[query]'''
 
* '''[query]'''
** ''type'' The type of query. See [[ServerAdministration]] for details.
+
** '''type''': The type of query. See [[ServerAdministration]] for details.

Revision as of 18:14, 19 February 2008

Multiplayer Server WML

This page describes the WML used to communicate with the multiplayer server (wesnothd).

The login procedure

  • server request (optional)
    • [version]
  • client response
    • [version]
      • version: The client's version string.
  • server request
    • [mustlogin]
  • client response
    • [login]
      • username: The username the client would like to have.
  • server response
    • [join_lobby]
  • 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.
        • 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 (version 1.3.7+svn).
      • 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.
  • [whisper]
    • receiver: The receiver of the whisper
    • sender: (optional - filled by the server) The sender of the whisper.
    • message: The message itself.

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
    • 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
    • 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.
    • human_sides: (obsolete) The number of sides played by humans.

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
  • [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 gives away one of his sides
    • side: the side to change controller
    • player: the nick of the player to take control
    • 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. ("human", "ai", "network", "none")
  • [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
        • description: the sender
        • team_name: the name of the team the message is for - empty if it's a public message

Administrative commands