Game server lifecycle#

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 Multiplay 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 Multiplay 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 Multiplay Hosting selected a server slot that isn’t running the correct build executable. In this case, Multiplay Hosting restarts the build executable with the correct build.
• You created an allocation, and Multiplay Hosting selects a server slot that’s using the wrong build configuration. In this case, Multiplay 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, Multiplay 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, Multiplay Hosting automatically restarts the server.

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 Multiplay 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:

• Intentional exits
• Crashes

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

Intentional exits#

An exit refers to an intentional termination of a build executable process with an exit code of 0. When Multiplay 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 Multiplay 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, Multiplay 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 Multiplay Hosting action, either due to a configuration or a response to the game server’s behavior. These scenarios include:

• An allocate API call with the restart flag set to true
• Game server misbehavior
• Build configuration change

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

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.

Build configuration ID change#

Multiplay Hosting restarts (stops, then starts) a build executable process if you create an allocation, and Multiplay 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, Multiplay 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.

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

1. Provision machine: Multiplay 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: Multiplay 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#

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.

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

1. Provision machine: Multiplay 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: Multiplay 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: Multiplay Hosting stops the machine when all the game servers on the machine have been idle for longer than the time to live.

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.