Packets

Health

Arcus provides a health check mechanism that determines whether client and server properly respond to traffic.

The game server (server) must send a health packet when no data has been received by the host agent (client) within 30 seconds.
In case the host agent (client) closed the connection but somehow the game server (server) didn't get notified about this, sending the health packet will fail and the game server must close the connection. The host agent will continuously attempt to re-establish the connection.

The host agent (client) uses the same mechanism but adds a small buffer to the interval and will never send a simple health packet when it didn't receive any message in the set interval + buffer value the connection will be closed and reopened.

Health check

The default interval is 30 seconds, and the default buffer is 1 second.

Packet structure

Data	Type	Value
Flags	byte	0
Opcode	byte	0x02
Reserved	byte	0
Reserved2	byte	0
PacketID	uint	Any positive integer, chosen by the server, will be mirrored back in the clients's response
Length	uint	Length of the payload data
Payload	JSON string	No payload

Soft Stop

With a soft stop it's possible to inform the application to gracefully shut itself down. By providing a timeout value higher than "0" the platform will hard stop the application in case it didn't gracefully shutdown yet.

Soft stop can be applied for instance patching For more information on patching see patching.

Timeout

Timeout unit is in seconds, an zero value will disable the timeout and the stop request will never timeout.

Packet structure

Data	Type	Value
Flags	byte	0
Opcode	byte	0x30
Reserved	byte	0
Reserved2	byte	0
PacketID	uint	Any positive integer, chosen by the client, will be mirrored back in the server's response
Length	uint	Length of the payload data
Payload	JSON string	JSON object with key value pair that contains the timeout value.

Example payload

{
    "timeout": 100
}

Warning

The default behavior of the platform will always hard stop your application, Its required to configure a soft stop method for your application before this packet will be send to your application.

Allocated

Inside one platform, it's possible to mark a game server as allocated this way the platform knows that the server is in use. Most matchmakers are taking care of this part with the help of arcus we could inform the game servers them self about this as well. A game server can already start loading maps or doing other tasks before the players are connected to improve the player waiting times for example.

In a couple of cases game servers needs to know what to load for example: which map does it need to load? this can be controlled with the help of meta data. An allocation request has a optional body containing a JSON object with key value pairs for meta data this keys and values are definable by the customer.

Packet structure

Data	Type	Value
Flags	byte	0
Opcode	byte	0x60
Reserved	byte	0
Reserved2	byte	0
PacketID	uint	Any positive integer, chosen by the client, will be mirrored back in the server's response
Length	uint	Length of the payload data
Payload	JSON string	(optional) JSON object with key value pair that contains the meta data object.

Example payload

{
  "data": [
    {
      "key": "map",
      "value": "islands_large"
    },
    {
      "key": "maxPlayers",
      "value": "16"
    }
  ]
}

MetaData

With this packet it's possible to transfer metadata from the ONE platform to the game server without the need of an allocation call first. This may be of use if you want to send extra information to the game server, such as: Load map "islands_large", Game mode: "Battle royal", Type: "Squads". The game server can prepare / load everything already before a single player has joined the server.

Packet structure

Data	Type	Value
Flags	byte	0
Opcode	byte	0x40
Reserved	byte	0
Reserved2	byte	0
PacketID	uint	Any positive integer, chosen by the client. It will be mirrored back in the server's response
Length	uint	Length of the payload data
Payload	JSON string	(optional) JSON object with key value pair that contains the metadata object.

Example payload

{
  "data": [
    {
      "key": "map",
      "value": "islands_large"
    },
    {
      "key": "mode",
      "value": "BR"
    },
    {
      "key": "type",
      "value": "squads"
    }   
  ]
}

Reverse MetaData

With this packet it's possible to transfer metadata from the game server to the ONE platform. This may be of use if you want to send information from the game server to the ONE platform.

Example situation:
There are situations where the game server made a decision which changed the metadata inside the game server. To receive this information from the game server this packet can be used to send the changed metadata back to the ONE platform.

Packet structure

Data	Type	Value
Flags	byte	0
Opcode	byte	0x41
Reserved	byte	0
Reserved2	byte	0
PacketID	uint	Any positive integer, chosen by the client. It will be mirrored back in the server's response
Length	uint	Length of the payload data
Payload	JSON string	(optional) JSON object with key value pair that contains the metadata object.

Example payload

{
  "data": [
    {
      "key": "map",
      "value": "islands_large_xl"
    },
    {
      "key": "mode",
      "value": "kingofhill"
    },
    {
      "key": "type",
      "value": "duos"
    }   
  ]
}

Live state

Live state packet is meant to sync up the game state in the server with the platform and inform if the game is in use by players.
To make sure the data is in sync, this packet will always be sent to new connections to sync up the current state. After the connection has been established it will be sent on every game state that update the state with a new player amount.

The payload of the response will contain a JSON object with the mandatory values, an developer can always add more information to the response.

Mandatory values
- current players
- max players
- server name
- map
- mode
- version.

