Skip to content

Arena Servers API

Note

ONLY works with Arena App Deployments of the Powered Ascent plan or higher.

A simple, fast and high availability API to manage your Colyseus Arena server deployment. Ideal for multi-regional deployment or can be used to pass simple configuration information to your game client. This client API is a quick and effective solution to provide simple configurable data and server endpoints to your users.

Getting Started

Arena Servers API can be deployed as a new app in your Arena Dashboard. To do so you will need to purchase a credit first and then deploy.

Setup

The API is configured by a JSON file to begin you will need to create a file config.json in the Server Code section of the Arena Dashboard. The file will need to be formatted as outlined below, you can add as many or as few servers as you would like with a minimum of 1 server required.

Required Value

  • url: This is the only required value as it will be used to poll the server to check for availability.

Note

  • Arena Servers API is only compatible with Arena Plans that support auto-scaling (Powered Ascent or higher).

Example config.json:

{
   "servers": [
      {
         "name": "Game US-East 1",
         "region": "US",
         "url": "fake.colyseus.dev",
         "port": 443,
         "visible": true
      },
      {
         "name": "Game EU-Central 1",
         "region": "Germany",
         "url": "fake.colyseus.de",
         "port": 443,
         "visible": false
      }
   ]
}

Deploying your API

To deploy you API save your config file and select Deploy on the top right corner. Make sure to check reload before pressing the Deploy button.

The new changes will be pushed to server drive and will trigger the launch of a new API server with these update changes, once the new server is active (approx 20 - 30 seconds) the old server will shutdown. This provides seamless availability for the API during the update.

Endpoints

To see results from your API server visit the URL displayed in the Manage section of your dashboard with the following endpoints. (IE: abc123.colyseus.dev/api/v1/list)

  • /api/v1/list: Provides a list of servers from the config.json file plus their current state, CCU count and number of game servers deployed.

  • /api/v1/listExpanded: This provides additional details from each application deployment including the specific game server IDs and local IPs. (Future updates will included direct connect endpoint to connect clients directly to that specific server).

Example Response for /api/v1/list:

{
  "arena": [
    {
      "name": "Game US-East 1",             // User Defined Values
      "region": "US",                       // *
      "url": "fake.colyseus.dev",           // *
      "port": 443,                          // *
      "visible": true,                      // *

      "totalCCU": 0,                        // Generated By API
      "totalGameServers": 1,                // *
      "state": "active"                     // *
    },
    {
      "name": "Game EU-Central 1",          // User Defined Values
      "region": "Germany",                  // *
      "url": "fake.colyseus.de",            // *
      "port": 443,                          // *
      "visible": false,                     // *

      "state": "unreachable"                // Generated By API
    }
  ]
}

Note

  • Arena currently only support port 2567, 80, 443 (SSL).
Back to top