Editing Network Protocol

{{Inaccurate}}

= Introduction =

BZFlag uses standard IP (Internet) networking protocols. The code is written to the BSD socket interface, with adjustments for winsock on win32 platforms. Future revisions may centralize the network code into one file behind a single class interface to simplify porting to platforms without the BSD socket API.
Most communication is non-blocking. That is, reads and sends return immediately instead of waiting for data to become available or to be sent. That's important since BZFlag is a real time game. It can't afford to get stuck waiting for a packet to come in. (The one exception to this is when BZFlag connects to a server, and this should get fixed someday.)
Communication is multiplexed using the select() call, which notifies the caller which sockets have data pending for read and/or are ready for sends. Instead of checking for incoming data by trying to read every socket and testing for success, we simply ask the system which sockets have data and read on those only. This also means that we use just a single thread for network communication.
BZFlag uses two distinct transport protocols to communicate with the server. Server communication uses TCP/IP for reliability. Live game data communication uses UDP for speed and efficiency. See the other pages for more details.


= Client/Server Communication =
The BZFlag server manages games. It is the judge and arbiter between clients. It manages game-global resources and information, such as flags and scores. It does not enforce game rules. Clients are trusted to follow the rules, saving the server the trouble of validating kills and client maneuvering.
For example, the server is not told of changes to a client's position on the game board. Therefore the server cannot enforce the rule that players can't drive through walls (without the OO or PH flags). This allows each client to run freely. If it had to wait for the server to okay each movement, it would be impossible to play BZFlag except on fast or dedicated networks.
Furthermore, clients inform the server when they've killed another client player. The server doesn't verify the kill was legal beyond checking to see if someone has already claimed a kill on the same player. If more than one player claims a kill or tries to grab a particular flag, the server decides which player gets the kill or the flag.
Client/server communication is mostly limited to those messages that must be successfully delivered. These include, among others, notifications of players coming alive or being killed, notifications of shots being fired, flags coming or going or being grabbed or dropped.
Client/server communication in BZFlag is through TCP. TCP has the advantages of being bidirectional, reliable, and sequential. Bidirectional means each side of the connection can send to the other. Reliable means that each message will be delivered to the destination. Sequential means that messages (on a particular connection) will be received in the order they were sent.
The main disadvantage of TCP is that it's slow. Reliability may require a given message to be sent several times, until the receiver acknowledges its receipt. While delays can cause problems, there really isn't a way around it. Messages between the client and server are specifically those messages that must not be lost. If we didn't use TCP we'd simply have to implement something that did the same thing, and which would necessarily suffer from the same drawbacks.
There are some instances where client/server communication doesn't use TCP. One example is client attempts to locate servers on the network. Clients send broadcast `pings' which the servers listen for and respond to in kind. These messages are not part of normal game communication.

= Client/Client Communication =
BZFlag clients send certain information to other clients during a game. This information includes: status, position, orientation, and linear and angular velocity. This state can change quickly and getting it late is no better than not getting it at all. So client-to-client packets are sent using UDP, a datagram protocol.
UDP is unreliable, meaning that packets are not guaranteed to be delivered. It's also connectionless, meaning we don't even know if anybody is listening for the message. However, it's also fast because it's so simple. UDP suits our needs because: we need fast delivery; we don't care if a message is lost because another will arrive shortly afterwards; and we don't care if the receiver isn't listening.
BZFlag clients need to send their information to all the other clients. There are several ways to do this. First, each client can send each message to all the other clients. If there are N clients then each message is sent N-1 times. Traffic grows as the square of clients. This is slow and wasteful.
Alternatively, each client can send all messages to one special computer (for example, the server) and that computer can forward the messages to all the other players. This makes life easier on the clients and much harder on the server. It also delays the delivery of each message. And traffic from the server still grows as N squared (though traffic to the server grows linearly).
Another possibility is to broadcast messages. A broadcast message is sent once and received by all computers on a subnet. This scales linearly and minimizes network traffic but broadcast traffic is never routed outside the subnet, so it means only clients on the same subnet of the same local area network could play together.
BZFlag uses the second technique, using the server as a relay system. The server uses the TCP client/server connection to send client traffic that must be reliable and UDP for information that must be timely but does not need to be reliable.

= Protocol =
  --> means from client to server
  <-- means from server to client

All multi-byte data is in network byte order (aka big endian); that is, the most significant byte comes first followed by successively less significant bytes.
All numbers are integers unless otherwise specified. Integers can be 8, 16, or 32 bit signed 2's compliment or unsigned (encoding is the same in regardless of signed status). Values in this document in byte boxes are given in hexadecimal. Values in the text are given in decimal unless otherwise noted.
Bit fields are encoded as unsigned integers. All floating point numbers are in standard IEEE-754 single precision format. Multi-byte values are *not* necessarily aligned on 2 or 4 byte boundaries.
A client normally follows the following sequence during game play: connect to server get the world database join the game send/receive game messages leave game disconnect from server
common message structures ------------------------- Most messages begin with the length of the message in bytes followed by a 16 bit code. The length is 16 bits and excludes itself and the code, so it's the actual length of the message minus 4.


Player identifiers are 1 byte and are used in many messages.

          0 - 243 : Regular Players
        244 - 250 : Special Team Ids
        251 - 252 : Unused IDs
              253 : ServerPlayer (World weapons, etc)
              254 : All Players
              255 : No Player (Invalid Player)

