Welcome to the i3D.net documentation!

This documentation is primarily aimed at people who want to understand the following services provided by i3D.net:

Game Hosting

The Game Hosting service can be used by game publishers to dynamically deploy their game servers all over the world, using our bare metal servers, flex metal servers, and cloud VMs.

There are two ways in which developers can learn about the inner workings of the platform:

• The Dashboard: For end-users and developers alike.

• The API: Learn how to communicate with the API in order to automate deployment related processes.

Anti-DDoS

We have expanded our infrastructure services to also include an Anti-DDoS solution, GLAD (Global Low-Latency anti-DDoS protection). This intuitive solution takes advantage of i3D.net’s extensive global network to prevent, detect, and thwart a strike to your services.

Compute: Bare Metal and FlexMetal servers

Our product offerings encompass Compute solutions such as Bare Metal and FlexMetal. Bare Metal provides a high-performance, single-tenant computing environment that eliminates virtualization layers, enabling customized hardware configurations to precisely meet specific requirements. FlexMetal combines the strength of physical servers with the flexibility of cloud services. This hybrid model provides the best of both worlds, enabling hourly or monthly billing to fit your needs and optimize costs.

Our new releases and improvements

We now support Tencent Cloud on our Game Hosting service

We have expanded our cloud provider portfolio to include Tencent Cloud. It is a viable option for game hosting, optimizing your game server performance and player experience. For more information, see our .

Optimize your game hosting with our Game Server Orchestrator

At i3D.net, we understand the challenges and uncertainties that come with game hosting. That's why we've developed a cutting-edge and adaptable method to assist you in effectively managing your infrastructure resources throughout the game's entire lifespan. Our complete product offers game build distribution, scaling, and automation. For more information, see .

Support

It's very easy to use our Game hosting dashboard. The following sections describes how to quickly get your game deployed. If you prefer setting up your game hosting through API, please see our .

Step 1: A CDN account is created

After you receive your credentials, you will be able to upload your build archive.

Once you have registered your build origin server from the previous step, you can now define your application. You can define your application in the following four types:

• A Game server

• A Utility / sidecar

• A Dependency installer

Nearly all endpoints in the API v3 require authentication as an i3D.net customer.

Authentication occurs in the form of an API key that can be .

API key

By clicking on the Generate API key button on the aforementioned control panel page, you create a new API key.

By default it has no IP whitelisting and no expiration date.

i3D.net provides the "Arcus" management protocol for communication with game servers. This protocol is used by the host agent and by the i3D.net Game Hosting platform to list information about servers such as their name, player count and whether or not they are password protected. Arcus can also be used to send instructions to a game server. E.g. to perform a graceful stop.

Continue reading: Usage

A2S is the standard Steam query protocol. It's simple and only used for querying your game server for information about the game.

Please refer to its manual for more information: Steam query protocol website

Protocol ID

The A2S query protocol uses protocol ID 1 in our platform.

For more information on how to setup the A2S query protocol within our platform, please refer to the Supported Management Protocols chapter.

To change your CPU platform, you can only do this with Google Cloud Provider (GCP). In order to upgrade to the CPU platform AMD Milan or later, you must first create a new Virtual Machine (VM) with a new template in ODP. The steps below explain the process.

1. Go to one.i3D.net and enter your login credentials.

2. Create a new VM with a new instance template.

3. After the creation of the new template, i3D.net automatically sends a request in GCP. With that template request, GCP creates a template with the same name. GCP will use this template to create a VM.

4. Each name is unique on GCP, so if you want to apply this new template on a name that already exists, you must:

   • Copy the name of the existing template.

   • Delete the template.

   • Paste the name on the newly created template.

5. Select the Series N2D in the drop down list.

6. Select the Machine type N2d-standard-2 (2 vCPU, 8 GB memory).

7. Select the CPU platform AMD Milan or later in the drop down list.

8. Click Create.

• About GLAD: i3D.net's Anti-DDoS solution

• DDoS attack types overview

• DDoS category attack types

• Customer onboarding guide

Looking for a quick start on game deployment within the Game Hosting platform using our Game Server Orchestrator? Here's how it works:

1. Register build origin and upload your build archive.

Before you can begin, you need to register a build origin; a secure web server that hosts your build archives. A build origin can be a web server that you host yourself, or you can use a build origin provided by us.

Once that's registered, upload your build to the origin.

2. Define your Application

Our platform needs to have some information about the application you're going to deploy. As such, you have to telling us what kind of application it is (a game application to begin with) and you must give it some , like a network (game) port that clients can connect to.

3. Create Application Build

Next you must point to your build archive from within an . Here you enter things like the name of the executable, along with any startup parameters that we need to pass to the game server when starting it.

4. Create Game Template

From within a you point to an Application Build you want to deploy. You need this step because you must point to this later on in the process.

5. Create Deployment Environment

A is the top most element in your deployment hierarchy. It encapsulates all Fleets that must be grouped together for a single purpose. E.g. you can have a development, testing and production environment.

6. Create Deployment Profile

Now it's time to tell the platform where you want your game servers deployed by creating a . Here you must define your geographical deployment regions (based on where you rent bare metal servers from us) and optionally add cloud bursting locations to each region.

7. Create Fleet

A ties all previously created elements together, defining for the platform all details it requires in order to deploy your game servers.

8. Enable Deployment

Finally, you must . Sit back and see your game servers come online within a few minutes(1)(2)

¹ the largest factor in deployment time is the size of your build archive that needs to be downloaded ² in order to deploy game servers you first need to have at least one bare metal or flex metal server active in your account

Related topics

This section of the documentation explains processes within the i3D.net ONE Game Hosting service.

A process is a certain aspect of the Platform that you may have to go through and complete before you can use the Platform, such as setting up your applications and application builds. Or setting up your deployment environment so that our system knows how to deploy your game servers.

