Arcus V2
Last updated
Last updated
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
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
In order for an Arcus connection to be possible, the game server needs to listen on the management port defined in the .
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 chapter. The client (Host Agent) will connect and wait for an 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.
[](../../images/ArcusHandshake.png)Figure 1: Arcus handshake process
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.
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.
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.
Both requests and responses are sent as TCP packets. Their payload follows the following basic structure:
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
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.
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.
A reserved byte not in use right now but can be used for future purposes.
A reserved byte not in use right now but can be used for future purposes.
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.
Client should always wait on the . 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.
The Opcode identifies the packet type. The Section describes each different packet type.
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