mirror of
https://github.com/FWGS/xash3d-fwgs.git
synced 2026-08-05 03:24:56 +08:00
367 lines
16 KiB
Markdown
367 lines
16 KiB
Markdown
# Xash3D 49 connectionless protocol
|
|
|
|
Connectionless protocol defines four common message sources and destinations, they can be:
|
|
* `S` for Server
|
|
* `C` for Client
|
|
* `M` for Master
|
|
* `A` for Anything else
|
|
|
|
All connectionless packets have `\xff\xff\xff\xff` (32-bit integer set to all ones) in it's header. Let's go through each of possible direction in this document.
|
|
|
|
<!--TOC-->
|
|
|
|
- [Any](#any)
|
|
- [Any to Any](#any-to-any)
|
|
- [`A2A_PING` and `A2A_GOLDSRC_PING`](#a2a_ping-and-a2a_goldsrc_ping)
|
|
- [`A2A_ACK` and `A2A_GOLDSRC_ACK`](#a2a_ack-and-a2a_goldsrc_ack)
|
|
- [Deprecated queries](#deprecated-queries)
|
|
- [`A2A_NETINFO`](#a2a_netinfo)
|
|
- [`A2A_INFO`](#a2a_info)
|
|
- [Any to Client](#any-to-client)
|
|
- [`A2C_PRINT` and `A2C_GOLDSRC_PRINT`](#a2c_print-and-a2c_goldsrc_print)
|
|
- [Any to Server and Server to Any](#any-to-server-and-server-to-any)
|
|
- [GoldSrc server queries](#goldsrc-server-queries)
|
|
- [`A2S_GOLDSRC_INFO`](#a2s_goldsrc_info)
|
|
- [`A2S_GOLDSRC_PLAYERS`](#a2s_goldsrc_players)
|
|
- [`A2S_GOLDSRC_RULES`](#a2s_goldsrc_rules)
|
|
- [Any to Master](#any-to-master)
|
|
- [`S2M_SCAN_REQUEST`](#s2m_scan_request)
|
|
- [Master to Any](#master-to-any)
|
|
- [`M2A_SERVERSLIST`](#m2a_serverslist)
|
|
- [Master and game server](#master-and-game-server)
|
|
- [Server to Master](#server-to-master)
|
|
- [`S2M_HEARTBEAT`](#s2m_heartbeat)
|
|
- [`S2M_SHUTDOWN`](#s2m_shutdown)
|
|
- [`S2M_INFO`](#s2m_info)
|
|
- [Master to Server](#master-to-server)
|
|
- [`M2S_CHALLENGE`](#m2s_challenge)
|
|
- [`M2S_NAT_CONNECT`](#m2s_nat_connect)
|
|
- [Client and game server](#client-and-game-server)
|
|
- [Client to Server](#client-to-server)
|
|
- [`C2S_BANDWIDTHTEST`](#c2s_bandwidthtest)
|
|
- [`C2S_GETCHALLENGE`](#c2s_getchallenge)
|
|
- [`C2S_CONNECT`](#c2s_connect)
|
|
- [Server to Client](#server-to-client)
|
|
- [`S2C_BANDWIDTHTEST`](#s2c_bandwidthtest)
|
|
- [`S2C_CHALLENGE`](#s2c_challenge)
|
|
- [`S2C_CONNECTION`](#s2c_connection)
|
|
- [`S2C_ERRORMSG`](#s2c_errormsg)
|
|
- [`S2C_REJECT`](#s2c_reject)
|
|
|
|
<!--TOC-->
|
|
|
|
## Any
|
|
|
|
### Any to Any
|
|
|
|
#### `A2A_PING` and `A2A_GOLDSRC_PING`
|
|
|
|
Simple ping message.
|
|
* Request, in ASCII: `ping` or `i` in GoldSrc format
|
|
* Response is always `A2A_ACK` or `A2A_GOLDSRC_ACK`
|
|
|
|
#### `A2A_ACK` and `A2A_GOLDSRC_ACK`
|
|
|
|
Simple ack message.
|
|
* Request, in ASCII: `ack` or `j` in GoldSrc format
|
|
* Response: none
|
|
|
|
#### Deprecated queries
|
|
|
|
These text-based Xash protocol queries are deprecated in favor of [GoldSrc server queries](#goldsrc-server-queries), which Xash3D FWGS servers implement as well. New implementations must not send them. The server still responds to `A2A_INFO` for compatibility with older clients, `A2A_NETINFO` is not handled anymore.
|
|
|
|
##### `A2A_NETINFO`
|
|
|
|
Used to implement Half-Life's NetAPI.
|
|
* Request message, in ASCII: `netinfo <version> <context> <request_id>`
|
|
- `version` must be 49, as text.
|
|
- `context` can be any 32-bit signed integer value, encoded as text.
|
|
- `request_id` see `common/net_api.h`
|
|
|
|
* Response message, in ASCII: `netinfo <context> <request_id> <response>`
|
|
- `context` same as in request.
|
|
- `request_id` same as in request.
|
|
- `response` is server's response, depending on request type. Always encoded as Quake info string.
|
|
|
|
Possible requests and response formats:
|
|
* Request ID `1` will make server respond with empty response string.
|
|
* Request ID `2` makes server respond with all server game rule cvars where the key is cvar name and the value is cvar value. One additional key `rules` with total amount of cvars is added.
|
|
* Request ID `3` makes server respond with players list, where:
|
|
- `p<id>name` is set to player's name
|
|
- `p<id>frags` is set to player's kill count
|
|
- `p<id>time` is set to player's total play time
|
|
- `players` is total player's list.
|
|
- Alternatively, it can respond with `neterror` set to `forbidden` if server does not wish to expose it's player list.
|
|
* Request ID `4` makes server to respond with common game details:
|
|
- `hostname` is server's name
|
|
- `gamedir` is game directory name
|
|
- `current` is total player count
|
|
- `max` is max players limit
|
|
- `map` is server's current level
|
|
* On any other server will respond with `neterror` set to `undefined`
|
|
* If protocol version doesn't match, server responds with `neterror` set to `protocol`
|
|
|
|
##### `A2A_INFO`
|
|
|
|
Used to request server's details.
|
|
* Request message, in ASCII: `info <version>`
|
|
- `version` must be 49, as text
|
|
* Response message, in ASCII: `info\n<response>`
|
|
- `response` is Quake info string, otherwise it's an error message.
|
|
|
|
* Response info string format:
|
|
- `p` is set to protocol version (FWGS extension)
|
|
- `map` is server's current level
|
|
- `dm` set to 1 if current game mode is deathmatch otherwise 0
|
|
- `team` set to 1 if current game mode includes teamplay otherwise 0
|
|
- `coop` set to 1 if current game mode is cooperative otherwise 0
|
|
- `numcl` is total player count
|
|
- `maxcl` is max players limit
|
|
- `gamedir` is game directory name
|
|
- `password` set to 1 if server is protected with password otherwise 0
|
|
- `host` is server's name
|
|
|
|
### Any to Client
|
|
|
|
#### `A2C_PRINT` and `A2C_GOLDSRC_PRINT`
|
|
|
|
Simple print message.
|
|
* Header: `\xff\xff\xff\xff`
|
|
* Request, in ASCII: `print <message>` or `l<message>` in GoldSrc format.
|
|
* Response: none
|
|
|
|
### Any to Server and Server to Any
|
|
|
|
#### GoldSrc server queries
|
|
|
|
These match Source Engine Query messages used in GoldSrc and Source engine and implemented for compatibility with existing server browsers and monitoring tools. The client uses them to query GoldSrc servers in the server browser, and as text-based Xash protocol queries are [deprecated](#deprecated-queries), it will use them to query Xash servers as well. Read documentation for them on VDC: https://developer.valvesoftware.com/wiki/Server_queries
|
|
|
|
Unlike other connectionless messages these are binary: integers are little-endian, floats are 32-bit IEEE 754 and strings are null-terminated.
|
|
|
|
`A2S_GOLDSRC_PLAYERS` and `A2S_GOLDSRC_RULES` requests carry a 32-bit challenge, `A2S_GOLDSRC_INFO` may have one appended after the query string. When no challenge is known yet, `\xff\xff\xff\xff` is sent in it's place. The server may answer with a challenge instead of the data: byte `A` (`0x41`) followed by a 32-bit challenge value, 9 bytes total with the header. The request is then repeated with the received challenge. Don't confuse this message with textual `S2C_GOLDSRC_CHALLENGE` used during connection, they only share the first byte. Xash servers respond to queries immediately and never send query challenges, GoldSrc servers require them since the 2020 update.
|
|
|
|
Responses that don't fit into a single packet (usually rules) come from GoldSrc servers split into fragments. Such packets start with `\xfe\xff\xff\xff` instead of `\xff\xff\xff\xff`, followed by a 32-bit sequence number, same in all fragments of one response, and a byte with total fragment count in the lower 4 bits and this fragment's index in the upper 4 bits. Fragment payloads concatenated in index order form a normal `\xff\xff\xff\xff` message. Xash servers never split query responses and send them as single datagrams.
|
|
|
|
#### `A2S_GOLDSRC_INFO`
|
|
|
|
Used to request server's details.
|
|
|
|
* Request: `TSource Engine Query\0`, optionally followed by a 32-bit challenge. Xash servers ignore it.
|
|
* Response: byte `I` (`S2A_GOLDSRC_INFO`), followed by:
|
|
- byte: protocol version, 48 on GoldSrc, 49 on Xash3D FWGS
|
|
- string: server's name
|
|
- string: server's current level
|
|
- string: game directory name
|
|
- string: game description
|
|
- int16: Steam AppID, always 0 on Xash servers
|
|
- byte: total player count, bots included
|
|
- byte: max players limit
|
|
- byte: bot count
|
|
- byte: server type, `d` for dedicated or `l` for listen server
|
|
- byte: server's operating system, `w` for Windows, `l` for Linux, `m` for macOS
|
|
- byte: set to 1 if server is protected with password otherwise 0
|
|
- byte: set to 1 if server is VAC secured, Xash servers put the `secure` value from gameinfo here
|
|
- string: server's version
|
|
|
|
Same as the Source engine response format but without the extra data flag and its fields.
|
|
|
|
Legacy GoldSrc servers respond with the obsolete `m` format (`S2A_GOLDSRC_LEGACY_INFO`) instead, see VDC for its layout. Xash servers never send it but the client understands it and assumes protocol 48.
|
|
|
|
#### `A2S_GOLDSRC_PLAYERS`
|
|
|
|
Used to request server's player list.
|
|
|
|
* Request: byte `U` (`0x55`), then a 32-bit challenge.
|
|
* Response: byte `D` (`S2A_GOLDSRC_PLAYERS`), followed by a byte with total player count, then for each player:
|
|
- byte: player's index. Xash servers send sequential indexes starting from 0, GoldSrc servers always send 0 here.
|
|
- string: player's name
|
|
- int32: player's kill count
|
|
- float: time in seconds the player is connected, -1.0 for bots on Xash servers
|
|
|
|
Xash server doesn't respond at all if the player list is empty, the server is protected with password or exposing the player list is disabled with `sv_expose_player_list` cvar.
|
|
|
|
#### `A2S_GOLDSRC_RULES`
|
|
|
|
Used to request server's game rules.
|
|
|
|
* Request: byte `V` (`0x56`), then a 32-bit challenge.
|
|
* Response: byte `E` (`S2A_GOLDSRC_RULES`), followed by an int16 with total rule count, then rule name and rule value strings for each.
|
|
|
|
Only server cvars (`FCVAR_SERVER`) are sent. Values of protected cvars (`FCVAR_PROTECTED`) are replaced with `1` if the value is set otherwise `0`. If there are no cvars to expose, server doesn't respond at all.
|
|
|
|
### Any to Master
|
|
|
|
#### `S2M_SCAN_REQUEST`
|
|
|
|
* Request: `1<region><IP:Port>\0<info>`
|
|
- Format of this message is loosely based on https://developer.valvesoftware.com/wiki/Master_Server_Query_Protocol
|
|
- `info` however adds few additional fields:
|
|
- `clver` set to engine's version
|
|
- `nat` set to 1 to filter only servers behind NAT and tell master to notify servers about scan
|
|
- `commit` set to engine's build commit hash
|
|
- `branch` set to engine's build branch
|
|
- `os` set to which operating system engine has been built
|
|
- `arch` set to which CPU architecture engine has been built
|
|
- `buildnum` set to engine's build number
|
|
- `key` set to random 32-bit value formatted as hex, used to validate master responses
|
|
* Response: `M2A_SERVERSLIST`
|
|
|
|
### Master to Any
|
|
|
|
#### `M2A_SERVERSLIST`
|
|
|
|
* Request: `f\xff<key><reserved><IP:Port>...`
|
|
- `key` is random 32-bit value set in `S2M_SCAN_REQUEST`
|
|
- `reserved` is single reserved 8-bit byte
|
|
- Following is list of IP addresses in binary form: 6-bytes for IPv4 address + port and 18-bytes for IPv6 address + port
|
|
- If port is 0, it means the end of list, otherwise it's the last IP used for pagination (not implemented in Xash3D)
|
|
* Response: client doesn't make response to master server but might request `A2S_GOLDSRC_INFO` from servers
|
|
|
|
## Master and game server
|
|
|
|
### Server to Master
|
|
|
|
#### `S2M_HEARTBEAT`
|
|
|
|
Used to update game server information on the master server.
|
|
|
|
* Request: `q\xff<heartbeat challenge>`
|
|
- `heartbeat challenge` is random 32-bit value, used to prevent faked/forged source IP addresses.
|
|
* Response: `M2S_CHALLENGE`
|
|
|
|
#### `S2M_SHUTDOWN`
|
|
|
|
Used to notify master server about server shutdown, but due to security reasons must be ignored by any master implementation.
|
|
|
|
* Request: `\x62\x0a`
|
|
* Response: none
|
|
|
|
#### `S2M_INFO`
|
|
|
|
Game server info response on `M2S_CHALLENGE`.
|
|
|
|
* Request: `0\n<info>`
|
|
- `info` is Quake info string containing server information passed to master server. It contains following fields:
|
|
- `protocol` is always 49
|
|
- `challenge` is master challenge
|
|
- `players` is total player count, without bots
|
|
- `max` is max players limits
|
|
- `bots` is total bot count
|
|
- `gamedir` is set to game directory
|
|
- `map` is server's current level
|
|
- `type` set to `d` for dedicated or `l` for listen server
|
|
- `password` set to `1` if server protected with password set otherwise `0`
|
|
- `os` always `w`
|
|
- `secure` always `0`
|
|
- `lan` always `0`
|
|
- `version` engine version
|
|
- `region` always `255`
|
|
- `product` same as `gamedir`
|
|
- `nat` set to `1` if server is behind NAT
|
|
* Response: none
|
|
|
|
### Master to Server
|
|
|
|
#### `M2S_CHALLENGE`
|
|
|
|
Master's respoonse on game server's heartbeat message.
|
|
|
|
* Request: `s<master challenge><heartbeat challenge>`
|
|
- `master challenge` contains 32-bit value, used in server response to prevent faked/forged source IP addresses.
|
|
- `heartbat challenge` cotnains 32-bit value, used in heartbeat request to prevent faked/forged source IP addresses.
|
|
* Response: `S2M_INFO`.
|
|
|
|
#### `M2S_NAT_CONNECT`
|
|
|
|
Master server's message with client IP address and port, used in NAT punching.
|
|
|
|
* Request: `c <IP:Port>`
|
|
* Response: `S2C_INFO` to a specified client address.
|
|
|
|
## Client and game server
|
|
|
|
### Client to Server
|
|
|
|
#### `C2S_BANDWIDTHTEST`
|
|
|
|
Used to figure out network MTU. The message is optional and server might choose to not implement it or respond with challenge.
|
|
|
|
* Request, in ASCII: `bandwidth <version> <max_size>`
|
|
- `version` must be 49, as text.
|
|
- `max_size` is requested maximum packet size.
|
|
|
|
* Possible responses:
|
|
- `S2C_BANDWIDTHTEST`
|
|
- `S2C_CHALLENGE`
|
|
- `A2A_PRINT` followed by `S2C_REJECT`
|
|
- `S2C_ERRORMSG` (as FWGS extension) followed by `A2A_PRINT` and `S2C_REJECT`.
|
|
|
|
#### `C2S_GETCHALLENGE`
|
|
|
|
Used to validate client's address to prevent faked/forged source IP addresses.
|
|
|
|
* Header: `\xff\xff\xff\xff`
|
|
* Request, in ASCII: `getchallenge steam`
|
|
- `steam` argument is optional and can be ignored by the server, as it's only kept for compatibility with similar GoldSrc 48 message.
|
|
|
|
* Possible responses:
|
|
- `S2C_CHALLENGE`
|
|
|
|
#### `C2S_CONNECT`
|
|
|
|
Used to build a connection with the server.
|
|
|
|
* Header: `\xff\xff\xff\xff`
|
|
* Request, in ASCII: `connect <version> <challenge> "<protinfo>" "<userinfo>"`
|
|
- `version` must be 49, as text.
|
|
- `challenge` must be challenge value, as text.
|
|
- `protinfo` is a Quake info string, containing protocol extensions and other connection information.
|
|
- `uuid` is this client's unique ID (FWGS extension) hasheed with MD5.
|
|
- `qport` is random integer value from 1 to 65535, unique for this engine run.
|
|
- `ext` is an integer value OR'ed with requested protocol extensions. Currently only extension is `NET_EXT_SPLITSIZE` with the value of `1`, which tells server to split messages based on `cl_dlmax` value from `userinfo`.
|
|
- `userinfo` contains initial user info, encoded as Quake info string.
|
|
* Possible responses:
|
|
- `A2A_PRINT` followed by `S2C_REJECT`
|
|
- `S2C_ERRORMSG` (as FWGS extension) followed by `A2A_PRINT` and `S2C_REJECT`.
|
|
- `S2C_CONNECTION`
|
|
|
|
### Server to Client
|
|
|
|
#### `S2C_BANDWIDTHTEST`
|
|
|
|
* Request: `testpacket<crc><blob>`
|
|
- `crc` is 32-bit CRC of `blob`
|
|
- `blob` random data
|
|
* There is no required response to this message
|
|
|
|
Total message size doesn't exceed request max size.
|
|
|
|
#### `S2C_CHALLENGE`
|
|
|
|
* Request, in ASCII: `challenge <value>`
|
|
- `value` is challenge value that client must include in it's response
|
|
* Response: `C2S_CONNECT`
|
|
|
|
#### `S2C_CONNECTION`
|
|
|
|
* Request, in ASCII: `client_connect <protinfo>`
|
|
- `protinfo` is an optional Quake info string, contains following optional fields:
|
|
- `ext` is an integer value OR'ed with allowed protocol extension. Bit fields match requested in `ext` field in `C2S_CONNECT`
|
|
- `cheats` set to 1 if server allows cheats otherwise 0
|
|
* Response: there is no out of band from the client but client will proceed to building netchan and switch client-server interaction to it.
|
|
|
|
#### `S2C_ERRORMSG`
|
|
|
|
Show client error message. Doesn't mean connection reject, only used for UI.
|
|
|
|
* Request, in ASCII: `errormsg <message>`
|
|
- `message` contains error message
|
|
* Response: none
|
|
|
|
#### `S2C_REJECT`
|
|
|
|
Client has been rejected in connection.
|
|
|
|
* Request, in ASCII: `disconnect`
|
|
* Response: client can cope, get depressed or mentally tell server to fuck off.
|