Guns Battle Protocol

The battle-mode protocol uses UDP datagrams for its transport. It is concerned with making sure clients receive data quickly, but if some pieces of data get lost in the transmission, well, shit happens.

Common Messages
These can be sent by either client or server, as needed.

Ping/pong: lag test
LAG [identifier]

A lag-test message requires that the receiving party (server or client) respond immediately to the sender with a LAG message of the same identifier. The identifier can be any string of reasonable length (recommend 2-4 chars for normal use). The sender can use the duration between sending original message and receiving reply to determine a reasonable round-trip time.

Implementation detail: The server may use this to poke at a client that hasn't sent any updates in a while.

Client to Server Messages
These can only be sent by the client.

Battle mode (UDP) authentication
UST &lt;token&gt;

When clients connect to the lobby (TCP stream, so reliable transmission), they are given an authentication token. The clients must send a message to the server identifying themselves with their token before the battle-mode simulation will accept input from them (via UDP). This must be done whenever the client detects it has lost connection (usually by receiving an ERR message with id 100), and when the client initially connects to the battle simulation.

Implementation detail: as the lobby is not yet implemented, any token will be accepted by the battle simulation, however the same token should be used for subsequent re-authentications of the same client.

Movement direction + velocity
USV &lt;xvel&gt;,&lt;yvel&gt;

The client sends the server its intended changes in velocity vector. It is up to the server to clamp these to reasonable values and simulate the outcome of direction changes (physics simulation). See also server position/rotation transmission.

Zoom level
USZ &lt;zoom-level&gt;

The client sends this to notify the server that the zoom level has been changed. Zoom-level is a ratio (decimal value between 0 and 1).

NOTE: Currently the server does in no way clamp this to reasonable values, though it will use the information to determine visibility of other players.

Viewport Size
USR &lt;xsize&gt;,&lt;ysize&gt;

The client sends this to notify the server that the viewport size has been changed. The server will use this value to help determine visibility of other players.

Player-set waypoints
WPT [xpos,ypos]

Client sends to server to request placing/removing a waypoint. If the x,y position is omitted, the client is requesting removal. See also how the server coordinates waypoints. Clients get a single custom waypoint each.

''Implementation detail: clients get a single waypoint each, and can clear it by right-clicking it again. Easiest way to do this is double-right-clicking while stopped.''

Player shooting
USF &lt;xpos&gt;,&lt;ypos&gt;

The client tells the server its player is trying to shoot at position (xpos,ypos). The server should correct for physical constraints (as needed) and notify all players of the result.

Username query
WHO &lt;user-id&gt;

If a client somehow loses a user-id-to-username mapping, they can ask again about a user-id they don't recognize.

''Implementation detail: Theoretically, the IDs-to-names mapping should be created while still in the lobby, using the (reliable) TCP stream to discuss it. Practically, with no lobby, we need this in case a critical packet drops unexpectedly.''

Server to client messages
These can only be sent by the server (but reuse some of the C2S message identifiers).

User ID notification
UID &lt;user-id&gt;

This is sent in response to the battle-mode authentication message, and tells the client its own user ID, as assigned by the server.

Implementation detail: This helps the client complete its own uid-username mapping for when it receives its own UID to name notification.

Player position/rotation update
USP &lt;user-id&gt; &lt;Xpos&gt;,&lt;Ypos&gt; &lt;rotation degrees&gt;

Sent to interested clients (Implementation detail: in the base implementation, all clients are interested. Otherwise, only clients who can see the client being described are interested.) when necessary. Describes the position and rotation of the client's tank. May be extended to include turret rotation when there are turrets in the game.

''Implementation detail: with stupid clients, we should just send these once per game tick (yes, this means a lot of bandwidth. Deal with it.) and maybe a few times more after they've settled down to constant values (UDP is unreliable. Yeah). Smarter clients should be getting velocity and angular velocity changes and only the occasional sanity check.''

Waypoint coordination
WPT &lt;waypoint-id&gt; [xpos,ypos waypoint-title] [owner-id]

Server sends this to clients to set/unset a waypoint with a given waypoint ID, with a given title, owned by player id owner-id. If the position and title are omitted, instructs the clients to delete the waypoint. If the owner-id is omitted, instructs the clients nobody owns the waypoint.

See also player-set waypoints.

No player view
NPV &lt;user-id&gt;

Sent when a player moves out of view range. This tells the client to stop drawing the player to avoid ghost bugs.

Player shot notification
USF &lt;user-id&gt; &lt;xpos&gt;,&lt;ypos&gt;

After the client tells the server its player is trying to shoot, the server corrects for physical constraints (as needed) and notifies all players of the result, using this S2C command.

Sample session
Legend: >>> messages from client to server <<< messages from server to client
 * 1) comments

>>> UST This\ is\ my\ auth\ token;\ there\ are\ many\ like\ it,\ but\ this\ one\ is\ mine. <<< UID 10 >>> USN narc <<< USN 10 narc   # sent to all clients <<< USN 5 Ez      # sent only to this client <<< USN 3 lemuel  # sent only to this client <<< USP 10 32,32 0 # sent to all clients (position: (32,32), rotation: 0) <<< USP 5 640,480 112 # sent only to this client <<< USP 3 512,384 90 #   -- " -- >>> MSG Hi, guys! <<< MSG 10 Hi, guys! # sent to all clients <<< MSG 3 Hey, narc, what's happening? <<< MSG 5 Good... evening, narc. Come to do battle with us? >>> MSG Naw, just checking if the chat works. Which it does. <<< MSG 10 Naw, just checking if the chat works. Which it does. >>> USD Client Quit <<< USD 10 Client Quit