Flag status is common to a few message types:

	u16	flag id
	u16	status
	u16	type
	u8	owner id
	float	position (x)
	float	position (y)
	float	position (z)
	float	launch (x)
	float	launch (y)
	float	launch (z)
	float	landing (x)
	float	landing (y)
	float	landing (z)
	float	flight time
	float	flight end time
	float	initial velocity

`Position,' `launch,' `landing,' `flight time,' `flight end,' and `initial velocity' are all floating point numbers. `Flag id' is the type of flag,enumerated in FlagId.

`Status' gives the current location of the flag:
  FlagNoExist  -- the flag is not active (i.e. not in the game)
  FlagOnGround -- the flag is sitting on the ground ready to get picked up
  FlagOnTank   -- the flag is on a player's tank
  FlagInAir    -- the flag is in the air and will fall back down
  FlagComing   -- the flag just appeared and is falling to the ground
  FlagGoing    -- the flag was thrown in the air and is disappearing

`Type' indicates the behavior of the flag: FlagNormal means the flag is permanent and can be dropped normally (e.g. a team flag); FlagUnstable means the flag may disappear after use (e.g. a good super flag); FlagSticky means the flag cannot be dropped normally (e.g. a bad super flag).
`Player id' indicates which player has the flag when `status' is FlagOnTank. It isn't used for any other status.
`Position' is the location of the flag on the ground. It only has meaning when `status' is FlagOnGround. The position of a flag when on a tank is the position of the tank (centered on and at the top of the tank)
`Launch' is the location of the flag where it was thrown in the air. `Landing' is the location where the flag will/would touch ground. These are used when `status' is FlagInAir, FlagComing, and FlagGoing. The client should make the flag follow a reasonable flight path (e.g. a parabolic arc) from `launch' to `landing.'
`Flight time' is the time elapsed since the flag was thrown into the air. `Flight end' the time when the flag will reach the ground. `Initial velocity' gives the vertical (z) velocity of the flag when launched. The vertical position of the flag at time t (ranging from 0 to `flight end') is: z = z0 + v * t + 0.5 * g * t * t. z0 = `launch z;' v = `initial velocity;' g = acceleration due to gravity.



== Connecting to a server ==
The [https://github.com/BZFlag-Dev/bzflag/blob/2.4/misc/bzfquery.php bzfquery.php script] is a nice example of how to connect to a server.

At the beginning you need to open a socket. Beginning with protocol 0048 you need to send "BZFLAG\r\n\r\n" in order to get any reply. At that time you unfortunately don't know the protocol, so send it by default or your client will probably freeze.

  -->   connect(server port)
  -->    +----+----+----+----+----+----+----+----+----+----+
 	| 42 | 5a | 46 | 4C | 41 | 47 | 0D | 0A | 0D | 0A |     BZFLAG\r\n\r\n
 	+----+----+----+----+----+----+----+----+----+----+
  <--    +----+----+----+----+----+----+----+----+----+
  	| 42 | 5a | 46 | 53 | 31 | 39 | 31 | 30 | FF |           BZFS1910        FF
  	+----+----+----+----+----+----+----+----+----+


Client should verify the version. In old versions the first four bytes indicates a BZFlag server, the next byte indicates the major version number (as an ASCII digit), the two bytes after that are the minor version number (as ASCII digits), and the 7th byte is the revision. Major and minor version number changes indicate incompatible protocol changes. Different revisions of a given version are compatible and usually just indicate client user interface changes. A following FF ends the packet. In new versions the protocol is just a number increased by 1 when the protocol changes.

If the reply was a protocol older than 0048 then bzfs will kick the client connecting to it. In this case we recommend a fallback, not sending BZFLAG\r\n\r\n during connection try:

  -->   connect(server port)
  <--    +----+----+----+----+----+----+----+----+----+
  	| 42 | 5a | 46 | 53 | 31 | 39 | 31 | 30 | FF |           BZFS1910        FF
  	+----+----+----+----+----+----+----+----+----+


Server owners will see something like the following in the logs if their server(s) use a protocol older than 0048:
  Player [0] sent huge packet length (len=16986), possible attack
  Player  [0] removed at 2007-04-11 15:52:55: large packet recvd

== Message types ==
Read this with caution, as it is very old information not reflecting the current status.


=== Negotiating world flags ===

  -->    +----+----+----+----+----+----+----+----+----+----+
 	| length  | 6E | 66 | FlagID1 | FlagID2 | ....... |     MsgNegotiateFlags
 	+----+----+----+----+----+----+----+----+----+----+     (List of client flag ids)
  <--    +----+----+----+----+----+----+----+----+----+----+
 	| length  | 6E | 66 | FlagID1 | FlagID2 | ....... |     MsgNegotiateFlags
 	+----+----+----+----+----+----+----+----+----+----+     (List of server flag ids, that client doesn't know)


Client sends to the server the two byte representation of all flags known to the client. In the case that a flag is only one letter, (N) for instance, the second byte is null. Otherwise, the null byte is implied at position 3. The server upon receipt of this list, finds all flags that are used by the server, but not known by the client, and sends this list to the client. The client upon receipt of the list, either disallows play, if flags exist, or continues if the list is empty.


=== getting the world hash ===
  -->    +----+----+----+----+
 	| 00 | 00 | 77 | 68 |                         MsgWantWHash
 	+----+----+----+----+
  <--    +----+----+----+----+----+----+----+----+
 	| length  | 77 | 68 | world hash data... |     MsgWantWHash
 	+----+----+----+----+----+----+----+----+

To improve performance World (bzc) files are cached on the client. The name of the cache file is an md5 hash of the file that is computed on the server. this hash is sent to the client, and the client looks for a file by that name in the bz world cache directory. If the hash starts with a 't', the world is a random world. If the hash starts with a 'p' the world is from a world file. If the client can find the file locally, it does not sent the following MsgGetWorld packet.


=== getting the world database ===
  -->    +----+----+----+----+----+----+
 	| 00 | 02 | 67 | 77 | offset  |                 MsgGetWorld
 	+----+----+----+----+----+----+
  <--    +----+----+----+----+----+----+----+----+
 	| length  | 67 | 77 |remaining| data... |       MsgGetWorld
 	+----+----+----+----+----+----+----+----+
 	or
 	+----+----+----+----+
 	| 00 | 00 | 73 | 6b |                           MsgSuperKill
 	+----+----+----+----+


Client sends MsgGetWorld requests until it has read the entire world database. Clients should send an `offset' of 0 for the first request and increase `offset' by however much data was sent in reply. Each MsgGetWorld reply includes the number of bytes left after the returned block of data in `remaining'. The server returns 0 in `remaining' when there is no more data left to read. In no event will the server return more than MaxPacketLen - 6 bytes of data in one reply (see protocol.h for the definition of MaxPacketLen). The server may return MsgSuperKill at any time during the download of the world database. The client should immediately close the connection to the server. No other messages should be returned by the server as long as the client sends only MsgGetWorld requests.


The `data' has the following encoding:

 	+----+----+----+----+
 	| 00 | 1E | 73 | 74 |        length of data, WorldCodeStyle
 	+----+----+----+----+----+----+
 	| version |      worldsize    |
 	+----+----+----+----+----+----+----+----+
 	|  style  | mxPlyrs | mxShots | mxFlags |
 	+----+----+----+----+----+----+----+----+
 	|linear acceleration|angulr acceleration|
 	+----+----+----+----+----+----+----+----+
 	| shake t | shake w |    epoch offset   |
 	+----+----+----+----+----+----+----+----+

Values are:
  version:      version of the bzw format
  worldsize:    size in meters of world
  style:        bitfield of game style
  maxPlayrs:    maximum number of players
  maxShots:     maximum number of shots at once per player
  maxFlags:     maximum number of flags that may exist at once
  linear acc.:  linear acceleration limit (float)
  angulr acc.:  angular acceleration limit (float)
  shake t:      time to shake a bad flag (1/10ths of seconds)
  shake w:      number of wins to shake a bad flag
  epoch offset: seconds since midnight Jan 1, 1970 GMT on the server, used when
		synchronizing times across clients


The rest of the world database is encoded in individual blocks describing each object. Only permanent immovable objects are included. The encodings for each type of object are:


team base:
 	+----+----+----+----+
 	| 00 | 2A | 62 | 61 | length of base data, team code
 	+----+----+----+----+----+----+
 	| team id |     center (x)    |
 	+----+----+----+----+----+----+----+----+
 	|     center (y)    |     center (z)    |
 	+----+----+----+----+----+----+----+----+
 	|       angle       |      size (x)     |
 	+----+----+----+----+----+----+----+----+
 	|      size (y)     |      size (z)     |
 	+----+----+----+----+----+----+----+----+
 	|    safety (x)     |    safety (y)     |
 	+----+----+----+----+----+----+----+----+
 	|    safety (z)     |
 	+----+----+----+----+

wall:
 	+----+----+----+----+
 	| 00 | 18 | 77 | 6C | length of wall data, wall code
 	+----+----+----+----+----+----+----+----+
 	|    center (x)     |    center (y)     |
 	+----+----+----+----+----+----+----+----+
 	|    center (z)     |    angle...       |
 	+----+----+----+----+----+----+----+----+
 	|       width       |       height      |
 	+----+----+----+----+----+----+----+----+


pyramid:
 	+----+----+----+----+
 	| 00 | 1D | 70 | 79 | length of pyramid data, pyramid code
 	+----+----+----+----+----+----+----+----+
 	|    center (x)     |    center (y)     |
 	+----+----+----+----+----+----+----+----+
 	|    center (z)     |     angle         |
 	+----+----+----+----+----+----+----+----+
 	|       width       |     depth         |
 	+----+----+----+----+----+----+----+----+
 	|      height       | sdf|
 	+----+----+----+----+----+

box:
 	+----+----+----+----+
 	| 00 | 1D | 62 | 78 | length of box data, box code
 	+----+----+----+----+----+----+----+----+
 	|    center (x)     |    center (y)     |
 	+----+----+----+----+----+----+----+----+
 	|    center (z)     |     angle         |
 	+----+----+----+----+----+----+----+----+
 	|       width       |     depth         |
 	+----+----+----+----+----+----+----+----+
 	|      height       | sdf|
 	+----+----+----+----+----+

teleporter:
 	+----+----+----+----+
 	| 00 | 21 | 74 | 65 | length of teleporter data, teleporter code
 	+----+----+----+----+----+----+----+----+
 	|    center (x)     |    center (y)     |
 	+----+----+----+----+----+----+----+----+
 	|    center (z)     |       angle       |
 	+----+----+----+----+----+----+----+----+
 	|       width       |       depth       |
 	+----+----+----+----+----+----+----+----+
 	|      height       |       border      |
 	+----+----+----+----+----+----+----+----+
 	| sdf|
 	+----+

teleporter link:
 	+----+----+----+----+
 	| 00 | 04 | 6C | 6E | length of link data, link code
 	+----+----+----+----+
 	|  from   |   to    |
  	+----+----+----+----+
end of data:
 	+----+----+----+----+
 	| 00 | 00 | 65 | 64 | length of worldcodeend data, worldcodeend code
 	+----+----+----+----+

The above values are interpreted as follows:

  angle (float):        in radians from the x-axis in the xy plane
  width (float):        half width (in xy) measured from center
  depth (float):        half depth (in xy) measured from center
  height (float):       full height (in z) measured from bottom
  border (float):       full size of the square cross section teleporter border
  center (float):       center in xy, bottom in z
  safety (float):       safety position for team flags, used when team A drops team B's
			flag on team C's base.
  from & to:            index of teleporter face starting from zero;  the N'th teleporter
			in the world data has face indices 2*N and 2*N+1.  teleporter
			links indicate which face teleports to which face;  faces may
			teleport to themselves.
  sdf (byte):           bit mask:
                              drive through is bitmask 0x01
                              shoot through is bitmask 0x02


== join game ==
Once connected a player normally requests to join the game.  The server replies with
MsgSuperKill, MsgReject, or MsgAccept.

  -->    +----+----+----+----+----+----+----+----+
 	| length  | 65 | 6e |  player id...             MsgEnter
 	+----+----+----+----+----+----+----+----+
 			    |  type   |  team   |
 	+----+----+----+----+----+----+----+----+
 	| call sign (CallSignLen bytes)...
 	+----+----+----+----+----+----+----+----+
 	...
 	+----+----+----+----+----+----+----+----+
 						|
 	+----+----+----+----+----+----+----+----+
 	| email address (EmailLen bytes)...
 	+----+----+----+----+----+----+----+----+
 	...
 	+----+----+----+----+----+----+----+----+
 						|
 	+----+----+----+----+----+----+----+----+
  <--    +----+----+----+----+
 	| 00 | 00 | 61 | 63 |                           MsgAccept
 	+----+----+----+----+
 	or
 	+----+----+----+----+----+----+
 	| 00 | 02 | 72 | 6a |  code   |                 MsgReject
 	+----+----+----+----+----+----+
 	or
 	+----+----+----+----+
 	| 00 | 00 | 73 | 6b |                           MsgSuperKill
 	+----+----+----+----+

`Type' is one of the enumerations in PlayerType and `team' is one from TeamColor.
The call sign is the player's `handle' during the game;  the call sign is used
to identify the player.  No attempt is made by the server to prevent the
duplication of call signs during a game.  The motto can be anything,
including the email address for human players (e.g. username@hostname).
BZFlag players can choose `anonymous' instead of their motto.  The call
sign and email address should be NUL terminated ASCII strings, padded with
NUL's to the required length.  `Length' is 12 + CallSignLen + EmailLen.

If the server responds with MsgSuperKill the client should close the connection
immediately.  If the server responds with MsgReject, the client has not joined the
game but may keep the server connection open and try again.  The reason for rejection
is included with the MsgReject message:

	RejectBadRequest        -- bogus data in MsgEnter
	RejectBadTeam           -- invalid team id
	RejectBadType           -- invalid client type
	RejectTeamFull          -- no more players allowed on team
	RejectServerFull        -- no more players allowed on any team

If the server responds with MsgAccept, the player has successfully joined the game.
The server then automatically sends updates about each flag, team, and player.  The
client should be prepared to accept these updates in any order.  The flag and team
updates are sent as MsgFlagUpdate and MsgTeamUpdate messages, respectively.  Player
updates are sent as MsgAddPlayer messages.  The client will receive a MsgAddPlayer
for the player it just added, but only after it has received a MsgAddPlayer for each
of the players already joined.

Until it receives the MsgAddPlayer for the player it just added, the client will
only receive the following kinds of messages:

	MsgSuperKill
	MsgFlagUpdate
	MsgTeamUpdate
	MsgAddPlayer

Players of type ComputerPlayer are not sent team or flag updates and only get the
MsgAddPlayer for themselves.  This probably wasn't a good idea, but there it is.


== Leave game ==
Once entered, a player can leave the game at any time.  This should be done by sending
the following message, then closing the connection:

  -->    +----+----+----+----+
 	| 00 | 00 | 65 | 78 |                           MsgExit
 	+----+----+----+----+

There is no reply.  Clients can also leave by simply closing the connection, but
sending MsgExit first is recommended.


== During a game ==
There are several types of messages that are delivered at any time after a player
enters a game.  Clients must be prepared to handle them in any order.

MsgSuperKill
  <--    +----+----+----+----+
 	| 00 | 00 | 73 | 6b |
 	+----+----+----+----+
Client must immediately disconnect from the server.

MsgTimeLeft
  <--    +----+----+----+----+----+----+
 	| 00 | 02 | 74 | 6f |time left|
 	+----+----+----+----+----+----+
Gives the time remaining in the game.  This message is only sent when the
server has time limit configured.  If the time remaining is zero, the client
should indicate to the player that the game is over.
`Time left' is in seconds.  It is not sent every second so clients will need
to do their own count down between messages.

MsgScoreOver
  <--    +----+----+----+----+----+----+----+----+
 	| 00 | 0a | 73 | 6f |     player id...
 	+----+----+----+----+----+----+----+----+
 			    | team id |
 	+----+----+----+----+----+----+
Gives the player or team that won the game by reaching the target score.
This message is only sent when the server has a target score configured.
The client should indicate which team or player won and that the game is
over.

If `team id' is NoTeam then `player id' indicates which player has won.
Otherwise `team id' indicates which team won.

MsgAddPlayer
  <--    +----+----+----+----+----+----+----+----+
 	| length  | 61 | 70 |     player id...
 	+----+----+----+----+----+----+----+----+
 			    |  type   |  team   |
 	+----+----+----+----+----+----+----+----+
 	|  wins   |  losses | call sign...
 	+----+----+----+----+----+----+----+----+
 		... (CallSignLen bytes)...      |
 	+----+----+----+----+----+----+----+----+
 	| email address...
 	+----+----+----+----+----+----+----+----+
 		 ... (EmailLen bytes)...        |
 	+----+----+----+----+----+----+----+----+
Sent when another player enters the game and when joining a game if other
players are already joined.  `Type' is enumerated in PlayerType, `team'
is enumerated in TeamColor.  `Wins' and `losses' give the player's score.
They are unsigned integers;  the player's score equals wins minus losses.
`Call sign' and `email address' are NUL terminated ASCII strings.  `Length'
is 16 + CallSignLen + EmailLen.

MsgRemovePlayer
  <--    +----+----+----+----+----+----+----+----+
 	| 00 | 08 | 72 | 70 |     player id...
 	+----+----+----+----+----+----+----+----+
 			    |
 	+----+----+----+----+
Sent when another player leaves the game.

MsgFlagUpdate
  <--    +----+----+----+----+----+----+----+----+
 	| 00 | 40 | 66 | 75 |flag num | flag id |
 	+----+----+----+----+----+----+----+----+
 	| status  |  type   |     player id...
 	+----+----+----+----+----+----+----+----+
 			    |    position (x)   |
 	+----+----+----+----+----+----+----+----+
 	|    position (y)   |    position (z)   |
 	+----+----+----+----+----+----+----+----+
 	|     launch (x)    |     launch (y)    |
 	+----+----+----+----+----+----+----+----+
 	|     launch (z)    |    landing (x)    |
 	+----+----+----+----+----+----+----+----+
 	|    landing (y)    |    landing (z)    |
 	+----+----+----+----+----+----+----+----+
 	|    flight time    |    flight end     |
 	+----+----+----+----+----+----+----+----+
 	| initial velocity  |
 	+----+----+----+----+
Sent when a flag's state changes.  Also sent to a client when it enters
a game.  `Flag num' is the index of the flag.  Flags are indexed from
zero up to the maximum number of flags minus one.

Clients must update the flag positions while the flag is in flight (i.e.
`status' is FlagInAir, FlagComing, or FlagGoing.  If FlagInAir or
FlagComing then the client should change the flag's status to
FlagOnGround when the flag's flight time equals or exceeds `flight end.'
The position should be set exactly to `landing.'  If FlagGoing, the
client should change the flag's status to FlagNoExist when the flight
time equals or exceeds `flight end.'

BZFlag uses the first half of the flight time for FlagComing and the
last half of the flight time for FlagGoing to make the flag appear or
disappear from/to nothing.  This allows players to adjust to the
appearance/disappearance of a flag.

MsgTeamUpdate
  <--    +----+----+----+----+----+----+----+----+
 	| 00 | 0a | 74 | 6f |  team   |  size   |
 	+----+----+----+----+----+----+----+----+
 	| active  |  wins   | losses  |
 	+----+----+----+----+----+----+
Gives the current state of team `team.'  `Size' is the number of
players on the team.  `Active' is the number of active players on the
team.  An active player is one that can participate in the game (e.g.
grab flags, shoot opponents, etc.);  a non-active player can only
observe the game.  Only active players are considered when deciding
if there are any players on a team (to decide if the team flag should
be inserted or withdrawn from the game).  `Wins' and `losses' give the
team's score (wins minus losses).

MsgAlive
  <--    +----+----+----+----+----+----+----+----+
 	| 00 | 20 | 61 | 6c |     player id...
 	+----+----+----+----+----+----+----+----+
 			    |    position (x)   |
 	+----+----+----+----+----+----+----+----+
 	|    position (y)   |    position (z)   |
 	+----+----+----+----+----+----+----+----+
 	|    forward (x)    |    forward (y)    |
 	+----+----+----+----+----+----+----+----+
 	|    forward (z)    |
 	+----+----+----+----+
Sent when a player comes alive.  A player that has joined is not on the
game board until it sends this message, which declares that it is in
game and gives the starting position and orientation.  Players are removed
from the game board when killed and do not reappear until sending this
message again.

  -->    +----+----+----+----+----+----+----+----+
 	| 00 | 18 | 61 | 6c |    position (x)   |
 	+----+----+----+----+----+----+----+----+
 	|    position (y)   |    position (z)   |
 	+----+----+----+----+----+----+----+----+
 	|    forward (x)    |    forward (y)    |
 	+----+----+----+----+----+----+----+----+
 	|    forward (z)    |
 	+----+----+----+----+
A player sends this message to enter the game board.  Note that this
version of the message differs from the one sent by the server in that
it lacks the player id (which is implicit in the server connection).
Players must send this message to change their state from dead to alive.
Players should not send MsgAlive for a certain penalty period after
being killed (but the server does not enforce a minimum time).  The
currently penalty is ExplodeTime.

`Position' gives the location of the player and `forward' gives the
player's forward direction vector.


MsgKilled
  <--    +----+----+----+----+----+----+----+----+
 	| 00 | 12 | 6b | 6c |     victim id...
 	+----+----+----+----+----+----+----+----+
 			    |     killer id...
 	+----+----+----+----+----+----+----+----+
 			    | shot id |
 	+----+----+----+----+----+----+
Sent by the server when a player is killed by itself or another player.
The victim id is the player that was destroyed and the killer id is the
player credited with the kill.  Shot id identifies which of the killer's
shots hit the victim;  if the shot isn't a laser or shockwave, other
players may assume the shot has stopped and needn't check themselves
against the shot (or they can wait until the MsgShotEnd message arrives).

  -->    +----+----+----+----+----+----+----+----+
 	| 00 | 0a | 6b | 6c |     killer id...
 	+----+----+----+----+----+----+----+----+
 			    | shot id |
 	+----+----+----+----+----+----+
Sent by the victim when it detects that it's been hit, naming the killer
and which of the killer's shots was the one that hit.  Note that the
server does not verify kills in any way so it's trivial to `cheat' by
claiming you've been killed;  this is generally unproductive.  It's
also easy to cheat by never sending MsgKilled, making you almost
immortal.  Don't do this.

MsgGrabFlag
  <--    +----+----+----+----+----+----+----+----+
 	| 00 | 48 | 67 | 66 |     grabber id...
 	+----+----+----+----+----+----+----+----+
 			    |flag num | flag id |
 	+----+----+----+----+----+----+----+----+
 	| status  |  type   |      owner id...
 	+----+----+----+----+----+----+----+----+
 			    |    position (x)   |
 	+----+----+----+----+----+----+----+----+
 	|    position (y)   |    position (z)   |
 	+----+----+----+----+----+----+----+----+
 	|     launch (x)    |     launch (y)    |
 	+----+----+----+----+----+----+----+----+
 	|     launch (z)    |    landing (x)    |
 	+----+----+----+----+----+----+----+----+
 	|    landing (y)    |    landing (z)    |
 	+----+----+----+----+----+----+----+----+
 	|    flight time    |    flight end     |
 	+----+----+----+----+----+----+----+----+
 	| initial velocity  |
 	+----+----+----+----+
Sent by the server when a player is allowed to grab a flag.  This is
both the notice to the player trying to grab the flag that it succeeded
and the notice to all other players that the flag was grabbed.  Note
that `grabber id' is redundant;  it's always equal to `owner id.'

`Flag num' is the index of the flag.  Flags are indexed from zero up to
the maximum number of flags minus one.

  -->    +----+----+----+----+----+----+
 	| 00 | 02 | 67 | 66 |flag num |
 	+----+----+----+----+----+----+
Sent by a player when it wants to grab a flag.  Players should only
send this message when their tank is within FlagRadius of a flag (that's
any part of the tank, not simply the center) and on the ground.  The
server will not verify this, but it will verify some other stuff.  The
player must not assume it will be able to grab the flag.  Instead it has
to wait for a MsgGrabFlag reply.

MsgDropFlag
  <--    +----+----+----+----+----+----+----+----+
 	| 00 | 48 | 64 | 66 |     dropper id...
 	+----+----+----+----+----+----+----+----+
 			    |flag num | flag id |
 	+----+----+----+----+----+----+----+----+
 	| status  |  type   |      owner id...
 	+----+----+----+----+----+----+----+----+
 			    |    position (x)   |
 	+----+----+----+----+----+----+----+----+
 	|    position (y)   |    position (z)   |
 	+----+----+----+----+----+----+----+----+
 	|     launch (x)    |     launch (y)    |
 	+----+----+----+----+----+----+----+----+
 	|     launch (z)    |    landing (x)    |
 	+----+----+----+----+----+----+----+----+
 	|    landing (y)    |    landing (z)    |
 	+----+----+----+----+----+----+----+----+
 	|    flight time    |    flight end     |
 	+----+----+----+----+----+----+----+----+
 	| initial velocity  |
 	+----+----+----+----+
Sent by the server when a player is allowed to drop a flag.  This is
both the notice to the player trying to drop the flag that it succeeded
and the notice to all other players that the flag was dropped.  `Owner
id' is meaningless in this message.

`Flag num' is the index of the flag.  Flags are indexed from zero up to
the maximum number of flags minus one.

  -->    +----+----+----+----+----+----+----+----+
 	| 00 | 0c | 64 | 66 |    position (x)   |
 	+----+----+----+----+----+----+----+----+
 	|    position (y)   |    position (z)   |
 	+----+----+----+----+----+----+----+----+
Sent by a player when it wants to drop a flag.  Players should only
send this message when they have a flag and only when the flag dropping
constraints have been met (i.e. the flag can be dropped at any time, or
the player got the antidote flag, etc.)  The player must not assume it
has dropped the flag until it receives a MsgDropFlag in response.

`Position' is in floating point and is the position of the tank that
dropped the flag when it was dropped.

MsgCaptureFlag
  <--    +----+----+----+----+----+----+----+----+
 	| 00 | 0c | 63 | 66 |    capturer id...
 	+----+----+----+----+----+----+----+----+
 			    |flag num | team id |
 	+----+----+----+----+----+----+----+----+
Sent by the server when a team's flag has been captured.  `Capturer id'
is the player who captured the flag.  `Flag num' is the index of the
captured flag.  Flags are indexed from zero up to the maximum number of
flags minus one.  `Team id' is the id of the team who's flag was
captured.  Note that the player who captures the flag may be on the team
that was captured.

The server makes all players on the captured team dead.  This message is
the only notice that the players are now dead so clients should act
accordingly.  This is also the only notice that the capturer is no longer
carrying a flag.

  -->    +----+----+----+----+----+----+
 	| 00 | 02 | 63 | 66 | team id |
 	+----+----+----+----+----+----+
Sent by a player when it captures a team flag.  `Team id' is the id of
the team who's flag was captured.  The player should wait until the
server sends back the MsgCaptureFlag response before assuming the
capture was successful.  A player should send this message only when
1) its tank is at least halfway inside a team base, 2) the tank is on
the ground, and 3) the player has its own team flag in an enemy base
or the player has another team's flag in its own base.  Note that the
server will not enforce any of these requirements.

MsgShotBegin
  <-- 
  -->    +----+----+----+----+----+----+----+----+
 	| 00 | 2c | 73 | 62 |    shooter id...
 	+----+----+----+----+----+----+----+----+
 			    | shot id | position
 	+----+----+----+----+----+----+----+----+
 	    (x)   |    position (y)   | position
 	+----+----+----+----+----+----+----+----+
 	    (z)   |    velocity (x)   | velocity
 	+----+----+----+----+----+----+----+----+
 	    (y)   |    velocity (z)   |  time
 	+----+----+----+----+----+----+----+----+
 		  |flag type|     lifetime      |
 	+----+----+----+----+----+----+----+----+
Sent by the server when a player has fired a shot.  The identical message
is send by a player when it fires a shot.  The server does not verify
that the player is allowed to fire a shot.

`Shooter id' identifies the player that did the shooting.  `Shot id' is
a number that uniquely identifies to the shooter which shot this is.
`Position,' `velocity,' `time,' and `lifetime' are floating point
numbers.  `Position' is the starting position of the shot.  `Velocity'
is the starting velocity of the shot.  `Time' is the time the shot has
existed (probably 0.0).  `Lifetime' is how long the shot exists.  `Flag
type' is a FlagId and is the type of flag the shooter had when the shot
was fired.

Clients are expected to compute the flight path of shots (except Guided
Missiles) given the information in MsgShotBegin.  That includes handling
ricochets, building impacts, and teleportation, but not tank impacts.
Each player decides if it itself has been hit by a shot at each time step
based on this flight path.  Since the path of a guided missile cannot be
predicted, updates to a guided missile's path is sent throughout its
flight by the shooter via MsgGMUpdate messages.

A player should test itself against a shot using whatever algorithm it
likes, but at a minimum should test the line segments the shot moves
along during the time step against a tank aligned bounding box.
Accounting for the linear motion of the tank over the time step is
better and accounting for both the linear and angular motion is better
still.  Note that the shot has a certain radius that should be taking
into account during intersection testing.  This is particularly
important when testing against a tank with the narrow flag.  Ideally,
the shot would be exactly tested against the tank geometry.  However,
that's more work than realistically necessary.

MsgShotEnd
  <-- 
  -->    +----+----+----+----+----+----+----+----+
 	| 00 | 0c | 73 | 65 |    shooter id...
 	+----+----+----+----+----+----+----+----+
 			    | shot id | reason  |
 	+----+----+----+----+----+----+----+----+
Sent by the server when a shot has been terminated before its lifetime
has expired.  The identical message is sent by the player that
terminates the shot.  This is normally the player that has just been
hit by the shot.  The server does not verify that the player has or
has not been hit.  This message is also sent by the player that fired
a guided missile when the shot hits the ground or a building (note that
guided missiles don't ricochet).

`Shooter id' identifies the player that fired the shot and `shot id'
is the same as in the MsgShotBegin message for the shot.  `Reason' is
one if the other players should show an explosion for the shot and
zero otherwise.

MsgScore
  <--    +----+----+----+----+----+----+----+----+
 	| 00 | 0c | 73 | 63 |     player id...
 	+----+----+----+----+----+----+----+----+
 			    |  wins   | losses  |
 	+----+----+----+----+----+----+----+----+
Sent by the server when a player's score changes.  `Player id' is the
player with the new score, and `wins' and `losses' are the new scores.

  -->    +----+----+----+----+----+----+----+----+
 	| 00 | 04 | 73 | 63 |  wins   | losses  |
 	+----+----+----+----+----+----+----+----+
Sent by a player when its score changes.

MsgTeleport
  <--    +----+----+----+----+----+----+----+----+
 	| 00 | 0c | 73 | 63 |     player id...
 	+----+----+----+----+----+----+----+----+
 			    |  from   |   to    |
 	+----+----+----+----+----+----+----+----+
Sent by the server when a player teleports.  `From' is the index of the
teleporter face the player entered and `to' is the index of the face
the player exited.

  -->    +----+----+----+----+----+----+----+----+
 	| 00 | 04 | 73 | 63 |  from   |   to    |
 	+----+----+----+----+----+----+----+----+
Sent by a player when it passes through a teleporter.

MsgMessage
  <--    +----+----+----+----+----+----+----+----+
 	| length  | 6d | 67 |  from player id...
 	+----+----+----+----+----+----+----+----+
 			    |   to player id...
 	+----+----+----+----+----+----+----+----+
 			    |  team   |message...
 	+----+----+----+----+----+----+----+----+
 	...(MessageLen bytes)...
 	+----+----+----+----+----+----+----+----+
 						|
 	+----+----+----+----+----+----+----+----+
Sent by the server when one player sends a message to others.  `Length'
is the length of the message (18 + MessageLen bytes).  `From player id'
is the player sending the message, `to player id' is the player to
receive the message, and `team' is the team to receive the message.
If `to player id' is all zeros then the message is being sent to
everyone on `team'.  If `to player id' is all zeros and `team' is
RogueTeam then the message is being sent to all players.  If `to player
id' is not all zeros then `team' is ignored and the message is only for
the identified player.

  -->    +----+----+----+----+----+----+----+----+
 	| length  | 6d | 67 |    player id...
 	+----+----+----+----+----+----+----+----+
 			    |  team   |message...
 	+----+----+----+----+----+----+----+----+
 	...(MessageLen bytes)...
 	+----+----+----+----+----+----+----+----+
 						|
 	+----+----+----+----+----+----+----+----+
Sent by player to send a message to other players.  `Length' is is the
length of the message (10 + MessageLen bytes).  `Player id' is the
player to receive the message (or all zeros for all players on the
given team) and `team' is the team to receive the message (or
RogueTeam for all teams).

MsgPlayerUpdate
 	+----+----+----+----+----+----+----+----+
 	| 00 | 2a | 70 | 75 |    player id...
 	+----+----+----+----+----+----+----+----+
 			    | status  | position
 	+----+----+----+----+----+----+----+----+
 	    (x)   |    position (y)   | position
 	+----+----+----+----+----+----+----+----+
 	    (z)   |    velocity (x)   | velocity
 	+----+----+----+----+----+----+----+----+
 	    (y)   |    velocity (z)   | azimuth
 	+----+----+----+----+----+----+----+----+
 		  | angular velocity  |
 	+----+----+----+----+----+----+
Sent by players to notify other players of changes in its status,
position, or velocity.

`Status' is the tank's current status.  See PlayerStatus for the
meaning of the bit field's bits.  The FlagActive bit indicates whether
the player's flag's special powers are active or not.  The Phantom
Zone flag is an example of a flag that's active only some of the time.
The CrossingWall bit indicates if the player's tank is intersected by
a wall or teleporter;  other players can use this to draw the player
in some special way.  CrossingWall could be computed by each player
from other information;  it's only provided to save the other players
the trouble.

`Position,' `velocity,' `azimuth,' and `angular velocity' are floating
point numbers.  `Azimuth' is the orientation of the tank in radians
(the +x axis is 0.0, +y is pi/2).  `Angular velocity' is the change in
azimuth per second.  `Position' is the tank position and `velocity' is
the change in tank position per second.

A player normally only sends an update when its position or orientation
as could be predicted by other players differs from its true position
or orientation by a certain tolerance.  Other players are expected to
use the last known player data to extrapolate the current position and
orientation.  This technique is known as dead reckoning and has two
primary benefits:  network traffic is decreased since updates needn't
be sent continuously and players on systems with slower frame rates
appear to move smoothly to players on systems with faster frame rates.

Players that fail to send updates often enough should be considered
to be not responding.  Unresponsive players should be ignored until
they start responding again.

MsgGMUpdate
 	+----+----+----+----+----+----+----+----+
 	| 00 | 2e | 67 | 6d |    shooter id...
 	+----+----+----+----+----+----+----+----+
 			    | shot id | position
 	+----+----+----+----+----+----+----+----+
 	    (x)   |    position (y)   | position
 	+----+----+----+----+----+----+----+----+
 	    (z)   |    velocity (x)   | velocity
 	+----+----+----+----+----+----+----+----+
 	    (y)   |    velocity (z)   |  time
 	+----+----+----+----+----+----+----+----+
 		  |    target id....
 	+----+----+----+----+----+----+----+----+
 		  |
 	+----+----+
Sent by players with active guided missiles to notify other players
of changes to the motion of the guided missile.

See MsgShotBegin for the meaning of most items.  `Time' is the current
age of the shot (the time since being fired).  `Target id' is the
current target of the guided missile or all zeros if there is no target.

Players are expected to use dead reckoning to update the position and
velocity of guided missiles between MsgGMUpdate messages.  Since
guided missiles deviate from their predicted course only when the
target changes, these message will be fairly rare.  Note that different
players may have different ideas of where the target is and that that
may cause slightly different courses.  This is generally not a problem.

MsgLagPing
 	+----+----+----+----+----+----+
 	| 00 | 02 | 70 | 69 | seq. no.|
 	+----+----+----+----+----+----+
Sent by the server to active players every 10s to measure lag. The
client just echoes the message back to the server. The time
between sending and receiving the message in the server is
considered to be the current lag of the respective player.

The two byte sequence number is included to be able to deal with
lost or severely delayed messages. On each ping sent by the server,
the sequence number is incremented (modulo 10000). The server
manages this number on a per player basis.

MsgReplayReset
 	+----+----+----+----+----+
 	| 00 | 01 | 72 | 72 | lp |
 	+----+----+----+----+----+
Sent by the server to active replay observers to remove state
information that they might have regarding players and flags.
The 'lp' value is the last player to be removed. PlayerId's above
'lp' are replay observers, and are not removed.


== UDP negotiation ==

*solo bots don't do this, they should use the existing player's connection

*MsgUDPLinkRequest = 0x6f66;		// 'of'

*MsgUDPLinkEstablished = 0x6f67;	// 'og'

*if client has udp enabled player sends MsgUDPLinkRequest with player number over udp

*if request has valid player number and is from same address server sends MsgUDPLinkEstablished over tcp to confirm inbound server sends MsgUDPLinkRequest back over udp to test outbound

*player gets MsgUDPLinkEstablished and starts sending udp

*player gets MsgUDPLinkRequest and sends MsgUDPLinkEstablished over udp

*server gets MsgUDPLinkEstablished
server can now send over udp

[[Category:Development]]
[[Category:Concepts]]