Arcus V2

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

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

[![](../../images/ArcusHandshake.png "Arcus handshake")](../../images/ArcusHandshake.png)Figure 1: Arcus handshake process

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.


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


Last updated

Was this helpful?