Open Game Protocol Specification v0.91

1. What is OGP?

The Open Game Protocol (OGP) was developed and designed to provide specific real-time information about games running at any given server.
Most effort was made to meet all the needs of a flexible game protocol which is supposed to support every kind of game. Basically this could be achieved because for an analyzer of the obtained information it is not necessarry to have knowledge about a single game.

OGP is characterized by a simple and therefore high reliable design requiring only a minimum of ressources. To meet also economical objectives OGP uses individual constructed queries in binary format to obtain only the desired information. In this way it is possible to request all information provided by a server (e.g. player information, server details) with just one packet.
Especially in the always growing online-game market traffic and performance more and more becomes a serious problem. Higher speed is another positive side effect of small dynamic requests and answers.
To provide the highest possible flexibility the design of OGP allows quickly updates/adaptions towards new conditions while providing full backwards compatibility.

For many administrators distributed denial of service (DDoS) attacks belongs to one of the most dangerous troubles in the current online businesses. Of course this is also handled by OGP to avoid additional exploits in the server environment.

2. Features

3. Protocol

3.1. Header

Type Name Dependency Comment
OGP Header (Query)
UINT32 Prefix Value: 0xFFFFFFFF
SzString Value: "OGP" (4 bytes incl. 0 byte)
UINT8 HeadSize Size in bytes of the ogp header including this field but without the prefix.
UINT8 Type 0x00 - Ping
0x01 - Default query v1
0x02 - (Rcon)
0x03 - Master Server Uplink (answer only)
0xFF - Error (answer only)
VarBitArray HeadFlags Bit 0.0: bAnswer = 0
Bit 0.1: bChallengeNumber
Bit 0.2: bRequestID
Bit 0.3: bSplit
Bit 0.4: (bPassword)

The server ignores the query if bAnswer is set.

The password field is reserved for future. It is needed for ogp rcon protocol and to request sensitiv information about some player via default protocol (e.g. IP address)
INT32 ChallengeNumber bChallengeNumber The challenge number to query the server. If the number is wrong or you don't specify one, you'll get one per answer packet. Send a challenge number of 0 to request a new one.
OGP uses the challenge number mechanism to prevent DDoS attacks using ip spooling. It is ip dependent and can change at any time.
The number is not mandatory for every ogp service and depends on the server implementation.
INT32 RequestID bRequestID User definied ID to associate an answer packet with a query and to detect duplicated UDP packets. If RequestID = 0 the server will choose a request id.
INT16 MaxBytesPerPacket bSplit Maximum number of bytes a UDP packet may contain. Valid range: 500 - 1500. Default 1400

OGP Header (Answer)
UINT32 Value: 0xFFFFFFFF
SzString ID Value: "OGP" (4 bytes incl. 0 byte)
UINT8 HeadSize Size in bytes of the ogp header including this field.
UINT8 Type See OGP Header (Query)
VarBitArray HeadFlags Bit 0.0: bAnswer = 1
Bit 0.1: bChallengeNumber
Bit 0.2: bRequestID
Bit 0.3: bSplit
Bit 0.4: (bPassword)
INT32 ChallengeNumber bChallengeNumber If bChallengeNumber is set your old challenge number was invalid and this field contains your new number.
INT32 RequestID bRequestID The RequestID of the query. If the answer is splitted a RequestID will be send automatically.
INT8 SplitPacketCount bSplit If a answer packet is splitted only the first packet (SplitPacketNo=0) contains the ChallengeNumber, Password information etc. The other packets only contain the RequestID and these split fields.
INT8 SplitPacketNo bSplit

3.2. Error Messages

Error (Answer)
UINT8 ErrorValue 0 - Banned
1 - Invalid Type: The query type in header is unkown
2 - Invalid Value: Any value in header is incorrect
3 - Invalid Challenge Number: The challenge number is incorrect
4 - Invalid Query: The query body is incorrect
Data ErrorValue == 3 (Invalid Challenge) Copy of the OGP request including the new challenge number. A client receiving this error code must only send this part of the packet back from where it came.

3.3. Master Server Uplink

Master Server Uplink (Answer)
UINT16 GameID

3.4. Default Query v1

Default Query v1 (Query)
VarBitArray RequestFlags Bit 0.0: bServerInfo
Bit 0.1: bTeamList
Bit 0.2: bPlayerList
Bit 0.3: bRuleList
Bit 0.4: bAddOnList
Bit 0.5: bLimitList

Bit 1.0: bColoredNames
VarBitArray ServerInfoFields bServerInfo Bit 0.0: bGameName
Bit 0.1: bServerFlags
Bit 0.2: bMod
Bit 0.3: bConnectPort

Bit 1.0: bHostName
Bit 1.1: bMap
Bit 1.2: bNextMap
Bit 1.3: bGameType
Bit 1.4: bGameMode