Here are all the documented processes where each has a short explanation and a link to the full process documentation.

Application Management

Application Management is the process of defining and maintaining the applications you want to deploy with the ONE Game Hosting service.

Application Build Provisioning

The purpose of the i3D.net ONE Game Hosting platform is to deploy your applications. Providing your build to the platform therefore is a crucial process.

Application Build Management

Application Build Management is the process of creating and maintaining software builds for your Application. An ApplicationBuild defines the software that will be deployed by our system. It can be a game server or a utility (side car).

Deployment Configuration

Deployment configuration is the process of setting up how you want your applications to be deployed and where and when.

Dependency Installation

Dependency Installation is the process of installing software requirements (dependencies) for your applications.

Deployment Process

This chapter describes the process of deploying an ApplicationInstance.

Automatic Deployment

Opposite the manual deployment process is the automatic deployment process whereby our platform takes care of deploying game servers and utilities (side cars) for you. This is done according to the Deployment Configuration you have setup for a Fleet.

Automatic Scaling

This chapter explains the logic behind our automatic scaling process.

Patching Process

A patching process is the process of updating game servers / utilities to a new version of the software. There are multiple ways in which this can be done.

Updating your game servers with a rolling update means that you update game servers as soon as they exit naturally or when they are empty and unallocated. This of course only works for game types that have matches that end. Some games do not have the concept of finite matches but instead run forever. That type of game might not be suited for this kind of update method.

No maintenance window is required. What is required is that your back end can handle multiple game server versions alongside each other. Additionally your clients should be able to connect to either version. As you can tell, you should only perform rolling updates if the new version is compatible with the old one.

After a while most game servers will be updated. Any remainders can be Forcibly Updated.

Benefits

• No maintenance window is required

• No extra server resources are required. The total amount of game servers will remain equal during a rolling update

• Completely transparent to your clients

Downsides

• No way to test your newly deployed game server versions. As such, testing must be done beforehand!

Performing a Rolling Deployment via the UI

Performing a Rolling Deployment via the API

Performing a Rolling Deployment manually

You can perform all of the above manually if you wish, bypassing our automated systems. For more details on how to do this, please see the chapter. Note that you will not receive any live-reporting emails then.

A deployment template defines which applications to deploy for a Fleet.

This section of the documentation elaborates on deployment template elements for game server builds, utilities and dependencency installers.

GameDeploymentTemplate

The GameDeploymentTemplate indicates which [game server] ApplicationBuilds you want to have deployed within a Fleet.

Continue reading ...

UtilityDeploymentTemplate

The UtilityDeploymentTemplate indicates which utility / utilities you want to deploy onto each host (bare metal or VM). A utility, also known as a sidecar, is always deployed once per host. You can indicate whether a utility should be deployed only on bare metal servers or virtual machines, or both.

DependencyDeploymentTemplate

The DependencyDeploymentTemplate enables you to provide scripts that install dependencies onto a Host that are required by your Application(s) to run properly. Besides an installer script, you must also define an un-installer script to remove the dependencies and to allow clean up of a Host after removing all applications running on it.

The figure below depicts the relationships between the different Application related elements:

• Application

• ApplicationProperty

• ApplicationBuild

Relationships

To use the protocol and fetch information or send requests to a game server, you need to open a TCP connection. The first thing you need to send is the Initialization packet (link to Initialization structure) the server will accept the Initialization or deny it. When it's denied, the server closes the connection. When the server accepts the Initialization it will reply with an "Acknowledged" packet.

You are now ready to communicate with the game server. When you send an instruction to the game server it will respond with a Not implemented packet or an Acknowledged packet to indicate what is going on.

When you request information such as Server information you will not receive an Acknowledged packet but just a packet with the response.

Missing a feature?

Does your game require a feature that we don't currently support? Please so we can see if we can help with the feature you require.

Versioning

Each packet contains a version byte in its headers. This byte will be used in case the packet structure will change in the future. By default this value is 1.

Continue reading:

The following examples are full walkthroughs for using the Game Hosting platform via the API.

Registering your application and builds

Go to the example

Creating a completely configured deployment environment from scratch

Deployment configuration is the process of setting up how you want your applications (its builds) to be deployed and where and when.

A deployment configuration is made up of several elements which are described in the following chapters. A deployment configuration always begins with a Deployment Environment.

Schematic deployment configuration overview

A PatchJobEmail element describes an email address that we send patching reports to.

You can set which reports to have sent to the email address:

• progress reports

• the final result report

For the best hosting results and for full control over your game servers and clients, you can integrate some functions of our platform within your game. Although this is not technically necessary, it is recommended.

Game Server Orchestrator

A smooth release of a multiplayer game with an efficient game hosting solution can help with its success. i3D.net understands the importance of that. To help burgeoning game studios in that endeavor, i3D.net offers a new product: The Game Server Orchestrator. The Game Server Orchestrator is a fully customizable game hosting solution that offers scalability solutions (scaling up / down game servers based on demand), health checks, monitoring, and more.

The DeploymentEnvironment is the topmost element in the deployment configuration hierarchy. It is normally used to reflect a title (game) that you host on our platform, split up into e.g. development, testing and production environments.

Figure 1: DeploymentEnvironment's place in the Deployment Configuration

Usage

Our recommendation is to create an environment per title. Additionally, separating your live environment from any development environments is advised so changes and experiments done for development purposes in a development environment won't affect your live environment.

Within a DeploymentEnvironment you can create multiple s, in case you want to separate e.g. different platforms like PC, PS4, Xbox, Switch, etc.

The ONE Game Hosting platform now has a utility patching mechanism that makes it easy for you to update builds for already running application instances. This document explains the following:

• Before you begin: Prerequisites for the utility patch

• Create a utility patch job

