Open Game Protocol Specification v1.01

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

OGP is a datagram based protocol and can be used e.g. over IPv4/UDP or IPv6/UDP.

A bracketed (variable) indicates that it is only a suggestion for a later addition to the protocol. These fields should not be used and can be removed or changed without keeping the backwards compatibility.

If you're a game developer and want to support OGP contact us per mail to get a game id for your game. If any field is missing contact us to talk about it or just put it into rules.

The dependency column contains a boolean expression. Ony if it is true the corresponding field exists. An empty field is treated as true. The "AND"/"OR" keyword represents the logical and/or combination.

We are working on an open source SDK written in C and a PHP client that will be released at www.open-game-protocol.org when it is fully tested and version 1.0 is ready. Later we plan to provide some client implementations in other languages too

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: bUTF8

The server ignores the query if bAnswer is set.

The bUTF8 fields indicates the character encoding of all strings used within the protocol. In general OGP uses the unicode character set. If bUTF8 is not set only the lower 256 unicode number could be encoded which are identical to the Latin-1 or ISO/IEC 8859-1 character encoding. Otherwise the full unicode charset is available and all strings are UTF-8 encoded.
A client indicates by settings the bUTF8 flag that it supports bUTF8. In that case the server is free to choose the character encoding. Otherwise it must answer in Latin-1.
UINT32 ChallengeNumber HeadFlags.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.
UINT32 RequestID HeadFlags.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.
UINT16 MaxBytesPerPacket HeadFlags.bSplit Maximum number of bytes a packet may contain. Set to 0 to deactivate OGP splitting mechanism and use the splitting mechansim of the underlying protocol.
The minimum value is 500 (if not set to 0). The default value is 0.

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)
UINT32 ChallengeNumber HeadFlags.bChallengeNumber If bChallengeNumber is set your old challenge number was invalid and this field contains your new number.
UINT32 RequestID HeadFlags.bRequestID The RequestID of the query. If the answer is splitted a RequestID will be send automatically.
UINT8 SplitPacketCount HeadFlags.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.
UINT8 SplitPacketNo HeadFlags.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 RequestFlags.bServerInfo Bit 0.0: bGameName
Bit 0.1: bServerFlags
Bit 0.2: bHostName
Bit 0.3: bConnectPort

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

Bit 2.0: bPlayerCount
Bit 2.1: bSlotMax
Bit 2.2: bBotCount
Bit 2.3: bReservedSlots
VarBitArray ModFields ServerInfoFields.bMod Bit 0.0: bModIdentifier
Bit 0.1: bModSize
Bit 0.2: bModVersion
Bit 0.3: bModURL
Bit 0.4: bModAuthor
VarBitArray MapFields ServerInfoFields.bMap Bit 0.0: bMapFileName
Bit 0.1: bMapFileSize
Bit 0.2: bMapFileMD5
Bit 0.3: bMapVersion
Bit 0.4: bMapURL
Bit 0.5: bMapAuthor
VarBitArray TeamFields RequestFlags.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 RequestFlags.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: bPlayerAddress
VarBitArray AddOnFields RequestFlags.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 RequestFlags.bServerInfo Server information
TEAMLIST TeamList RequestFlags.bTeamList Complete team list
PLAYERLIST PlayerList RequestFlags.bPlayerList Complete player list
RULELIST RuleList RequestFlags.bRuleList Complete rule list
ADDONLIST AddOnList RequestFlags.bAddOnList Complete AddOn List
LIMITLIST LimitList RequestFlags.bLimitList Complete Limit List

SERVERINFO
VarBitArray ServerInfoFields
SzString GameName bGameName Name of game (e.g. Half-Life)
VarBitArray ServerFlags bServerFlags Bit 0.0-0.1: bType

0 - Unkown
1 - Listen
2 - Dedicated

Bit 0.2: bPassword: If set the server is password protected
Bit 0.3: bProxy: If set the server is a proxy for game broadcasting (e.g. hltv)
Bit 0.4-0.6: OperatingSystem

0 - Unkown
1 - Windows
2 - Linux
3 - Mac
SzString HostName bHostName
StringColorInfo HostNameColor bHostName AND bColoredNames
UINT16 ConnectPort bConnectPort Connect port of game server. Set to 0 if the server has no special connect port i.e. connect port is equal to query port
MODINFO ModInfo bMod
SzString GameType bGameType Type of game that is being played (NO mod). e.g. CTF (Capture the Flag), Deathmatch
SzString GameMode bGameMode String which specifies what is going on in the game at that time. Suggested modes are:

wait - waiting for players to join
closedplaying - game is in progress, no joining allowed
openplaying - game is in progress, players may still join
debriefing - game is over, stats / info is being shown
exiting - server is shutting down
pause - game is paused

