This wiki is deprecated. Visit https://ddnet.org/docs/libtw2/serverinfo_extended for the current version of this page
This file is mirrored from the libtw2 documentation and is dual-licensed under MIT or APACHE.
In the following document, “vanilla” refers to unmodified Teeworlds.
An extended server info can be requested from the Teeworlds server by sending the following UDP packet:
[2] magic_bytes
[2] extra_token
[2] reserved
[4] padding
[4] vanilla_request
[1] token
magic_bytes must be the ASCII representation of “xe”.
extra_token contains a 16 bit big-endian integer that should be
shifted by 8 to the left and combined with token with a bitwise or,
before the extended server info is sent back.
reserved is reserved for future protocol versions and must be zeroed
by the sender and ignored by the receiver with this protocol version.
padding must be filled with 0xff bytes.
vanilla_request must be the ASCII representation of “gie3”.
token is an arbitrary byte chosen by the client which will be sent
back with the server info. For the extended server info, the
extra_token field needs to be included in the server info response.
If a server receives such a request (detected by the magic_bytes
field), it can either respond with the vanilla server info, or by
sending the extended server info, described in the following.
If the server does not recognize the magic_bytes, it should send back
the vanilla server info.
The extended server info can consist of several packets, the “main” packet and the “more” packets, which can contain additional player data in case they don’t fit in the first packet.
The str type is a zero-terminated UTF-8 string. Implementations should
be prepared to either replace invalid UTF-8 with the replacement
character or to treat these fields as opaque zero-terminated byte
sequences.
The int type is an integer encoded in the decimal system in a
zero-terminated ASCII string.
NOTE: The reference implementation clears control characters (replacing bytes with a value of less than 32 with the ASCII space ’ ‘) and skips leading whitespace in all strings.
The receiver of such a server info can detect whether it has received the server info completely by comparing the number of players received with the number of players set in the main packet.
The main server info packet looks like follows:
[ 10] padding
[ 4] type
[int] token
[str] version
[str] name
[str] map
[int] map_crc
[int] map_size
[str] game_type
[int] flags
[int] num_players
[int] max_players
[int] num_clients
[int] max_clients
[str] reserved
[ *] players
padding must be filled with 0xff bytes.
type must be the ASCII representation of “iext”.
token must be the token from the request. If the server info isn’t
sent upon a request, it mut be -1.
version contains the server version. The first three bytes must equal
the client’s version, otherwise it will be filtered out as “incompatible
version”.
name, map, game_type are the server’s name, its current map and
gametype, respectively. map_crc is the current map’s CRC (note that
Teeworlds uses incorrect starting values to calculate the CRC) and
map_size is the map’s size in bytes.
There is currently only one flag for the flags field, namely the
password flag, whose value is 1. It must be set if entering the server
requires a password, and unset in the other case.
num_players, max_players, num_clients, max_clients: These values
describe how many players (people that are not in “spectator mode”) and
clients (people that are connected to the server) the server currently
has (num_*) and is able to handle (max_*). The following natural
inequalities must hold:
<= max_players
0 <= num_players <= max_clients
<= num_clients
Note that there is no upper limit for max_clients enforced by the
protocol.
The field reserved is reserved for future protocol versions. Senders
of this message must set the field to the empty string, and receivers of
this message must ignore its value.
players contains the player info described further below.
A “more” packet looks like this:
[ 10] padding
[ 4] type
[int] token
[int] packet_no
[str] reserved
[ *] players
padding, token, reserved, players: See the explanation on the
main packet.
type must contain the ASCII representation of “iex+”.
packet_no must be packet number in the server info response. It must
be greater than 0 and less than 64. The main packet has an implicit
packet_no of 0. This field can be used to detect duplicated packets.
A single player info is defined as:
[str] name
[str] clan
[int] country
[int] score
[int] is_player
[str] reserved
The name, clan and score field contain the player’s name, clan and
score, respectively.
The country field contains the ISO 3166-1 numeric code of the player’s
country, or -1 if unset.
The is_player field contains a non-zero integer if the player is not a
spectator, and 0 otherwise. Producers of this message should always use
1 to indicate a non-spectator client.