Skip to main content

Integration

Key definitions​

  • Session Type: This is an identifier set on an allocation, and is included by the game client in the Create Session request to filter the allocation in which to create the session in.
  • Session Config: This is provided by the game client, when calling Create Session. The session config is set on the payload when the session is first created. The game server can read it using the Payload Local API - Get Session Config.
    • This is not exposed when listing sessions, this allows you to include secret server only data that should not be exposed to game clients.
  • Session Status: Use this for storing any attributes that you want to be visible to the player when they are listing session. This is set and updated by the game server using the Payload Local API - Set Session Status, and is included in the List Sessions response for the game client to expose to the player.

Configure the IMS zeuz allocations​

The update allocation screen, with a session_type set in the allocation metadata section

To make the allocation available to the Session Manager add the annotation session_type to the allocation in the IMS Console.

The session_type value in the Session Manager API calls need to match the session_type annotation configured in the allocation.

For example to create a session on the above allocation the API call would be:

POST: https://session-manager.ims.improbable.io/api/v0/projects/alpha-beta-123456/sessions?session_type=eu-1v1

session_type should be unique per allocation, as session manager will pick the first allocation it finds with the matching session type. Having two allocations with the same session_type will result in one allocation not being used.

info

Allocations that are to be used with session manager, should only be used with session manager and not shared with your backend. Reasonable max payload counts should be added to control your cost.

Game Client​

Create Session​

A sequence diagram outlining the steps taken by the session manager to create a session

To create a custom game session the game client can call the Create session API.

To understand how this works in relation to allocations and payloads in IMS zeuz you can see an outline of the key steps' taken by Session Manager here:

  1. The Game Client calls Create Session with a session type, and optional session config.
  2. The Session Manager calls IMS zeuz and reserves a payload in an allocation that has the annotation session_type that matches the provided session type.
  3. When reserving the payload, the session config provided in step 1 is set on the payload ready to be read by the game server.
  4. The Create Session API call completes and Game Client receives the session ID, IP, and Port.
  5. The Game client can then join the game using the provided details.

Listing Sessions​

The Game Client can call the Session Manager - List Sessions to view the sessions others have created, this will include the connection details, and session status. Session Status can be used on the game client to filter the sessions as required.

Game Server​

Reading session config and setting session status​

sequence diagram showing the steps taken to read and set the session config from the game server

The process to read session config and set session status in the game server should be as follows:

  1. Wait for payload to be reserved, to do this, in a loop call the Payload Local API - Get Payload Details and check if the Payload status is reserved.
  2. Once the payload is reserved, call the Payload Local API - Get Session Config, parse the config and adjust game server accordingly
  3. Set the session status by calling Payload Local API - Set Session Status. For example the session status might include the map, and game mode. The game client can then read this the Session Manager API - List Sessions.
danger

session_config is provided by the game client on a players machine, therefore this data should be treated with caution and sanitized appropriately by your game server.

As the game server changes you can update the session status, and the game client can periodically call the List Session API to get the latest sessions and their statuses.

info

Due to a caching mechanism used by session manager, session status may take up to 12 seconds to update.

We do not recommend that you use the session status as a way of sharing session data with players that have already joined the session. You should share the required details over the already established connection that the players have to the game server.