The PatchJobOverallProgress element describes a high level overview of the progress of a .

For a more in-depth view on the progress of a PatchJob, refer to the PatchJobProgress element.

Element structure

A/B deployment is an update process whereby you deploy new versions of your game servers alongside your already existing game servers. First in small amounts, allowing you to test your new build first with a few clients, maybe a team of internal or external testers. You control the clients that will connect to the new versions via your matchmaker - you do not update all clients at the same time. Only when you are happy with the new game server version will you send all client-update instructions and will you let all other clients join with the new game servers.

This has the side effect that your game servers running the old version will automatically be abandoned once all your clients have updated. When that moment has been reached, you can delete the remaining game servers still running the old version.

We have a core part of the i3D platform which are ping beacons. The ping beacons examine User Datagram Protocol (UDP) traffic to measure latency with a multiplayer games' UDP transport. We operate these beacons in multiple regions so that your game operates optimally. Using a ping beacon will measure the time of sending a UDP message and when you receive a response. In short, the quicker the response received, the lower the latency you have for your games.

Why do multiplayer games use UDP versus other protocols?

User Datagram Protocol is used for multiplayer games since it allows for data transmission at a much faster rate than other protocols such as TCP.

The PatchJobApplicationBuild element describes an old ApplicationBuild ID and a new one to replace the old with.

This element is one of the properties that define the selection of ApplicationInstances to patch. Additionally it defines which new ApplicationBuild to deploy over the olde one.

The other PatchJob properties that create the selection of ApplicationInstances are:

• DeploymentEnvironment ID (PatchJob.deploymentEnvironmentId property)

