Launcher Protocol
From OdaWiki
Contents
Overview
This is the Odamex Launcher protocol, which will help developers develop custom launchers in other programming languages
Transport notes
- This protocol uses UDP (User Datagram Protocol) as its transport medium.
- All packets are uncompressed.
- All data is little endian.
Types used
These are the types used in this specification
| Type name | Range | Size |
|---|---|---|
| Signed Integers | ||
| char | -128 to 127 | 8-bit |
| short | -32768 to 32767 | 16-bit |
| int | -2147483648 to 2147483647 | 32-bit |
| Unsigned integers | ||
| byte | 0 to 255 | 8-bit |
| word | 0 to 65535 | 16-bit |
| long | 0 to 4294967295 | 32-bit |
| Strings | ||
| string | ASCIIZ | null terminated |
| Other | ||
| bool | 0 or 1 | byte |
Keywords:
> = Sent to
+ = Array of information (amount here)
X = Any value
Specifications
Master server list request
| Type | Data | Description |
|---|---|---|
| Launcher > Master | ||
| int | 777123 | Request |
| Master > Launcher | ||
| int | 777123 | Response |
| short | X | Server count |
| byte | X | +Server IP 1 (Server count) |
| byte | X | +Server IP 2 |
| byte | X | +Server IP 3 |
| byte | X | +Server IP 4 |
| short | X | +Server Port |
Server Information Request
| Type | Data | Description |
|---|---|---|
| Launcher > Server | ||
| int | 777123 | Request |
| Server > Launcher | ||
| int | 5560020 | Response |
| int | X | Token |
| string | X | Server Name |
| byte | X | Players in server |
| byte | X | Maximum clients |
| string | X | Current map |
| byte | X | WAD count |
| string | X | +PWAD name (WAD count) |
| byte | X | Game type |
| byte | X | Skill level |
| bool | X | Teamplay |
| bool | X | CTF mode |
| string | X | +Player name (numplayers) |
| short | X | +Player frags |
| int | X | +Player ping |
| byte | X | +Player team |
| string | X | +PWAD MD5 hashes (WAD count) |
| string | X | Server Website address |
| int | X | Teamplay/CTF score limit |
| bool | X | Blue team |
| int | X | Blue score (if team enabled) |
| bool | X | Red team |
| int | X | Red score (if team enabled) |
| bool | X | Gold team |
| int | X | Gold score (if team enabled) |
| short | X | Protocol version (e.g. 63) |
| string | X | Server admin email address |
| short | X | Time limit |
| short | X | Time left |
| short | X | Frag limit |
| bool | X | Item respawn |
| bool | X | Weapon stay |
| bool | X | Friendly fire |
| bool | X | Allow exit |
| bool | X | Infinite ammo |
| bool | X | No monsters |
| bool | X | Monsters respawn |
| bool | X | Fast monsters |
| bool | X | Allow jumping |
| bool | X | Allow freelook |
| bool | X | Wad download |
| bool | X | Empty reset |
| bool | X | Frag exit switch |
| short | X | +Kill count (numplayers) |
| short | X | +Death count |
| short | X | +Time in game |
| long | 0x01020304 | Spectator information field |
| short | X | Number of players who can play (the rest are spectators) |
| bool | X | +Spectator (numplayers) |
| long | 0x01020305 | Extra information field |
| bool | X | Passworded |
| int | X | Game version |
Additional Notes
- Token is unnecessary for a launcher I think.
- First PWAD is always the IWAD
- Game types are: 0 = COOP, 1 = Deathmatch, 2 = Deathmatch 2.0
- Skill levels are: 0 = ITYTD, 1 = HNTR, 2 = HMP, 3 = UV, 4 = NM (Acronyms).
- Player teams are: 0 = None, 1 = Blue, 2 = Red, 3 = Gold
- If CTF is enabled, Teamplay will be enabled and deathmatch (2.0?).
- If Teamplay is enabled, then deathmatch (2.0?) will be too.
- Scorelimit, team scores and player teams (excluding team 0) only appear if Teamplay/CTF is enabled.
Possible Future Protocol Improvements
Data structuring
- Container (header based) protocol which would contain: Magic Tag, Size, Version (see above) and the data, this would allow features to be added in any order in 1 packet without breaking it, so if the launcher/server can't understand the magic value, it'll bypass it, via jumping past the entire size of the unknown header to the next one.
- Packets will have a size, to indicate their boundary, including a null termination
- Strings will have a size value, including the null termination.
- Strings will be UTF-8 encoded. (Unicode)
Protocol additions
- Dedicated Odamex Query/Response values (rather than old csdoom ones)
- Proper versioning, with possible subversion number.
- Operating system information the server is running on.