Application Instance Allocation Overview
If you use a game with a matchmaker in its backend, it will want to figure out which game server to send players who are waiting to start a new match. Your matchmaker can request an unused game server with an API allocation call. This process is an application instance allocation which is the key to helping to host multiplayer games. I3d.net's service allows for a seamless experience when using an allocation request.
What are the endpoint details?
Here is an example with an API allocation call using the ApplicationInstance element:
"/v3/applicationInstance/game/{applicationId}/empty/allocateWithErrors?filters=regionId=1 and fleetId=456".
- applicationId is the ID of the application.
- Using allocateWithErrors will allow you (if the call comes back where you cannot allocate) to help you with error handling.
- Using the regionId and fleetId filters will ensure that you are directed to the correct servers.
What are the prerequisites to enable a new allocation flow?
You must create a firewall rule to allow traffic into the following port:
| Port | Protocol | Description |
|---|---|---|
| 6824 | TCP | ODP uses HTTP to call into the Host Agent v2 to determine the current status of the application instance. |
How does the application instance allocation connection work?
Here is a visual example:
On the visual above, you see that when you send an application instance allocation, that our platform will always prioritize allocations on Bare Metal before allocating game servers on a Virtual Machine (VM), unless you perform an allocation request with an explicit filter to allocate a games server on a VM.
How to perform an application instance allocation
- Request an unused game server using an API allocation call. (Example with filters used: "/v3/applicationInstance/game/{applicationId}/empty/allocateWithErrors?filters=regionId=1 and fleetId=456") For more information, see the ApplicationInstance reference documentation.
- The server will find Bare Metal (BM) application instances to use. The server will check for application instances with Status 4.
- If there are no BM application instances to use, then the server will select a VM application instance. If there are no application instances available, you will receive a return error message stating the same. See the next section for more information about error messages and how to handle them.
- Once an application instance is found, the server converts the Status from 4 (Online) to 6 (Allocating).
- The hostagent API is called for allocation. Then the hostagent API responds back with a Status from 6 (Allocating) to 5 (Allocated).
- Lastly, the customer/match maker receives a response back with the correct application instance.
Filtering on the following parameters is currently not supported:
| autoRestart | liveGameVersion | liveHostName | liveMap | liveRules |
| manuallyDeployed | markedForDeletion | numPlayers | numPlayersMax | properties |
| ipAddress | labelReadOnly | labelPublic | metadata | pid |
| pidChangedAt | startedAt | status | stoppedAt | updatedAt |
What are the allocation status codes?
For your reference, here is a listing of the Status codes and descriptions:
| Status code | Status name | Description |
|---|---|---|
| 0 | inactive | The instance is no longer in use |
| 1 | setup | The instance is being setup / deployed for the first time |
| 2 | offline | The instance is deployed but not running |
| 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 |
| 6 | allocating | The instance is in the stage of being allocated by a matchmaker |
Using matchmaking with metadata
Our platform also has a mechanism in place that allows your backend to send custom data (metadata) to game servers in the form of key / value pairs. This mechanism has primarily been created to reconfigure game servers during allocation, based on what kind of map it should run. However, you can use metadata in any way you see fit.
Your matchmaker can collect game clients and then allocate (request and reserve) a game server by doing an allocation call towards the i3D.net API. During the allocation call, the matchmaker sends metadata along which will be stored for the allocated game servers. This same metadata can then be forwarded to the same game servers, which in turn can react to the metadata. For example, it can load another map or change the game mode.
What are the requirements for metadata usage?
In order for the platform to send metadata to your game servers, you must implement the Arcus protocol. This is currently the only game server management protocol that has a mechanism for receiving metadata.
If your game already supports a way to receive custom information similar to the metadata described here, and you would like our platform to be compatible with that, please contact us and we may be able to support your management protocol.
Host Agent error reference list
| Code | Message | Description | HTTP status code |
|---|---|---|---|
| 76000 | Internal error in host agent | The host agent returned an unexpected response. | Internal Server Error (500) |
| 76001 | Unauthenticated | The provided token is invalid. | Unauthorized (403) |
| 76002 | Internal Server error | The host agent encountered an unspecified internal server error. | Unprocessable Entity (422) |
| 76003 | The application instance does not exist on the host | The found application instance (=session) was removed from the host and thus cannot be allocated. | Not Found (404) |
| 76004 | The application instance is invalid and cannot be allocated on the host | The application instance is found but not in an allocatable state. | Not Found (404) |
| 76005 | The application instance is currently being allocated on the host | The application instance is already in the process of being allocated - cannot allocate it again. | Unprocessable Entity (422) |
| 76006 | The application instance is already allocated on the host | The application instance is already allocated - cannot allocate it again. | Unprocessable Entity (422) |
| 76007 | Failed to allocate the application instance on the host is aborted or timed out | The allocation process on the host agent has timed out (5 seconds) or was aborted for another reason. | Unprocessable Entity (422) |
| 76007 | Failed to allocate the application instance on the host is aborted or timed out | The host agent was not reachable or did not respond to a request in a timely fashion. | Gateway Timeout (504) |
Error message reference list
400: deploymentEnvironmentId An invalid filter column is provided.
403: Invalid credentials.
404: Invalid applicationId, or if any of the following filters contain a value that cannot be resolved to their respective entity (labels and nested objects not supported):
- 1: deploymentEnvironmentId
- 2: deploymentEnvironmentName
- 3: fleetId
- 4: fleetName
- 5: regionId
- 6: regionName
- 7: dcLocationId
- 8: deLocationName
If no application instances can be allocated and if your application is configured to use the Arcus protocol, and there is a connection problem with Arcus or Arcus is not implemented properly in your application build, a separate error may be thrown. Alternatively, if your filters contain one (or more) of the following properties but they filter out application instances that would be available for allocation, a 404 error can be thrown detailing which filter caused no application instances to be found:
- 1: deploymentEnvironmentId
- 2: fleetId
- 3: regionId
- 4: dcLocationId
500: Internal service error For more information about this error see the Deployment-Platorm Endpoints documentation.
Game server deallocation
When the match of a game server is over, the operational status of said game server needs to be updated to indicate it is free again for other clients to join. It can then be allocated again by your matchmaker for other clients to join and start a match. For this to be possible, the status of the game server needs to be changed from Allocated (5) to Online (4).
This can be achieved in several ways:
- Your game server can make an API call to set its own status back to
Online (4) - Your matchmaker, when aware of game match progression, can make an API call and set the status of a game server back to
Online (4) - Your game server can shut itself down after a match. Our platform will automatically restart it with the result that the game server's status will automatically be set to a correct value again