Bit 2.0: bPlayerCount
Bit 2.1: bSlotMax
Bit 2.2: bBotCount
Bit 2.3: bReservedSlots
VarBitArray TeamFields bTeamList Bit 0.0: bTeamName
Bit 0.1: bTeamScore
Bit 0.2: bTeamAveragePing
Bit 0.3: bTeamAverageLoss
Bit 0.4: bTeamPlayerCount
Bit 0.5: bTeamColor
VarBitArray PlayerFields bPlayerList This field indicates which player information will be returned

Bit 0.0: bPlayerFlags
Bit 0.1: bPlayerSlot
Bit 0.2: bPlayerName
Bit 0.3: bPlayerTeam
Bit 0.4: bPlayerClass
Bit 0.5: bPlayerRace

Bit 1.0: bPlayerScore
Bit 1.1: bPlayerFrags
Bit 1.2: bPlayerKills
Bit 1.3: bPlayerDeath
Bit 1.4: bPlayerSuicides
Bit 1.5: bPlayerTeamKills

Bit 2.0: bPlayerID
Bit 2.1: bPlayerGlobalID
Bit 2.2: bPlayerPing
Bit 2.3: bPlayerLoss
Bit 2.4: bPlayerModel
Bit 2.5: bPlayerTime

Bit 3.0: bPlayerIPv4
VarBitArray AddOnFields bAddOnList Bit 0.0: bAddOnFlags
Bit 0.1: bAddOnShortName
Bit 0.2: bAddOnLongName
Bit 0.3: bAddOnVersion

Default Query v1 (Answer)
UINT16 GameID Unique identifier of each game that supports OGP. You find a list of games at www.open-game-protocol.org
VarBitArray RequestFlags See Requests field in query
SERVERINFO ServerInfo bServerInfo Server information
TEAMLIST TeamList bTeamList Complete team list
PLAYERLIST PlayerList bPlayerList Complete player list
RULELIST RuleList bRuleList Complete rule list
ADDONLIST AddOnList bAddOnList Complete AddOn List
LIMITLIST LimitList bLimitList Complete Limit List

SERVERINFO
VarBitArray ServerInfoFields
SzString GameName bGameName Name of game (e.g. Half-Life)
VarBitArray ServerFlags bServerFlags Bit 0.0: bDedicated
Bit 0.1: bProxy
Bit 0.2-0.5: OperatingSystem

0 - Unkown
1 - Windows
2 - Linux
3 - Mac

SzString ModName bMod Name of the mod. If ModName is empty the server is running no special modification.
e.g. Counter-Strike
SzString ModDir bMod Directory of the mod. On Quake based games all modifications has their own directory.
e.g. cstrike
UINT16 ConnectPort bConnectPort Connect Port of the game server
SzString HostName bHostName
StringColorInfo HostNameColor bHostName AND bColoredNames
SzString MapName bMap
SzString MapFile bMap The file name of the map (without extension). If this field is empty the map file name is equal to the map name.
SzString NextMapName bNextMap
SzString NextMapFile bNextMap The file name of the map (without extension). If this field is empty the map file name is equal to the map name.
SzString GameType bGameType
SzString GameMode bGameMode
VarUINT8-32 PlayerCount bPlayerCount
VarUINT8-32 SlotMax bSlotMax
VarUINT8-32 BotCount bBotCount
VarUINT8-32 ReservedSlots bReservedSlots

TEAMLIST
VarUINT8-32 TeamCount Team count in team list.
VarBitArray TeamFields TeamCount != 0 See TeamFields in query
TEAMLISTENTRY x TeamCount TeamList Team list

TEAMLISTENTRY
SzString TeamName bTeamName
StringColorInfo TeamNameColor bTeamName AND bColoredNames
VarSINT8-32 TeamScore bTeamScore
UINT16 TeamAveragePing bTeamAveragePing
UINT16 TeamAverageLoss bTeamAverageLoss
VarUINT8-32 TeamPlayerCount bTeamPlayerCount
UINT16 TeamColor bTeamColor 16 Bit color value in 5-6-5 RGB format

PLAYERLIST
VarUINT8-32 PlayerCount Player count in player list.
VarBitArray PlayerFields PlayerCount != 0 See PlayerFields in query
PLAYERLISTENTRY x PlayerCount PlayerList Player list

PLAYERLISTENTRY
VarBitArray PlayerFlags bPlayerFlags Bit 0.0: bAlive
Bit 0.1: bDead
Bit 0.2: bBot

