ProtocolDescription.xml

<?xml version='1.0'?>
<!DOCTYPE ProtocolDescription SYSTEM "ProtocolDescription.dtd">

<!-- transform this xml into html (so you can view it in a browser): -->
<?xml-stylesheet type="text/xsl" href="ProtocolDescription_xml2html.xsl"?>


<!-- 
NOTE: This document is available in HTML form at: https://springrts.com/dl/LobbyProtocol/ 
-->


<ProtocolDescription>

  <Intro>

  <h3>Introduction</h3>
  <p>
  This is a simple text protocol in a "human readable form". Text protocol was chosen because
  it's easier to debug and implement on the client side. It does require some more overhead,
  but since server and clients do not communicate much anyway, this is not an issue.
  </p>

  <h3>Nomenclature</h3>
  <p>
  We use two terms for "clients": <i>client</i> and <i>user</i>.
  At first, <i>user</i> was considered to be a registered or logged-in client.
  The two terms are used uncleanly though, so you may best think of them as equal.
  </p>

  <h4>Formating rules: lines, words and sentences</h4>
  <p>
  All communication must be encoded in utf-8. Binary data is not permitted.
  </p>
  <p>
  A <i>line</i>, also known as a <i>message</i>, consists of a single protocol command, plus its arguments, communicated as a single string, and terminated by a newline character (\n).
  Lines may be of any length, although the server enforces a somewhat (arbitrary) limit of 10,000 chars.
  A natural implementation of the protocol will result in almost all lines being under 1,000 chars in length.
  <!--Nevertheless, some commands (like <clink name="AGREEMENT"/>) do divide the data they send into several lines, but only for clarity.-->
  </p>
  <p>
  Each line begins with a <i>command</i>, written in capitals. 
  The arguments of the command, which come next, come in two types: <i>words</i> and <i>sentences</i>. 
  Word arguments are sequences of non-whitespace characters, and are separated from each other by whitespaces.
  Sentence arguments are sequences of words (separated by whitespaces), 
  which are considered as a single argument.
  Sentences arguments are seperated from each other by tab characters (\t).
  </p>
  <p>
  The word arguments of a command <i>always</i> come first, followed by its sentence arguments.
  The last word argument is separated from the first sentence argument by a single whitespace.
  Some examples:
  </p>
  <p>
  <ul>
  <li> <clink name="JOINEDBATTLE"/>, with 2 word arguments: <br/><code>JOINEDBATTLE 25869 oxido</code></li> 
  <li> <clink name="UPDATEBATTLEINFO"/>, with 4 words and 1 sentence argument: <br/><code>UPDATEBATTLEINFO 25903 1 0 -210360064 Trojan Hills v03</code></li>
  <li> <clink name="BATTLEOPENED"/>, with 10 words and 4 sentences: <br/><code>BATTLEOPENED 4437 0 0 BlackHoleHost6 71.2.10.1 8626 10 0 0 -1213614804 Spring 104.0 &#160;&#160; Coastline_Dry_V1 &#160;&#160; The BlackHoleHost - Conflict &#160;&#160; Balanced Annihilation V9.46</code></li>
  </ul>
  </p>
  <p>
  (So, when a client talks to the server, if you want to include a tab character in a sentence, you can't!)
  </p>

  <h4>Legend</h4>
  <p>
  The following notation is used within the arguments of a command.
  A given argument should be assumed to be a word, unless {} is present, in which case it is a sentence.
  <ul>
    <li>{...} = a sentence arg </li>
    <li>{...} {...} = two sentence args (which should be separated by a tab character!)</li>
    <li>| = multiple choices for the argument i.e. "OR"</li>
    <li>[...] = an optional argument</li>
  </ul>
  </p>
  <p>
  All commands, except for some developer/admin specific commands, are listed in the commands section of this document.
  Their arguments are listed in order, and should be sent in that order.
  </p>
  <!--<p>
  For future use (currently only applies to PROMOTE):
  A few commands require that they be invoked using a JSON format, which allows arguments to be named (and, consequently, sent in any order).
  Named arguments can be written in any order and the names are case sensitive, e.g. username != userName.
  The main benefit of named arguments is that they help with backwards compatibility when the protocol changes, and it is planned that more commands will use JSON in future, particularly commands related to statuses and battles. 
  
  </p>
-->

  <h3>Protocol rules</h3>
  <h4> Keep-alive signals</h4>
  <p>
  A client must maintain a 'constant' connection with the server, to ensure that network timeouts and disconnects can be detected.
  If no data is being transfered, the client must send <clink name="PING"/> commands to the server at regular intervals -- every 30 seconds is recommended.
  The server will reply with a <clink name="PONG"/> command.
  If no data or ping command has been sent for 60 seconds, the server will assume a network timeout and disconnect the client.
  Similarly, if the client does not hear back within 30 seconds of a ping, it should assume the server has gone down.
  </p>
  <h4>Zero status assumption</h4>
  <p>
  When a client joins the server, the client will be notified about statuses of users only for cases where this status is non-zero.
  A client's status and battle status should be assumed to be 0, if not specified otherwise by the server.
  (This saves on bandwidth, not that we really need to...)
  </p>
  
  <h4> Status change updates </h4>
  <p>
  Most of the commands that notify about some changes are forwarded to the source of the change.
  For example: When a client sends a <clink name="MYBATTLESTATUS"/> command,
  the server sends a <clink name="CLIENTBATTLESTATUS"/> command to all users in the battle,
  including the client who sent the <clink name="MYBATTLESTATUS"/> command.
  This allows the client to synchronize their local status with the server's, 
  after the server has verified that the status change is valid; therefore, it also serves as confirmation mechanism.
  </p>
  
  <h4>Message IDs</h4>
  <p>
  Any message can be prefixed with a message ID.
  For example:
  <code>
  '#123 SAY main hello world!'
  </code>
  is a valid <clink name="SAY"/> command with message ID 123. The server will use this ID in any message sent as a reply, for example:
  <code>
  '#123 SAID main Betalord hello world!'
  </code>
  would communicate the greeting on to other clients with a <clink name="SAID"/> command.
  </p>
  <p>
  The message ID has only one function: to ease tracking server responses for the client.
  They makes it easier to implement commands that require multiple responses in both directions.
  You can also use them with <clink name="PING"/>/<clink name="PONG"/> to measure your round trip time.
  </p>
  <p>
  Message IDs should be non-negative values, within 31-bit range (so, 0 up to 2147483647).
  Negative values are reserved by the server for internal use.
  </p>

  <p>
  <h3>Sub-systems</h3>
  </p>

  <h4>Email Verification</h4>
  <p>
  Uberserver carries out email verification for registering new accounts, for account recovery and for changing email address.
  In order to verify an email address: the server sends a four or eight digit verification code to an email address, and the client must send this code back to the server.
  Each verification code is valid for 48h, and allows max 3 attempts at verification.
  </p>
  <p>
  The following pairs list which commands notify that verification codes were sent, and where they are expected back:
  <ul>
    <li> sent: <clink name="REGISTRATIONACCEPTED"/>, back: <clink name="CONFIRMAGREEMENT"/> </li>
    <li> sent: <clink name="CHANGEEMAILREQUESTACCEPTED"/>, back: <clink name="CHANGEEMAIL"/> </li>
	<li> sent: <clink name="RESETPASSWORDREQUESTACCEPTED"/>, back: <clink name="RESETPASSWORD"/></li>
  </ul>
  The code can be re-sent, up to three times, using <clink name="RESENDVERIFICATION:client"/>.
  </p>

  <h4> Channels and Battles </h4>
  <p>
  A channel is an IRC-like setting in which users can send messages, which are typically visible to all other users in the same channel. 
  A battle is a special type of channel, with extra properties corresponding to the extra information needed to set up and launch an online multiplayer game of Spring.
  </p><p>
  Channels can be either registered or unregistered. Unregistered channels simply forward messages between clients and have no stored settings or data.
  Registered channels can set topics, password, mutes/bans, store a history, and so on; these data/settings are stored within the server database.
  </p><p>
  Each registered channel has a founder who sets the various permanent properties of the channel (such as a password).
  The founder may also pick channel operators, who are able to handle day-to-day stuff like mutes, topics and bans.   
  </p>
  
  <h4> ChanServ </h4>
  <p>
  ChanServ is a fake client, which the server shows as present in all registered channels and battles. 
  It listens for text-based channel commands (listed on <url>https://springrts.com/wiki/ChanServ</url>) and also carries them out.
  The long term plan is that ChanServ will be replaced with server commands and a client-side GUI.
  </p>
  
  <h4> Bridge bots </h4>
  <p>
  The interface stemming from <clink name="BRIDGECLIENTFROM"/>, <clink name="JOINFROM"/> and <clink name="SAYFROM"/> 
  allows users in external chat channels (e.g. Discord, IRC) to join and talk natively within Uberserver channels and battles, via bridge bot. 
  Users talking via a bridge bot are referred to as bridged users.
  </p>
  <p>
  Bridged users are identified to the bridge bot by a <i>(location, external_id)</i> pair, which should be unique (and should not change when the same user is bridged again).
  Each external user also has a <i>external_username</i> which should be their current username within their location, and such the <i>(location, external_username)</i> is also unique (e.g. use the screenname on Discord, with the 'extra' #1234 part appended when necessary to achieve uniqueness).
  At most one bridge bot can bridge users from any given location.
  </p>
  <p>
  For non bridge bots, the server identifies bridged users by a username of the form <i>external_username:location</i> for bridged users. 
  Note that the ':' char is not permitted in normal usernames.  
  </p>
  
  <h4>Syncing</h4>
  <p>
  To be in <i>sync</i> means to have the same versions of all the content
  required to play a particular game (including the map, engine, dependencies, etc).
  See <clink name="JOINBATTLE:server"/> or the unitsync documentation for details.
  </p>

  <h4>Hole punching</h4>
  <p>
  <quote>
  Hole punching is a networking technique
  for establishing communications between two parties in separate organizations
  who are both behind restrictive firewalls.
  </quote>
  <url>https://en.wikipedia.org/wiki/Hole_punching</url>
  We use it to allow clients to connect to the lobby server, that would otherwise not be able to. 
  See the commands
  <clink name="TASSERVER"/>,
  <clink name="OPENBATTLE"/>,
  <clink name="UDPSOURCEPORT"/>,
  <clink name="CLIENTIPPORT"/>,
  <clink name="HOSTPORT"/>.
  <!--It will probably not work in LAN mode, especially if combined with players from the internet.-->
  </p>
   
  <h3>Hosting battles</h3>
  <p>
  Any client may host a <i>battleroom</i>, also referred to as a <i>battle</i>, which is (effectively) a special type of chat channel with extra features related to setting up and launching a multi-player game.
  A client may join at most one battleroom at any given time. 
  This includes when the client is hosting the battle. The server automatically enforces this rule.
  </p>
  <p>
  Clients detect whether a battle has a game currently in progress by monitoring the hosts status.
  For example, if the hosts status changes to "in game", then the battles is "in game".
  </p>
  <p>
  <code>spring.exe</code> uses UDP connections for online multi-player games (TCP is not suitable due to latency).
  These connections are made between the host client (of the battleroom) and non-host clients. 
  Consequently, the lobby protocol contains a set of commands dedicated to setting up UDP connections between host/non-host clients.
  </p>
  
  <h4> Setting up UDP connections: non-host perspective </h4>
  
  <p>
  Before joining a battle, a client is expected to first acquire their UDP source port from the server.
  This is done by sending a UDP packet, which a response coming via <clink name="UDPSOURCEPORT"/>.
  Once the client has done that, the client should keep sending UDP packets to the server at regular 20 second intervals, 
  to keep the connection alive and ensure that the clients router does not remove the UDP connection from its port translation table.
  After <code>spring.exe</code> is launched, these UDP keep-alive signals may be discontinued (because then <code>spring.exe</code> will be sending regular UDP packets).
  Once <code>spring.exe</code> exits, the client should resume sending UDP keep-alive signals.
  </p>
  <p>
  Just before starting the game, the host should send a <clink name="HOSTPORT"/> command to the user,
  containing the host's public UDP source port.
  The lobby cient should replace the battles port with this one,
  as it will have to connect to the game using this port and not the original one
  (that was acquired through the <clink name="BATTLEOPENED"/> command).
  </p>
  <p>
  Note: If the client is not hosting, then it does not need to "punch through", which is does have to do when hosting, because <code>spring.exe</code> will take care of that. <i> Todo: make this clearer!</i>
  </p>
  
  <h4> Setting up UDP connections: host perspective </h4>
  <p>
  Before sending the <clink name="OPENBATTLE"/> command,
  the host should try to acquire its UDP source port from the server,
  just to make sure it can acquire it at all
  (better to find out it does not work before hosting,
  than right before starting the game).
  However, the client does not need to keep this UDP connection alive,
  since it will not be used to actually host the game.
  It is just a test to see if UDP connectivity works.
  </p>
  <p>
  When a new client joins the battle,
  the server will send a <clink name="CLIENTIPPORT"/> command to the host,
  informing the host of this client's public UDP source port.
  The host should remember this information,
  as he will have to use it when starting the game.
  </p>
  <p>
  Right before starting the game,
  the host should try to acquire his source port again.
  This time he will actually use this port to host the game.
  Upon starting the game,
  the server will notify all clients participating in his battle about his port,
  using the <clink name="HOSTPORT"/> command.
  The host does not need to keep refreshing his connection
  to keep the port open,
  as spring.exe will do that for him.
  Upon returning from the first game that was hosted in his battleroom,
  the host does not need to keep refreshing it either (as a client would have to do --
  because when the host starts a new game
  it will have to acquire a new source port anyway).
  </p>
  
  <h4> Why? </h4>
  <p>
  This setup exists because some host clients might play "single-player" games with bots
  before opening their battleroom to other players,
  in which case any UDP port that was originally set up would have long ago timed out (spring.exe would not keep it alive during a single player game!).
  For this reason, the host has to acquire a new UDP port each time it starts a battle.
  </p>

  <h3> Further information </h3>
  <p>
  If this document doesn't provide what you are looking for, 
  you may have a look at the Uberserver source code, in <code>protocol.py</code>, 
  or ask for help in the <code>#sy</code> channel of the SpringRTS lobbyserver.
  </p>
   
  </Intro>

  <CompatFlags>
        This list details the current compatibility flags a client may send
        with the <clink name="LOGIN:client"/> command.
		Clients should update their behaviour for compatibility with the changes below, and send the appropriate flag to announce compatibility.
		<br/><br/>
        This list may be emptied when a new protocol version is released, at which point legacy clients may break.
    <p><ul>
      <li><b>b</b>: <clink name="JOINBATTLEREQUEST"/> and <clink name="JOINBATTLEACCEPT"/>, <clink name="JOINBATTLEDENY"/> (this flag is optional).</li>
	  <li><b>sp</b>: script passwords </li>
	  <li><b>u</b>: use <clink name="SAY"/> to talk in battles, support for <clink name="SAYFROM"/> command set.</li>
    </ul></p>
  <p>
  In a small number of cases, the arguments of a command were different in earlier versions of the protocol. 
  The details below refer to the latest dev version of the protocol, and assume that the client has all the latest compatibility flag present.
  </p>
  </CompatFlags>  
  
  <Versions>
  
 <Version Name="0.38+dev -- current live version --">  
  Nothing new yet!<br/><br/>
 </Version>  
  
 <Version Name="0.38">  
  <ul>
    <li> Added <b>u</b> compat flag, for Battle/Channel merge:
	  <ul>
	    <li><clink name="JOINBATTLE:server"/> sends an extra arg, the name of the channel in which the battle chat takes place.</li>
		<li> Use <clink name="SAY"/> and <clink name="SAYEX"/> to talk in battles i.e. into that channel.</li>
		<li> Users joining/leaving a battle are automatical joined/left to its channel.</li>
	  </ul>
	</li>
    <li> The functionality of some previous compat flags is now mandatory for all clients:
	  <ul>
	    <li> <b>t</b>: <clink name="CHANNELTOPIC"/> omits time, empty topic string signifies no topic </li>
		<li> <b>l</b>: args of <clink name="ADDUSER"/></li>
		<li> <b>cl</b>: Engine Name / Engine Version args of <clink name="BATTLEOPENED:server" />/ <clink name="OPENBATTLE:client"/> </li>
	  </ul>
	</li>
	<li> Removed support for some deprecated compat flags:
		<ul>
			<li> <b>et</b>: NOCHANNELTOPIC and related</li>
			<li> <b>p</b>: <clink name="AGREEMENT:server"/>, the agreement is sent in plaintext format</li>
			<li> <b>cu, sd, m, a</b>: superceeded or were already no ops</li>
		</ul>
	  The server no longer expects to be sent these flags.
	</li>
	<li> Added new interface for bridge bots: <clink name="BRIDGECLIENTFROM"/>, <clink name="UNBRIDGECLIENTFROM"/>, 
	  <clink name="JOINFROM"/>, <clink name="SAYFROM"/>, <clink name="LEAVEFROM"/>, <clink name="CLIENTSFROM"/>. 
	</li>
    <li> Added email verification and related features:
		<ul>
		  <li>Added/updated <clink name="CHANGEEMAIL"/> command set. </li>
		  <li>Added <clink name="RESENDVERIFICATION"/> command set. </li>
		  <li>Added <clink name="RESETPASSWORD"/> command set. </li>
		  <li> When email verification is enabled, 
		    <ul> 
		 	  <li> <clink name="REGISTER"/> requires an email arg</li>
			  <li> <clink name="CONFIRMAGREEMENT"/> requires a verification code arg</li>
			  <li> <clink name="CHANGEEMAIL"/> requires a verification code arg</li>
			  <li> <clink name="RESETPASSWORD"/> requires a verification code arg</li>
		    </ul>
		  </li>
		</ul>
	</li>
	<li> Replaced the whole moderation interface, with new/updated commands.</li>
	<li> Removed all cypto commands from 0.37. The server now uses TLS, beginning with <clink name="STLS"/>.</li>
    <li> Removed SAYDATA command set. </li>
    <li> Removed SAYBATTLEPRIVATE command set. </li>
    <li> Removed FORCEJOINBATTLE. </li>
	<li> Removed JOINBATTLEREQUEST command set.</li>
	<li> Deprecated SAYBATTLE, SAYBATTLEEX. </li>
	<li> Deprecated MUTE, UNMUTE, MUTELIST, SETCHANNELKEY. </li>
    </ul>
 
 </Version>


  <Version Name="0.37">
  <ul>
    <li>Added the <clink name="NOCHANNELTOPIC:server"/> server command.</li>
    <li>Added the <clink name="IGNORE"/> command set.</li>
    <li>Added crypto commands for secure connections (edit: removed/replaced in 0.38).</li>
    <li>Added the SAYDATA command set (edit: removed in 0.38).</li>
  </ul>
  </Version>

  <Version Name="0.36">
  <ul>
    <li>Added the <clink name="LISTCOMPFLAGS:client"/> client command.</li>
    <li>Added the <clink name="COMPFLAGS:server"/> server command.</li>
	<li>Added the FORCEJOINBATTLE command set (edit: removed in 0.38).</li>
    <li>Added the CONNECTUSER command set (edit: removed in 0.38).</li>
    <li>Added the <clink name="CHANGEEMAIL:client"/> client command.</li>
    <li>Added the <clink name="EXIT:client"/> client command.</li>
    <li>Added the <clink name="GETINGAMETIME:client"/> client command.</li>
	<li>removed REQUESTUPDATEFILE, OFFERFILE, FORGEREVERSEMSG, USERID, GENERATEUSERID, ACQUIREUSERID</li>
    <li>'scriptPassword' argument added: This change affects the following commands:
        <clink name="LOGIN"/>, <clink name="JOINBATTLE"/>, <clink name="JOINEDBATTLE"/>.</li>
  </ul>
  <ul>
    <li>
    <i>Compatibility-Flags</i>
    <ul>
      <li><b>sp</b>: the scriptPassword parameter, sent in the <clink name="JOINEDBATTLE"/> command</li>
    </ul>
    </li>
  </ul>
  </Version>

  </Versions>

  <CommandList>

    <Command Name="PING" Source="client">
      <Description>
      Requests a <clink name="PONG"/> back from the server. 
	  <br/><br/>
	  Clients should send <clink name="PING"/> once every 30 seconds, if no other data is being sent to the server. For details, see the notes above on keep-alive signals. 
	  </Description>
      <Response>
      <clink name="PONG"/>
      </Response>
    </Command>

    <Command Name="PONG" Source="server">
      <Description>
      Sent as the response to a <clink name="PING"/> command.
      </Description>
    </Command>

<!--- tls -->	
	
	<Command Name="STLS" Source="client">
      <Description>
        Initiate a TLS connection to the server.
	  </Description>
      <Response>
      <clink name="OK"/>
      </Response>
    </Command>

    <Command Name="OK" Source="server">
      <Description>
      Sent as the response to a <clink name="STLS"/> command. The client now can now start the tls connection. The server will send again the greeting
      <clink name="TASSERVER"/>.
      </Description>
    </Command>

<!--- greeting / exiting -->	

    <Command Name="TASSERVER" Source="server">
      <Arguments>
        <Argument Name="protocolVersion" Optional="no" Sentence="no">
        This is the lobby protocol version used by the server.
        The client may check if it supports this version before attempting to log in.
        </Argument>
        <Argument Name="springVersion" Optional="no" Sentence="no">
        Default spring version used on lobby server. Can be locally determinated by calling unitsyncs GetSpringVersion(), IsSpringReleaseVersion() and GetSpringVersionPatchset(),
        which will return the version, for example "95.0" or "94.1.1-1062-g9d16c2d develop".
        <br/>
        Note that if the value of this parameter is "*",
        the client should simply ignore it since this means that
        the server does not contain any updates nor does it require latest Spring version
        (this is usually the case when the server is running in LAN mode).
        </Argument>
        <Argument Name="udpPort" Optional="no" Sentence="no">
        This is server UDP port where the "NAT Help Server" is running.
        This is the port to which clients should send their UDP packets
        when trying to figure out their public UDP source port.
        This is used with some NAT traversal techniques (e.g. "hole punching").
        </Argument>
        <Argument Name="serverMode" Optional="no" Sentence="no">
        Tells what mode the server is in.
        Currently valid are:
        <ul>
          <li>0 - normal mode</li>
          <li>1 - LAN mode</li>
        </ul>
        </Argument>
      </Arguments>
      <Description>
      This is the first message (i.e. "greeting message") that a client receives
      upon connecting to the server.
      </Description>
      <Examples>
        <Example>TASSERVER 0.35 0.72b1 8201 0</Example>
        <Example>TASSERVER 0.35 * 8201 0</Example>
      </Examples>
    </Command>
	
    <Command Name="EXIT" Source="client">
      <Arguments>
        <Argument Name="reason" Optional="yes" Sentence="yes">
        Clients may optionally specify a reason for quitting. 
		If the user simply wished to exit, many lobby clients send their name and version.
        </Argument>
      </Arguments>
      <Description>
      Clients should send this as their last command before severing their connection to the server, to notify
      a clean and deliberate disconnect. 
      </Description>
	  <Response>
	  The server is not required to acknowledge, or respond, to the exiting client. <br/>
	  Other clients via server messages or status change commands.
	  </Response>
    </Command>	

<!--- registration -->	

    <Command Name="REGISTER" Source="client">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="password" Optional="no" Sentence="no">
          The user's password string. If a client uses a secure session
          (which means the command itself shall be encrypted, including
          its arguments), it should send BASE64(password), otherwise it
          should send BASE64(MD5(password)).
        </Argument>
        <Argument Name="email" Optional="yes" Sentence="no">
          A valid email address. Case will not be considered.
        </Argument>
      </Arguments>
      <Description>
      The client sends this command when trying to register a new account.
      Note that the client must not already be logged in,
      or else the server will deny his request.
	  <br/>
	  <br/>
	  The username and password are given sanity/uniqueness checks, and these primarily determine the servers response. If email verification is enabled, and no valid email address is provided, the server will deny the registration.
      </Description>
      <Response>
      <clink name="REGISTRATIONDENIED"/>
      or <clink name="REGISTRATIONACCEPTED"/>.
      </Response>
      <Examples>
        <Example>REGISTER Johnny Gnmk1g3mcY6OWzJuM4rlMw== enormous_crocodile@hawtmail.com</Example>
      </Examples>
    </Command>

    <Command Name="REGISTRATIONDENIED" Source="server">
      <Arguments>
        <Argument Name="reason" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      Sent in response to a <clink name="REGISTER"/> command,
      if registration has been refused.
      </Description>
    </Command>

    <Command Name="REGISTRATIONACCEPTED" Source="server">
      <Description>
      Sent in response to a <clink name="REGISTER"/> command,
      if registration has been accepted. 
	  <br/><br/>
	  If email verification is enabled, sending of this command notifies that the server has sent a verification code to the users email address. This verification code is expected back from the client in <clink name="CONFIRMAGREEMENT"/>
      <br/><br/>
	  Upon reciept of this command, a lobby client would normally be expected to reply with a <clink name="LOGIN"/> attempt (but this is not a requirement of the protocol).
	  </Description>
    </Command>

<!--- login -->	

    <Command Name="LOGIN" Source="client">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="password" Optional="no" Sentence="no">
          The user's password string. If a client uses a secure session
          (which means the command itself shall be encrypted, including
          its arguments), it should send BASE64(password), otherwise it
          should send BASE64(MD5(password)).
        </Argument>
        <Argument Name="cpu" Optional="no" Sentence="no">
        deprecated, set it to 0
        </Argument>
        <Argument Name="localIP" Optional="no" Sentence="no">
        The client should supply his local IP (e.g. 192.168.x.y, or whatever it uses)
        so the server can forward local IPs to clients behind the same NAT
        (this resolves some of the host/joining issues).
        If the client is unable to determine its local IP,
        he should send "*" instead.
        </Argument>
        <Argument Name="lobby name and version" Optional="no" Sentence="yes"/>
        <Argument Name="userID" Optional="yes" Sentence="no">
        This is a unique user identification number provided by the client-side software.
        It has to be an unsigned 32 bit integer which is generated by calculating the crc32
        from the binary mac address of the primary network interface.
        If it can't be determinated it has to be set to 0.
        </Argument>
        <Argument Name="compFlags" Optional="yes" Sentence="yes">
        When connecting, the lobby client can tell the lobby server
        that it is compatible with some optional functionalities
        that break backward compatibility.
        Each flag in this space separated parameter indicates a specific functionality
        (like IRC user/channel flags).
        By default, all the optional functionalities are considered as not supported by the client.
        For the current list of flags, see the section on recent changes.
        </Argument>
      </Arguments>
      <Description>
      Sent by a client asking to log on to the server.
	  <br/><br/>
      Note: if the client has not yet confirmed the user agreement,
      then server will send the <clink name="AGREEMENT"/> to the client as a response to this command.
	  In this case the response to <clink name="LOGIN"/> will be delayed until after <clink name="CONFIRMAGREEMENT"/>.
      <br/><br/>
      Also see <clink name="LOGININFOEND"/> command.
      </Description>
	  <Response>
	    If the client has previously accepted the user agreement: <clink name="ACCEPTED"/> or <clink name="DENIED"/>. <br/>
		If the client has not already acepted the user agreement: <clink name="AGREEMENT"/>.<br/>
		See these commands for further responses.
	  </Response>
      <Examples>
        <Example>LOGIN Johnny Gnmk1g3mcY6OWzJuM4rlMw== 3200 192.168.1.100 SpringLobby 0.264</Example>
        <Example>LOGIN Johnny Gnmk1g3mcY6OWzJuM4rlMw== 3200 * SpringLobby 0.264</Example>
        <Example>LOGIN Johnny Gnmk1g3mcY6OWzJuM4rlMw== 3200 * SpringLobby 0.264<b>[TAB]</b>123456</Example>
        <Example>LOGIN Johnny Gnmk1g3mcY6OWzJuM4rlMw== 3200 * SpringLobby 0.264<b>[TAB]</b>0<b>[TAB]</b>a b</Example>
      </Examples>
    </Command>

    <Command Name="ACCEPTED" Source="server">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent as a response to the <clink name="LOGIN"/> command, if it succeeded.
      Next, the server will send much info about clients and battles:
      <ul>
        <li>multiple <clink name="MOTD"/>, each giving one line of the current welcome message</li>
        <li>multiple <clink name="ADDUSER"/>, listing all users currently logged in</li>
        <li>multiple <clink name="BATTLEOPENED"/>, <clink name="UPDATEBATTLEINFO"/>, detailing the state of all currently open battles</li>
		<li>multiple <clink name="JOINEDBATTLE"/>, indiciating the clients present in each battle</li>
        <li>multiple <clink name="CLIENTSTATUS"/>, detailing the statuses of all currently logged in users</li>
      </ul>
	  Finally, 
      it will send a <clink name="LOGININFOEND"/> command
      indicating that it has finished sending all this info. Note that, except for this final command, the commands/info listed above may be sent to the client in any order. 
      </Description>
    </Command>

    <Command Name="DENIED" Source="server">
      <Arguments>
        <Argument Name="reason" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      Sent as a response to a failed <clink name="LOGIN"/> command. 
      </Description>
    </Command>

    <Command Name="LOGININFOEND" Source="server">
      <Description>
      Sent by the server, indicating that it has finished sending the login info, completing the sequence initiated by <clink name="ACCEPTED"/>
      </Description>
      <Examples>
      </Examples>
    </Command>

<!--- agreement -->	

    <Command Name="AGREEMENT" Source="server">
      <Arguments>
        <Argument Name="agreement" Optional="no" Sentence="yes">
        The user agreement is sent in "Text" format (.txt file streamed via socket).
        </Argument>
      </Arguments>
      <Description>
      Sent by the server upon receiving a <clink name="LOGIN"/> command,
      if the client has not yet agreed to the server's "terms-of-use".
      The server may send multiple AGREEMENT commands, 
      each of corresponds to a new line in the agreement text,
      finishing with an <clink name="AGREEMENTEND"/> command.
      The client should send <clink name="CONFIRMAGREEMENT"/>
      and then resend the <clink name="LOGIN"/> command,
      or disconnect from the server if he has chosen to refuse the agreement.
      </Description>
      <Response>
      No response is expected until <clink name="AGREEMENTEND"/> is received.
      See that command for more info.
      </Response>
      <Examples>
      </Examples>
    </Command>

    <Command Name="AGREEMENTEND" Source="server">
      <Description>
      Sent by the server after multiple <clink name="AGREEMENT"/> commands.
      This way, the server tells the client that he has finished sending the agreement
      (this is the time when the lobby client should popup the "agreement" screen
      and wait for the user to accept/reject it).
      </Description>
      <Response>
      A response is not mandatory, but the server now awaits a <clink name="CONFIRMAGREEMENT"/> command from the client, providing that the user agreed to the agreement.
      Otherwise, the client should disconnect from the server, and restart the <clink name="LOGIN"/> sequence.
      </Response>
    </Command>

    <Command Name="CONFIRMAGREEMENT" Source="client">
      <Arguments>
        <Argument Name="verificationCode" Optional="yes" Sentence="no">
        </Argument>
      </Arguments>
      <Description>
        Confirm that the user agreed to the user agreement, and supply an email verification code (if necessary).
	  </Description>
      <Response>
      <clink name="ACCEPTED"/>, if the verification was either accepted or was not needed. <br/>
	  <clink name="DENIED"/>, if the verification code was not accepted.
      </Response>
    </Command>
	
    <Command Name="MOTD" Source="server">
      <Arguments>
        <Argument Name="message" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
       Sent by the server after <clink name="ACCEPTED"/>.
       The server may send multiple MOTD commands, each MOTD corresponds to one line of the current welcome message.
      </Description>
      <Examples>
      </Examples>
    </Command>

		
<!--- account management -->	

    <Command Name="RENAMEACCOUNT" Source="client">
      <Arguments>
        <Argument Name="newUsername" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Will rename the current account name to newUsername.
      The user has to be logged in for this to work.
      After the server renames the account, it will disconnect the client.
      </Description>
      <Response>
      No formal response is required,
      although the server may reply with a <clink name="SERVERMSG"/>.
      </Response>
      <Examples>
        <Example>RENAMEACCOUNT Johnny2</Example>
      </Examples>
    </Command>

    <Command Name="CHANGEPASSWORD" Source="client">
      <Arguments>
        <Argument Name="oldPassword" Optional="no" Sentence="no"/>
        <Argument Name="newPassword" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Will change the password of the users's account.
      </Description>
      <Response>
      No formal response is required,
      although the server may reply with a <clink name="SERVERMSG"/>.
      </Response>
    </Command>
	
    <Command Name="CHANGEEMAILREQUEST" Source="client">
      <Arguments>
        <Argument Name="newEmail" Optional="no" Sentence="no">
          The email address the user wishes to change too.
        </Argument>
      </Arguments>
      <Description>
		Requests a verification code, to be sent to a new email address that the user wishes to associate to their account.
		<br/><br/>
		Even if email verification is disabled, it is intended that the client will call this before calling <clink name="CHANGEEMAIL"/>.
		If email verification is disabled, the response will be a <clink name="CHANGEEMAILREQUESTDENIED"/>, containing a message informing the user that a blank verification code will be accepted.
	  </Description>
      <Response>
		<clink name="CHANGEEMAILREQUESTDENIED"/> or <clink name="CHANGEEMAILREQUESTACCEPTED"/>
      </Response>
    </Command>

    <Command Name="CHANGEEMAILREQUESTACCEPTED" Source="server">
      <Description>
	    Notifies that a verification code was sent, in response to <clink name="CHANGEEMAILREQUEST"/>.
		<br/><br/>
		No response is required from the client, although a <clink name="CHANGEEMAIL"/> command would normally be sent once the user has supplied their verification code.
	  </Description>
    </Command>

    <Command Name="CHANGEEMAILREQUESTDENIED" Source="server">
	  <Arguments>
        <Argument Name="errorMsg" Optional="no" Sentence="yes"/>
      </Arguments>
	  <Description>
	    Notifies that a verification code was not sent, in response to <clink name="CHANGEEMAILREQUEST"/>.
	  </Description>
    </Command>
	
    <Command Name="CHANGEEMAIL" Source="client">
      <Arguments>
        <Argument Name="newEmail" Optional="no" Sentence="no">
          The email address the user wishes to change too. 
        </Argument>
        <Argument Name="verificationCode" Optional="yes" Sentence="no">
		  The verification code recieved as a result of <clink name="CHANGEEMAILREQUESTACCEPTED"/>.
		</Argument>
      </Arguments>
      <Description>
        Asks the server to change the email address associated to the client. See also <clink name="CHANGEEMAILREQUEST"/>, which would typically be called first.
	  </Description>
      <Response>
		<clink name="CHANGEEMAILDENIED"/> or <clink name="CHANGEEMAILACCEPTED"/>
      </Response>
    </Command>

    <Command Name="CHANGEEMAILACCEPTED" Source="server">
      <Description>
	    Notifies that client that their email address was changed, in response to <clink name="CHANGEEMAIL"/>.
	  </Description>
    </Command>

    <Command Name="CHANGEEMAILDENIED" Source="server">
	  <Arguments>
        <Argument Name="errorMsg" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
	    Notifies that the email address could not be changed, in response to <clink name="CHANGEEMAIL"/>.
	  </Description>
    </Command>	

    <Command Name="RESENDVERIFICATION" Source="client">
      <Arguments>
        <Argument Name="newEmail" Optional="no" Sentence="no">
          The email address the user wished to change too, or register with, but has forgotten/lost/eaten or not recieved their verification code for. 
        </Argument>
      </Arguments>
      <Description>
        Request that an active verification code to be re-sent.
	  </Description>
      <Response>
		<clink name="RESENDVERIFICATIONDENIED"/> or <clink name="RESENDVERIFICATIONACCEPTED"/>
      </Response>
    </Command>

    <Command Name="RESENDVERIFICATIONACCEPTED" Source="server">
      <Description>
	    Notifies that a verification code was re-sent, in response to <clink name="RESENDVERIFICATION"/>.
	  </Description>
    </Command>

    <Command Name="RESENDVERIFICATIONDENIED" Source="server">
	  <Arguments>
        <Argument Name="errorMsg" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
	    Notifies that a verification code was not re-sent, in response to <clink name="RESENDVERIFICATION"/>.
	  </Description>
    </Command>	
	
    <Command Name="RESETPASSWORDREQUEST" Source="client">
      <Arguments>
        <Argument Name="email" Optional="no" Sentence="no">
          The email address associated to the acccount.
        </Argument>
      </Arguments>
      <Description>
		Requests a verification code, to be sent to the email address of a user wishing to reset their password.
	  </Description>
      <Response>
		<clink name="RESETPASSWORDREQUESTACCEPTED"/> or <clink name="RESETPASSWORDREQUESTDENIED"/>
      </Response>
    </Command>

    <Command Name="RESETPASSWORDREQUESTACCEPTED" Source="server">
      <Description>
	    Notifies that a verification code was sent, in response to <clink name="RESETPASSWORDREQUEST"/>.
		<br/><br/>
		No response is required from the client, although a <clink name="RESETPASSWORD"/> command would normally be sent.
	  </Description>
    </Command>

    <Command Name="RESETPASSWORDREQUESTDENIED" Source="server">
	  <Arguments>
        <Argument Name="errorMsg" Optional="no" Sentence="yes"/>
      </Arguments>
	  <Description>
	    Notifies that a verification code was not sent, in response to <clink name="RESETPASSWORDREQUEST"/>.
	  </Description>
    </Command>
	
    <Command Name="RESETPASSWORD" Source="client">
      <Arguments>
        <Argument Name="email" Optional="no" Sentence="no">
          The email address the user wishes to change too. 
        </Argument>
        <Argument Name="verificationCode" Optional="no" Sentence="no">
		  The verification code recieved as a result of <clink name="RESETPASSWORDREQUESTACCEPTED"/>.
		</Argument>
      </Arguments>
      <Description>
        Asks the server to change the password associated to the client. See also <clink name="RESETPASSWORDREQUEST"/>, which would typically be called first.
	  </Description>
      <Response>
		<clink name="RESETPASSWORDDENIED"/> or <clink name="RESETPASSWORDACCEPTED"/>
      </Response>
    </Command>

    <Command Name="RESETPASSWORDACCEPTED" Source="server">
      <Description>
	    Notifies that client that their password was changed, in response to <clink name="RESETPASSWORD"/>. The new password will be emailed to the client.
	  </Description>
    </Command>

    <Command Name="RESETPASSWORDDENIED" Source="server">
	  <Arguments>
        <Argument Name="errorMsg" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
	    Notifies that the password could not be changed, in response to <clink name="RESETPASSWORD"/>.
	  </Description>
    </Command>	
	

<!--- other users logins -->	

    <Command Name="ADDUSER" Source="server">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="country" Optional="no" Sentence="no">
        A two-character country code based on ISO 3166 standard.
        See <url>http://www.iso.org/iso/en/prods-services/iso3166ma/index.html</url>
        </Argument>
        <Argument Name="cpu" Optional="no" Sentence="no">
        deprecated, see the <clink name="LOGIN"/> command.
        </Argument>
        <Argument Name="userID" Optional="no" Sentence="no"/>
        <Argument Name="lobbyID" Optional="no" Sentence="yes">
		A string of text sent by the client, typically identifying the lobby client they are using.
		</Argument>
      </Arguments>
      <Description>
      Tells the client that a new user joined a server.
      The client should add this user to his clients list,
      which he must maintain while he is connected to the server.
      </Description>
    </Command>

    <Command Name="REMOVEUSER" Source="server">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Indicates that a user disconnected from the server.
      The client should remove this user from his clients list,
      which he must maintain while he is connected to the server.
      </Description>
    </Command>
	
<!-- server messages -->
	
    <Command Name="SERVERMSG" Source="server">
      <Arguments>
        <Argument Name="message" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      A general purpose message sent by the server.
      The lobby client program should display this message to the user in a non-invasive way, but clearly visible to the user 
	  (for example, as a SAYEX-style message from the server, printed into all the users chat panels).
      </Description>
      <Examples>
        <Example>SERVERMSG Server is going down in 5 minutes for a restart, due to a new update.</Example>
      </Examples>
    </Command>

    <Command Name="SERVERMSGBOX" Source="server">
      <Arguments>
        <Argument Name="message" Optional="no" Sentence="yes"/>
        <Argument Name="url" Optional="yes" Sentence="yes">
        If specified, the lobby client should ask the user
        if he wants this URL to be opened in a browser window.
        The lobby client should then (once the user clicked OK)
        launch the default browser and open this URL in there.
        </Argument>
      </Arguments>
      <Description>
      The lobby client program should display this message to the user in an invasive way, which requires response from the user (for example, in a dialogue box with an OK button).
      </Description>
    </Command>
	

	
<!-- channel commands -->
	
    <Command Name="CHANNELS" Source="client">
      <Description>
      Sent by a client when requesting the list of all channels on the server
      </Description>
      <Response>
      A series of <clink name="CHANNEL"/> commands,
      followed by an <clink name="ENDOFCHANNELS"/> command.
      </Response>
      <Examples>
        <Example>JOIN main</Example>
      </Examples>
    </Command>

    <Command Name="CHANNEL" Source="server">
    <Arguments>
      <Argument Name="chanName" Optional="no" Sentence="no"/>
      <Argument Name="userCount" Optional="no" Sentence="no">
      Number of users in the channel.
      </Argument>
      <Argument Name="topic" Optional="yes" Sentence="yes">
      Is omited if the topic is not set for the channel.
      </Argument>
    </Arguments>
    <Description>
    Sent by the server to a client who requested the channels list
    via the <clink name="CHANNELS"/> command.
    A series of these commands will be sent to the client,
    one for each open channel.
    A series of CHANNEL commands is followed by the <clink name="ENDOFCHANNELS"/> command.
    </Description>
    </Command>

    <Command Name="ENDOFCHANNELS" Source="server">
      <Description>
      Sent to a client who previously requested the channel list,
      after a series of <clink name="CHANNEL"/> commands (one for each channel).
      </Description>
    </Command>	
    <Command Name="JOIN" Source="client">
      <Arguments>
        <Argument Name="chanName" Optional="no" Sentence="no"/>
        <Argument Name="key" Optional="yes" Sentence="no">
        If the channel is locked, non-priviledged clients must supply the correct key to join.
        </Argument>
      </Arguments>
      <Description>
      Sent by a client requesting to join a channel.
      </Description>
	  <Response>
	    <clink name="JOIN:server"/> or <clink name="JOINFAILED"/>. See there for further responses.
	  </Response>
      <Examples>
        <Example>JOIN moddev</Example>
      </Examples>
    </Command>

    <Command Name="JOIN" Source="server">
      <Arguments>
        <Argument Name="chanName" Optional="no" Sentence="no">
        Name of the channel which the client has just joined
        </Argument>
      </Arguments>
      <Description>
      Sent to a client who has successfully <clink name="JOIN:client"/>ed a channel. 
	  The server will now send the client a <clink name="CLIENTS"/> and a <clink name="CLIENTSFROM"/> command, which together give the list of users present in the channel.
      </Description>
      <Examples>
        <Example>JOIN main</Example>
      </Examples>
    </Command>

    <Command Name="JOINFAILED" Source="server">
      <Arguments>
        <Argument Name="chanName" Optional="no" Sentence="no"/>
        <Argument Name="reason" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      Sent if joining a channel failed for some reason.
      </Description>
    </Command>

    <Command Name="CHANNELTOPIC" Source="server">
      <Arguments>
        <Argument Name="chanName" Optional="no" Sentence="no"/>
        <Argument Name="author" Optional="no" Sentence="no"/>
        <Argument Name="topic" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      Sent to a client who just <clink name="JOIN"/>ed a channel, or who was already present in a channel when the topic was changed.
      This command informs the client of the current channel topic.
      </Description>
    </Command>

    <Command Name="CHANNELTOPIC" Source="client">
      <Arguments>
        <Argument Name="chanName" Optional="no" Sentence="no"/>
        <Argument Name="topic" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
        A request to change a channel's topic, typically sent by a priviledged user.
      </Description>
    </Command>

    <Command Name="CLIENTS" Source="server">
      <Arguments>
        <Argument Name="chanName" Optional="no" Sentence="no"/>
        <Argument Name="clients" Optional="no" Sentence="yes">
		  A sentence in which each word is the username of a client present in the channel. 
		</Argument>
      </Arguments>
      <Description>
      Sent to a client who just joined the channel. This command informs the client of the list of users present in the channel, including the client itself.
	  <br/><br/>
	  This command is always sent (to a client joining a channel), and the list it conveys includes the newly joined client. 
	  It is sent after all the <clink name="CLIENTSFROM"/> commands.
	  Once <clink name="CLIENTS"/> has been processed, the joining client has been informed of the full list of other clients and bridged clients currently present in the joined channel.
      </Description>
    </Command>

    <Command Name="JOINED" Source="server">
      <Arguments>
        <Argument Name="chanName" Optional="no" Sentence="no"/>
        <Argument Name="userName" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent to all clients in a channel (except the new client)
      when a new user joins the channel.
      </Description>
    </Command>

    <Command Name="LEAVE" Source="client">
      <Arguments>
        <Argument Name="chanName" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by a client when requesting to leave a channel.
      <br/><br/>
	  Note that when the client is disconnected, the client is automatically removed from all channels.
      </Description>
	  <Response>
		None. The server will broadcast the <clink name="LEFT"/> command to all users in the channel, including the user who sent the <clink name="LEAVE"/> command.
	  </Response>
    </Command>

    <Command Name="LEFT" Source="server">
      <Arguments>
        <Argument Name="chanName" Optional="no" Sentence="no"/>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="reason" Optional="yes" Sentence="yes"/>
      </Arguments>
      <Description>
      Sent by the server to inform a client, present in a channel, that another user or himself has left that channel.
      </Description>
    </Command>

    <Command Name="CHANNELMESSAGE" Source="server">
      <Arguments>
        <Argument Name="chanName" Optional="no" Sentence="no"/>
        <Argument Name="message" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by the server to all clients in a channel.
      Used to broadcast messages in a channel.
      </Description>
    </Command>

    <Command Name="SAY" Source="client">
      <Arguments>
        <Argument Name="chanName" Optional="no" Sentence="no"/>
        <Argument Name="message" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      Send a chat message to a specific channel.
      The client has to join the channel first,
      to be allowed to use this command.
      </Description>
      <Response>
      See <clink name="SAID:server"/>.<br/>
	  <i> If the request to speak is denied, a <clink name="FAILED"/> command will be sent in JSON format. </i>
      </Response>
    </Command>

    <Command Name="SAID" Source="server">
      <Arguments>
        <Argument Name="chanName" Optional="no" Sentence="no"/>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="message" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      Sent to all clients participating in a specific channel
      when one of the clients sent a chat message to it
      (including the author of the message).
      </Description>
    </Command>

    <Command Name="SAYEX" Source="client">
      <Arguments>
        <Argument Name="chanName" Optional="no" Sentence="no"/>
        <Argument Name="message" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      Sent by any client requesting to say something in a channel in "/me" IRC style.
      (The <clink name="SAY:client"/> command is used for normal chat messages.)
      </Description>
      <Response>
      See <clink name="SAIDEX:server"/>.<br/>
	  <i> If the request to speak is denied, a <clink name="FAILED"/> command will be sent in JSON format. </i>
      </Response>
    </Command>

    <Command Name="SAIDEX" Source="server">
      <Arguments>
        <Argument Name="chanName" Optional="no" Sentence="no"/>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="message" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      Sent by the server when a client said something
      using the <clink name="SAYEX:client"/> command.
      </Description>
    </Command>

    <Command Name="SAYPRIVATE" Source="client">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="message" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      Send a private chat message to an other client.
      </Description>
      <Response>
      <clink name="SAYPRIVATE:server"/> and <clink name="SAIDPRIVATE:server"/>
      </Response>
    </Command>

    <Command Name="SAYPRIVATE" Source="server">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="message" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      Sent to a client that just sent a <clink name="SAYPRIVATE:client"/> command.
      This notifies the client that the server sent the private message on to its intended recipient.
      </Description>
    </Command>

    <Command Name="SAIDPRIVATE" Source="server">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="message" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      Sends a private message on to its intended recipient.
      </Description>
    </Command>

    <Command Name="SAYPRIVATEEX" Source="client">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="message" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      Sent by a client requesting to say something in "/me" IRC style in a private message.
      (Normal chat messages are sent via the <clink name="SAYPRIVATE:client"/> command.)
      </Description>
      <Response>
      <clink name="SAYPRIVATEEX:server"/> and <clink name="SAIDPRIVATE:server"/>
      </Response>
    </Command>

    <Command Name="SAYPRIVATEEX" Source="server">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="message" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      Sent to a client that just sent a <clink name="SAYPRIVATE:client"/> command.
      This notifies the client that the server sent the private message on to its intended recipient.
      </Description>
    </Command>

    <Command Name="SAIDPRIVATEEX" Source="server">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="message" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      Sends a private message in "/me" IRC style on to its intended recipient.
      </Description>
    </Command>

    <Command Name="GETCHANNELMESSAGES" Source="client">
      <Arguments>
        <Argument Name="chanName" Optional="no" Sentence="no"/>
        <Argument Name="lastID" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by a client requesting the history of a channel, since the lastID.
	  </Description>
	  <Response>
	  The server will respond with a sequence of <clink name="SAID"/> commands via the <clink name="JSON"/> command, one for each chat message requested (up to a two week limit). 
	  </Response>
    </Command>
	
<!-- bridge bot interface -->

    <Command Name="BRIDGECLIENTFROM" Source="client">
      <Arguments>
        <Argument Name="location" Optional="no" Sentence="no">
		'discord', for example. Battle hosts bridging ingame users should use their own name username as the location.
		</Argument>
        <Argument Name="externalID" Optional="no" Sentence="no">
		A string which unqiuely identifies the external client, within its specified location, and which will not change if the external client changes username.
        </Argument>
		<Argument Name="externalUsername" Optional="no" Sentence="no">
		The current username of the external client, in its external location.
		</Argument>
      </Arguments>
      <Description>
      Sent by a bridge bot notifying the server of a new bridged client.
	  </Description>
	  <Response>
	  The server will reply with either <clink name="FAILED"/> or <clink name="BRIDGEDCLIENTFROM:server"/>. 
	  </Response>
    </Command>

    <Command Name="BRIDGEDCLIENTFROM" Source="server">
      <Arguments>
        <Argument Name="location" Optional="no" Sentence="no"/>
        <Argument Name="externalID" Optional="no" Sentence="no"/>
        <Argument Name="externalUsername" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by the server in response to a successful <clink name="BRIDGECLIENTFROM"/> command.
	  <br/><br/>
	  The server will use 'externalUser:location' as the username for the bridged client.
	  </Description>
    </Command>

    <Command Name="UNBRIDGECLIENTFROM" Source="client">
      <Arguments>
        <Argument Name="location" Optional="no" Sentence="no"/>
        <Argument Name="externalID" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by a bridge bot notifying the server that a bridged client has left the bridge.
	  </Description>
	  <Response>
	  The server will reply with either <clink name="FAILED"/> or <clink name="UNBRIDGEDCLIENTFROM:server"/>. 
	  </Response>
    </Command>

    <Command Name="UNBRIDGEDCLIENTFROM" Source="server">
      <Arguments>
        <Argument Name="location" Optional="no" Sentence="no"/>
        <Argument Name="externalID" Optional="no" Sentence="no"/>
        <Argument Name="externalUsername" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by the server in response to a successful <clink name="UNBRIDGECLIENTFROM"/> command.
	  </Description>
    </Command>
	
    <Command Name="JOINFROM" Source="client">
      <Arguments>
        <Argument Name="chan" Optional="no" Sentence="no"/>
        <Argument Name="location" Optional="no" Sentence="no"/>
        <Argument Name="externalID" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
	  Send by a bridge bot requesting to join a bridged client to a channel.
	  </Description>
	  <Response>
	  The server will reply with either <clink name="FAILED"/> or <clink name="UNBRIDGECLIENTFROM:server"/>. 
	  </Response>
    </Command>

    <Command Name="JOINEDFROM" Source="server">
      <Arguments>
        <Argument Name="chan" Optional="no" Sentence="no"/>
        <Argument Name="bridge" Optional="no" Sentence="no"> The username of the bridge bot for this bridged client. </Argument>
        <Argument Name="userName" Optional="no" Sentence="no">This will have the form externalUsername:location.</Argument>
      </Arguments>
      <Description>
      Sent by the server in response to a successful <clink name="JOINFROM"/> command.	  
	  </Description>
    </Command>	

    <Command Name="LEAVEFROM" Source="client">
      <Arguments>
        <Argument Name="chan" Optional="no" Sentence="no"/>
        <Argument Name="location" Optional="no" Sentence="no"/>
        <Argument Name="externalID" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
	  Sent by a bridge bot requesting to remove a bridged client from a channel.
	  </Description>
	  <Response>
	  The server will reply with either <clink name="FAILED"/> or <clink name="LEFTFROM:server"/>. 
	  </Response>
    </Command>

    <Command Name="LEFTFROM" Source="server">
      <Arguments>
        <Argument Name="chan" Optional="no" Sentence="no"/>
        <Argument Name="userName" Optional="no" Sentence="no">
		This will have the form externalUsername:location.
		</Argument>
      </Arguments>
      <Description>
      Sent by the server in response to a successful <clink name="LEFTFROM"/> command.	  
	  </Description>
    </Command>	
	
    <Command Name="SAYFROM" Source="client">
      <Arguments>
        <Argument Name="chan" Optional="no" Sentence="no"/>
        <Argument Name="location" Optional="no" Sentence="no"/>
        <Argument Name="externalID" Optional="no" Sentence="no"/>
        <Argument Name="message" Optional="yes" Sentence="yes "/>
      </Arguments>
      <Description>
	  Sent by a bridge bot to notify that a bridged user spoke into a channel.
	  </Description>
	  <Response>
	  The server will reply with either <clink name="FAILED"/> or <clink name="SAIDFROM:server"/>. 
	  </Response>
    </Command>

    <Command Name="SAIDFROM" Source="server">
      <Arguments>
        <Argument Name="chan" Optional="no" Sentence="no"/>
        <Argument Name="userName" Optional="no" Sentence="no">
		This will have the form externalUsername:location.
		</Argument>
        <Argument Name="message" Optional="yes" Sentence="yes"/>
      </Arguments>
      <Description>
      Sent by the server in response to a successful <clink name="SAYFROM"/> command.	  
	  </Description>
    </Command>		
	
   <Command Name="CLIENTSFROM" Source="server">
      <Arguments>
        <Argument Name="chan" Optional="no" Sentence="no"/>
        <Argument Name="bridge" Optional="no" Sentence="no"> The username of the bridge bot for the following clients. </Argument>
        <Argument Name="clients" Optional="no" Sentence="yes">
		A list of usernames of clients who are bridged into this channel.
		</Argument>
      </Arguments>
      <Description>
	  Sent by the server to a (non-bridged) client who just joined a channel.
	  </Description>
    </Command>

<!-- joining/opening battle commands -->
	
    <Command Name="OPENBATTLE" Source="client">
      <Arguments>
        <Argument Name="type" Optional="no" Sentence="no">
        Can be 0 or 1 (0 = normal battle, 1 = battle replay)
        </Argument>
        <Argument Name="natType" Optional="no" Sentence="no">
        NAT traversal method used by the host.
        Must be one of:
        0: none
        1: Hole punching
        2: Fixed source ports
        </Argument>
        <Argument Name="password" Optional="no" Sentence="no">
        Must be "*" if founder does not wish to have password-protected game.
        </Argument>
        <Argument Name="port" Optional="no" Sentence="no"/>
        <Argument Name="maxPlayers" Optional="no" Sentence="no"/>
        <Argument Name="gameHash" Optional="no" Sentence="no">
        A signed 32-bit integer (acquired via the unitsync library).
        </Argument>
        <Argument Name="rank" Optional="no" Sentence="no">
		The minimum rank required for a client in the battle to be allowed to become a player.
		</Argument>
        <Argument Name="mapHash" Optional="no" Sentence="no">
        A signed 32-bit integer (acquired via the unitsync library).
        </Argument>
        <Argument Name="engineName" Optional="no" Sentence="yes">Use 'Spring'</Argument>
        <Argument Name="engineVersion" Optional="no" Sentence="yes">For example: '94.1.1-1062-g9d16c2d develop', same format as in <clink name="TASSERVER:server"/></Argument>
        <Argument Name="map" Optional="no" Sentence="yes"/>
        <Argument Name="title" Optional="no" Sentence="yes"/>
        <Argument Name="gameName" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      Sent by the client requesting to open a new battle. 
      If the command is successful, the client becomes the founder (i.e. host) of the new battle.
	  <br/><br/>
	  Clients without botflags will have their maxPlayers capped at 10; 
	  the founding client will be informed via a server message if the server applies this limitation.
      </Description>
      <Response>
      If accepted: <clink name="BATTLEOPENED"/> and <clink name="OPENBATTLE:server"/><br/>
	  If denied: <clink name="OPENBATTLEFAILED:server"/> 
      </Response>
    </Command>

    <Command Name="OPENBATTLEFAILED" Source="server">
      <Arguments>
        <Argument Name="reason" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      Informs a client that tried to open a battle that their request has been rejected.
      </Description>
    </Command>

    <Command Name="BATTLEOPENED" Source="server">
      <Arguments>
        <Argument Name="battleID" Optional="no" Sentence="no"/>
        <Argument Name="type" Optional="no" Sentence="no">
        Can be 0 or 1 (0 = normal battle, 1 = battle replay)
        </Argument>
        <Argument Name="natType" Optional="no" Sentence="no">
        NAT traversal method used by the host.
        Must be one of:
        0: none
        1: Hole punching
        2: Fixed source ports
        </Argument>
        <Argument Name="founder" Optional="no" Sentence="no">
        Username of the client who started this battle.
        </Argument>
        <Argument Name="ip" Optional="no" Sentence="no"/>
        <Argument Name="port" Optional="no" Sentence="no"/>
        <Argument Name="maxPlayers" Optional="no" Sentence="no"/>
        <Argument Name="passworded" Optional="no" Sentence="no">
        A boolean - must be "0" (meaning false) or "1"!
        </Argument>
        <Argument Name="rank" Optional="no" Sentence="no"/>
        <Argument Name="mapHash" Optional="no" Sentence="no">
        A signed 32-bit integer (acquired via the unitsync library).
        </Argument>
        <Argument Name="engineName" Optional="no" Sentence="yes">For example: 'my spring'</Argument>
        <Argument Name="engineVersion" Optional="no" Sentence="yes">For example: '94.1.1-1062-g9d16c2d develop', See also <clink name="TASSERVER:server"/></Argument>
        <Argument Name="map" Optional="no" Sentence="yes"/>
        <Argument Name="title" Optional="no" Sentence="yes"/>
        <Argument Name="gameName" Optional="no" Sentence="yes"/>
        <Argument Name="channel" Optional="no" Sentence="yes"> The name of the channel (which will contain no whitespace) in which the chat for this battle takes place. By convention, these channels have names of the form __battle__1234.</Argument>
      </Arguments>
      <Description>
      Sent by the server to all registered users, when a new battle becomes open. 
      </Description>
    </Command>

    <Command Name="OPENBATTLE" Source="server">
      <Arguments>
        <Argument Name="battleID" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent to a client who previously sent an <clink name="OPENBATTLE:client"/> command,
      if the client's request to open a new battle has been approved. 
	  <br/><br/>
	  Note that the corresponding <clink name="BATTLEOPENED"/> command is sent <i>before</i> this command is used to reflect the successful <clink name="OPENBATTLE:client"/> command back to the client.
	  <br/><br/>
      After sending this command, the server will send a <clink name="JOINBATTLE:server"/> (to notify the founding client that they have joined their own battle) followed by a <clink name="REQUESTBATTLESTATUS"/>.
	  </Description>
    </Command>

    <Command Name="JOINBATTLE" Source="client">
      <Arguments>
        <Argument Name="battleID" Optional="no" Sentence="no"/>
        <Argument Name="password" Optional="yes" Sentence="no"/>
        <Argument Name="scriptPassword" Optional="yes" Sentence="no">
        A random, client-generated string (which is used to avoid account spoofing ingame, and will appear in script.txt).
        Note that if this argument is sent, a password must be sent too. If the battle is not passworded then an empty password should be sent.
        </Argument>
      </Arguments>
      <Description>
      Sent by a client requesting to join a battle.
      </Description>
	  <Response>
	  The server will reply to the client with either <clink name="JOINBATTLE:server"/> or <clink name="JOINBATTLEFAILED"/>. 
	  In order to determine which response is given, the server may send a <clink name="JOINBATTLEREQUEST"/> to the battle founder, and wait for the reply. 
	  </Response>
	</Command>

    <Command Name="JOINBATTLE" Source="server">
      <Arguments>
        <Argument Name="battleID" Optional="no" Sentence="no"/>
        <Argument Name="hashCode" Optional="no" Sentence="no">
        A signed 32-bit integer (acquired via the unitsync library).
  	    This code is computed using the current map, game, and other dependencies.
	    It is used to check that the client has correct non-corrupt downloads of the required content.
        </Argument>
        <Argument Name="channelName" Optional="no" Sentence="no">
		The name of the chat channel used for this battle.
		</Argument>
      </Arguments>
      <Description>
      Notifies a client that their request to <clink name="JOINBATTLE:client"/> was successful, and that they have just joined the battle.
      <br/><br/>
	  Clients in the battle will be notified of the new user via <clink name="JOINEDBATTLE"/>.
	  <br/><br/>      
	  Next, the server will send a series of commands to the newly joined client, which might include <clink name="DISABLEUNITS"/>, <clink name="ADDBOT"/>, <clink name="ADDSTARTRECT"/>, <clink name="SETSCRIPTTAGS"/> and so on, 
	  along with multiple <clink name="CLIENTBATTLESTATUS"/>, in order to describe the current state of the battle to the joining client.
	  <br/><br/>
	  If the battle has natType>0, the server will also send the clients IP port to the host, via the <clink name="CLIENTIPPORT"/> command. <i> Someone who knows more about this should write more! </i>
	  </Description>
    </Command>

	<Command Name="JOINBATTLEREQUEST" Source="server">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="ip" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by the server to a battle host, each time a client requests to join his battle.
      </Description>
      <Response>
      The battle host should reply with either <clink name="JOINBATTLEACCEPT"/>
      or <clink name="JOINBATTLEDENY"/>.
      </Response>
    </Command>
    <Command Name="JOINBATTLEACCEPT" Source="client">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by a battle host, in response to a <clink name="JOINBATTLEREQUEST"/> command,
      instructing the server to allow the user to join their battle.
      </Description>
    </Command>
    <Command Name="JOINBATTLEDENY" Source="client">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="reason" Optional="yes" Sentence="yes"/>
      </Arguments>
      <Description>
      Sent by a battle host, in response to a <clink name="JOINBATTLEREQUEST"/> command,
      instructing the server to disallow the user to join their battle.
      </Description>
    </Command>

    <Command Name="JOINBATTLEFAILED" Source="server">
      <Arguments>
        <Argument Name="reason" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      Notifies a client that their request to <clink name="JOINBATTLE:client"/> was denied.
      </Description>
    </Command>

    <Command Name="JOINEDBATTLE" Source="server">
      <Arguments>
        <Argument Name="battleID" Optional="no" Sentence="no"/>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="scriptPassword" Optional="yes" Sentence="no">
        A random, client-generated string,
        wich will be written to script.txt by the host,
        to avoid account spoofing
        (= someone is trying to join the battle under a wrong user-name).
        </Argument>
      </Arguments>
      <Description>
      Sent by the server to all clients when a new client joins the battle. <br/><br/>
	  The server does not send this command for a host, when that host opens its own battle.
      </Description>
    </Command>

    <Command Name="LEFTBATTLE" Source="server">
      <Arguments>
        <Argument Name="battleID" Optional="no" Sentence="no"/>
        <Argument Name="userName" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by the server to all users when a client left a battle
      (or got disconnected from the server).
      </Description>
    </Command>

    <Command Name="LEAVEBATTLE" Source="client">
      <Description>
      Sent by the client when he leaves a battle.
	  <br/><br/>
      When this command is by the founder of a battle, it notifies that the battle is now closed.
      </Description>
	  <Response>
	  If sent by the founder, <clink name="BATTLECLOSED"/>.
	  </Response>
    </Command>

    <Command Name="BATTLECLOSED" Source="server">
      <Arguments>
        <Argument Name="battleID" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent to all users to notify that a battle has been closed.
      </Description>
    </Command>

<!-- udp port commands -->

    <Command Name="UDPSOURCEPORT" Source="server">
      <Arguments>
        <Argument Name="port" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent as a response to a client's UDP packet
      (used with "hole punching" NAT traversal technique).
	  <br/><i> Someone who knows more about this should document it!</i>
      </Description>
      <Examples>
        <Example>UDPSOURCEPORT 52361</Example>
      </Examples>
    </Command>

    <Command Name="CLIENTIPPORT" Source="server">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="ip" Optional="no" Sentence="no"/>
        <Argument Name="port" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent to the battle's host, notifying him about another client's IP address
      and his public UDP source port. 
      <!--The host needs to know public UDP source ports of all players in his battle
      in order for the <i>Hole punching</i> technique to work.
      The IP is needed for both NAT traversal methods
      ("hole punching" and "fixed source ports").
      This command is sent to the the battle host immediately after a new user joins the battle
      (currently only if some NAT traversal technique is used).-->
      </Description>
    </Command>

    <Command Name="HOSTPORT" Source="server">
      <Arguments>
        <Argument Name="port" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by the server to all clients participating in the battle, except for the host, notifying them about the (possibly new) host port.
      <!--This message will only be sent right before the host starts a game,
      if this battle is being hosted using "hole punching" NAT traversal technique.
      When a client receives this message,
      he should replace the battle's host port with this new port,
      so that when the game actually starts,
      he will connect to this new port,
      rather than to the port which the host selected when he initialy started the battle
      (with the <clink name="OPENBATTLE"/> command).-->
      </Description>
    </Command>
		
	
<!-- battle state commands -->
	
    <Command Name="UPDATEBATTLEINFO" Source="server">
      <Arguments>
        <Argument Name="battleID" Optional="no" Sentence="no"/>
        <Argument Name="spectatorCount" Optional="no" Sentence="no">
        Assume that spectator count is 0,
        if battle type is 0 (normal battle)
        and 1 if battle type is 1 (battle replay),
        as the founder of the battle is automatically set as a spectator in that case.
        </Argument>
        <Argument Name="locked" Optional="no" Sentence="no">
        A boolean ("0" (for false) or "1").
        Note that when the client creates a battle,
        the server assumes it is unlocked (by default).
        The client must make sure it assumes this same default.
        </Argument>
        <Argument Name="mapHash" Optional="no" Sentence="no">
        A signed 32-bit integer.
        See the <clink name="OPENBATTLE"/> command for more info.
        </Argument>
        <Argument Name="mapName" Optional="no" Sentence="yes"/>
      </Arguments>
      <Description>
      Sent by the server to all registered clients,
      telling them some of the parameters of the battle changed.
      A battle's internal changes,
      like starting metal, energy, starting position etc.,
      are sent only to clients participating in the battle
      (via the <clink name="SETSCRIPTTAGS:server"/> command).
      </Description>
    </Command>

    <Command Name="UPDATEBATTLEINFO" Source="client">
      <Arguments>
        <Argument Name="spectatorCount" Optional="no" Sentence="no"/>
        <Argument Name="locked" Optional="no" Sentence="no">
        A boolean ("0" (for false) or "1").
        Note that when the client creates a battle,
        the server assumes it is unlocked (by default).
        The client must make sure it assumes this same default.
        </Argument>
        <Argument Name="mapHash" Optional="no" Sentence="no">
        A signed 32-bit integer.
        See the <clink name="OPENBATTLE"/> command for more info.
        </Argument>
        <Argument Name="mapName" Optional="no" Sentence="yes">
        Must NOT contain the file extension!
        </Argument>
      </Arguments>
      <Description>
      Sent by the founder of the battle,
      telling the server that some of the "external" parameters of the battle changed.
      </Description>
    </Command>

<!-- client status changes -->

    <Command Name="MYSTATUS" Source="client">
      <Arguments>
        <Argument Name="status" Optional="no" Sentence="no">
        A signed integer in text form (e.g. "1234").
        Each bit has its meaning:
        <ul>
          <li>b0 = in game (0 - normal, 1 - in game)</li>
          <li>b1 = away status (0 - normal, 1 - away)</li>
          <li>b2-b4 = rank (see Account class implementation for description of rank) - client is not
              allowed to change rank bits himself (only server may set them).</li>
          <li>b5 = access status (tells us whether this client is a server moderator or not) - client is not
              allowed to change this bit himself (only server may set them).</li>
          <li>b6 = bot mode (0 - normal user, 1 - automated bot). This bit is copied from user's account
              and can not be changed by the client himself. Bots differ from human players in that
              they are fully automated and that some anti-flood limitations do not apply to them.</li>
        </ul>
        </Argument>
      </Arguments>
      <Description>
      Sent by a client to inform the server about his changed status.
      <br/><br/>
	  Note: To tell out if a battle is "in-game", a client must check the in-game status of the host.
      </Description>
	  <Response>
	  The status change will be communicated to relevant users via <clink name="CLIENTSTATUS"/> commands.<br/><br/>
	  If a battle founder changes from being not in-game to being in-game, <clink name="HOSTPORT"/> commands will be sent to users in their battle.
	  </Response>
    </Command>

    <Command Name="CLIENTSTATUS" Source="server">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="status" Optional="no" Sentence="no">
        See the <clink name="MYSTATUS:client"/> command for possible values of this parameter.
        </Argument>
      </Arguments>
      <Description>
      Sent by the server to all registered clients,
      indicating that a client's status changed.
      Note that client's status is considered 0 if not indicated otherwise
      (for example, when you login,
      the server sends only statuses of those clients whose statuses differ from 0,
      to save bandwidth).
      </Description>
    </Command>

    <Command Name="MYBATTLESTATUS" Source="client">
      <Arguments>
        <Argument Name="battleStatus" Optional="no" Sentence="no">
          An integer, but with limited range:
          0..2147483647 (use signed int and consider only positive values and zero)
          This number is sent as text.
          Each bit has its meaning:
          <ul>
            <li>b0 = undefined (reserved for future use)</li>
            <li>b1 = ready (0=not ready, 1=ready)</li>
            <li>b2..b5 = team no. (from 0 to 15. b2 is LSB, b5 is MSB)</li>
            <li>b6..b9 = ally team no. (from 0 to 15. b6 is LSB, b9 is MSB)</li>
            <li>b10 = mode (0 = spectator, 1 = normal player)</li>
            <li>b11..b17 = handicap (7-bit number. Must be in range 0..100). Note: Only host can
                change handicap values of the players in the battle (with HANDICAP command).
                These 7 bits are always ignored in this command. They can only be changed
                using HANDICAP command.</li>
            <li>b18..b21 = reserved for future use (with pre 0.71 versions these bits were used for team color index)</li>
            <li>b22..b23 = sync status (0 = unknown, 1 = synced, 2 = unsynced)</li>
            <li>b24..b27 = side (e.g.: arm, core, tll, ... Side index can be between 0 and 15, inclusive)</li>
            <li>b28..b31 = undefined (reserved for future use)</li>
          </ul>
        </Argument>
        <Argument Name="myTeamColor" Optional="no" Sentence="no">
        Should be a 32-bit signed integer in decimal form (e.g. 255 and not FF)
        where each color channel should occupy 1 byte (e.g. in hexdecimal: $00BBGGRR,
        B = blue, G = green, R = red).
        Example: 255 stands for $000000FF.
        </Argument>
      </Arguments>
      <Description>
      Sent by a client to the server, telling him his battle status changed.
      </Description>
	  <Response>
	  The status change will communicated to relevant users via the <clink name="CLIENTBATTLESTATUS"/> and <clink name="UPDATEBATTLEINFO:server"/> commands.
	  </Response>
    </Command>

    <Command Name="CLIENTBATTLESTATUS" Source="server">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="battleStatus" Optional="no" Sentence="no">
        See the <clink name="MYBATTLESTATUS:client"/> command
        for possible values of this argument.
        </Argument>
        <Argument Name="teamColor" Optional="no" Sentence="no">
        Uses the same format as the one used with
        the <clink name="MYBATTLESTATUS:client"/> command.
        </Argument>
      </Arguments>
      <Description>
      Sent by the server to users participating in a battle
      when one of the clients changes his battle status.
      </Description>
    </Command>

    <Command Name="REQUESTBATTLESTATUS" Source="server">
      <Description>
      Sent by the server to a user which just opened a battle or joined one.
      Sent after all <clink name="CLIENTBATTLESTATUS"/>
      commands for all clients have been sent.
      </Description>
      <Response>
      This command is an invitation for the user with a <clink name="MYBATTLESTATUS"/> and choose a suitable team, ally-team and color,
      since the user now knows the battle statuses of other clients.
      </Response>
    </Command>

    <Command Name="HANDICAP" Source="client">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="value" Optional="no" Sentence="no">
        Must be in range [0, 100] (inclusive).
        </Argument>
      </Arguments>
      <Description>
      Sent by the founder of the battle when changing a user's handicap value
      (which is part of that users battle status).
      <br/><br/>
	  Only the founder can change other users handicap values, and that requests from non-founder users will be ignored.
      </Description>
    </Command>

    <Command Name="KICKFROMBATTLE" Source="client">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by the founder of the battle, to tell the server to kick a client from the battle.
      The server removes the target client from the battle and notifies the target client via <clink name="FORCEQUITBATTLE:server"/> command.
      </Description>
    </Command>

    <Command Name="KICKFROMBATTLE" Source="server">
      <Arguments>
        <Argument Name="battleID" Optional="no" Sentence="no"/>
        <Argument Name="userName" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by the server to notify the battle host that the named user should be kicked from the battle in progress.
      </Description>
    </Command>
    
	<Command Name="FORCEQUITBATTLE" Source="server">
      <Description>
      Sent to a client that was kicked from their current battle by the battle founder.
      <br/><br/>
	  The client does not need to send <clink name="LEAVEBATTLE"/>,
      as removal has already been done by the server.
      The only purpose of this command
      is to notify the client that they were kicked.
      (The client will also recieve a corresponding <clink name="LEFTBATTLE:server"/> notification.)
      </Description>
    </Command>

    <Command Name="FORCETEAMNO" Source="client">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="teamNo" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by the founder of a battle
      to change the team number of a user.
      The server will update the client's battle status automatically.
      </Description>
    </Command>

    <Command Name="FORCEALLYNO" Source="client">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="teamNo" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by the founder of a battle
      to change the ally team number of a user.
      The server will update the client's battle status automatically.
      </Description>
    </Command>

    <Command Name="FORCETEAMCOLOR" Source="client">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
        <Argument Name="color" Optional="no" Sentence="no">
        Should be a 32-bit signed integer in decimal form (e.g. 255 and not FF)
        where each color channel should occupy 1 byte (e.g. in hexdecimal: $00BBGGRR,
        B = blue, G = green, R  = red).
        Example: 255 stands for $000000FF.
        </Argument>
      </Arguments>
      <Description>
      Sent by the founder of a battle
      to change the team colour of a team.
      The server will update the client's battle status automatically.
      </Description>
    </Command>

    <Command Name="FORCESPECTATORMODE" Source="client">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by the founder of a battle
      to force a given user to become a spectator.
      The server will update the client's battle status automatically.
      </Description>
    </Command>

    <Command Name="DISABLEUNITS" Source="client">
      <Arguments>
        <Argument Name="unitName1" Optional="no" Sentence="no">
        Multiple units may follow, but at least one must be present in the arguments list.
        </Argument>
        <Argument Name="unitName2" Optional="yes" Sentence="no"/>
        <Argument Name="..." Optional="yes" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by the founder of a battle
      to tell the server that one or more units are now disabled.
      The server will update the client's battle status automatically.
      </Description>
    </Command>

    <Command Name="DISABLEUNITS" Source="server">
      <Arguments>
        <Argument Name="unitName1" Optional="no" Sentence="no">
        Multiple units may follow, but at least one must be present in the arguments list.
        </Argument>
        <Argument Name="unitName2" Optional="yes" Sentence="no"/>
        <Argument Name="..." Optional="yes" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by the server to all clients in a battle,
      telling them that some units have been added to disabled units list.
      Also see the <clink name="DISABLEUNITS:client"/> command.
      </Description>
    </Command>

    <Command Name="ENABLEUNITS" Source="client">
      <Arguments>
        <Argument Name="unitName1" Optional="no" Sentence="no">
        Multiple units may follow, but at least one must be present in the arguments list.
        </Argument>
        <Argument Name="unitName2" Optional="yes" Sentence="no"/>
        <Argument Name="..." Optional="yes" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by the founder of a battle
      to tell the server that one or more units are now enabled.
      The server will update the client's battle status automatically.
      </Description>
    </Command>

    <Command Name="ENABLEUNITS" Source="server">
      <Arguments>
        <Argument Name="unitName1" Optional="no" Sentence="no">
        Multiple units may follow, but at least one must be present in the arguments list.
        </Argument>
        <Argument Name="unitName2" Optional="yes" Sentence="no"/>
        <Argument Name="..." Optional="yes" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by the server to all clients in a battle,
      telling them that some units have been added to enabled units list.
      Also see the <clink name="DISABLEUNITS:client"/> command.
      </Description>
    </Command>

    <Command Name="ENABLEALLUNITS" Source="client">
      <Description>
      Sent by the founder of a battle,
      telling the server that he enabled ALL units and,
      and is thus clearing the disabled units list.
      </Description>
    </Command>

    <Command Name="ENABLEALLUNITS" Source="server">
      <Description>
      Sent by the server to all clients in a battle,
      telling them that the disabled units list has been cleared.
      </Description>
    </Command>

    <Command Name="RING" Source="client">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent to request that a "ring" sound to be played to other user.
      </Description>
      <Response>
      See <clink name="RING:server"/>.
      </Response>
    </Command>

    <Command Name="RING" Source="server">
      <Arguments>
        <Argument Name="userName" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent to notify a client that another user requested that a "ring" sound be played to them.
      </Description>
    </Command>

    <Command Name="ADDBOT" Source="client">
      <Arguments>
        <Argument Name="name" Optional="no" Sentence="no"/>
        <Argument Name="battleStatus" Optional="no" Sentence="no"/>
        <Argument Name="teamColor" Optional="no" Sentence="no">
        Should be a 32-bit signed integer in decimal form (e.g. 255 and not FF)
        where each color channel should occupy 1 byte (e.g. in hexdecimal: $00BBGGRR,
        B = blue, G = green, R  = red).
        </Argument>
        <Argument Name="ai dll" Optional="no" Sentence="yes"/> <!-- FIXME outdated (at least the name) -->
      </Arguments>
      <Description>
      Allows a client to add a bot to the battle.
      </Description>
    </Command>

    <Command Name="ADDBOT" Source="server">
      <Arguments>
        <Argument Name="battleID" Optional="no" Sentence="no">
        helps the client verify that the bot is meant for his battle.
        </Argument>
        <Argument Name="name" Optional="no" Sentence="no"/>
        <Argument Name="owner" Optional="no" Sentence="no"/>
        <Argument Name="battleStatus" Optional="no" Sentence="no"/>
        <Argument Name="teamColor" Optional="no" Sentence="no">
        Should be 32-bit signed integer in decimal form (e.g. 255 and not FF)
        where each color channel should occupy 1 byte (e.g. in hexdecimal: $00BBGGRR,
        B = blue, G = green, R  = red).
        </Argument>
        <Argument Name="ai dll" Optional="no" Sentence="yes"/> <!-- FIXME outdated (at least the name) -->
      </Arguments>
      <Description>
      Indicates that a client has added a bot to the battle.
      </Description>
    </Command>

    <Command Name="REMOVEBOT" Source="client">
      <Arguments>
        <Argument Name="name" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Removes a bot from the battle.
      </Description>
    </Command>

    <Command Name="REMOVEBOT" Source="server">
      <Arguments>
        <Argument Name="battleID" Optional="no" Sentence="no">
        helps the client verify that the bot is meant for his battle.
        </Argument>
        <Argument Name="name" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Indicates that a bot has been removed from the battle.
      </Description>
    </Command>

    <Command Name="UPDATEBOT" Source="client">
      <Arguments>
        <Argument Name="name" Optional="no" Sentence="no"/>
        <Argument Name="battleStatus" Optional="no" Sentence="no">
        Similar to that of the normal client's,
        see <clink name="MYBATTLESTATUS:client"/> for more info.
        </Argument>
        <Argument Name="teamColor" Optional="no" Sentence="no">
        Should be a 32-bit signed integer in decimal form (e.g. 255 and not FF)
        where each color channel should occupy 1 byte (e.g. in hexdecimal: $00BBGGRR,
        B = blue, G = green, R  = red).
        </Argument>
      </Arguments>
      <Description>
      Sent by a client when he is trying to update the status of a bot.
      Only the bot owner and battle host may update a bot's status.
      </Description>
    </Command>

    <Command Name="UPDATEBOT" Source="server">
      <Arguments>
        <Argument Name="battleID" Optional="no" Sentence="no">
        helps the client verify that the bot is meant for his battle.
        </Argument>
        <Argument Name="name" Optional="no" Sentence="no"/>
        <Argument Name="battleStatus" Optional="no" Sentence="no">
        Similar to that of the normal client's,
        see <clink name="MYSTATUS:client"/> for more info.
        </Argument>
        <Argument Name="teamColor" Optional="no" Sentence="no">
        Should be a 32-bit signed integer in decimal form (e.g. 255 and not FF)
        where each color channel should occupy 1 byte (e.g. in hexdecimal: $00BBGGRR,
        B = blue, G = green, R  = red).
        </Argument>
      </Arguments>
      <Description>
      Sent by the server notifying a client in the battle that one of the bots just got his status updated.
      Also see the <clink name="UPDATEBOT:client"/> command.
      </Description>
    </Command>

    <Command Name="ADDSTARTRECT" Source="client">
      <Arguments>
        <Argument Name="allyNo" Optional="no" Sentence="no"/>
        <Argument Name="left" Optional="no" Sentence="no"/>
        <Argument Name="top" Optional="no" Sentence="no"/>
        <Argument Name="right" Optional="no" Sentence="no"/>
        <Argument Name="bottom" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Adds a start rectangle for the 'allyno' ally team.
      Only the battle founder may use this command.
      See lobby client implementations and Spring docs for more info on this one.
      "left", "top", "right" and "bottom" refer to a virtual rectangle that is 200x200 in size,
      where coordinates should be in the interval [0, 200].
      </Description>
    </Command>

    <Command Name="ADDSTARTRECT" Source="server">
      <Arguments>
        <Argument Name="allyNo" Optional="no" Sentence="no"/>
        <Argument Name="left" Optional="no" Sentence="no"/>
        <Argument Name="top" Optional="no" Sentence="no"/>
        <Argument Name="right" Optional="no" Sentence="no"/>
        <Argument Name="bottom" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by the server to clients participating in a battle (except for the host).
      See lobby client implementations and Spring docs for more info on this one.
      "left", "top", "right" and "bottom" refer to a virtual rectangle that is 200x200 in size,
      where coordinates should be in the interval [0, 200].
      </Description>
    </Command>

    <Command Name="REMOVESTARTRECT" Source="client">
      <Arguments>
        <Argument Name="allyNo" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Removing a start rectangle the for 'allyNo' ally team.
      Sent by the host of the battle.
      See client implementations and Spring docs for more info on this one.
      </Description>
    </Command>

    <Command Name="REMOVESTARTRECT" Source="server">
      <Arguments>
        <Argument Name="allyNo" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Removing a start rectangle the for 'allyNo' ally team.
      Sent to clients participating in a battle (except for the host).
      Also see <clink name="ADDSTARTRECT:client"/> command.
      </Description>
    </Command>

    <Command Name="SETSCRIPTTAGS" Source="client">
      <Arguments>
        <Argument Name="pair1" Optional="no"  Sentence="yes"/>
        <Argument Name="pair2" Optional="yes" Sentence="yes"/>
        <Argument Name="pair3" Optional="yes" Sentence="yes"/>
        <Argument Name="..."   Optional="yes" Sentence="yes"/>
      </Arguments>
      <Description>
      Sent by a client (battle host), to inform other clients about current
      battle configuration (start positions type, mod options, map options...).
      Only the battle host itself needs to write the corresponding script tags
      into script.txt, other battle clients should merely use them for display
      purposes.

      The [pair] format is "key=value can have spaces". Keys may not contain
      spaces, and are expected to use the '/' character to separate tables, see
      example:
      <ul>
        <li>SETSCRIPTTAGS game/startmetal=1000</li>
        <li>SETSCRIPTTAGS game/startenergy=1000</li>
        <li>SETSCRIPTTAGS game/maxunits=500</li>
        <li>SETSCRIPTTAGS game/startpostype=1</li>
        <li>SETSCRIPTTAGS game/gamemode=0</li>
        <li>SETSCRIPTTAGS game/limitdgun=1</li>
        <li>SETSCRIPTTAGS game/diminishingmms=0</li>
        <li>SETSCRIPTTAGS game/ghostedbuildings=1</li>
      </ul>
      Though in reality, all tags are joined together in a single command.
      Note that when specifying multiple key+value pairs,
      they must be separated by TAB characters.

      All keys are made lowercase by the server.

      See the examples bellow.
      </Description>
      <Examples>
        <Example>SETSCRIPTTAGS game/modoptions/test=true</Example>
        <Example>SETSCRIPTTAGS game/startmetal=1000<b>[TAB]</b>game/startenergy=1000</Example>
        <Example>See whitespaces: SETSCRIPTTAGS game/startmetal=1000<b>[TAB]</b>game/startenergy=1000</Example>
      </Examples>
    </Command>

    <Command Name="SETSCRIPTTAGS" Source="server">
      <Arguments>
        <Argument Name="pair1" Optional="no"  Sentence="yes"/>
        <Argument Name="pair2" Optional="yes" Sentence="yes"/>
        <Argument Name="pair3" Optional="yes" Sentence="yes"/>
        <Argument Name="..."   Optional="yes" Sentence="yes"/>
      </Arguments>
      <Description>
      Relayed from battle host's <clink name="SETSCRIPTTAGS:client"/> message.
      A client lobby program must process these tags and apply them accordingly
      to the GUI presenting current battle configuration to the player.

      All keys are made lowercase by the server.
      </Description>
      <Examples>
        <Example>SETSCRIPTTAGS game/modoptions/test=true</Example>
        <Example>SETSCRIPTTAGS game/startmetal=1000<b>[TAB]</b>game/startenergy=1000</Example>
        <Example>See whitespaces: SETSCRIPTTAGS game/startmetal=1000<b>[TAB]</b>game/startenergy=1000</Example>
      </Examples>
    </Command>

    <Command Name="REMOVESCRIPTTAGS" Source="client">
      <Arguments>
        <Argument Name="key1" Optional="no"  Sentence="no"/>
        <Argument Name="key2" Optional="yes" Sentence="no"/>
        <Argument Name="key3" Optional="yes" Sentence="no"/>
        <Argument Name="..."  Optional="yes" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by a client (battle host), to inform other clients that a battle
      configuration setting has been removed (this is mainly usefull when
      changing map with map options).
      </Description>
      <Examples>
        <Example>REMOVESCRIPTTAGS game/modoptions/test1 game/modoptions/test2</Example>
      </Examples>
    </Command>

    <Command Name="REMOVESCRIPTTAGS" Source="server">
      <Arguments>
        <Argument Name="key1" Optional="no"  Sentence="no"/>
        <Argument Name="key2" Optional="yes" Sentence="no"/>
        <Argument Name="key3" Optional="yes" Sentence="no"/>
        <Argument Name="..."  Optional="yes" Sentence="no"/>
      </Arguments>
      <Description>
      Relayed from battle host's <clink name="REMOVESCRIPTTAGS:client"/> message.
      A client lobby program has to remove these from the GUI presenting
      current battle configuration to the player.
      </Description>
      <Examples>
        <Example>REMOVESCRIPTTAGS game/modoptions/test1 game/modoptions/test2</Example>
      </Examples>
    </Command>

<!-- ignore list -->   

    <Command Name="IGNORE" Source="client">
      <Arguments>
        <Argument Name="userName=value" Optional="no" Sentence="no">
          The username of the user to be ignored.
        </Argument>
        <Argument Name="reason=value" Optional="yes" Sentence="yes">
          Reason for the ignore.
        </Argument>
      </Arguments>
      <Description>
        Tells the server to add the user to the client's ignore list. Doing this will prevent any SAID*, SAY* and RING commands to be received from the ignored user.
        This command uses named arguments, see "Named Arguments" chapter of the Intro section.
     </Description>
      <Examples>
        <Example>IGNORE userName=joe&#60;TAB&#62;reason=Really annoying, keeps pestering me to play DSD.</Example>
        <Example>IGNORE userName=anotherdsdguy</Example>
      </Examples>
    </Command>

    <Command Name="IGNORE" Source="server">
      <Arguments>
        <Argument Name="userName=value" Optional="no" Sentence="no">
          The username of the ignored user.
        </Argument>
        <Argument Name="reason=value" Optional="yes" Sentence="yes">
          Reason for the ignore.
        </Argument>
      </Arguments>
      <Description>
        Tells the client that the user has been ignored (usually as a result of the IGNORE command sent by the client, but other sources are also possible).
        Also see the <clink name="IGNORE:client"/> command.
        This command uses named arguments, see "Named Arguments" chapter of the Intro section.
      </Description>
    </Command>

    <Command Name="UNIGNORE" Source="client">
      <Arguments>
        <Argument Name="userName=value" Optional="no" Sentence="no">
          The username of the user to be unignored.
        </Argument>
      </Arguments>
      <Description>
        Tells the server to remove the user to the client's ignore list.
        Also see the <clink name="IGNORE:client"/> command.
        This command uses named arguments, see "Named Arguments" chapter of the Intro section.
      </Description>
      <Examples>
        <Example>UNIGNORE userName=joe</Example>
      </Examples>
    </Command>

    <Command Name="UNIGNORE" Source="server">
      <Arguments>
        <Argument Name="userName=value" Optional="no" Sentence="no">
          The username of the unignored user.
        </Argument>
      </Arguments>
      <Description>
        Tells the client that the user has been unignored (usually as a result of the UNIGNORE command sent by the client, but other sources are also possible).
        Also see the <clink name="UNIGNORE:client"/> command.
        This command uses named arguments, see "Named Arguments" chapter of the Intro section.
      </Description>
    </Command>

    <Command Name="IGNORELIST" Source="client">
      <Description>
        Sent by a client when requesting its ignore list.
      </Description>
      <Examples>
        <Example>IGNORELIST</Example>
      </Examples>
    </Command>

    <Command Name="IGNORELISTBEGIN" Source="server">
      <Description>
        Sent by the server when sending the ignore list to the client.
      </Description>
      <Response>
        0 or more <clink name="IGNORELIST:server"/> commands
        and finally a <clink name="IGNORELISTEND"/> command.
      </Response>
    </Command>

    <Command Name="IGNORELIST" Source="server">
      <Arguments>
        <Argument Name="userName=value" Optional="no" Sentence="no">
          The username of the user to be ignored.
        </Argument>
        <Argument Name="reason=value" Optional="yes" Sentence="yes">
          Reason for the ignore.
        </Argument>
      </Arguments>
      <Description>
        Multiple commands of this kind may be sent after a <clink name="IGNORELISTBEGIN"/> command (or none, if the ignore list is empty).
        This command uses named arguments, see "Named Arguments" chapter of the Intro section.
      </Description>
      <Examples>
        <Example>IGNORE userName=joe&#60;TAB&#62;reason=Really annoying, keeps pestering me to play DSD.</Example>
        <Example>IGNORE userName=anotherdsdguy</Example>
      </Examples>
    </Command>

    <Command Name="IGNORELISTEND" Source="server">
      <Description>
        Sent by the server after it has finished sending the ignore list for a client.
        Also see the <clink name="IGNORELIST:server"/> and <clink name="IGNORELISTBEGIN"/> commands.
      </Description>
    </Command>	

<!-- compat flags -->

    <Command Name="LISTCOMPFLAGS" Source="client">
      <Description>
      A client may send this command after it has received <clink name="TASSERVER"/>
      to query the server for supported comp-flags that may be specified on <clink name="LOGIN"/>.
      </Description>
      <Response>
      See <clink name="COMPFLAGS:server"/>.
      </Response>
   </Command>

   <Command Name="COMPFLAGS" Source="server">
      <Arguments>
        <Argument Name="compFlag1" Optional="yes" Sentence="no"/>
        <Argument Name="compFlag2" Optional="yes" Sentence="no"/>
        <Argument Name="..." Optional="yes" Sentence="no"/>
      </Arguments>
      <Description>
      Sent as a response to a <clink name="LISTCOMPFLAGS:client"/> command.
      The server sends a list of supported comp-flags that may be specified
      by the client on <clink name="LOGIN"/>.
      </Description>
      <Examples>
        <Example>COMPFLAGS a b</Example>
        <Example>COMPFLAGS a b sp</Example>
        <Example>COMPFLAGS</Example>
      </Examples>
    </Command>

<!-- Other -->

    <Command Name="REDIRECT" Source="server">
      <Arguments>
        <Argument Name="ip" Optional="no" Sentence="no"/>
        <Argument Name="port" Optional="no" Sentence="no"/>
      </Arguments>
      <Description>
      Sent by the server when running in "redirection mode".
      When a client connects, the server will send him only this message
      and disconnect the socket immediately.
      The client should connect to the given IP and port, in that case.
      This command may be useful when the official server ip/address changes,
      so that clients are automatically redirected to the new one.
      </Description>
      <Examples>
        <Example>
        REDIRECT 87.96.164.14 8200
        </Example>
      </Examples>
    </Command>

    <Command Name="FAILED" Source="server">
      <Description>
		A command used to notify that a command sent to the server has either failed, been denied, or otherwise cannot be completed. 
		<br/>
		This normally is used as a generic error command, to inform lobby/client developers that they have not used the protocol correctly.
	  </Description>
    </Command>

    <Command Name="PROMOTE" Source="client">
      <Description>
		This command posts a message in particular channels, calling for players. It is currently the (only) test case for a client command used JSON format.
	  </Description>
    </Command>

    <Command Name="JSON" Source="server">
      <Description>
		A command used to send information to clients in JSON format. (Currently rarely used.)
	  </Description>
    </Command>

	
	
	
  </CommandList>

</ProtocolDescription>