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.)

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.

  • ZEUZ_PAYLOADID
  • ZEUZ_PROJID
  • ZEUZ_ENVID
  • ZEUZ_ALLOCATIONID
  • ZEUZ_MACHINEID
  • ZEUZ_NODEID
  • ZEUZ_REGIONS
  • ZEUZ_STAGE

📘

TIP

We recommend that you use the execdelay property to define a window of time for the game’s executable (binary) code to start. After the defined number of milliseconds, if zeuz does not detect that the game’s executable (binary) file defined in binaryactivename is running, it attempts a restart with a new payload.

To use the execdelay property, add the following line to the Command field:

execdelay=<number of milliseconds>

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
execdelay=15000
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

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-04-12 Page updated with editorial review: fixes to API key parameters
2021-04-09 Page updated with editorial review
2021-02-24 Page updated with editorial review
2020-12-14 Updated to include CCU tracking section with editorial review
2020-11-27 Page created with editorial review

Updated about a month 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.