zeuz Multiplayer Operations documentation

Welcome to the zeuz Multiplayer Operations documentation. Here, you'll find the zeuz User Manual and API reference. You can also check out the Helpdesk and Knowledge Base.

User Manual    API Reference

Payload definition

You define a payload as part of creating an allocation. In the zeuz control panel go to Orchestration > Allocations and click +ADD ALLOCATION. See Create an allocation for more information.

A payload defines an instance of your game server’s software that runs as a containerized service. We create the payload using:

  • An image of your game’s server and
  • the commands that describe how to execute it.

Image

The Image drop-down displays the images you have uploaded and published using zeuz tool. Select an image for this allocation to use in its payloads.

You can upload a new version of an existing image (with the same filename) to update an image.

(For guidance, see Upload and publish an image.)

📘

NOTE

An optional feature allows you to configure your payload definition to Always Use Latest Image. This tells zeuz to refresh all unreserved payloads for the allocation with the latest image, each time an image is published. To manually select an image, disable Always Use Latest Image.

Contact zeuz Support to find out more about this feature and have it enabled for your account.

Command

The Command field contains settings that define how zeuz deploys the payload to the server hardware you specified in your orchestration setup. This includes details of your game’s executable (binary) file and the settings to use during your payload’s deployment.

Configure the Command field with the following details. See the Command format section below for details on how to format the Command field.

Note: Do not change the rest of the supplied Command settings.

  • binaryactivename: Replace NAME_OF_YOUR_BINARY with the name of the executable (binary) file which launches the payload. Required.
  • binaryexecpath: Replace PATH_TO_YOUR_BINARY with the path to your game’s executable (binary) file. Do not change the start of the path. Required.
  • execargs: Use this line to add settings to the payload such as ports to use (required), identification variables (required), and other optional variables.
    See Settings below for more information.

Settings

You use settings to further specify the details of your payload deployment.

Ports

As a minimum, you must specify a port for your players to use, to connect to your game. You might also want to specify additional ports, for example a separate port for debugging and a separate port for game statistics reporting.

To define ports, specify them in the Command field using the ${servicePort:PortName} variable. When you add a port, you see it listed below the Command field in alphabetical order. For example,

2 ports in use (debug, default)

Use this list to check that you have entered the correct names for your ports and that there are no typos.

If you want to enable the CCU tracking feature and view the number of your game’s concurrent players, you must include the ${statsPort} variable in the Command field. This variable passes the port configuration to your game and allows it to transmit information about concurrent players. See the Payload definition CCU tracking section and the CCU tracking page for more information.

Note: If you previously set up ports using the ${serviceContainerPortX} and ${serviceHostPortX} syntax, they will continue to work.

Identification variables

You must include the following identification variables. They are required for some API requests.

  • ${serviceIP}: The active payload reports the IP address of the server the game is running on.
  • ${payloadID}: The active payload reports its ID.

Optional environment variables

If you use a matchmaking backend service to allocate players to a game server, you might want the payload to report to it. You can use the following environment variables inside a shell script or your executable (binary) file, so that the payload provides additional useful information for routing players and debugging.

You can use any of the following environment variables in your script; the examples below illustrate the types of values the variables might contain. The actual values will depend on your zeuz configuration, and will vary from payload to payload.

Variable name

Description

ZEUZ_ALLOCATIONID

The unique ID of the allocation for the payload. This displays as the ID on the Allocations page of the ZCP.

For example: tfiuDnppqrsnxYYoBKlrXlgcagy

ZEUZ_ENVID

The unique ID of the environment. This displays as the ENVIRONMENT ID on the left panel of the ZCP.

For example: xZjuARrbUeahqKsqfUxTOpLxuCH

ZEUZ_MACHINEID

The ID of the machine that was allocated to run a payload. This displays as the MACHINE ID on the Machines page and the Payloads page of the ZCP.

For example: bAxrSlvDerxllEOqmUiVanQKdmX

ZEUZ_PAYLOADID

The unique ID of the payload. This is displayed as the PAYLOAD ID on the Payloads page of the ZCP.

For example: dKgnGTtFxlXCtWgkiTaaMrixocl

ZEUZ_PROJID

The unique ID of the project. This displays as the PROJECT ID on the left panel of the ZCP.

For example: icYmKawQrtBwtCzfrwxqAjkZbwi

ZEUZ_REGIONS

The geographical areas in which your allocation’s server hardware reside. These display on the Allocations page of the ZCP. The variable holds multiple regions as comma-separated values without spaces.

For example: US-East,US-Mid,Asia

The full list of available regions is:

  • US
  • Asia
  • Europe
  • Australia
  • US-East
  • US-Mid
  • US-West
  • South America
  • Russia
  • Australia (GCP-N1)

Automatic payload release

You can set the payload to stop running when a game session comes to an end. This automatically frees up server hardware resources and saves you from doing this manually.

To do this:

  1. Obtain an API key:
    In the zeuz control panel, click the drop-down arrow next to your login name in the top right corner and select API Keys.

  2. Add the following lines to the Command field:

apiendpoint=https://zcp.zeuz.io/api/v1
apikey=API_KEY (replace API_KEY with your API key)
apisecret=API_KEY_PASSWORD (replace API_KEY_PASSWORD with your API key's password)

Command format

It is important to use a new line for each argument. An example Command field definition is as follows:

/opt/zeuz/bin/payloadrunner
run
binaryactivename=MY_GAME
binaryexecpath=/opt/zeuz/gameserver/mygame/start_in_zeuz.sh
execargs=-PlayerPort=${servicePort:PlayerPort} -IP=${serviceIP} -statsPort=${statsPort} -id=${payloadID}
apiendpoint=https://zcp.zeuz.io/api/v1
apikey=MY_API_KEY
apisecret=MY_API_KEY_PASSWORD

CCU tracking

You can use the CCU tracking feature to view how many concurrent players are connected to your zeuz game servers.

If you don’t see the CCU Tracking drop-down on the Allocation : Create page in the zeuz control panel and you'd like to use this feature, contact zeuz Support, who can add it to your account.

For information on how to enable the feature, see the CCU tracking page

Payload artifacts

Game servers run in a transient state (see Wikipedia: transient). This means that when a payload stops running, any crash dump files and other operational data you configure your game server to save does not persist. The payload artifacts feature saves the data and uploads it to a central location (a zeuz AWS S3 bucket), so that you can download and analyze it after a payload stops running.

Payload artifacts is a beta feature which zeuz must enable for you. Contact zeuz Support to have the feature enabled for your account.

Other sections

Ensure you have completed the other sections on the create allocation page, to finish configuring your allocation:

  • Basic information
    Add a text description and specify the regions where you want its server hardware located.
    See the Create an allocation page for details.
  • Hardware configuration
    Specify your hardware configuration.
    See the Hardware configuration page for details.
  • Scaling definition
    Define the scaling rules.
    See the Scaling rules page for details.

Save

Click the SAVE button at the top of the page to save the allocation. You can click CANCEL to return to the main Allocations page.



2021-sep-09 Page updated with editorial review: execdelay command setting deprecated. Added details for environment variables.
2021-aug-24 Page updated with editorial review: added note about payload artifacts feature.
2021-aug-17 Page updated with editorial review: added note about Always Use Latest Image feature.

Updated 18 days ago


Payload definition


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.