Game server lifecycle

Note: The content on this page pertains to Game Server Hosting (Multiplay) available on the Unity Cloud Dashboard. If you’re using Game Server Hosting (Clanforge), refer to the Game Server Hosting (Clanforge) documentation.

The server lifecycle is the lifecycle of the build executable as a process running on a machine with protected resources. It has three distinct stages:

  1. Create
  2. Start
  3. Stop

The beginning and end of the server lifecycle varies depending on the requirements of your game. It might start well before or immediately before the allocation lifecycle, and it can end after each allocation or continue for many allocations.

Create

The first stage of the server lifecycle involves creating a server slot on a machine. The server slot is akin to a placeholder of resources for a build executable to run in. When Game Server Hosting provisions and starts a machine, it creates a number of server slots based on the server density calculation. The server density calculation finds the number of server slots that can fit on a machine based on the machine’s available resources and the fleet’s usage settings.

Start

The second stage of the server lifecycle involves using information (such as the build and configuration options) to start the build executable (or Docker image) as a process in the server slot created during the first stage.

When the server starts depends on the requirements of your game. It usually starts in response to an allocation request or when Game Server Hosting provisions a machine (depending on whether you have the start on provision setting enabled for the fleet).

Other situations in which a server starts include:

  • You created an allocation, and Game Server Hosting selected a server slot that isn’t running the correct build executable. In this case, Game Server Hosting restarts the build executable with the correct build.
  • You created an allocation, and Game Server Hosting selects a server slot that’s using the wrong build configuration. In this case, Game Server Hosting restarts the build executable with the correct build configuration.
  • You manually start a server with the API or through the Unity Cloud Dashboard.
  • The build executable process crashed. In this case, Game Server Hosting detects the crash and automatically restarts the build executable.
  • When a machine completes the provisioning process, and the start on provision setting is enabled.
  • You have the start on provision setting enabled and the build executable process intentionally exited. In this case, Game Server Hosting automatically restarts the server.

Note: Using allocation payloads might also change server start behavior.

Stop

The third stage of the server lifecycle involves stopping the server build executable process. This can occur in several ways, each triggering different responses from Game Server Hosting. Both internal and external scenarios can cause a game server to stop and sometimes more than one scenario is involved (such as an exit and a crash).

Internal stops

Internal scenarios are events that originate from the game server itself (the process of the build executable). These scenarios include:

The following diagram illustrates the server lifecycle when an internal scenario triggers a server stop.

Internal stops

Intentional exits

An exit refers to an intentional termination of a build executable process with an exit code of 0. When Game Server Hosting detects that a build executable exits intentionally, it automatically deallocates the server slot, clearing the allocation ID in the server.json file and readying the server slot for the next allocation.

The recommended best practice for most games is to use a matchmaker flow where the build executable process exits after each session. Exiting in this way triggers an automatic deallocation.

Crashes

A crash refers to an unintentional termination of a build executable process with any exit code other than 0 (opposed to an intentional exit). When Game Server Hosting detects that a build executable crashed, it attempts to recover the server by restarting it with the same allocation ID. However, if the server continues to crash, Game Server Hosting won’t keep restarting it. Refer to Crash backoff.

External stops

External scenarios are events that originate from an API call or an automated Game Server Hosting action, either due to a configuration or a response to the game server’s behavior. These scenarios include:

The following diagram illustrates the server lifecycle when an external scenario triggers a server stop.

External stops

Game server misbehavior

Misbehavior means something unexpected (other than a crash) happened with the build executable process. Usually, this means the build executable process is using more resources than the server slot allows or isn’t responding to queries for an extended period of time.

Note: Game Server Hosting only checks if game servers respond to queries if you implement a query protocol in the build and specify it in the build configuration.

Note: If the intention is to manually Stop a currently Allocated server this will not work, instead you should send a Deallocation request.

Build configuration ID change

Game Server Hosting restarts (stops, then starts) a build executable process if you create an allocation, and Game Server Hosting selects a server slot that’s using the wrong build configuration (a build configuration other than the one specified in the allocation request). In this case, Game Server Hosting restarts the build executable with the correct build configuration. Changes to values in a build configuration currently in use by a server may not be reflected immediately. It is recommended that you follow the zero downtime releases model to update your build configurations.

Server lifecycle variations

Although there are commonalities between them, not all game servers follow the same lifecycle. The exact behavior depends on how you manage your game sessions. The two most common methods are:

  • Multi-session allocations: Keep a game server continuously allocated and reuse the same allocation for multiple game sessions.
  • Single-session allocations: Deallocate a game server each time a game session ends, then start the next game session with a new allocation.

Multi-session allocations

Multi-session allocations is a game session management pattern where you reuse the same allocation for multiple game sessions. In this pattern, you keep game servers allocated between game sessions. Instead of exiting the game server executable between game sessions, you use another form of clean-up, such as resetting the game server state or exiting to a lobby.

Note: The recommended best practice for multi-session allocations is to enable the start on provision setting. This means game servers are ready for allocations when the machine provisioning completes.

The lifecycle of a game server with multi-session allocations uses the following process:

  1. Provision machine: Game Server Hosting provisions the machine.
  2. Start server: The game server starts immediately because the start on provision setting is enabled.
  3. Allocate server: You allocate the game server.
  4. Game session starts: The game session (or match) begins.
  5. Game session ends: The game session (or match) ends.
  6. Game session clean up: The build executable continues to run, possibly performing clean-up logic, such as resetting the game server state or exiting to a lobby.
  7. Game session starts: The game session (or match) begins.
  8. Game session ends: The game session (or match) ends.
  9. Deallocate server: You deallocate the game server.
  10. Server becomes idle: The game server becomes idle because it’s not allocated.
  11. Stop machine: Game Server Hosting stops the machine when all the game servers on the machine have been idle for longer than the time to live.

Multi-session allocations

Single-session allocations

Single-session allocations is a game session management pattern with a one-to-one relationship between game sessions and allocations. In this pattern, you have your build executable exit and deallocate the game server each time a game session ends. Then, you create a new allocation for the next game session.

Note: The recommended best practice for single-session allocations is to disable the start on provision setting. This means game servers don’t start until you allocate them.

The lifecycle of a game server with single-session allocations uses the following process:

  1. Provision machine: Game Server Hosting provisions the machine.
  2. Server is idle: The game server is idle because it’s not allocated.
  3. Allocate server: You allocate the game server.
  4. Start server: The game server starts when it’s allocated.
  5. Game session starts: The game session (or match) begins.
  6. Game session ends: The game session (or match) ends.
  7. Exit build executable: The build executable automatically exits with a code 0 when it detects that the game session has been completed and all players have disconnected.
  8. Deallocate server: Game Server Hosting automatically deallocates the game server when it detects that the build executables exits with code 0.
  9. Server becomes idle: The game server becomes idle because it’s not allocated.
  10. Stop machine: Game Server Hosting stops the machine when all the game servers on the machine have been idle for longer than the time to live.

Single-session allocations

Server hold

Server hold is a server management pattern which allows the server to remain capable of receiving an allocation or executing a reservation for a specified period of time. This is explained in more detail in the server hold section.