GameSpy Protocol and New Broadcaster

# Introduction Tiberian Technologies has introduced a new GameSpy broadcaster in TT 4.8 (r8841) which aims to replace the stock broadcaster with a more reliable one, reduce the ambiguity caused by other developers implementing their own broadcasters and standardize a few key factors. Broadcaster resolves the following names to send heartbeats, in order, on port 27900. (They're also used for querying from GameSpy listing) ``` gamespy.tiberiantechnologies.org zenmasters.cncirc.net renmaster.cncirc.net renmaster-backup.cncirc.net renmaster-backup2.cncirc.net renmaster-backup3.cncirc.net renmaster-backup4.cncirc.net ``` # Protocol Summary ## Communication GameSpy protocol in a nutshell is a set of key value pairs, also called dictionary, delimited by backslashes `\\`. It is possible to split up messages, with the requirement of each message ending with `final` keyword but not each part. So, only the last part of the message should end with `final`. However, each part must include a parameter named `queryid` as a decimal where the whole part represents a number incremented for each message, and fractional part represents a number incremented for each part of a message. For example, the message `\key1\value1\key2\value2\final\queryid\1337.1` contains 2 key value pairs with values key1 => value1 and key2 => value2. It is the 1337th message to the broadcaster since the startup, and it's the first (and only) part of the message. If we wanted to send the message in two parts with 4 pairs, then it should be done like `\key1\value1\key2\value2\queryid\1337.1` and then `\key3\value3\key4\value4\final\queryid\1337.2`. By design, it is recommended to keep parts less than 400 characters. ## Heartbeat Servers should send a heartbeat message to the master server for their server to be listed in public listing in at most 30 seconds intervals. Heartbeats should be sent in the form `\heartbeat\[query port]\gamename\[game name]\final` where `[game name]` is the name of your game (For Renegade: `ccrenegade`) and `[query port]` is your query port. This parameter should match the game name that is sent in the basic response, which will be detailed further in this tutorial. For every heartbeat, master server sends a feedback response with name `heartbeatresult` following a numerical result code. For example, `\heartbeatresult\0\final` means that heartbeat processing was successful, and server is now listed in public listing. Here's a list of possible result codes: | Code | Result Name | Description | | ---- | ---------------------- | ---------------------------------------------------------------------------------------------- | | 0 | OK | Request was successfully processed. | | 1 | INVALID_GAMENAME | The `gamename` parameter in the query does not match the game name that was sent in heartbeat. | | 2 | MISSING_MAP | The `mapname` parameter in the query is missing or invalid. | | 3 | MISSING_HOSTNAME | The `hostname` parameter in the query is missing or invalid. | | 4 | MISSING_HOSTPORT | The `hostport` parameter in the query is missing or invalid. | | 5 | BANNED_NAME | The `hostname` parameter in the query matches a listing ban. | | 6 | BANNED_ADDRESS | The server address matches a listing ban. | | 7 | DUPLICATE_SERVER | The same server is already in the listing. | | 8 | BLOCKED_MAP_PREFIX | The map prefix found in `mapname` parameter in the query matches a listing ban. | | 9 | BLOCKED_GAMETYPE | The `gametype` parameter in the query matches a listing ban. | | 10 | INVALID_HEARTBEAT | The format of the heartbeat or the response to initial query was invalid. | | 11 | SERVER_CLOSED | Server requested removal from the list. | | 12 | NO_RESPONSE | The GameSpy master could not receive a response to initial query from the server. | # Features ## WOL/XWIS Simultaneous Broadcasting The GameSpy broadcaster supports simultaneously broadcasting to GameSpy along with WOL/XWIS via the `SimultaneousGameSpyBroadcasting` server.ini keyword. Note that this only works if `GameType` is set to `WOL`. ## Custom Rules It is possible to add custom rules to the `rules` (will be detailed in next section) message by creating `gamespy_rules.ini` in the server folder. Here's an example file content for custom rules. ``` [GamespyRules] Owner=Unstoppable Discord=discord.gg/123abcd IRC=irc.cncirc.net #MyServer ``` ## Messages The GameSpy broadcaster is capable of handling 6 messages: `basic`, `info`, `rules`, `players`, combination of all 4 which is `status` and `echo`. ### `basic` Broadcaster replies to this message in order: game type (`gamename`) and game version (`gamever`). ### `info` Broadcaster replies to this message in order: game title (`hostname`), game port (`hostport`), current map name (`mapname`), next map name (`nextmap`), game mode (`gametype`), current player count (`numplayers`), maximum player count (`maxplayers`), time left (`timeleft`), time elapsed (`timeelapsed`) and time limit (`timelimit`). To join a server, the IP address used to query the GameSpy broadcaster must be taken and `hostport` value must be used to join the server. Game mode is the map prefix if no mod package was loaded. Otherwise, game mode is the name of the mod package. All times has to be formatted in the following format: `HH.mm.ss` where `HH` is total hours, `mm` is minutes and `ss` is seconds. ### `rules` Broadcaster replies to this message in order: server version (`SVER`), console server/FDS flag (`CSVR`), dedicated server flag (`DED`), driver is always gunner flag (`DG`), password flag (`password`), team change allowed flag (`TC`), friendly fire flag (`FF`). If the game is a C&C Mode game then starting credits (`SC`), building destruction ends game flag (`BDEG`), pedestal beacon ends game flag (`BPEG`) is included in the response. If there are any custom rules, then they're also included in the response after all parameters. Flag parameters report either 0 or 1. To report the server version, TT uses the following pattern: `TT/4.80-r8841` ### `players` Broadcaster replies to this message by first including team names, kills, deaths and score then each player's name, kills, deaths, score, ping and total play time. For both main teams, 4 pairs are included in the response, which are: - `team_tX`, name of the team - `kills_tX`, total kills of the team, - `deaths_tX`, total deaths of the team, - `score_tX`, total score of the team. where `X` is the team ID. For Renegade, `1` is for GDI and `0` is for Nod. Custom implementations may return other teams, which in that case `X` may be a negative number. For each player, 7 pairs are included in the response, which are: - `player_X`, name of the player - `kills_X`, total kill count of the player - `deaths_X`, total death cound of the player - `score_X`, total score of the player - `kills_X`, team ID of the player - `ping_X`, ping of the player, in milliseconds - `time_X`, total play time of the player formatted as "HH.mm.ss". where `X` is the player ID. This value ranges from 1 to 127, inclusive. Note that `X` is the true player ID assigned by the server, and these IDs may not be sequential. In other words, there might be a `player_1` and `player_3` in the game, but not a `player_2`! ### `status` Broadcaster replies to this message by combining responses of `basic`, `info`, `rules`, `players`. ### `echo` Broadcaster replies to this message by resending the message to the client.