Skip to main content

Payloads

A payload is the unit running a game server, depending on its state it may have players connected to it. Your game server runs inside a container, a payload represents the set of containers necessary to run your game server on IMS zeuz.

Payloads

Payload ID​

A Payload ID is composed of two 5 character string separated by a hyphen, e.g. 8hhtn-fvpvq.

caution

A payload ID is unique within an allocation at any one point in time, however there can be multiple payloads with the same ID over the lifetime of an allocation. Payload IDs should not be used as historic match identifiers.

The Payload Local API can be used within a Payload to get its details including the ID.

Payload state​

Payloads are managed by the system. The payload state represent the status of any payload:

string (v0PayloadStatusState)
Default: "Unknown"
Enum: "Unknown" "Creating" "Preparing" "Starting" "Ready" "Reserved" "Shutdown" "Error" "Unhealthy"

Payload state.

  • Unknown: The payload is in an unknown state.
  • Creating: The payload is being scheduled and has not yet started.
  • Preparing: The payload is downloading its container image.
  • Starting: The payload has been scheduled and is starting. Waiting for the payload to mark itself as ready.
  • Ready: The payload has called the ready endpoint, making it available to the system to be reserved for a game session. While ready, the system is free to remove the payload at any time, and players shouldn't be connected to this payload.
  • Reserved: The payload has been reserved for a game session, players can be connected to it. The system will not be able to remove the payload until it shuts down or gets unreserved.
  • Shutdown: The payload is stopping and is being removed.
  • Error: Something has gone wrong with the payload.
  • Unhealthy: The payload is failing to report itself as healthy.
"Unknown"

A simplified version of the payload lifecycle is:

Payload Lifecycle

info

Two things could happen when the main process of a payload exits

  • If the payload hasn't reached Ready, it will restart with exponential back-off, entering Error state while waiting to be restarted.
  • Otherwise, if the payload was Ready or Reserved, the payload will transition into Unhealthy state and will be shut down shortly after. :::

Payload Local API​

The Payload Local API provides an interface between your game server and the IMS zeuz orchestration service. It is run in parallel to your game server in the payload. The game server should communicate with the API to perform operations such as:

  • Setting the payload to ready
  • Fetching the payload state
  • Setting the session_status
  • Retrieving the session_config

Payload metadata​

See this guide for how to use payload metadata.