Launcher protocol
This launcher protocol lets you to talk to servers and get information from them, allowing you to make your own custom programs like browsers, stat tools, and so on.
Contents |
Protocol information
Version: 0.54 (July 8, 2009), compatible with the developmental version, 97e.
See "article history" to look up the protocol for prior versions.
The basics
All Skulltag servers use UDP as their network protocol. Additionally, all traffic is compressed using the Huffman algorithm to save bandwidth. Therefore, you'll need a copy of huffman.cpp or huffman.java to encode and decode your traffic appropriately.
Definition of data types used in this article:
Byte: 8 bit integer Short: 16 bit integer Long: 32 bit integer Float: Long representation of a float String: null-terminated series of Bytes
Getting the list of servers
This is very easy, accomplished by sending a single long to the master server:
Type Value Description ------------------------------- Long 199 Launcher challenge
The server will respond with one of the following:
Type Value Description ------------------------------- Long 0 Beginning of list Byte 3 Denied; your IP is banned Byte 4 Denied; your IP has made a request in the past 10 seconds
Assuming you were accepted, you get this next block, which is repeated for every server.
Type Value Description ------------------------------- Byte 1 Beginning of server Byte 0-255 IP octet Byte 0-255 IP octet Byte 0-255 IP octet Byte 0-255 IP octet Short 0-65535 IP port
Finally, the response should end with this:
Type Value Description ------------------------------- Byte 2 End of list
Querying individual servers
As with the master, you begin with the challenge long.
Type Value Description ------------------------------- Long 199 Launcher challenge
Next you need to choose what data you'd like. To do so, bitshift the combination of flags with a boolean OR.
The flags are:
SQF_NAME 0x00000001 SQF_URL 0x00000002 SQF_EMAIL 0x00000004 SQF_MAPNAME 0x00000008 SQF_MAXCLIENTS 0x00000010 SQF_MAXPLAYERS 0x00000020 SQF_PWADS 0x00000040 SQF_GAMETYPE 0x00000080 SQF_GAMENAME 0x00000100 SQF_IWAD 0x00000200 SQF_FORCEPASSWORD 0x00000400 SQF_FORCEJOINPASSWORD 0x00000800 SQF_GAMESKILL 0x00001000 SQF_BOTSKILL 0x00002000 SQF_DMFLAGS 0x00004000 SQF_LIMITS 0x00010000 SQF_TEAMDAMAGE 0x00020000 SQF_TEAMSCORES 0x00040000 // Deprecated SQF_NUMPLAYERS 0x00080000 SQF_PLAYERDATA 0x00100000 SQF_TEAMINFO_NUMBER 0x00200000 SQF_TEAMINFO_NAME 0x00400000 SQF_TEAMINFO_COLOR 0x00800000 SQF_TEAMINFO_SCORE 0x01000000 SQF_TESTING_SERVER 0x02000000 SQF_DATA_MD5SUM 0x04000000
For example, to get the server's name and player count, you'd use (SQF_NAME|SQF_NUMPLAYERS). Use these flags appropriately; doing so saves your users' and server hosters' bandwidth.
Type Value Description ------------------------------- Long Flags Desired information
Next you send the time. This will be sent back to you so you can determine ping.
Type Value Description ------------------------------- Long Time The current time
The server will respond with one of the following:
Type Value Description ---------------------------------------------------------------- Long 5660023 Beginning of data Long 5660024 Denied; your IP has made a request in the past 10 seconds Long 5660025 Denied; your IP is banned
Regardless of this message, you'll also get:
Type Value Description ---------------------------------------------------------------- Long Time The time you sent to the server
Next, assuming you were accepted, you'll get:
Type Value Description ---------------------------------------------------------------- String Version Server version string with revision number. Long Flags The info you'll be receiving. (Possibly corrected - see below)
Note: The server will automatically correct your request if you made a mistake (like request team scores in cooperative games), so always use the flags it sends back to you when reading your data.
Followed by:
Type Request flag Description
----------------------------------------------------------------
String SQF_NAME The server's name (sv_hostname)
String SQF_URL The server's WAD URL (sv_website)
String SQF_EMAIL The server host's e-mail (sv_hostemail)
String SQF_MAPNAME The current map's name
Byte SQF_MAXCLIENTS The max number of clients (sv_maxclients)
Byte SQF_MAXPLAYERS The max number of players (sv_maxplayers)
Byte SQF_PWADS The number of PWADs loaded
String SQF_PWADS The PWAD's name (Sent for each PWAD)
Byte SQF_GAMETYPE The current game mode. See below.
Byte SQF_GAMETYPE Instagib - true (1) / false (0)
Byte SQF_GAMETYPE Buckshot - true (1) / false (0)
String SQF_GAMENAME The base game's name
("DOOM", "DOOM II", "HERETIC", "HEXEN", "ERROR!")
String SQF_IWAD The IWAD's name
Byte SQF_FORCEPASSWORD Whether a password is required to join the server
(sv_forcepassword)
Byte SQF_FORCEJOINPASSWORD Whether a password is required to join the game
(sv_forcejoinpassword)
Byte SQF_GAMESKILL The game's difficulty (skill)
Byte SQF_BOTSKILL The bot difficulty (botskill)
Long SQF_DMFLAGS DMFlags
Long SQF_DMFLAGS DMFlags2
Long SQF_DMFLAGS Compatflags
Short SQF_LIMITS fraglimit
Short SQF_LIMITS timelimit
Short SQF_LIMITS timeleft in minutes ( returned when timelimit > 0 )
Short SQF_LIMITS duellimit
Short SQF_LIMITS pointlimit
Short SQF_LIMITS winlimit
Float SQF_TEAMDAMAGE The team damage scalar (teamdamage)
Short SQF_TEAMSCORES [Deprecated] This team's fragcount/wincount/score
(Repeated for each team (blue, then red))
Byte SQF_NUMPLAYERS The number of players in the server
String SQF_PLAYERDATA Player's name
Short SQF_PLAYERDATA Player's pointcount/fragcount/killcount
Short SQF_PLAYERDATA Player's ping
Byte SQF_PLAYERDATA Player is spectating - true (1) / false (0)
Byte SQF_PLAYERDATA Player is a bot - true (1) / false (0)
Byte SQF_PLAYERDATA Player's team ( returned on team games, 255 is no team )
Byte SQF_PLAYERDATA Player's time on the server, in minutes.
Byte SQF_TEAMINFO_NUMBER The number of teams used.
String SQF_TEAMINFO_NAME The team's name. (Sent for each team.)
Long SQF_TEAMINFO_COLOR The team's color. (Sent for each team.)
Short SQF_TEAMINFO_SCORE The team's score. (Sent for each team.)
Byte SQF_TESTING_SERVER Whether this server is running a testing binary
- true (1) / false (0)
String SQF_TESTING_SERVER An empty string in case the server is running a stable
binary, otherwise name of the testing binary
archive found in http://skulltag.com/testing/files/
String SQF_DATA_MD5SUM A string with the MD5 sum of the main data file
(skulltag.wad/skulltag_data.pk3) the server uses.
And that's it!
Notes
Game modes: Game modes are defined as:
0 GAMEMODE_COOPERATIVE 1 GAMEMODE_SURVIVAL 2 GAMEMODE_INVASION 3 GAMEMODE_DEATHMATCH 4 GAMEMODE_TEAMPLAY 5 GAMEMODE_DUEL 6 GAMEMODE_TERMINATOR 7 GAMEMODE_LASTMANSTANDING 8 GAMEMODE_TEAMLMS 9 GAMEMODE_POSSESSION 10 GAMEMODE_TEAMPOSSESSION 11 GAMEMODE_TEAMGAME 12 GAMEMODE_CTF 13 GAMEMODE_ONEFLAGCTF 14 GAMEMODE_SKULLTAG 15 GAMEMODE_DOMINATION
To discuss the protocol, use this topic.
Happy coding!