home *** CD-ROM | disk | FTP | other *** search
/ Komputer for Alle 2003 Ekstra 100 Spil / K-CD_2003_Ekstra_100_Spil.iso / Action / BZFlag / bzflag17g2.exe / doc / protocol.txt < prev    next >
Text File  |  2002-06-07  |  41KB  |  920 lines

  1. BZFlag network protocol
  2. -----------------------
  3. [ This is a work in progress.  It is mostly done but still incomplete. ]
  4.  
  5. --> means from client to server
  6. <-- means from server to client
  7.  
  8. All multi-byte data is in network byte order (aka big endian);  that is, the most
  9. significant byte comes first followed by successively less significant bytes.
  10.  
  11. All numbers are integers unless otherwise specified.  Integers can be 8, 16, or 32
  12. bit signed 2's compliment or unsigned (encoding is the same in regardless of signed
  13. status).  Values in this document in byte boxes are given in hexadecimal.  Values
  14. in the text are given in decimal unless otherwise noted.
  15.  
  16. Bitfields are encoded as unsigned integers.
  17.  
  18. All floating point numbers are in standard IEEE-754 single precision format.
  19.  
  20. Multibyte values are *not* necessarily aligned on 2 or 4 byte boundaries.
  21.  
  22. A client normally follows the following sequence during game play:
  23.  
  24.   connect to server
  25.   get the world database
  26.   join the game
  27.   send/receive game messages
  28.   leave game
  29.   disconnect from server
  30.  
  31.  
  32. common message structures
  33. -------------------------
  34. Most messages begin with the length of the message in bytes followed by a 16 bit code.
  35. The length is 16 bits and excludes itself and the code, so it's the actual length of
  36. the message minus 4.
  37.  
  38. Player identifiers are used in many messages and are always the same:
  39.  
  40.     +----+----+----+----+----+----+----+----+
  41.     | server host addr  |  port   | number  |
  42.     +----+----+----+----+----+----+----+----+
  43.  
  44. The `client host addr' is the IP address of the host the server is on.  This is
  45. superfluous for TCP connections with the server, but is necessary for UDP multicast
  46. communication.  `Port' is the TCP port on the server the client is connected to.
  47. Since clients have to reconnect to the server (see `connect to server'), this will be
  48. unique to each client.  `Number' is the player number on this particular client.
  49. Normally this is zero, but a client is allowed to have multiple players over one
  50. server connection.
  51.  
  52. Flag status is common to a few message types:
  53.  
  54.     +----+----+----+----+----+----+----+----+
  55.     | flag id | status  |  type   |
  56.     +----+----+----+----+----+----+----+----+
  57.            owner id...            | position
  58.     +----+----+----+----+----+----+----+----+
  59.         (x)   |    position (y)   | position
  60.     +----+----+----+----+----+----+----+----+
  61.         (z)   |     launch (x)    |  launch
  62.     +----+----+----+----+----+----+----+----+
  63.         (y)   |     launch (z)    | landing
  64.     +----+----+----+----+----+----+----+----+
  65.         (x)   |    landing (y)    | landing
  66.     +----+----+----+----+----+----+----+----+
  67.         (z)   |    flight time    |  flight
  68.     +----+----+----+----+----+----+----+----+
  69.      end time | initial velocity  |
  70.     +----+----+----+----+----+----+
  71.  
  72. `Position,' `launch,' `landing,' `flight time,' `flight end,' and `initial velocity'
  73. are all floating point numbers.  `Flag id' is the type of flag,enumerated in FlagId.
  74.  
  75. `Status' gives the current location of the flag:
  76.   FlagNoExist  -- the flag is not active (i.e. not in the game)
  77.   FlagOnGround -- the flag is sitting on the ground ready to get picked up
  78.   FlagOnTank   -- the flag is on a player's tank
  79.   FlagInAir    -- the flag is in the air and will fall back down
  80.   FlagComing   -- the flag just appeared and is falling to the ground
  81.   FlagGoing    -- the flag was thrown in the air and is disappearing
  82.  
  83. `Type' indicates the behavior of the flag:  FlagNormal means the flag is permanent
  84. and can be dropped normally (e.g. a team flag);  FlagUnstable means the flag may
  85. disappear after use (e.g. a good super flag);  FlagSticky means the flag cannot be
  86. dropped normally (e.g. a bad super flag).
  87.  
  88. `Player id' indicates which player has the flag when `status' is FlagOnTank.  It
  89. isn't used for any other status.
  90.  
  91. `Position' is the location of the flag on the ground.  It only has meaning when
  92. `status' is FlagOnGround.  The position of a flag when on a tank is the position
  93. of the tank (centered on and at the top of the tank)
  94.  
  95. `Launch' is the location of the flag where it was thrown in the air.  `Landing' is
  96. the location where the flag will/would touch ground.  These are used when `status'
  97. is FlagInAir, FlagComing, and FlagGoing.  The client should make the flag follow a
  98. reasonable flight path (e.g. a parabolic arc) from `launch' to `landing.'
  99.  
  100. `Flight time' is the time elapsed since the flag was thrown into the air.  `Flight
  101. end' the time when the flag will reach the ground.  `Initial velocity' gives the
  102. vertical (z) velocity of the flag when lanuched.  The vertical position of the flag
  103. at time t (ranging from 0 to `flight end') is:  z = z0 + v * t + 0.5 * g * t * t.
  104. z0 = `launch z;' v = `initial velocity;'  g = acceleration due to gravity.
  105.  
  106.  
  107. connect to server
  108. -----------------
  109.   -->   connect(server port)
  110.   <--   +----+----+----+----+----+----+----+----+
  111.     | 42 | 5a | 46 | 53 | 31 | 30 | 37 | 62 |       BZFS107b        version
  112.     +----+----+----+----+----+----+----+----+
  113.     |   port  |
  114.     +----+----+
  115.   -->   close
  116.   -->   connect(port)
  117.  
  118.  
  119. Client should verify the version.  The first four bytes indicates a BZFlag server,
  120. the next byte indicates the major version number (as an ascii digit), the two bytes
  121. after that are the minor version number (as ascii digits), and the 8th byte is the
  122. revision.  Major and minor version number changes indicate incompatible protocol
  123. changes.  Different revisions of a given version are compatible and usually just
  124. indicate client user interface changes.
  125.  
  126. The reconnect port is the port the client should reconnect to the server at.  If
  127. the connection is rejected for some reason then this port will be zero.  Yes, this
  128. step is really pointless, complicates firewall tunnels, and it could just as well
  129. use the original connection.  It's unfortunate historical cruft.  Note that the
  130. server will not wait long for the reconnection.
  131.  
  132. The reconnected socket should have TCP_NODELAY enabled (Nagle algorithm disabled)
  133. to prevent the client from batching the many small packets.
  134.  
  135.  
  136. getting the world database
  137. --------------------------
  138.   -->   +----+----+----+----+----+----+
  139.     | 00 | 02 | 67 | 77 | offset  |                 MsgGetWorld
  140.     +----+----+----+----+----+----+
  141.   <--   +----+----+----+----+----+----+----+----+
  142.     | length  | 67 | 77 |remaining| data... |       MsgGetWorld
  143.     +----+----+----+----+----+----+----+----+
  144.     or
  145.     +----+----+----+----+
  146.     | 00 | 00 | 73 | 6b |                           MsgSuperKill
  147.     +----+----+----+----+
  148.  
  149. Client sends MsgGetWorld requests until it has read the entire world database.
  150. Clients should send an `offset' of 0 for the first request and increase `offset'
  151. by however much data was sent in reply.
  152.  
  153. Each MsgGetWorld reply includes the number of bytes left after the returned
  154. block of data in `remaining'.  The server returns 0 in `remaining' when there
  155. is no more data left to read.  In no event will the server return more than
  156. MaxPacketLen - 6 bytes of data in one reply (see protocol.h for the definition
  157. of MaxPacketLen).
  158.  
  159. The server may return MsgSuperKill at any time during the download of the world
  160. database.  The client should immediately close the connection to the server.
  161.  
  162. No other messages should be returned by the server as long as the client sends
  163. only MsgGetWorld requests.
  164.  
  165. The `data' has the following encoding:
  166.  
  167.     +----+----+----+----+----+----+----+----+
  168.     | 73 | 74 | 00 | 18 |  style  | players |       WorldCodeStyle, length of data
  169.     +----+----+----+----+----+----+----+----+
  170.     |  shots  |  flags  |linear acceleration|
  171.     +----+----+----+----+----+----+----+----+
  172.     |angulr acceleration| shake t | shake w |
  173.     +----+----+----+----+----+----+----+----+
  174.     |    server time    |
  175.     +----+----+----+----+
  176.  
  177. Values are:
  178.   style:        bitfield of game style
  179.   players:      maximum number of players
  180.   shots:        maximum number of shots at once per player
  181.   flags:        maximum number of flags that may exist at once
  182.   linear acc.:  linear acceleration limit (float)
  183.   angulr acc.:  angular acceleration limit (float)
  184.   shake t:      time to shake a bad flag (1/10ths of seconds)
  185.   shake w:      number of wins to shake a bad flag
  186.   server time:  seconds since midnight Jan 1, 1970 GMT on the server, used when
  187.         synchronizing times across clients
  188.  
  189. The rest of the world database is encoded in individual blocks decribing each
  190. object.  Only permanent immovable objects are included.  The encodings for each
  191. type of object are:
  192.  
  193.   team base:
  194.     +----+----+----+----+----+----+----+----+
  195.     | 62 | 61 | team id |     center (x)    |
  196.     +----+----+----+----+----+----+----+----+
  197.     |     center (y)    |     center (z)    |
  198.     +----+----+----+----+----+----+----+----+
  199.     |       angle       |      size (x)     |
  200.     +----+----+----+----+----+----+----+----+
  201.     |      size (y)     |    safety (x)     |
  202.     +----+----+----+----+----+----+----+----+
  203.     |    safety (y)     |    safety (z)     |
  204.     +----+----+----+----+----+----+----+----+
  205.  
  206.   wall:
  207.     +----+----+----+----+----+----+----+----+
  208.     | 77 | 6c |    center (x)     | center...
  209.     +----+----+----+----+----+----+----+----+
  210.      (y)      |    center (z)     | angle...
  211.     +----+----+----+----+----+----+----+----+
  212.           |       width       | height...
  213.     +----+----+----+----+----+----+----+----+
  214.           |
  215.     +----+----+
  216.  
  217.   pyramid:
  218.     +----+----+----+----+----+----+----+----+
  219.     | 70 | 79 |    center (x)     | center...
  220.     +----+----+----+----+----+----+----+----+
  221.      (y)      |    center (z)     | angle...
  222.     +----+----+----+----+----+----+----+----+
  223.           |       width       | depth...
  224.     +----+----+----+----+----+----+----+----+
  225.           |      height       |
  226.     +----+----+----+----+----+----+
  227.  
  228.   box:
  229.     +----+----+----+----+----+----+----+----+
  230.     | 62 | 78 |    center (x)     | center...
  231.     +----+----+----+----+----+----+----+----+
  232.      (y)      |    center (z)     | angle...
  233.     +----+----+----+----+----+----+----+----+
  234.           |       width       | depth...
  235.     +----+----+----+----+----+----+----+----+
  236.           |      height       |
  237.     +----+----+----+----+----+----+
  238.  
  239.   teleporter:
  240.     +----+----+----+----+----+----+----+----+
  241.     | 74 | 65 |    center (x)     | center...
  242.     +----+----+----+----+----+----+----+----+
  243.      (y)      |    center (z)     | angle...
  244.     +----+----+----+----+----+----+----+----+
  245.           |       width       | depth...
  246.     +----+----+----+----+----+----+----+----+
  247.           |      height       | border...
  248.     +----+----+----+----+----+----+----+----+
  249.           |
  250.     +----+----+
  251.  
  252.   teleporter link:
  253.     +----+----+----+----+----+----+
  254.     | 6c | 6e |  from   |   to    |
  255.     +----+----+----+----+----+----+
  256.  
  257.   end of data:
  258.     +----+----+
  259.     | 65 | 64 |
  260.     +----+----+
  261.  
  262. The above values are interpreted as follows:
  263.  
  264.   angle (float):        in radians from the x-axis in the xy plane
  265.   width (float):        half width (in xy) measured from center
  266.   depth (float):        half depth (in xy) measured from center
  267.   height (float):       full height (in z) measured from bottom
  268.   border (float):       full size of the square cross section teleporter border
  269.   center (float):       center in xy, bottom in z
  270.   safety (float):       safety position for team flags, used when team A drops team B's
  271.             flag on team C's base.
  272.   from & to:            index of teleporter face starting from zero;  the N'th teleporter
  273.             in the world data has face indices 2*N and 2*N+1.  teleporter
  274.             links indicate which face teleports to which face;  faces may
  275.             teleport to themselves.
  276.  
  277.  
  278. join game
  279. ---------
  280. Once connected a player normally requests to join the game.  The server replies with
  281. MsgSuperKill, MsgReject, or MsgAccept.
  282.  
  283.  
  284.   -->   +----+----+----+----+----+----+----+----+
  285.     | length  | 65 | 6e |  player id...             MsgEnter
  286.     +----+----+----+----+----+----+----+----+
  287.                 |  type   |  team   |
  288.     +----+----+----+----+----+----+----+----+
  289.     | call sign (CallSignLen bytes)...
  290.     +----+----+----+----+----+----+----+----+
  291.     ...
  292.     +----+----+----+----+----+----+----+----+
  293.                         |
  294.     +----+----+----+----+----+----+----+----+
  295.     | email address (EmailLen bytes)...
  296.     +----+----+----+----+----+----+----+----+
  297.     ...
  298.     +----+----+----+----+----+----+----+----+
  299.                         |
  300.     +----+----+----+----+----+----+----+----+
  301.   <--   +----+----+----+----+
  302.     | 00 | 00 | 61 | 63 |                           MsgAccept
  303.     +----+----+----+----+
  304.     or
  305.     +----+----+----+----+----+----+
  306.     | 00 | 02 | 72 | 6a |  code   |                 MsgReject
  307.     +----+----+----+----+----+----+
  308.     or
  309.     +----+----+----+----+
  310.     | 00 | 00 | 73 | 6b |                           MsgSuperKill
  311.     +----+----+----+----+
  312.  
  313. `Type' is one of the enumerants in PlayerType and `team' is one from TeamColor.
  314. The call sign is the player's `handle' during the game;  the call sign is used
  315. to identify the player.  No attempt is made by the server to prevent the
  316. duplication of call signs during a game.  The email address can be anything,
  317. but should be the email address for human players (e.g. username@hostname).
  318. BZFlag players can choose `anonymous' instead of their email address.  The call
  319. sign and email address should be NUL terminated ASCII strings, padded with
  320. NUL's to the required length.  `Length' is 12 + CallSignLen + EmailLen.
  321.  
  322. If the server responds with MsgSuperKill the client should close the connection
  323. immediately.  If the server responds with MsgReject, the client has not joined the
  324. game but may keep the server connection open and try again.  The reason for rejection
  325. is included with the MsgReject message:
  326.  
  327.     RejectBadRequest        -- bogus data in MsgEnter
  328.     RejectBadTeam           -- invalid team id
  329.     RejectBadType           -- invalid client type
  330.     RejectNoRogues          -- rogue team requested but rogues not allowed
  331.     RejectTeamFull          -- no more players allowed on team
  332.     RejectServerFull        -- no more players allowed on any team
  333.  
  334. If the server responds with MsgAccept, the player has successfully joined the game.
  335. The server then automatically sends updates about each flag, team, and player.  The
  336. client should be prepared to accept these updates in any order.  The flag and team
  337. updates are sent as MsgFlagUpdate and MsgTeamUpdate messages, respectively.  Player
  338. updates are sent as MsgAddPlayer messages.  The client will receive a MsgAddPlayer
  339. for the player it just added, but only after it has received a MsgAddPlayer for each
  340. of the players already joined.
  341.  
  342. Until it receives the MsgAddPlayer for the player it just added, the client will
  343. only receive the following kinds of messages:
  344.  
  345.     MsgSuperKill
  346.     MsgFlagUpdate
  347.     MsgTeamUpdate
  348.     MsgAddPlayer
  349.     MsgNetworkRelay
  350.  
  351. Players of type ComputerPlayer are not sent team or flag updates and only get the
  352. MsgAddPlayer for themselves.  This probably wasn't a good idea, but there it is.
  353.  
  354.  
  355. leave game
  356. ----------
  357. Once entered, a player can leave the game at any time.  This should be done by sending
  358. the following message then closing the connection:
  359.  
  360.   -->   +----+----+----+----+
  361.     | 00 | 00 | 65 | 78 |                           MsgExit
  362.     +----+----+----+----+
  363.  
  364. There is no reply.  Clients can also leave by simply closing the connection, but
  365. sending MsgExit first is recommended.
  366.  
  367.  
  368. during a game
  369. -------------
  370. There are several types of messages that are delivered at any time after a player
  371. enters a game.  Clients must be prepared to handle them in any order.
  372.  
  373.   MsgSuperKill
  374.   <--   +----+----+----+----+
  375.     | 00 | 00 | 73 | 6b |
  376.     +----+----+----+----+
  377.     Client must immediately disconnect from the server.
  378.  
  379.   MsgTimeLeft
  380.   <--   +----+----+----+----+----+----+
  381.     | 00 | 02 | 74 | 6f |time left|
  382.     +----+----+----+----+----+----+
  383.     Gives the time remaining in the game.  This message is only sent when the
  384.     server has time limit configured.  If the time remaining is zero, the client
  385.     should indicate to the player that the game is over.
  386.  
  387.     `Time left' is in seconds.  It is not sent every second so clients will need
  388.     to do their own count down between messages.
  389.  
  390.   MsgScoreOver
  391.   <--   +----+----+----+----+----+----+----+----+
  392.     | 00 | 0a | 73 | 6f |     player id...
  393.     +----+----+----+----+----+----+----+----+
  394.                 | team id |
  395.     +----+----+----+----+----+----+
  396.     Gives the player or team that won the game by reaching the target score.
  397.     This message is only sent when the server has a target score configured.
  398.     The client should indicate which team or player won and that the game is
  399.     over.
  400.  
  401.     If `team id' is NoTeam then `player id' indicates which player has won.
  402.     Otherwise `team id' indicates which team won.
  403.  
  404.   MsgSetTTL
  405.   <--   +----+----+----+----+----+----+
  406.     | 00 | 02 | 74 | 74 | new TTL |
  407.     +----+----+----+----+----+----+
  408.     Should a client join with a larger TTL than any other client, the server
  409.     notifies all the clients of the new minimum TTL.  The TTL is the time-
  410.     to-live for the multicast player-to-player packets.  Upon receipt of this
  411.     message a client should change the TTL of outgoing multicast packets to
  412.     at least `new TTL.'
  413.  
  414.   MsgNetworkRelay
  415.   <--   +----+----+----+----+
  416.     | 00 | 00 | 6e | 72 |
  417.     +----+----+----+----+
  418.     This message means that the client must start sending messages normally
  419.     sent via multicast directly to the server.  The server will send the
  420.     messages to each client.  The server may send this when a client first
  421.     enters a game or later when another client requests multicast-over-tcp
  422.     relaying.  If the server itself cannot do multicasting then it must
  423.     force all clients to do multicast-over-tcp.
  424.  
  425.   -->   +----+----+----+----+
  426.     | 00 | 00 | 6e | 72 |
  427.     +----+----+----+----+
  428.     When a client can't do multicasting it notifies the server of that fact
  429.     and the server begins listening for multicast traffic on behalf of the
  430.     client and forwarding it to that client via tcp.  It also sends messages
  431.     from that client via multicast to other clients.  Send this message to
  432.     the server soon after connecting if you cannot contact the server via
  433.     multicast so you don't miss messages from other players.
  434.  
  435.   MsgAddPlayer
  436.   <--   +----+----+----+----+----+----+----+----+
  437.     | length  | 61 | 70 |     player id...
  438.     +----+----+----+----+----+----+----+----+
  439.                 |  type   |  team   |
  440.     +----+----+----+----+----+----+----+----+
  441.     |  wins   |  losses | call sign...
  442.     +----+----+----+----+----+----+----+----+
  443.         ... (CallSignLen bytes)...      |
  444.     +----+----+----+----+----+----+----+----+
  445.     | email address...
  446.     +----+----+----+----+----+----+----+----+
  447.          ... (EmailLen bytes)...        |
  448.     +----+----+----+----+----+----+----+----+
  449.     Sent when another player enters the game and when joining a game if other
  450.     players are already joined.  `Type' is enumerated in PlayerType, `team'
  451.     is enumerated in TeamColor.  `Wins' and `losses' give the player's score.
  452.     They are unsigned integers;  the player's score equals wins minus losses.
  453.     `Call sign' and `email address' are NUL terminated ASCII strings.  `Length'
  454.     is 16 + CallSignLen + EmailLen.
  455.  
  456.   MsgRemovePlayer
  457.   <--   +----+----+----+----+----+----+----+----+
  458.     | 00 | 08 | 72 | 70 |     player id...
  459.     +----+----+----+----+----+----+----+----+
  460.                 |
  461.     +----+----+----+----+
  462.     Sent when another player leaves the game.
  463.  
  464.   MsgFlagUpdate
  465.   <--   +----+----+----+----+----+----+----+----+
  466.     | 00 | 40 | 66 | 75 |flag num | flag id |
  467.     +----+----+----+----+----+----+----+----+
  468.     | status  |  type   |     player id...
  469.     +----+----+----+----+----+----+----+----+
  470.                 |    position (x)   |
  471.     +----+----+----+----+----+----+----+----+
  472.     |    position (y)   |    position (z)   |
  473.     +----+----+----+----+----+----+----+----+
  474.     |     launch (x)    |     launch (y)    |
  475.     +----+----+----+----+----+----+----+----+
  476.     |     launch (z)    |    landing (x)    |
  477.     +----+----+----+----+----+----+----+----+
  478.     |    landing (y)    |    landing (z)    |
  479.     +----+----+----+----+----+----+----+----+
  480.     |    flight time    |    flight end     |
  481.     +----+----+----+----+----+----+----+----+
  482.     | initial velocity  |
  483.     +----+----+----+----+
  484.     Sent when a flag's state changes.  Also sent to a client when it enters
  485.     a game.  `Flag num' is the index of the flag.  Flags are indexed from
  486.     zero up to the maximum number of flags minus one.
  487.  
  488.     Clients must update the flag positions while the flag is in flight (i.e.
  489.     `status' is FlagInAir, FlagComing, or FlagGoing.  If FlagInAir or
  490.     FlagComing then the client should change the flag's status to
  491.     FlagOnGround when the flag's flight time equals or exceeds `flight end.'
  492.     The position should be set exactly to `landing.'  If FlagGoing, the
  493.     client should change the flag's status to FlagNoExist when the flight
  494.     time equals or exceeds `flight end.'
  495.  
  496.     BZFlag uses the first half of the flight time for FlagComing and the
  497.     last half of the flight time for FlagGoing to make the flag appear or
  498.     disappear from/to nothing.  This allows players to adjust to the
  499.     appearance/disappearance of a flag.
  500.  
  501.   MsgTeamUpdate
  502.   <--   +----+----+----+----+----+----+----+----+
  503.     | 00 | 0a | 74 | 6f |  team   |  size   |
  504.     +----+----+----+----+----+----+----+----+
  505.     | active  |  wins   | losses  |
  506.     +----+----+----+----+----+----+
  507.     Gives the current state of team `team.'  `Size' is the number of
  508.     players on the team.  `Active' is the number of active players on the
  509.     team.  An active player is one that can participate in the game (e.g.
  510.     grab flags, shoot opponents, etc.);  a non-active player can only
  511.     observe the game.  Only active players are considered when deciding
  512.     if there are any players on a team (to decide if the team flag should
  513.     be inserted or withdrawn from the game).  `Wins' and `losses' give the
  514.     team's score (wins minus losses).
  515.  
  516.   MsgAlive
  517.   <--   +----+----+----+----+----+----+----+----+
  518.     | 00 | 20 | 61 | 6c |     player id...
  519.     +----+----+----+----+----+----+----+----+
  520.                 |    position (x)   |
  521.     +----+----+----+----+----+----+----+----+
  522.     |    position (y)   |    position (z)   |
  523.     +----+----+----+----+----+----+----+----+
  524.     |    forward (x)    |    forward (y)    |
  525.     +----+----+----+----+----+----+----+----+
  526.     |    forward (z)    |
  527.     +----+----+----+----+
  528.     Sent when a player comes alive.  A player that has joined is not on the
  529.     game board until it sends this message, which declares that it is in
  530.     game and gives the starting position and orientation.  Players are removed
  531.     from the game board when killed and do not reappear until sending this
  532.     message again.
  533.  
  534.   -->   +----+----+----+----+----+----+----+----+
  535.     | 00 | 18 | 61 | 6c |    position (x)   |
  536.     +----+----+----+----+----+----+----+----+
  537.     |    position (y)   |    position (z)   |
  538.     +----+----+----+----+----+----+----+----+
  539.     |    forward (x)    |    forward (y)    |
  540.     +----+----+----+----+----+----+----+----+
  541.     |    forward (z)    |
  542.     +----+----+----+----+
  543.     A player sends this message to enter the game board.  Note that this
  544.     version of the message differs from the one sent by the server in that
  545.     it lacks the player id (which is implicit in the server connection).
  546.     Players must send this message to change their state from dead to alive.
  547.     Players should not send MsgAlive for a certain penalty period after
  548.     being killed (but the server does not enforce a minimum time).  The
  549.     currently penalty is ExplodeTime.
  550.  
  551.     `Position' gives the location of the player and `forward' gives the
  552.     player's forward direction vector.
  553.  
  554.  
  555.   MsgKilled
  556.   <--   +----+----+----+----+----+----+----+----+
  557.     | 00 | 12 | 6b | 6c |     victim id...
  558.     +----+----+----+----+----+----+----+----+
  559.                 |     killer id...
  560.     +----+----+----+----+----+----+----+----+
  561.                 | shot id |
  562.     +----+----+----+----+----+----+
  563.     Sent by the server when a player is killed by itself or another player.
  564.     The victim id is the player that was destroyed and the killer id is the
  565.     player credited with the kill.  Shot id identifies which of the killer's
  566.     shots hit the victim;  if the shot isn't a laser or shockwave, other
  567.     players may assume the shot has stopped and needn't check themselves
  568.     against the shot (or they can wait until the MsgShotEnd message arrives).
  569.  
  570.   -->   +----+----+----+----+----+----+----+----+
  571.     | 00 | 0a | 6b | 6c |     killer id...
  572.     +----+----+----+----+----+----+----+----+
  573.                 | shot id |
  574.     +----+----+----+----+----+----+
  575.     Sent by the victim when it detects that it's been hit, naming the killer
  576.     and which of the killer's shots was the one that hit.  Note that the
  577.     server does not verify kills in any way so it's trivial to `cheat' by
  578.     claiming you've been killed;  this is generally unproductive.  It's
  579.     also easy to cheat by never sending MsgKilled, making you almost
  580.     immortal.  Don't do this.
  581.  
  582.   MsgGrabFlag
  583.   <--   +----+----+----+----+----+----+----+----+
  584.     | 00 | 48 | 67 | 66 |     grabber id...
  585.     +----+----+----+----+----+----+----+----+
  586.                 |flag num | flag id |
  587.     +----+----+----+----+----+----+----+----+
  588.     | status  |  type   |      owner id...
  589.     +----+----+----+----+----+----+----+----+
  590.                 |    position (x)   |
  591.     +----+----+----+----+----+----+----+----+
  592.     |    position (y)   |    position (z)   |
  593.     +----+----+----+----+----+----+----+----+
  594.     |     launch (x)    |     launch (y)    |
  595.     +----+----+----+----+----+----+----+----+
  596.     |     launch (z)    |    landing (x)    |
  597.     +----+----+----+----+----+----+----+----+
  598.     |    landing (y)    |    landing (z)    |
  599.     +----+----+----+----+----+----+----+----+
  600.     |    flight time    |    flight end     |
  601.     +----+----+----+----+----+----+----+----+
  602.     | initial velocity  |
  603.     +----+----+----+----+
  604.     Sent by the server when a player is allowed to grab a flag.  This is
  605.     both the notice to the player trying to grab the flag that it succeeded
  606.     and the notice to all other players that the flag was grabbed.  Note
  607.     that `grabber id' is redundant;  it's always equal to `owner id.'
  608.  
  609.     `Flag num' is the index of the flag.  Flags are indexed from zero up to
  610.     the maximum number of flags minus one.
  611.  
  612.   -->   +----+----+----+----+----+----+
  613.     | 00 | 02 | 67 | 66 |flag num |
  614.     +----+----+----+----+----+----+
  615.     Sent by a player when it wants to grab a flag.  Players should only
  616.     send this message when their tank is within FlagRadius of a flag (that's
  617.     any part of the tank, not simply the center) and on the ground.  The
  618.     server will not verify this, but it will verify some other stuff.  The
  619.     player must not assume it will be able to grab the flag.  Instead it has
  620.     to wait for a MsgGrabFlag reply.
  621.  
  622.   MsgDropFlag
  623.   <--   +----+----+----+----+----+----+----+----+
  624.     | 00 | 48 | 64 | 66 |     dropper id...
  625.     +----+----+----+----+----+----+----+----+
  626.                 |flag num | flag id |
  627.     +----+----+----+----+----+----+----+----+
  628.     | status  |  type   |      owner id...
  629.     +----+----+----+----+----+----+----+----+
  630.                 |    position (x)   |
  631.     +----+----+----+----+----+----+----+----+
  632.     |    position (y)   |    position (z)   |
  633.     +----+----+----+----+----+----+----+----+
  634.     |     launch (x)    |     launch (y)    |
  635.     +----+----+----+----+----+----+----+----+
  636.     |     launch (z)    |    landing (x)    |
  637.     +----+----+----+----+----+----+----+----+
  638.     |    landing (y)    |    landing (z)    |
  639.     +----+----+----+----+----+----+----+----+
  640.     |    flight time    |    flight end     |
  641.     +----+----+----+----+----+----+----+----+
  642.     | initial velocity  |
  643.     +----+----+----+----+
  644.     Sent by the server when a player is allowed to drop a flag.  This is
  645.     both the notice to the player trying to drop the flag that it succeeded
  646.     and the notice to all other players that the flag was dropped.  `Owner
  647.     id' is meaningless in this message.
  648.  
  649.     `Flag num' is the index of the flag.  Flags are indexed from zero up to
  650.     the maximum number of flags minus one.
  651.  
  652.   -->   +----+----+----+----+----+----+----+----+
  653.     | 00 | 0c | 64 | 66 |    position (x)   |
  654.     +----+----+----+----+----+----+----+----+
  655.     |    position (y)   |    position (z)   |
  656.     +----+----+----+----+----+----+----+----+
  657.     Sent by a player when it wants to drop a flag.  Players should only
  658.     send this message when they have a flag and only when the flag dropping
  659.     constraints have been met (i.e. the flag can be dropped at any time, or
  660.     the player got the antidote flag, etc.)  The player must not assume it
  661.     has dropped the flag until it receives a MsgDropFlag in response.
  662.  
  663.     `Position' is in floating point and is the position of the tank that
  664.     dropped the flag when it was dropped.
  665.  
  666.   MsgCaptureFlag
  667.   <--   +----+----+----+----+----+----+----+----+
  668.     | 00 | 0c | 63 | 66 |    capturer id...
  669.     +----+----+----+----+----+----+----+----+
  670.                 |flag num | team id |
  671.     +----+----+----+----+----+----+----+----+
  672.     Sent by the server when a team's flag has been captured.  `Capturer id'
  673.     is the player who captured the flag.  `Flag num' is the index of the
  674.     captured flag.  Flags are indexed from zero up to the maximum number of
  675.     flags minus one.  `Team id' is the id of the team who's flag was
  676.     captured.  Note that the player who captures the flag may be on the team
  677.     that was captured.
  678.  
  679.     The server makes all players on the captured team dead.  This message is
  680.     the only notice that the players are now dead so clients should act
  681.     accordingly.  This is also the only notice that the capturer is no longer
  682.     carrying a flag.
  683.  
  684.   -->   +----+----+----+----+----+----+
  685.     | 00 | 02 | 63 | 66 | team id |
  686.     +----+----+----+----+----+----+
  687.     Sent by a player when it captures a team flag.  `Team id' is the id of
  688.     the team who's flag was captured.  The player should wait until the
  689.     server sends back the MsgCaptureFlag response before assuming the
  690.     capture was successful.  A player should send this message only when
  691.     1) its tank is at least halfway inside a team base, 2) the tank is on
  692.     the ground, and 3) the player has its own team flag in an enemy base
  693.     or the player has another team's flag in its own base.  Note that the
  694.     server will not enforce any of these requirements.
  695.  
  696.   MsgShotBegin
  697.   <--
  698.   -->   +----+----+----+----+----+----+----+----+
  699.     | 00 | 2c | 73 | 62 |    shooter id...
  700.     +----+----+----+----+----+----+----+----+
  701.                 | shot id | position
  702.     +----+----+----+----+----+----+----+----+
  703.         (x)   |    position (y)   | position
  704.     +----+----+----+----+----+----+----+----+
  705.         (z)   |    velocity (x)   | velocity
  706.     +----+----+----+----+----+----+----+----+
  707.         (y)   |    velocity (z)   |  time
  708.     +----+----+----+----+----+----+----+----+
  709.           |flag type|     lifetime      |
  710.     +----+----+----+----+----+----+----+----+
  711.     Sent by the server when a player has fired a shot.  The identical message
  712.     is send by a player when it fires a shot.  The server does not verify
  713.     that the player is allowed to fire a shot.
  714.  
  715.     `Shooter id' identifies the player that did the shooting.  `Shot id' is
  716.     a number that uniquely identifies to the shooter which shot this is.
  717.     `Position,' `velocity,' `time,' and `lifetime' are floating point
  718.     numbers.  `Position' is the starting position of the shot.  `Velocity'
  719.     is the starting velocity of the shot.  `Time' is the time the shot has
  720.     existed (probably 0.0).  `Lifetime' is how long the shot exists.  `Flag
  721.     type' is a FlagId and is the type of flag the shooter had when the shot
  722.     was fired.
  723.  
  724.     Clients are expected to compute the flight path of shots (except Guided
  725.     Missiles) given the information in MsgShotBegin.  That includes handling
  726.     ricochets, building impacts, and teleportation, but not tank impacts.
  727.     Each player decides if it itself has been hit by a shot at each time step
  728.     based on this flight path.  Since the path of a guided missile cannot be
  729.     predicted, updates to a guided missile's path is sent throughout its
  730.     flight by the shooter via MsgGMUpdate messages.
  731.  
  732.     A player should test itself against a shot using whatever algorithm it
  733.     likes, but at a minimum should test the line segments the shot moves
  734.     along during the time step against a tank aligned bounding box.
  735.     Accounting for the linear motion of the tank over the time step is
  736.     better and accounting for both the linear and angular motion is better
  737.     still.  Note that the shot has a certain radius that should be taking
  738.     into account during intersection testing.  This is particularly
  739.     important when testing against a tank with the narrow flag.  Ideally,
  740.     the shot would be exactly tested against the tank geometry.  However,
  741.     that's more work than realistically necessary.
  742.  
  743.   MsgShotEnd
  744.   <--
  745.   -->   +----+----+----+----+----+----+----+----+
  746.     | 00 | 0c | 73 | 65 |    shooter id...
  747.     +----+----+----+----+----+----+----+----+
  748.                 | shot id | reason  |
  749.     +----+----+----+----+----+----+----+----+
  750.     Sent by the server when a shot has been terminated before its lifetime
  751.     has expired.  The identical message is sent by the player that
  752.     terminates the shot.  This is normally the player that has just been
  753.     hit by the shot.  The server does not verify that the player has or
  754.     has not been hit.  This message is also sent by the player that fired
  755.     a guided missile when the shot hits the ground or a building (note that
  756.     guided missiles don't ricochet).
  757.  
  758.     `Shooter id' identifies the player that fired the shot and `shot id'
  759.     is the same as in the MsgShotBegin message for the shot.  `Reason' is
  760.     one if the other players should show an explosion for the shot and
  761.     zero otherwise.
  762.  
  763.   MsgScore
  764.   <--   +----+----+----+----+----+----+----+----+
  765.     | 00 | 0c | 73 | 63 |     player id...
  766.     +----+----+----+----+----+----+----+----+
  767.                 |  wins   | losses  |
  768.     +----+----+----+----+----+----+----+----+
  769.     Sent by the server when a player's score changes.  `Player id' is the
  770.     player with the new score, and `wins' and `losses' are the new scores.
  771.  
  772.   -->   +----+----+----+----+----+----+----+----+
  773.     | 00 | 04 | 73 | 63 |  wins   | losses  |
  774.     +----+----+----+----+----+----+----+----+
  775.     Sent by a player when its score changes.
  776.  
  777.   MsgTeleport
  778.   <--   +----+----+----+----+----+----+----+----+
  779.     | 00 | 0c | 73 | 63 |     player id...
  780.     +----+----+----+----+----+----+----+----+
  781.                 |  from   |   to    |
  782.     +----+----+----+----+----+----+----+----+
  783.     Sent by the server when a player teleports.  `From' is the index of the
  784.     teleporter face the player entered and `to' is the index of the face
  785.     the player exited.
  786.  
  787.   -->   +----+----+----+----+----+----+----+----+
  788.     | 00 | 04 | 73 | 63 |  from   |   to    |
  789.     +----+----+----+----+----+----+----+----+
  790.     Sent by a player when it passes through a teleporter.
  791.  
  792.   MsgMessage
  793.   <--   +----+----+----+----+----+----+----+----+
  794.     | length  | 6d | 67 |  from player id...
  795.     +----+----+----+----+----+----+----+----+
  796.                 |   to player id...
  797.     +----+----+----+----+----+----+----+----+
  798.                 |  team   |message...
  799.     +----+----+----+----+----+----+----+----+
  800.     ...(MessageLen bytes)...
  801.     +----+----+----+----+----+----+----+----+
  802.                         |
  803.     +----+----+----+----+----+----+----+----+
  804.     Sent by the server when one player sends a message to others.  `Length'
  805.     is the length of the message (18 + MessageLen bytes).  `From player id'
  806.     is the player sending the message, `to player id' is the player to
  807.     receive the message, and `team' is the team to receive the message.
  808.     If `to player id' is all zeros then the message is being sent to
  809.     everyone on `team'.  If `to player id' is all zeros and `team' is
  810.     RogueTeam then the message is being sent to all players.  If `to player
  811.     id' is not all zeros then `team' is ignored and the message is only for
  812.     the identified player.
  813.  
  814.   -->   +----+----+----+----+----+----+----+----+
  815.     | length  | 6d | 67 |    player id...
  816.     +----+----+----+----+----+----+----+----+
  817.                 |  team   |message...
  818.     +----+----+----+----+----+----+----+----+
  819.     ...(MessageLen bytes)...
  820.     +----+----+----+----+----+----+----+----+
  821.                         |
  822.     +----+----+----+----+----+----+----+----+
  823.     Sent by player to send a message to other players.  `Length' is is the
  824.     length of the message (10 + MessageLen bytes).  `Player id' is the
  825.     player to receive the message (or all zeros for all players on the
  826.     given team) and `team' is the team to receive the message (or
  827.     RogueTeam for all teams).
  828.  
  829.   MsgPlayerUpdate
  830.     +----+----+----+----+----+----+----+----+
  831.     | 00 | 2a | 70 | 75 |    player id...
  832.     +----+----+----+----+----+----+----+----+
  833.                 | status  | position
  834.     +----+----+----+----+----+----+----+----+
  835.         (x)   |    position (y)   | position
  836.     +----+----+----+----+----+----+----+----+
  837.         (z)   |    velocity (x)   | velocity
  838.     +----+----+----+----+----+----+----+----+
  839.         (y)   |    velocity (z)   | azimuth
  840.     +----+----+----+----+----+----+----+----+
  841.           | angular velocity  |
  842.     +----+----+----+----+----+----+
  843.     Sent by players to notify other players of changes in its status,
  844.     position, or velocity.  This message may be received directly from
  845.     other players via multicast or from the server.
  846.  
  847.     `Status' is the tank's current status.  See PlayerStatus for the
  848.     meaning of the bitfield's bits.  The FlagActive bit indicates whether
  849.     the player's flag's special powers are active or not.  The Phantom
  850.     Zone flag is an example of a flag that's active only some of the time.
  851.     The CrossingWall bit indicates if the player's tank is intersected by
  852.     a wall or teleporter;  other players can use this to draw the player
  853.     in some special way.  CrossingWall could be computed by each player
  854.     from other information;  it's only provided to save the other players
  855.     the trouble.
  856.  
  857.     `Position,' `velocity,' `azimuth,' and `angular velocity' are floating
  858.     point numbers.  `Azimuth' is the orientation of the tank in radians
  859.     (the +x axis is 0.0, +y is pi/2).  `Angular velocity' is the change in
  860.     azimuth per second.  `Position' is the tank position and `velocity' is
  861.     the change in tank position per second.
  862.  
  863.     A player normally only sends an update when its position or orientation
  864.     as could be predicted by other players differs from its true position
  865.     or orientation by a certain tolerance.  Other players are expected to
  866.     use the last known player data to extrapolate the current position and
  867.     orientation.  This technique is known as dead reckoning and has two
  868.     primary benefits:  network traffic is decreased since updates needn't
  869.     be sent continuously and players on systems with slower frame rates
  870.     appear to move smoothly to players on systems with faster frame rates.
  871.  
  872.     Players that fail to send updates often enough should be considered
  873.     to be not responding.  Unresponsive players should be ignored until
  874.     they start responding again.
  875.  
  876.   MsgGMUpdate
  877.     +----+----+----+----+----+----+----+----+
  878.     | 00 | 2e | 67 | 6d |    shooter id...
  879.     +----+----+----+----+----+----+----+----+
  880.                 | shot id | position
  881.     +----+----+----+----+----+----+----+----+
  882.         (x)   |    position (y)   | position
  883.     +----+----+----+----+----+----+----+----+
  884.         (z)   |    velocity (x)   | velocity
  885.     +----+----+----+----+----+----+----+----+
  886.         (y)   |    velocity (z)   |  time
  887.     +----+----+----+----+----+----+----+----+
  888.           |    target id....
  889.     +----+----+----+----+----+----+----+----+
  890.           |
  891.     +----+----+
  892.     Sent by players with active guided missiles to notify other players
  893.     of changes to the motion of the guided missile.  This message may be
  894.     received directly from other players via multicast or from the server.
  895.  
  896.     See MsgShotBegin for the meaning of most items.  `Time' is the current
  897.     age of the shot (the time since being fired).  `Target id' is the
  898.     current target of the guided missile or all zeros if there is no target.
  899.  
  900.     Players are expected to use dead reckoning to update the position and
  901.     velocity of guided missiles between MsgGMUpdate messages.  Since
  902.     guided missiles deviate from their predicted course only when the
  903.     target changes, these message will be fairly rare.  Note that different
  904.     players may have different ideas of where the target is and that that
  905.     may cause slightly different courses.  This is generally not a problem.
  906.  
  907.   MsgLagPing
  908.     +----+----+----+----+----+----+
  909.     | 00 | 02 | 70 | 69 | seq. no.|
  910.     +----+----+----+----+----+----+
  911.     Sent by the server to active players every 10s to measure lag. The
  912.     client just echoes the message back to the server. The time
  913.     between sending and receiving the message in the server is
  914.     considered to be the current lag ot the respective player.
  915.     
  916.     The two byte sequence number is included to be able to deal with
  917.     lost or severely delayed messages. On each ping sent by the server,
  918.     the sequence number is incremented (modulo 10000). The server
  919.     manages this number on a per player basis.
  920.