Allocation lifecycle
The allocation lifecycle relates to but is distinct from the server lifecycle. The allocation lifecycle starts with a request to the Game Server Hosting API for an allocation. The Game Server Hosting uses the build configuration and build from the allocation request to select the best available server slot. The selected server slot might or might not have the correct build executable already running. When a server slot is allocated, the resources of the server slot are effectively protected during the allocation lifespan. This means actions like descaling and system maintenance can’t occur while the server slot is allocated.
There are three lifecycle stages involved in the allocation lifecycle:
Available
Before the allocation lifecycle begins, the state of a server slot is called available. The available state isn't part of the allocation lifecycles, but it's worth mentioning because it's the default state of the server slot Available server slots contain a combination of stopped and started build executables.
Allocate
The allocation lifecycle begins when you send an allocation request to allocate a server slot for a game session. Game Server Hosting uses the information from the allocation request (namely, the build, build configuration, and location) to find the best server slot in which to run the build executable. Game Server Hosting then allocates the server slot and, if it’s not already running, starts the correct build (with the correct build configuration).
After the server slot becomes allocated, Game Server Hosting updates the server.json file with the allocation information and ensures the SDK has the latest information about the allocation.
Deallocate
The allocation lifecycle ends with a deallocation. This can occur in several ways:
- You send a deallocation request using the API.
- You trigger a deallocation by having the build executable exit with code 0.
- The game server remains idle for longer than the allocation time to live (TTL).
The recommended best practice for most games is to trigger a deallocation by having the build executable exit.
It’s also valid to deallocate server slots using the deallocate API endpoint. This is a common pattern if your game is using a matchmaker (such as the Unity Matchmaker). In this case, you have the build executable call back to the matchmaker to let it know the game session has finished. The matchmaker then calls the deallocate endpoint to deallocate the server slot. After deallocation, Game Server Hosting clears the allocation ID in the server.json file and updates the SDK. The build executable detects the cleared allocation ID using the SDK or, less preferably, by watching the server.json file.