• Application ID (PatchJob.applicationId

After sending a request packet, the server must always respond with a packet. If the server does not recognize the request, it can send a Not implemented packet in response so the system will detect that the server cannot handle the request and report back that there is an error and cannot perform the request.

When the server acknowledges the request, it must send the Acknowledged packet back. If the request has a specific response like a Server information response, don’t send the acknowledged packet back but only the response for that specific response.

This element represents an IP address directly allocated to a .

Element structure

This section of the documentation explains additional features of the ONE Game Hosting service.

Triggers

Task System

The DeploymentContainer element is a wrapper that holds the primary or secondary cloud (dc) locations to burst towards when your bare metal pool runs dry.

Figure 1: Highlighting where the DeploymentContainer elements belong in the overview

Usage

A cloud instance type defines the amount of hardware resources (e.g. CPU cores & memory) a VM will have available. Some examples of available instance types on different cloud providers:

• (AKA machine types)

Within our system you can use any instance type you want or need. You can even use specialized instance types if that suits your requirements. That said, under normal circumstances you would use regular compute instance types.

Application Management is the process of defining and maintaining the applications you want to deploy with the ONE Game Hosting service.

Application elements

An Application is defined by the following two elements:

Application definition elements:

• Application

For information on maintaining builds for your Application, please see the chapter.

Application & ApplicationProperty example

To be able to deploy an imaginary game called "Bluewolf", you first have to create an Application element, defining your application within the platform. It would be specified as follows:

Application

JSON request data :

The value 2 for managementProtocol stands for the management protocol.

Next, ApplicationProperty elements are added to the Application. This is necessary for Application configuration and to ensure the platform knows how to deploy related instances:

ApplicationProperty 1

JSON request data :

The value 1 for propertyType stands for "public network port". In this case we give it the name game_port and the default value of 0. Passing 0 instructs the platform to find a random free port each time an application instance is started.

ApplicationProperty 2

JSON request data :

The value 6 for propertyType stands for "private network port". Giving your Application a managementport property tells the platform that your game servers can be queried for information, or that commands can be issued. The latter depends on the value of the Application.management_protocol property you provided while creating the Application. Just like with the previous game_port property, the value 0 tells the platform to pick a random port on each application instance start.

ApplicationProperty 3

JSON request data :

This is a raw property. The platform does not use these internally for any kind of functionality and these properties are here only for your own reference, or to use as a static configuration parameter in your game server startup configurations.

We now have a complete Application element with definitions for:

• application type, Application.type = 1 (game)

• a managementProtocol, Application.managementProtocol = 2 (Arcus)

• a management private network port, ApplicationProperty "managementport" with default value 0 (random port)

This element details the CPU information of a Host.

Element structure

Table 1: HostCpu element structure

Hyperthreading

You can tell whether hyperthreading is enabled by looking at the cores and threads properties.

The cores property represents physical cores. The threads property represents logical cores.

Hyperthreading is enabled when threads is double the amount of cores.

Hyperthreading is disabled when threads is equal to the amount of cores.

Element relation

The Cpu element is part of the element and is not used stand-alone.

The following terms are used throughout the documentation pages and should be understood in order to fully comprehend the components and inner workings of the i3D.net Game Hosting service.

The DeploymentContainerLocation element defines a cloud (dc) location to burst towards when your bare metal pool runs dry.

Figure 1: Highlighting where the DeploymentContainerLocation elements belong in the overview.

Usage

Element structure

Table 1: DeploymentContainerLocation element structure

API example

DeploymentContainerLocation elements are not created separately, but are always inside the containers property, as children of the elements.

This element describes an IP address of an ApplicationInstance. Every ApplicationInstance element has one or more IP addresses. Virtual hosts have both private (internal) and public IP addresses, whereas bare metal hosts normally only have a public IP address, unless you have a custom networking setup.

Element structure

Table 1: ApplicationInstanceIP element structure

Public and private IP addresses

An ApplicationInstance will have at least one public IP address. An instance deployed onto a VM will additionally have at least one private IP address (). The reason for this is that a VM has no public IP address defined on the host level, but instead gets its public IP address via NAT. This means that the VM host itself only has knowledge of private IP addresses and not any public ones. The illustration below explains this further:

[](images/BM-&-VM-ip-address-assignment.png) Figure 1: BM & VM IP address assignment

Our platform has knowledge about all IP addresses involved with a bare metal server or VM. As such it can populate an element with all public and private IP addresses related to the host it's deployed on.

IP address binding

If you must bind a specific IP address to your application's socket(s), care must be taken during configuration of your 's properties.

When configuring an application, you can use in your application's startup parameters or configuration file(s). If you have a socket that must be bound to a specific IP address, note that you should use the platform variable VARIPV4BINDING or VARIPV6BINDING. These variables contain the correct IP addresses to use for socket binding, depending on whether your application is being deployed onto a bare metal (BM) server or a cloud VM. If it concerns a BM, a public IP address will be used. Otherwise, on a VM, its private IP address will be used, allowing your application to bind to the correct socket.

If you specifically need the public IP addresses of an ApplicationInstance during Application configuration, you can use the platform variable VARIPV4PUBLIC. See the chapter on for all available platform variables.

Version: v0.9.1 (Beta)

All v1.0 features are complete and ready for integration and use. Customer iteration will determine any final changes before labelling as v1.0.

The SDK provides games with the ability to communicate with the i3D.net ONE Platform, for easy scaling of game servers! In order to integrate Arcus into the Game Server itself, you will need to read the following guides:

• Build – How to build and test the repository.

• Integration Guide – How to integrate the Arcus API into a Game Server.

The i3D.net Game Hosting SDK works on Windows and Linux. If you need further assistance after reading the documentation, please .

Major Goals

1. C/C++ v11 library.

2. Easy-to-use C API interface for maximum language compatibility.

3. Source-only build allowing for "copy and drop-in" of files.

4. Supported platforms:

Not Included

The below are not provided or part of current goals. Please for change requests.

1. Testing on Linux distros other than Ubuntu 18.04.

Layout

The SDK is made up of code to be integrated into the Game plus additional components that aid in the testing, development and integration.

1. is the library that provides communication between the Game Server and the scaling environment in the One Platform. It is to be integrated into the Game Server. It contains a C/C++ implementation of the ONE platform's Arcus protocol and messages, and provides a TCP server to communicate with the ONE Platform.

2. is a library that provides a way to obtain server addresses of the ONE backend and utilities to ping the servers, for use in a game's player client code's matchmaking features.

3. contains samples that use the SDK components to aid in integration, development, and testing.

Engine Plugins

Unity

Unity engine support is implemented as a plugin which is available .

Unreal

Unreal engine support is implemented as a plugin which is available and also located in our documentation .

Data Types used in packet structures

Packet header

Continue reading:

The PatchJobFleet element describes a Fleet whose ApplicationInstances will be patched (in combination with other selectors).

This element is one of the PatchJob properties that define the selection of ApplicationInstances to patch.

The other PatchJob properties that create the selection of ApplicationInstances are:

• DeploymentEnvironment ID (PatchJob.deploymentEnvironmentId property)

• Application ID (PatchJob.applicationId property)

• One or more old ApplicationBuild IDs (PatchJob.applicationBuild property)

Element structure

Table 1: PatchJobFleet element structure

API example

This element is not created individually, but is included in, and created with the element.

The ONE Game Hosting platform has a patching mechanism that makes it easy for you to update builds for already running application instances. You can perform updates in different ways, using different patching methods. Each method has a different purpose and performs different actions. To learn more about each patching method, choose one of the following:

When creating a new Patch Job, you can choose one of these methods and make a selection of which application instances to update. You can run the Patch Job right away, or schedule it to run at a later time. Reporting emails will be sent to any email addresses you submit inside the Patch Job. Reporting will start as soon as the Patch Job begins giving you an overview of which instances will be affected. During the patching process itself we keep sending report emails to show you the patching progress. When all is done, a final report will be sent. More details about the different patching method and all the Patch Job settings can be found in this and the following chapters.

API v3 endpoint prefix

Throughout these documentation pages we will refer to API endpoints like this:

GET /deploymentEnvironment

This is not a complete endpoint. You must prefix this with the API uri and API version tag:

https://api.i3d.net/v3/

That results in the complete URL:

This chapter describes the process of deploying an .

Prerequisites

Before an ApplicationInstance can be deployed, you must first create a . This ensures you have a with s and s. Hosts (bare metal servers in your account or VMs) onto which ApplicationInstances are deployed will automatically become part of a region based on their geographical location.

Here is a schematic overview of the resulting structure:

Figure 1: Deployment (environment) structure with ApplicationInstances

With the HostCapacityTemplate element you can define how many game instances you want deployed on any specified BM instance types and / or VM instance types. The actual definitions of the instance types and capacities themselves are defined in the elements, which are assigned to this HostCapacityTemplate upon creation.

Element Structure

These chapters elaborate on the individual components used by the Platform.

Application Elements

The SDK contains multiple separate components providing specific functionality. This integration guide will provide information of how to integrate the Arcus and Ping components.

• Arcus Component: For communication between Game Server and the ONE Game Hosting Platform.

• Ping Component: For obtaining available servers and pings from the game's Player code.

This element represents a disk drive of a .

Element structure

Once you have defined your application and created your application build from the previous step, you can now create your templates. Follow the instructions below.

Game template overview

A Game template is used by a fleet and defines which game application builds will be deployed for that Fleet. You can create as many Game templates as you like on the platform. However, a Fleet can only point to one Game template at a time. A Game template can be shared across multiple fleets though.

If an uses configuration files (e.g. setup.cfg), then these can be submitted and assigned to an in the form of ApplicationBuildConfiguration elements. Each of these elements represent a configuration file. An ApplicationBuild can have zero or more ApplicationBuildConfiguration elements.

Element structure

This element represents a memory slot of a .

Element structure

This document introduces you to the three concepts of the deployment configuration hierarchy. Next, you will learn how to create your own environment, profile, and fleets in the dashboard.

• Deployment environment: The deployment environment is the top most element in the deployment configuration hierarchy. It is normally used to reflect a game title that you host on our platform, split up into development, testing, and production environments.

• Fleet: The Fleet is the second layer within the deployment configuration hierarchy, which represents a collection of hosts (Bare metal or Virtual machines). You can have as many Fleets under a deployment environment as you like. There are no limits.

• Deployment profile: The deployment profile is the main element that determines how your application instances will be deployed.

Create your deployment environment

It's recommended to create an environment per title. Additionally, it's advised to separate your live environment from any development environments. When you separate the environments, changes and experiments done for development purposes in a development environment won't affect your live environment. Within a game deployment environment, you can create multiple Fleets in case you want to separate for different platforms such as PC, PS4, Xbox, Switch, and more.

1. Go to Game Hosting > Deployments.

2. Click Create enivronment.

3. Enter your Environment Name.

4. Click Create.

Create your deployment profile name

A deployment profile is always the only child of a fleet. You can only have one deployment profile per fleet.

1. Go to Game Hosting > Deployments.

2. Select the Profiles tab.

3. Click Create Profile.

4. Enter the Name of your profile.

Create your deployment profile settings

1. After you have created your deployment profile name, click the cog icon to the right of the profile name to set your Profile settings.

2. On the Profile page, the default Global Strategy setting is Round Robin. For more information about the Round robin strategy, see .

3. To define the amount of instances you want to deploy in a specific region, enter your Miniumum amount of instances and Maximum amount of instances in the Global Capacity section.

1. Next you will need to create your region. Follow the steps below.

Create your deployment region

This defines a geographical region that contains one or more i3D.net data center (dc) locations.

1. On the Profile settings page, click Create region.

2. On the Create Region pop up window, select at least one i3D.net location and click Next.

3. Enter the Region Name and click Create.

4. Follow the steps below to Add Bare Metal locations and cloud groups

Add Bare Metal locations

1. Click the cog wheel icon next to the deployment region you just created. This will bring you to the region settings page.

2. To add location to a Bare Metal Group, Click Add location.

3. On the Add Bare Metal Location window, select your location.

4. Click Save.

Add cloud groups

A cloud group is a wrapper that holds multiple cloud locations to burst towards when your bare metal pool runs dry.

1. Click Add cloud location.

2. On the Add Cloud Location window, select your Cloud provider from the drop down list.

3. Select your Location from the drop down list.

4. Select your Primary instance from the drop down list.

Create your fleets

Fleets are normally used to differentiate between different builds or platforms such as PC, Xbox, Playstation, Switch, and more. But you can use fleets to deploy instances for temporary or testing purposes while keeping these separate from other fleets. Be aware that you cannot deploy multiple fleets on one host at a time.

1. Go to Game Hosting > Deployments.

2. Select the Fleets tab.

3. Select your Deployment Environment that you want to add the fleet to from the drop down list.

4. Click Create fleet.

Enable your deployment

After you have set your Minimum Capacity on your Deployment profile to anything higher than 0, then you can see the instance being deployed and online on the Instance Management page.

Related topics

This chapter explains the logic behind our automatic scaling process.

For more information on how to enable the automatic scaling mode for a Fleet, please see the Automatic Deployment chapter.

For more information on how the deployment process works, please refer to the Deployment Process chapter.

The reasons for having a scaling mechanism

Before explaining how the scaling mechanism (the Scaler) works, let's take a minute to understand why a dynamic deployment system is important.

You will never run out of available game servers

If your game is higly successful, you can experience a sudden influx of players. Your basic game server capacity deployed onto your own bare metal servers may not be sufficient in that case. You could order more bare metal servers to increase capacity, but by the time we have delivered them to you, it may be too late to cater for the ingress of new players. This is where cloud scaling comes into play. To fill this gap in game server resources, we have created a dynamic game server deployment system that can scale onto any cloud platform. This has the result that you will never have a shortage of game servers. Even if a cloud provider is down entirely, there will still be other cloud providers that we can deploy game servers onto. We can pretty much guarantee game server availability this way.

Cost savings

Even though you could host your entire game in the cloud, we strongly advise using our bare metal servers as much as possible, or at least for your base requirements. Our bare metal servers simply perform better than cloud VMs. But not only that, renting a bare metal server for a month (or longer) is much cheaper than renting a similary sized VM for a month.

How the Scaler works (overview)

The Scaler combines the major elements described in this documentation in order to deploy game servers when and where they they are needed. The Scaler needs to know which application (builds) it needs to deploy ( & ) and where to deploy them (). Together with live game server status information ( / ) the Scaler knows the amount of occupied and free game servers and can then determine whether there are too few or too many free game servers and deploy or remove game servers as needed.

This in a nutshell is how the scaler operates.

Deployment occurs per-region, per-location, per-ApplicationBuild

The scaling mechanism always operates on a combination of DeploymentRegion + DC location + ApplicationBuild. You can view each of these combinations as stand alone environments on which the scaling mechanism operates.

Figure 1: Combinations of region + location + build the Scaler operates on

This means that the Scaler will iterate over all the regions in your DeploymentProfile, then within each region it iterates over all DC locations and then per location it iterates over all the s defined in the of your . Then for each ApplicationBuild it will do its checks to see whether the amount of ApplicationInstances is too low, too high or just right.

To summarize, the scaling mechanism always operates on individual combinations of region + DC location + ApplicationBuild. Deployment of game servers first occurs on bare metal servers and when they are full, the Scaler continues to deploy onto any configured cloud locations.

Host selection (round robin strategy)

When the scaling mechanism needs to deploy a new , it will first look for a usable bare metal host (BM). If you have run out of BM hosts, the Scaler will continue with cloud VMs, provided you have configured cloud locations in your .

A selected BM or VM host will be fully filled with instances before the mechanism will find the next free host. The number of instances that can be deployed onto a host is defined individually for each BM or VM instance type and is explained in the chapter "".

Differences with host selection between using items in a containerLocation versus multiple containerLocations

When you define multiple items within a containerLocation they will be treated in a round-robin fashion. When you have multiple containerLocations they will be processed sequentially.

Here is a simple example:

• If you have a primary on Google Cloud and Azure, then the Scaler ensures that both are running an equal amount of Game Servers, which will always make sure that first a cloud is filled up completely.

If you have 8 core machines on Google Cloud and 4 core machines on Azure, and you request 16 Game Servers, then you will have the following combination:

• 1 Google Cloud and 2 Azure VMs: (8 + 4 + 4 = 16 Game Servers).

Example when using multiple containers

When you use multiple containers, the process works differently.

• Container A is set up the same: You have 2 Azure and 1 Google Cloud VMs

When Google Cloud doesn't have anymore capacity, then the following process occurs:

1. The machine will switch over to Azure.

2. Also, the secondary machine needs to be out of quota.

When you have a primary and secondary with Google and Azure, then the switch over will occur if you cannot spin up any more VMs within the primary. If you request for 16 games instances and Azure is out, then you get 2 Google instances.

If Google and Azure doesn't have anymore capacity, then the following process occurs:

1. It will switch over to the secondary container.

2. Within the secondary container (for example, if it contains Amazon and Tencent inside) then a round robin is performed again for those 2 containers until the primary has capacity again.

Initializing an empty host

When a new, empty host (BM or VM) has been selected for game server deployment, the scaling mechanism will first deploy all the utilities (sidecars) defined in your . After that, the new game server(s) are deployed.

Removing instances (downscaling)

If at any moment in time too many application instances are deployed, the scaling mechanism will start removing unused instances until the number of free / unallocated instances equals the again.

If you have application instances deployed onto VMs, we will remove those first. Only empty instances are removed, of course. If no VMs are in use, or if there are no VMs with free / unallocated instances, the Scaler will continue downscaling instances on bare metal hosts.

The host with the least amount of application instances (or secondary, with the most free instances) will be selected as the host to start removing instances from. This attempts to help with freeing up VMs so we can destroy them, reducing cloud hosting cost as much as possible.

Keep in mind though that we do not control (gaming) clients already playing on a game server deployed onto a VM. That means that if your game server hosts matches that do not necessarily end, or take a long time, a VM cannot be destroyed until all those players have left the game server. If your game falls into that category you may want to invest in a mechanism that can transfer players to another game server, in an attempt to reduce cloud hosting costs.

Cleaning up a host when it's empty

After the last game server instance has been removed from a host, any side cars (utilities) will also be removed. If the host concerns a VM, the VM will be destroyed. A bare metal host will become usable again for deployments (for the same or another environment / fleet / any other purpose).

The DcLocation element represents a data center in a certain location. This can be an i3D.net data center or one of a cloud provider. The latter parties often refer to this as a region, but really these are simply data centers with a varying degree of redundancy in the form of availability zones.

Usage

The DcLocation element is used throughout your DeploymentProfile, or more specifically DeploymentRegions and DeploymentContainerLocations, where you can specify in which data center you want to deploy your applications.

Element structure

Table 1: DcLocation element structure

Examples

Below you will find some example DcLocation elements along with explanations.

HTTP request

Response body

The first entry with ID 6 represents an i3D.net data center (providerId = 1). It is located in Europe (continentId = 5), in Rotterdam, the Netherlands. It has no availability zones and no region name. These are only populated for cloud locations. This is an i3D.net data center.

The second entry with ID 29 represents an AWS data center (providerId = 27). It is located in Europe (continentId = 5), in Frankfurt, Germany. It has 3 availability zones and its region name is the official AWS region "eu-central-1".

The third entry with ID 64 represents a GCP data center (providerId = 31). It is located in North America (continentId = 7), in Montreal, Canada. It has 3 availability zones and its region name is the official GCP region "northamerica-northeast1".

Availability zones

You cannot configure / specify availability zones in your . The platform will create VMs in a round-robin fashion to spread your VMs over all available availability zones automatically.

Labels are pre-defined or custom key / value pairs that can be tied to elements for easy recognition and selection.

The following elements in the platform can have labels:

• ApplicationBuild

• ApplicationInstance

• Host

Structure

Table 1: Label element structure

Requirements

A Label element has the following constraints:

• allowed characters in the label key are a-z 0-9 _ -

• the label key may be no longer than 50 characters

• the label value may be no longer than 150 characters

Adding & updating labels

Labels in the ApplicationBuild and ApplicationInstance elements are stored as an array of Label elements:

PUT /applicationInstance/{applicationInstanceId}

Figure 1: Example labels for an ApplicationInstance element

When you want to add a new label, you can PUT an element with only that new label. You would submit:

PUT /applicationInstance/{applicationInstanceId}

Figure 2: Example of adding a new label to an ApplicationInstance element

The result will be that the element has 3 labels: label1, label2 and label3.

When you want to update a label, you only have to submit that one label for the element:

PUT /applicationInstance/{applicationInstanceId}

Figure 3: Example of updating an existing label of an ApplicationInstance element

Deleting a label is done by submitting a label with a null value:

PUT /applicationInstance/{applicationInstanceId}

Figure 4: Example of deleting a label from an ApplicationInstance element

After these example mutations, the element ends up with the following labels:

GET /applicationInstance/{applicationInstanceId}

Figure 5: The resulting labels for an ApplicationInstance element after applying the examples

Pre-defined labels

For ApplicationInstance elements, the platform creates a number of default labels (platform defined labels):

• application_id

• fleet_id

• host_id

• dc_location_id

These labels are always present for all ApplicationInstance elements. It does mean that user-defined labels cannot have the same name as platform defined labels. These names are reserved.

Using labels

Labels can be used to trim selections of elements.

In the API v3, using labels is done by adding a label expression as an URL query parameter.

An example of a label expression:

When used in an API v3 request the expression must be url encoded:

If you filter on region_name (or any other label with a string value) you must wrap the search value in double quotes:

The url encoded request:

The purpose of the i3D.net ONE Game Hosting platform is to deploy your applications. Providing your builds to the platform therefore is a crucial process. On this page we will explain how you can upload your builds.

Origin node request / registration

An origin node is simply a server to which you can upload your build archives and from where our platform can download builds. A build archive file will be downloaded, cached and distributed by the i3D.net CDN as soon as the first deployment of your application takes place.

The i3D.net CDN (Content Delivery Network) will download your build from an origin node, using HTTP(S). That means that an origin node must run a web server. Files are often secured by firewalls allowing only certain IP addresses, or by means of HTTP headers to add an additional layer of security. We prefer JWT tokens, but any kind of header aimed at security will work, e.g. an Authorization header.

Custom CDN Domain Name

Origin nodes must be registered in our system so our CDN knows where to grab your archives. And because files are distributed by our CDN, you will also be given a XXXXX.cdn.i3d.net sub-domain. While requesting or registering your origin node you can indicate the desired sub-domain prefix.

i3D.net provided origin node

You can request an origin node provided by i3D.net. At the time of writing, you must request this through a ticket and you must be a game hosting client.

When requesting an i3D.net provided origin node, you must provide us with the following details:

• a custom name for your origin node

• desired CDN domain (XXXXX.cdn.i3d.net where you can choose XXXXX)

  • only a-z characters allowed, max length: 16 characters

  • if it's no longer available we will ask for a new suggestion

Once setup, we send you the login details, after which you can upload your first build to the origin node using the SCP or Rsync-over-SSH protocol.

You can find your registered origin node in our API by performing a request on . You will need these details when creating an ApplicationBuild.

Structure of your build archive

For the best deployment predictability of your application, please ensure that your build archive's root contents is the root of your application's folder. By that we mean, ensure you do not have only a folder in the root of the archive that contains all the files. The root of your archive must be the root of your application's folder structure.

Wrong structure

This faulty example has the game server's root folder inside the archive.

Figure 1: Wrong archive folder structure

Correct structure

This correct example has the game server's files immediately in the archive root. You are permitted to create a folder and place your packed game server there.

Figure 2: Correct archive folder structure

Upload your build archive

Using the credentials provided by us, log in on the origin node and upload your file. Be sure to only use zip or rar files.

List files on your origin

Once your file is uploaded, it will be available in the following list with a very small delay (seconds).

API Documentation:

Create ApplicationBuild element

With your file uploaded to our platform, you can point to it in your ApplicationBuild element. This process is described in the next chapter:

Build distribution via CDN

Distribution of your build archives towards your gaming hosts is done via the i3D.net CDN (Content Delivery Network). The CDN is comprised of servers in many regions. Each region will individually download the build archive from your build origin and cache it. The default cache time-to-live is 7 days for any file served by the CDN. This TTL is not reset, so after 7 days the file will always be purged. If the file is downloaded again through the CDN, the file will be pulled from your origin again.

It is therefore very important you do not remove build archives from your build origin until you really do not need it anymore.

Changing a file in the CDN : Guidelines to follow

When you change or upload a new file in the CDN the following steps will occur:

1. The old file with the same name in the CDN is deleted.

2. A new file entry is automatically created for you with a new ID.

Next steps after you create a new file ID:

1. You must create a new application build with the newly created file ID.

2. Link your newly created file ID to your fleet so that you can use it.

Related topics

Many game servers have an initialization process to go through when starting up. This has the effect that the game server will not actually be usable during this initialization period. Our platform should know about this, otherwise it will assume the game server is ready to accept clients immediately after starting. For this to be possible, your game server can let our back end know when it is ready to accept players. We refer to this as a "game server run-status update" and can be performed by having the game server make an API call either towards our public API, or locally on the host towards our Host Agent.

You do not have to worry about this if your game server start (nearly) instantly. We will by default set a game server's run-status to "RUNNING" after starting it.

Please refer to the ApplicationInstance status chapter for more information about all possible status values.

Public API example

The following example illustrates how to change the run-status of a game server via the public API.

HTTP request

Request body

<NOT NEEDED>

Response body

Local Host Agent API example

TBD

A management protocol is a means for a game server to be queried or controlled by an external source. In this case the external source is i3D.net's ONE Game Hosting service.

Management protocols are used for different purposes. They can allow for an external program to query a game server for live game related information (status queries returning the number of players, the current map, rules, etc), or sending commands for e.g. a graceful (soft) stop. Some management protocols go further than that and allow full administrative functionality for a game server (kick players, send messages to clients, reconfigure map & rules, etc.), but that goes beyond the scope of this article.

There are different management protocols. Examples of these are A2S, RCON, U3E. Most protocols have the same kind of functionality, but their implementations can differ. So in order for our system to communicate with your game servers, you have to indicate which management protocol they support. You can indicate this in the Application element(s) you create for your game server application(s).

Application management properties

In order for your game to use a management protocol within our platform, you have to tell it on which network port your management protocol is listening, enabling our Host Agent to connect with it. You do that by adding an to your Application, with:

• a propertyType of 6 (private network port)

• a propertyKey called "managementPort"

• a propertyValue between 30000 and 49151

If your management protocol / implementation also requires a password (e.g. an admin password) then you must also add the following ApplicationProperty:

• a propertyType of 2, 3 or 4 (password8, password16, password24)

• a propertyKey called "managementPassword"

• a propertyValue empty if you want our system to generate unique passwords for each ApplicationInstance, or fill in a password for this value to pre-define one

Supported management protocols

When you create an in our system, you must provide a value for the managementProtocol property. The following table lists the supported protocols and their IDs:

Table 1: Supported management protocols and IDs

Supported features per management protocol

1: A2S

• game server information (server query)

2: Arcus

• game server information (server query)

• soft-stop method 1 (Arcus msg)

• metadata (pushing metadata to the game server, to update its configuration)

• isAllocated (ask game server for allocation status)

Requesting support for your management protocol

If you have a protocol that we currently do not support, or maybe you have one that we support but you've customized it, then please to discuss how we can support your version of the management protocol and how we have to implement it.

Application Build Management is the process of creating and maintaining builds for your . An ApplicationBuild defines the software that will be deployed by our system. It can be a game server or a utility (side car). Whenever you have a software update, you must upload the new build to our system and create an ApplicationBuild for it before it can be deployed.

Prerequisites

Before you can create an element, you must first create:

An Application is an component that describes a program that the system can deploy. As such, every program you want to deploy must be defined by an Application component. You can specify the application type, whether it has a (only applies to application type Game), give it a name, a website, description, etc.

Application types

An Application can be one of four types:

• a game server (type: Game)

Prebuilt binaries are currently not supplied. The integration code is very lightweight. Integrations have two options:

1. Copy the code in one/arcus directly into the game engine and build directly as part of the regular build.

2. Or build the repository with the following instructions, and then copy required headers and binaries. Binaries will be output into the build folder; for example, the build/one/arcus/release/one_arcus.lib.

It's recommended to build the repository as it will also create a fake agent executable to aid testing of your game server without deploying to the remote ONE Platform.

The ONE Game Hosting service has a feature called Platform Variables, which can be used for configuration of your applications. Platform variables come in two types:

• variables pre-defined by the platform

• user defined variables

These variables can be used inside the startupParameters property of an and inside configuration files ( elements), submitted for an ApplicationBuild. Examples are provided near the end of this page.

As you may know, multiplayer online gaming has been rapidly growing over the past few years. Many studios are researching game hosting solutions (early during development) that can help their games to be as efficient as possible when it's released. A smooth release of a multiplayer game with an efficient game hosting solution can help with its success. i3D.net understands the importance of that. To help burgeoning game studios in that endeavor, i3D.net offers a new product: The Game Server Orchestrator.

In a nutshell, the Game Server Orchestrator is a fully customizable game hosting solution that offers scalability solutions (scaling up / down game servers based on demand), health checks, monitoring, and more.

Specifically, the Game Server Orchestrator operates by connecting to the database that contains the application instance entries and our designated message broker. It first retrieves the current state of the application instances from the database, checking if they are in the correct state. Based on this information, the Orchestrator sends messages through the message broker to communicate with the VM Manager, instructing it to create or destroy virtual machines as necessary. This coordination allows the Orchestrator to manage the provisioning and scaling of game server instances dynamically, ensuring optimal performance, and resource utilization in the game environment.

Metadata elements are custom, client provided key / value pairs that can be forwarded to application instances (e.g. a game server). The main purpose of this is for a Matchmaker to provide game server configuration values to be sent to a game server upon allocation of said game server.

In our system, Metadata elements are part of elements.

See the chapter about the for more information.

Structure

“A globally scalable game server hosting platform that aims to never run out of game server capacity”

Introduction

The i3D.net ONE Game Hosting service has been created to provide game publishers with a globally scalable and high performance game server hosting platform that aims to never run out of game server capacity.

Game servers will be deployed dynamically in the locations where you need them. Similarly they will be removed if not needed anymore due to overcapacity, while not dropping below the minimum number of deployed game servers defined by you.

Updating your game servers with a rolling update means that you update game servers as soon as they exit naturally or when they are empty and unallocated.

Initial situation sketch

We have a fleet with 1 ApplicationBuild in its deployment template. 100 game servers have been deployed.

This chapter assumes you already have created a new for your updated software.

It is possible to receive events from within our platform, allowing you to get more insight into which actions it performing. You could log these for your own purposes.

At the time of writing this is an experimental feature that we are testing with a few clients. There is no publicly available endpoint that allows to you automatically sign up to our event stream. But you can request access to it via the usual support channels.

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

The DependencyDeploymentTemplate enables you to point to scripts (ApplicationBuilds) that install dependencies onto a Host that are required by your Application(s) to run properly. Besides an installer script, you must also define an un-installer script to remove the dependencies and to allow clean up of a Host after removing all applications running on it.

Usage

A DependencyDeploymentTemplate is used by a and defines which ApplicationBuilds (of type DependencyInstaller / DependencyUninstaller) will be deployed for that Fleet. A single DependencyDeploymentTemplate defines both the DependencyInstaller and DependencyUninstaller ApplicationBuild elements. Both are required as we need enforce cleanup of a Host in order to keep it clean and usable by you for other purposes without having to do frequent re-installs of the operating system.

The DependencyInstaller ApplicationBuild will be installed and executed before the platform deploys any other Application onto a Host.

Version: v0.9 (Beta)

All v1.0 features are complete and ready for integration and use. Customer iteration will determine any final changes before labelling as v1.0.

The current version of i3D.net ONE Game Hosting SDK code used in this plugin is referenced .

Overview

The plugin provides Unreal Engine game servers with the ability to communicate over TCP with the i3D.net ONE Platform, for easy and efficient scaling of game servers.

Arcus currently supports the following configuration options for its protocol:

IP Address Binding

Your Arcus server port must be bound to localhost (127.0.0.1). This prevents any security issues that could otherwise arise when binding to a public IP address on a host.