The BZRC protocol is a simple, text-based, line-oriented, command-response protocol which runs over TCP. The server in this protocol is bzrobots, a specialized BZFlag client. The client in the protocol is referred to as the remote agent.
The bzrobots program listens on a specified TCP port for an incoming connection. Once a connection has been accepted, it will not accept another connection until the first is closed. BZRobots immediately introduces itself by saying, "bzrobots 1\n" (1 being the protocol version). The remote agent then responds with a similar introduction: "agent 1\n". The session is now initiated.
Once the session has been initiated, bzrobots listens for commands from the remote agent. It will issue exactly one response for each command. Responses will always be returned in the same order as the corresponding commands.
The single exception to this general rule is low-level errors, in which case an error message will be sent by bzrobots. See below for more details.
A command consists of a command name followed by a space-delimited list of arguments and ending with a newline. A command is always a single line. The following are sample commands:
shoot 0 obstacles speed 3 -0.241
A response consists of an acknowledgment line followed by a value, which may be several lines long. The acknowledgment line begins with a timestamp (a number of seconds) within brackets and ends with the command being responded to. For example:
ack 128.2342 speed 3 -0.241
Note thet the acknowledgment line is not a character-by-character copy. It's more like the conversational, "If I understood you correctly, you're saying..." For example, if the request specifies robot 17, but no such tank exists, bzrobots will respond with -1 for the tank index.
The value is either a simple value or a list. A simple value is a single line. A list is more than one line. The first line of a list is "begin", and the last line is "end". In between are simple values. If the value line of a response does not start with "begin", then it will always be a simple response and therefore will fit on a single line. A simple value may look like:
ok Success
A list may look like:
begin line 1 line 2 line 3 line 4 end
A full response line might look like:
ack 169.43 shoot abc fail Invalid parameter
or:
ack 66.155 obstacles begin obstacle 100 20 100 40 80 40 80 20 obstacle -30 0 0 0 0 50 -30 50 obstacle 22 17 4 -2 10 -8 end
The single exception to the general behavior is low-level errors. It is possible for bzrobots to send an "error" response at any time. This can even happen in the middle of another response. For example, if the remote agent sends a large number of requests but neglects to read the responses, bzrobots' buffer will fill up and data will be dropped. When the agent finally catches up, bzrobots will send an "error" response to say what happened. Since the truncation could have happened anywhere, the remote agent should always look for an "error" response. Incidentally, the agent should also make sure not to ask questions without listening for the answers.
Error messages may happen in less drastic situations as well. For example, if the agent sends a command that bzrobots doesn't understand, the request will be ignored, and the response will be an error message.
A remote agent may close the connection simply by closing the TCP session. BZRobots will then wait for a connection from another agent.
The following list describes common BZRC requests and their associated responses:
shoot [index]
Request the tank indexed by the given parameter to fire a shot. Returns either:
ok [Comment]
or:
fail [Comment]
where the comment is optional.
speed [index] [speed]
Request the tank indexed by the given parameter to accelerate as quickly as possible to the specified speed, given as a multiple of maximum possible speed (1 is full throttle). A negative parameter will cause the tank to go in reverse. Returns a boolean ("ok" or "fail" as described above).
angvel [index] [angvel]
Request the tank indexed by the given parameter to begin angular acceleration with the specified target angular velocity. The parameter is given as a multiple of maximum possible angular velocity, where positive values indicate counter-clockwise motion, and negative values indicate clockwise motion. The sign is consistent with the convention used in angles in the circle. Returns a boolean ("ok" or "fail" as described above).
accelx [index] [accel] accely [index] [accel]
Request the specified tank to accelerate in the x or y dimension. The value ranges between -1 and 1. Returns a boolean ("ok" or "fail" as described above).
teams
Request a list of teams. The response will be a list, whose elements are of the form:
team [color] [playercount]
Color is the identifying team color/team name. Playercount is the number of tanks on the team.
obstacles
Request a list of obstacles. The response will be a list, whose elements are of the form:
obstacle [x1] [y1] [x2] [y2] ...
where (x1, y1), (x2, y2), etc. are the corners of the obstacle in counter-clockwise order. Depending on runtime configuration, visibility may be limited, so the list of obstacles will not always be complete.
bases
Request a list of bases. The response will be a list, whose elements are of the form:
obstacle [team color] [x1] [y1] [x2] [y2] ...
where (x1, y1), (x2, y2), etc. are the corners of the base in counter-clockwise order.
flags
Request a list of visible flags. The response is a list of flag elements:
flag [team color] [possessing team color] [x] [y]
The team color is the color of the owning team, and the possessing team color is the color of the team holding the flag. If no tanks are carrying the flag, the possessing team is "none". The coordinate (x, y) is the current position of the flag. Note that the list may be incomplete if visibility is limited.
shots
Request a list of visible shots. The response is a list of shot lines:
shot [x] [y] [vx] [vy]
where (x, y) is the current position of the shot and (vx, vy) is the current velocity.
mytanks
Request the status of the tanks controlled by this connection. The response is a list of tanks:
mytank [index] [callsign] [status] [shots available] [time to reload] [flag] [x] [y] [angle] [vx] [vy] [angvel]
Index is the 0 based index identifying this tank. This index is used for instructions. The callsign is the tank's unique identifier within the game. The status is a string like "alive," "dead," etc. Shots available is the number of shots remaining before a reload delay. Flag is the color/name of the flag being held, or "-" if none is held. The coordinate (x, y) is the current position. Angle is the direction the tank is pointed, between negative pi and pi. The vector (vx, vy) is the current velocity of the tank, and angvel is the current angular velocity of the tank (in radians per second).
othertanks
Request the status of other tanks in the game (those not controlled by this connection). The response is a list of tanks:
othertank [callsign] [color] [status] [flag] [x] [y] [angle]
where callsign, status, flag, x, y, and angle are as described under mytanks and color is the name of the team color.
constants
Request a list of constants. These constants define the rules of the game and the behavior of the world. The response is a list:
constant [name] [value]
Name is a string. Value may be a number or a string. Boolean values are 0 or 1.