Skip to content
RallyHere Docs

Session Basics

This document describes some potential use cases of sessions, and an example way to implement them. Note that the described method may not be the only way to achieve the same goal.

Most of the APIs referenced in this document are part of the Session API.

Note that for our pre-built integrations (such as the Unreal integration), much of this functionality will be handled for you. See the documentation on those integrations for more information on how to use the integration layer.

Forming a Session

Sessions are formed by calling the createOrJoinSession API call. As the name implies, this will create a session in most cases, or join a session in case of a hub. The call will return the Session Id of the resulting session.

The API call takes a request object called a CreateOrJoinRequest. While it has a number of fields, some are required:

  • Session Type - The name of the Session Template to use
  • Client Version - A compatibility version string used to determine compatibility with the session
  • Region Id - For session operations such as matchmaking that use the region, this specifies the region to use

Joining and Leaving a Session

Players can be invited to a session via the updateSessionPlayerByUuid API call. Updating the session to have a player of status Invited will allow the invitee to see the session in their session list, and allow them to join it in the case of a private session (public sessions can be joined at any time, so an invite is not required).

To join a session, use the joinSessionByIdSelf call. As mentioned, for public sessions, this can be done at any time. For private sessions, the player must be invited first. To leave a session, use the leaveSessionByIdSelf.

To get the list of all sessions a player is currently associated with, use getPlayerSessionsSelf.

Gameplay via Instances

Instances are hosted connected sessions, usually used for gameplay. Once a session is formed, you can request an instance on that session via the handleInstanceRequest call. These instance can be player hosted or dedicated servers based on the specified HostType. In the dedicated case, a server will be acquired from the allocation system.

Once the instance is complete, you can call endInstance to end the instance. This will allow a new instance to be created as well, should a session want to run multiple instances.

Note that sessions can be configured to automatically launch instances on creation (for example, for hubs.

Examples

Parties

Sessions can be used for the functionality usually desribed as a “party” in a game.
These are usually small groupings of players, that are then able to play together and may have secondary functionality as well. For this example, we will assume that the party is a group of 4 players.

  1. Create a new Session Template (we will call it “party”)
    1. Open the Developer Portal, and navigate to the Session Configuration for your Sandbox
    2. Set the Session Type as “party”
    3. Set the max member count as 4
    4. Set the join rule as private
  2. In game, have the player who will lead the party make a new session of type “party”
  3. Have the leader send party invites to the other members
  4. Those members can accept the invite by joining the session by its Session Id

Hubs

Session templates can be configured to perform as a “hub” type. This changes how sessions are joined via the createOrJoinSession API call. Instead of creating a new session the API will instead attempt to find a pre-existing session and join it, but will create a new session if it does not exist. This is intended to handling open world type use cases, where you would want every player joining that session to end up in the same area (up to some cap, then make a new one).

Think of a city in an MMO as an example, where you would want to have a social space for players to congregate.

While not required, it is strongly suggested that hubs use an automatically started dedicated instance. This means that when a new session is created, the instance will be spinning up in the background so that is ready for players as fast as possible.

Session Browser

Sesssions can be registered into the session browser, either manually via an API call or automatically via a session template configuration.

This browser is searchable, and that search can be either done under the hood for your game (for example, to swap between sessions of a hub type), or potentially from having a “server browser” type screen within your game.

Once an appropriate session is found, simply join on the session (assuming the appropriate join rule is set).

Matchmaking

Matchmaking is done via queuing one session (such as a party like session), and outputs a new session. This is non-destructive to the previous session. The output session is of a type specified in the matchmaking configuration. Generally speaking, matchmaking created sessions will be owned by the “host.”

Matchmade sessions can be configured to automatically launch instances with specific parameters, and if so will wait until that instance is joinable before notifying players that it is available (the host is able to interact with it earlier, to prepare for players). This is to allow failures (such as an unresponsive host) to keep the players in matchmaking.