Overview
Introduction
The ONE Arcus Protocol V2 is a TCP/IP-based communication protocol used by the ONE Game Hosting Platform, allowing it to communicate with your game servers and vice versa.
The Arcus protocol when implemented into a Game Server provides two benefits:
- Allows a game developer to connect to his game servers to fetch status information and control it
- Enables additional functionality within the ONE game hosting platform
- adds support for a Matchmaker allocation system
- allows the ONE Game Hosting Platform to retrieve player numbers needed for automatic scaling, if no Allocation mechanism is supported by the game
- enables the ONE Game Hosting Platform to request graceful shutdowns
- enables a game server to request meta data for the host it runs on and request meta data about itself
- custom functionality
Info
The Arcus protocol specification has room for custom functionality that you can integrate if needed. i3D.net is always available to support your specific use cases and add additonal integration functions.
In order for an Arcus connection to be possible, the game server needs to listen on the management port defined in the Management protocol.
Using One Arcus
Our Host Agent will always connect to localhost. This means that for security reasons, a game server should have Arcus listen for local connections only (127.0.0.1).
An Arcus (game) server will listen for a new TCP connection on the management port indicated in the startup parameters of the application instance (game server). More information can be found in the Management protocol port chapter. The client (Host Agent) will connect and wait for an Arcus HELLO packet packet which will tell it the version of the protocol.
The client (Host Agent) will verify whether it supports this version. If not, it will close the connection and report this problem to the ONE Game Hosting platform for logging purposes.
Connection handshake flow
Warning
Client should always wait on the Arcus HELLO packet. In case the server receive any byte before he send the HELLO packet the server will close the connection because an client should always wait.
Tracking requests and responses
Now that the client knows which version it needs to use it can use the arcus protocol, every arcus message contains a PacketID that will be echoed in all the packets an arcus server will send to the clients requests. This will help the client to map responses to requests and makes it possible for the protocol to handle multiple requests.
HELLO Packet Structure
| Data | Type | Comment |
|---|---|---|
| Ident | 4 bytes | Protocol identifier, This value will start with arc and ends with a null byte ["arc"null] |
| Version | byte | Version number of the protocol |
| Reserved | byte | A reserved byte which is not in use right now. it may be used for future purposes. |
Different packet structure than regular Arcus messages
The HELLO packet structure differs from the rest of the packet structures. This structure is specifically designed to fit the requirements of the HELLO packet.
Basic Packet Structure
Both requests and responses are sent as TCP packets. Their payload follows the following basic structure:
| Data | Type | Comment |
|---|---|---|
| Flags | byte | Define extra properties to a packet, Example: gzip compressed payload. |
| Opcode | byte | Identifier of the request |
| Reserved | byte | A reserved byte which is not in use right now. It may be used for future purposes. |
| Reserved2 | byte | |
| PacketID | uint | Unique packetId for the request |
| Length | uint | Length of the payload data |
| Payload | JSON string | Optional payload of the packet |
Flags
Currently flags are not in used, Flags are meant to define special properties to packets such as Compressing, different byte order etc. Right now we don't have any flag defined so the byte flag will be always null.
PacketID
The packet id field is a unsigned 32-bit integer chosen by the client for each request. It may be set to any integer. When the server responds to the request, the response packet will have the same packet id as the original request It need not be unique, but if a unique packet id is assigned, it can be used to match incoming responses to their corresponding requests.
Opcode
The Opcode identifies the packet type. The Section Requests and Responses describes each different packet type.
Reserved
A reserved byte not in use right now but can be used for future purposes.
Reserved2
A reserved byte not in use right now but can be used for future purposes.
Length
The packet Length field is an unsigned 32-bit integer, representing the length of the request in bytes. Note that the length field itself is not included when determining the length of the packet. Hence the value of this field is always 12 less than the packet's actual length.
Payload
Every payload is a JSON string, the Length of the string can be found in the Length property.
Keep in mind that every packet type has his own payload structure. To find the payload structures of a specific type check Requests and Responses