Bit 1.0: (bBomp)
Bit 1.1: (bVIP)
VarUINT8-32 PlayerSlot bPlayerSlot The server slot that is used by this player.
SzString PlayerName bPlayerName Name of the player
StringColorInfo PlayerNameColor bPlayerName AND bColoredNames
VarSINT8-32 PlayerTeamNo bPlayerTeam The number of the team
-1 - Not Assinged
-2 - Spectator
SzString PlayerClass bPlayerClass
SzString PlayerRace bPlayerRace
VarSINT8-32 PlayerScore bPlayerScore
VarSINT8-32 PlayerFrags bPlayerFrags
VarUINT8-32 PlayerKills bPlayerKills
VarUINT8-32 PlayerDeath bPlayerDeath
VarUINT8-32 PlayerSuicides bPlayerSuicides
VarUINT8-32 PlayerTeamKills bPlayerTeamKills
UINT32 PlayerID bPlayerID Server wide unique identifier
SzString PlayerGlobalID bPlayerGlobalID
UINT16 PlayerPing bPlayerPing
UINT16 PlayerLoss bPlayerLoss
SzString PlayerModel bPlayerModel
UINT16 PlayerTime bPlayerTime Time in seconds the player is on the server
UINT32 PlayerIPv4 bPlayerIPv4 Player IPv4 Address

RULELIST
VarUINT8-32 RuleCount Rule count in rule list.
RULELISTENTRY x RuleCount RuleList Rule list

RULELISTENTRY
SzString RuleKey
SzString RuleValue

ADDONLIST
VarUINT8-32 AddOnCount
VarBitArray AddOnFields AddOnCount != 0 See AddOnFields in query
ADDONLISTENTRY x AddOnCount AddOnList AddOn list

ADDONLISTENTRY
VarBitArray AddOnFlags bAddOnFlags Bit 0.0: bActive
Bit 0.1: bAntiCheatTool
Bit 0.2: bMutator
Bit 0.3: bAdminTool
SzString AddOnShortName bAddOnShortName
SzString AddOnLongName bAddOnLongName
SzString AddOnVersion bAddOnVersion

LIMITLIST
VarUINT8-32 LimitCount
LIMITLISTENTRY x LimitCount LimitList Limit list

LIMITLISTENTRY
VarBitArray LimitType bLimitType Bit 0.0: bLimitLeft
Bit 0.1-0.4: LimitType
0 - Time (in seconds)
1 - Player Score
2 - Round
3 - Team Score
VarUINT8-32 Limit
VarUINT8-32 Left bLimitLeft

3.4. Elementary Data Types

VarBitArray Type:
UINT8 Byte[n] n=0 or Bit 7 of Byte[n-1] is set The type begins with n=0 (Byte[0]).
This is the n+1th byte of bit array. Bits 0-6 are free to use and are indicated by "n.x". If Bit 7 is not set VarBitArray ends here and all other bits are adopted to 0. Otherwise it follows Byte[n+1] of same format.

StringColorInfo Type:
VarUINT8-32 ColorSize
StringColorInfoEntry List Data This fields has a length of ColorSize bytes.

StringColorInfoEntry Type:
VarUINT8-32 DeltaPosition
UINT8 ColorValue 0x00-0x0F: Change text color to ColorValue (VGA Colors)
0x10: Reset text color to default
0x20-0x2F: Change background color to ColorValue-16 (VGA Colors)
0x30: Reset background color to defaul
0x40: Toggle bold
0x41: Toggle underlined
0x42: Toggle cursive

0x90: Use 16-Bit text color
0x91: Use 16-Bit background color
UINT16 ColorValue16 ColorValue >= 0x90 OR ColorValue <= 0x9F 16 Bit color value in 5-6-5 RGB format

VarUINT8-32 Type:
UINT8 Len8 8-Bit Length:
Len8 <= 0xFE: VarUINT data structure ends here
Len8 == 0xFF: Use the next 16-Bit length field
UINT16 Len16 Len8 == 0xFF 16-Bit Length:
Len16 <= 0xFFFE: VarUINT data structure ends here
Len16 == 0xFFFF: Use the next 32-Bit length field
UINT32 Len32 Len16 == 0xFFFF 32-Bit Length

VarSINT8-32 Type:
SINT8 Len8 8-Bit Length:
-0x7F <= Len8 <= 0x7F: VarSINT data structure ends here
Len8 == -0x80: Use the next 16-Bit length field
SINT16 Len16 Len8 == -0x80 16-Bit Length:
-0x7FFF <= Len16 <= 0x7FFF: VarSINT data structure ends here
Len16 == -0x8000: Use the next 32-Bit length field
SINT32 Len32 Len16 == -0x8000 32-Bit Length

4. Protocol Change Log

Date Version Description
03/22/2004 0.91 Added Changelog
04/10/2004 0.91 Added ServerInfoField to SERVERINFO structure
Changed type of TeamScore from SINT32 to VarSINT8-32
Removed bLimitType dependency from LimitType because LimitType is mandatory

SINTx: Signed x bit integer in little-endian (intel) byte order
UINTx: Unsigned x bit integer in little-endian (intel) byte order
String: Character String of unkown length
SzString: Null-Terminated string


OGP designed by Timo Stripf and Tobias Oetzel

Copyright (c) 2003-2004 by Timo Stripf