Packet structure

Data	Type	Value
Flags	byte	0
Opcode	byte	0x20
Reserved	byte	0
Reserved2	byte	0
PacketID	uint	Any positive integer, chosen by the server, will be mirrored back in the clients's response
Length	uint	Length of the payload data
Payload	JSON string	JSON object with key value pair that contains live state information.

Example payload

{
  "players": 5,
  "maxPlayers": 16,
  "name": "My awesome Game Server",
  "map": "islands",
  "mode": "DEATHMATCH",
  "version": "1.0.0.1"
}

Host information

On all new connections the client will send the Host Information to the server.
To inform the server on what type of host he is running.

Packet structure

Data	Type	Value
Flags	byte	0
Opcode	byte	0x50
Reserved	byte	0
Reserved2	byte	0
PacketID	uint	Any positive integer, chosen by the client. It will be mirrored back in the server's response
Length	uint	Length of the payload data
Payload	JSON string	Below you can find a example payload.

Example payload

[
  {
    "id": 0,
    "serverId": 0,
    "serverName": "string",
    "projectName": "string",
    "clientServerName": "string",
    "clientState": "string",
    "isVirtual": 0,
    "locationId": 0,
    "dcLocationId": 0,
    "fleetId": "string",
    "fleetAssociatedSince": 0,
    "serviceTag": "string",
    "ipAddress": [
      {
        "ipAddress": "string",
        "version": 0,
        "type": 0,
        "private": 0,
        "interface": 0,
        "macAddress": "string",
        "rDns": "string",
        "vlanId": 0,
        "gateway": "string",
        "netmask": "string",
        "prefix": 0
      }
    ],
    "brand": "string",
    "model": "string",
    "numCpu": 0,
    "labels": [
      {
        "key": "string",
        "value": "string"
      }
    ]
  }
]

ApplicationInstance information

On all new connections the client will send the ApplicationInstance information message to the server.
This will contain information that is known for the instance by our one platform.

Below you will find an example object that will be send to indicate what kind of information you can expect.

Packet structure

Data	Type	Value
Flags	byte	0
Opcode	byte	0x70
Reserved	byte	0
Reserved2	byte	0
PacketID	uint	Any positive integer, chosen by the client. It will be mirrored back in the server's response
Length	uint	Length of the payload data
Payload	JSON string	Payload see Example payload below

Example payload

{
    "fleetId": "string",
    "hostId": 0,
    "isVirtual": 0,
    "applicationId": "string",
    "applicationType": 0,
    "applicationBuildId": "string",
    "installId": "string",
    "dcLocationId": 0,
    "regionId": "string",
    "status": 0,
    "createdAt": 0,
    "startedAt": 0,
    "stoppedAt": 0,
    "pid": 0,
    "pidChangedAt": 0,
    "manuallyDeployed": 0,
    "properties": [
      {
        "id": "string",
        "propertyType": 0,
        "propertyKey": "string",
        "propertyValue": "string"
      }
    ],
    "ipAddress": [
      {
        "ipAddress": "string",
        "ipVersion": 0,
        "private": 0
      }
    ],
    "labels": [
      {
        "key": "string",
        "value": "string"
      }
    ],
    "metadata": [
      {
        "key": "string",
        "value": "string"
      }
    ],
    "autoRestart": 0
  }

ApplicationInstance status

This packet is meant to sync the game status in the server with the platform and inform on what status it's is running.
To make sure the data is in sync, this packet will always been sent to new connections to sync up the current state. After the connection has been established it will be sent on every game status state update.

The payload of the response will contain a JSON object with the mandatory values.

List of possible values

Status code	Status name	Description
3	starting	The instance is currently starting up (optional)
4	online	The instance has started up and is fully working (and initialized)
5	allocated	The instance has been allocated by a matchmaker

More information see ApplicationInstance status

Packet structure

Data	Type	Value
Flags	byte	0
Opcode	byte	0x71
Reserved	byte	0
Reserved2	byte	0
PacketID	uint	Any positive integer chosen by the server. Will be mirrored back in the clients's response
Length	uint	Length of the payload data
Payload	JSON string	Json object with key `status` which contains the new status of the instance

Example payload

{
  "status": 4
}

Custom Command

This packet can be used to create your own custom commands to fit your needs. The structure of the packet is pre-defined, it's a simple key value object with 2 predefined keys command, arguments.

Example
An example command can be command:kickplayer argument:<name> <reason>. Below you will find an example object

Packet structure

Data	Type	Value
Flags	byte	0
Opcode	byte	0x45
Reserved	byte	0
Reserved2	byte	0
PacketID	uint	Any positive integer, chosen by the client. It will be mirrored back in the server's response
Length	uint	Length of the payload data
Payload	JSON string	Payload see Example payload below

Example payload

{
  "data": [
    {
      "key": "command",
      "value": "kickplayer"
    },
    {
      "key": "arguments",
      "value": "player1 Hacking"
    }
  ]
}