VarBitArray MapFields bMap
MAPINFO using MapFields MapInfo bMap
MAPINFO using MapFields NextMapInfo bMap AND bNextMap
VarUINT8-32 PlayerCount bPlayerCount
VarUINT8-32 SlotMax bSlotMax
VarUINT8-32 BotCount bBotCount
VarUINT8-32 ReservedSlots bReservedSlots

MODINFO
SzString ModName Name of modification. If ModName is empty the server has no mod and MODINFO structure ends here.
VarBitArray ModFields ModName not empty See ModFields in query.
SzString ModIdentifier ModName not empty AND bModIdentifier Identifier string of modifiction. If this field is empty the mod identifier is equal to mod name. It can be used to carry the mod directory (e.g. for Half-Life or other Quake based games).
UINT32 ModSize ModName not empty AND bModSize Size in bytes needed by the modification for installing on the client computer.
SzString ModVersion ModName not empty AND bModVersion Version string of modification
SzString ModURL ModName not empty AND bModURL URL of modification
SzString ModAuthor ModName not empty AND bModAuthor Author of modification

MAPINFO
SzString MapName
SzString MapFileName bMapFileName The file name of the map (without extension). If this field is empty the map file name is equal to the map name.
UINT32 MapFileSize bMapFileSize Size of map file(s)
UINT8 x 16 MapFileMD5 bMapFileMD5 16 bytes MD5 digest of map file(s)
SzString MapVersion bMapVersion Version of map
SzString MapURL bMapURL URL of map
SzString MapAuthor bMapAuthor Author of map

TEAMLIST
VarUINT8-32 TeamCount Number of teams 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
VarUINT8-32 PlayerAddressLen bPlayerAddress Length of PlayerAddress structure
UINT8 x PlayerAddressLen PlayerAddress bPlayerAddress Contains the BSD 3.3 (NOT BSD 3.4) sockaddr_in (IPv4), sockaddr_in6 (IPv6, RFC 2553) or any other sockaddr structure. 
struct sockaddr_in {
  UINT16 sin_family; // AF_INET = 2
  UINT16 sin_port;
  UINT8  sin_addr[4];
};
Some implementations of the sockaddr_in structure contain a sin_zero member at the end. To save space it is recommended to remove this member and cut the structure to 8 bytes.

struct sockaddr_in6 {
  UINT16 sin6_family; // AF_INET6 = 10
  UINT16 sin6_port;
  UINT32 sin6_flowinfo;
  UINT8  sin6_addr[16];	
  UINT32 sin6_scope_id;
};

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 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 <= 0xFD: VarUINT data structure ends here
Len8 == 0xFE: Use the next 16-Bit length field
Len8 == 0xFF: Use the next 32-Bit length field
UINT16 Len16 Len8 == 0xFE 16-Bit Length
UINT32 Len32 Len8 == 0xFF 32-Bit Length

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

3.5. Atomic Data Types

Type Description
SINTx Signed x bit integer in little-endian (intel) byte order
UINTx Unsigned x bit integer in little-endian (intel) byte order
SzString Null-Terminated character string

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
    		•
    04/24/2004 0.92
  • Redesigned ServerFlags
  • Added GameMode description
  • Updated ConnectPort description
  • Redesigend Map Information
  • Added extra information to some dependency fields
  • Redesigned VarSINT8-32 and VarUINT8-32 data types
  • Added atomtic data types table
  • Removed atomic data type "String"
    		•
    04/25/2004 0.92
  • Corrected some html errors
  • Included some internal links for better navigation
  • Redesigend Mod Information
  • You can use ip stack udp splitting method by settings split size to 0
    		•
    05/05/2004 0.93
  • Updated splitting description and default value
  • Changed name of PlayerIP field to PlayerAddress and updated format to be protocol independet
  • Added some small information at the beginning of protocol part
  • Added contact information
    		•
    06/23/2004 0.94
  • Some small modification in MODINFO structure
    		•
    08/12/2004 0.95
  • Removed bLimitType dependency from LimitType because LimitType is mandatory
    		•
    03/28/2010 1.01
  • Added option to switch from Latin-1 to Unicode/UTF-8 character encoding.
    		•

    5. Contact

    Homepage: www.open-game-protocol.org
    To get in contact with the OGP team please use the contact link form found at www.open-game-protocol.org.




    OGP designed by Timo Stripf and Tobias Oetzel
    Thx to David Foltyn-Dwarden
    Thx to Marcel Rath for the PHP client implementation and alpha testing.

    Copyright (c) 2003-2010 by Timo Stripf