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.
A Payload ID is composed of two 5 character string separated by a hyphen, e.g.
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.
Payloads are managed by the system. The payload state represent the status of any payload:
- 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
readyendpoint, 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.
A simplified version of the payload lifecycle is:
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
Errorstate while waiting to be restarted.
- Otherwise, if the payload was
Reserved, the payload will transition into
Unhealthystate 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
- Fetching the payload state
- Setting the
- Retrieving the
See this guide for how to use payload metadata.