Integrate game session

Last updated on April 18, 2024

Overview

This article walks you through how to manage a game session through the AccelByte Gaming Services (AGS) Game SDK.

Integrate a game session using the AGS Game SDK

This section provides code snippets showing how to:

Create a game session
Query a game session list
Retrieve the current user's game sessions
Retrieve game session details
Update a game session
Delete a game session
Invite a player to a game session
Join a game session
Reject a game session invite
Leave a game session
Promote a game session leader
Listen to game session notifications

Create a game session

Create a new game session based on the creation request.

Unreal Engine
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FAccelByteModelsV2GameSessionCreateRequest Request;
Request.ConfigurationName = ConfigurationName; // MANDATORY
Request.Joinability = EAccelByteV2SessionJoinability::INVITE_ONLY; // Optional
Request.Type = EAccelByteV2SessionConfigurationServerType::DS; // Optional
Request.ClientVersion = GameServerVersion; // Optional
Request.ServerName = LocalServerName; // Optional
Request.Deployment = Deployment; // Optional
Request.RequestedRegions = {"us-west-1", "us-west2"}; // Optional

// Optional
TArray<FString> TeamA = {TeamAUserId1, TeamAUserId2};
TArray<FString> TeamB = {TeamBUserId1, TeamBUserId2};
TArray<FAccelByteModelsV2GameSessionTeam> Teams;
Teams.Add({TeamA});
Request.Teams = Teams;

// Optional
Request.Attributes.JsonObject = MakeShared<FJsonObject>();
Request.Attributes.JsonObject->SetStringField("PartyAttribute", "Attribute1");

Request.MaxPlayers = 10; // Optional
Request.MinPlayers = 1; // Optional
Request.InactiveTimeout = 30; // Optional
Request.InviteTimeout = 86400; // Optional


ApiClient->Session.CreateGameSession(Request,
     THandler<FAccelByteModelsV2GameSession>::CreateLambda(
        [&](const FAccelByteModelsV2GameSession& Result)
         {
             // Do something when operation is successful
         }),
     FErrorHandler::CreateLambda(
        [&](int32 ErrorCode, const FString& ErrorMessage)
         {
             // Do something when operation fails or has an error
         }));

var session = AccelByteSDK.GetClientRegistry().GetApi().GetSession();

SessionV2GameSessionCreateRequest createGameSessionRequest = new SessionV2GameSessionCreateRequest
{
    joinability = SessionV2Joinability.OPEN,
    configurationName = configurationTemplateName
};

session.CreateGameSession(createGameSessionRequest, result =>
{
    if (result.IsError)
    {
        // Do something if CreateGameSession has an error
        Debug.Log($"Error CreateGameSession, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Do something if CreateGameSession has been successful
});

Query a game session list

Query all the game sessions that have the same attribute as the requested.

Unreal Engine
Unity

note

The code snippet for Unreal will be added soon.

var session = AccelByteSDK.GetClientRegistry().GetApi().GetSession();

var attributeRequest = new Dictionary<string, object>()
{
    { "map", "SampleMap" },
};

session.QueryGameSession(attributeRequest, result =>
{
    if (result.IsError)
    {
        // Do something if QueryGameSession has an error
        Debug.Log($"Error QueryGameSession, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Do something if QueryGameSession has been successful
});

Retrieve the current user's game sessions

Retrieve the list of the user's game sessions and its detail information.

Unreal Engine
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

ApiClient->Session.GetMyGameSessions(
    THandler<FAccelByteModelsV2PaginatedGameSessionQueryResult>::CreateLambda(
        [&](const FAccelByteModelsV2PaginatedGameSessionQueryResult& Result)
        {
            // Do something when operation is successful
        }),
    FErrorHandler::CreateLambda(
        [&](int32 ErrorCode, const FString& ErrorMessage)
        {
            // Do something when operation fails or has an error
        }));

var session = AccelByteSDK.GetClientRegistry().GetApi().GetSession();

session.GetUserGameSessions(null, null, null, result =>
{
    if (result.IsError)
    {
        // Do something if GetUserGameSessions has an error
        Debug.Log($"Error GetUserGameSessions, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Do something if GetUserGameSessions has been successful
});

Retrieve game session details

Retrieve the specific game session details by specifying the game session identity.

Unreal Engine
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

ApiClient->Session.GetGameSessionDetails( SessionId,
    THandler<FAccelByteModelsV2GameSession>::CreateLambda(
         [&](const FAccelByteModelsV2GameSession& Result)
         {
             // Do something when operation is successful
         }),
    FErrorHandler::CreateLambda(
         [&](int32 ErrorCode, const FString& ErrorMessage)
         {
             // Do something when operation fails or has an error
         }));

var session = AccelByteSDK.GetClientRegistry().GetApi().GetSession();

var sessionId = "targeted-session-id";

session.GetGameSessionDetailsBySessionId(sessionId, result =>
{
    if (result.IsError)
    {
        // Do something if GetGameSessionDetailsBySessionId has an error
        Debug.Log($"Error GetGameSessionDetailsBySessionId, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Do something if GetGameSessionDetailsBySessionId has been successful
});

Update a game session

Update the game session's data from the specific game session.

Unreal Engine
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FAccelByteModelsV2GameSessionUpdateRequest Request;
Request.Version = PartyDataVersion; // Mandatory, must be the same version as current data in the backend
Request.Joinability = EAccelByteV2SessionJoinability::INVITE_ONLY; // Optional
Request.Attributes.JsonObject = MakeShared<FJsonObject>(); // Optional
Request.Attributes.JsonObject->SetStringField("AttributeName", "Attribute1"); // Optional
Request.MaxPlayers = 10; // Optional
Request.MinPlayers = 1; // Optional
Request.InactiveTimeout = 30; // Optional
Request.InviteTimeout = 86400; // Optional

ApiClient->Session.UpdateGameSession(GameSessionID, Request, THandler<FAccelByteModelsV2GameSession>::CreateLambda(
    [&](const FAccelByteModelsV2GameSession& Result)
    {
        // Do something when the operation is successful
    }),
    FErrorHandler::CreateLambda([&](int32 ErrorCode, const FString& Message)
    {
        // Do something when operation fails or has an error
    }));

var session = AccelByteSDK.GetClientRegistry().GetApi().GetSession();

var sessionId = "targeted-session-id";

var updateRequest = new SessionV2GameSessionUpdateRequest()
{
    joinability = SessionV2Joinability.INVITE_ONLY,
    version = 2
 };

session.PatchGameSession(sessionId, updateRequest, result =>
{
    if (result.IsError)
    {
        // Do something if PatchGameSession has an error
        Debug.Log($"Error PatchGameSession, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Do something if PatchGameSession has been successful
});

Delete a game session

Remove the existing game session.

Unreal Engine
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();
ApiClient->Session.DeleteGameSession(SessionId, FVoidHandler::CreateLambda([]
{
   // Successfully deleted game session
}),
FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& Message)
{
   // Error deleting game session
}));

var session = AccelByteSDK.GetClientRegistry().GetApi().GetSession();

var sessionId = "targeted-session-id";

session.DeleteGameSession(sessionId, result =>
{
    if (result.IsError)
    {
        // Do something if DeleteGameSession has an error
        Debug.Log($"Error DeleteGameSession, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Do something if DeleteGameSession has been successful
});

Invite a player to a game session

Invite other players to join the game session by specifying their user identity.

Unreal Engine
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

ApiClient->Session.SendGameSessionInvite(SessionId, UserIdToInvite, FVoidHandler::CreateLambda(
    [&]
    {
        // Do something when the operation is successful
    }),
    FErrorHandler::CreateLambda([&](int32 ErrorCode, const FString& Message)
    {
        // Do something when operation fails or has an error
    }));

var session = AccelByteSDK.GetClientRegistry().GetApi().GetSession();

var sessionId = "targeted-session-id";
var userIdToInvite = "targeted-user-id";

session.InviteUserToGameSession(sessionId, userIdToInvite, result =>
{
    if (result.IsError)
    {
        // Do something if InviteUserToGameSession has an error
        Debug.Log($"Error InviteUserToGameSession, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Do something if InviteUserToGameSession has been successful
});

Join a game session

Join the existing game session by specifying the session identity.

Unreal Engine
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

ApiClient->Session.JoinGameSession(SessionId, THandler<FAccelByteModelsV2GameSession>::CreateLambda(
    [&](const FAccelByteModelsV2GameSession& Result)
    {
        // Do something when the operation is successful
    }),
    FErrorHandler::CreateLambda([&](int32 ErrorCode, const FString& Message)
    {
        // Do something when operation fails or has an error
    }));

var session = AccelByteSDK.GetClientRegistry().GetApi().GetSession();

var sessionId = "targeted-session-id";

session.JoinGameSession(sessionId, result =>
{
    if (result.IsError)
    {
        // Do something if JoinGameSession has an error
        Debug.Log($"Error JoinGameSession, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Do something if JoinGameSession has been successful
});

Reject a game session invitation

Reject another player's invitation to the join the game session.

Unreal Engine
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

ApiClient->Session.RejectGameSessionInvite(GameSessionID, FVoidHandler::CreateLambda(
    [&]
    {
        // Do something when the operation is successful
    }),
    FErrorHandler::CreateLambda([&](int32 ErrorCode, const FString& Message)
    {
        // Do something when operation fails or has an error
    }));

var session = AccelByteSDK.GetClientRegistry().GetApi().GetSession();

var sessionId = "targeted-session-id";

session.RejectGameSessionInvitation(sessionId, result =>
{
    if (result.IsError)
    {
        // Do something if RejectGameSessionInvitation has an error
        Debug.Log($"Error RejectGameSessionInvitation, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Do something if RejectGameSessionInvitation has been successful
});

Leave a game session

Leave the current joined game session by specifying its game session identity.

Unreal Engine
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

ApiClient->Session.LeaveGameSession(SessionId, FVoidHandler::CreateLambda(
    [&]
    {
        // Do something when the operation is successful
    }),
    FErrorHandler::CreateLambda([&](int32 ErrorCode, const FString& Message)
    {
        // Do something when operation fails or has an error
    }));

var session = AccelByteSDK.GetClientRegistry().GetApi().GetSession();

var sessionId = "current-session-id";

session.LeaveGameSession(sessionId, result =>
{
    if (result.IsError)
    {
        // Do something if LeaveGameSession has an error
        Debug.Log($"Error LeaveGameSession, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Do something if LeaveGameSession has been successful
});

Promote a game session leader

As a game session leader, it can promote another member to become a game session leader. Since there is only one game session leader, the previous leader will become a member.

Unreal Engine
Unity

note

The code snippet for Unreal will be added soon.

var session = AccelByteSDK.GetClientRegistry().GetApi().GetSession();

var sessionId = "targeted-session-id";
var userIdToPromote = "targeted-user-id";

session.PromoteUserToGameSessionLeader(sessionId, userIdToPromote, result =>
{
    if (result.IsError)
    {
        // Do something if PromoteUserToGameSessionLeader has an error
        Debug.Log($"Error PromoteUserToGameSessionLeader, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Do something if PromoteUserToGameSessionLeader has been successful
});

Listen to game session notifications

There are some game session notifications that can be listened to in order to receive various updates from the game session, which helps improve the game experience. It uses a WebSocket connection to ensure that the notification can be received in real-time.

Unreal Engine
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

ApiClient->Lobby.SetV2GameSessionInvitedNotifDelegate(Api::Lobby::FV2GameSessionInvitedNotif::CreateLambda(
    [&](const FAccelByteModelsV2GameSessionUserInvitedEvent& Notif)
    {
        // Do something when notification is received
    }));

ApiClient->Lobby.SetV2GameSessionMembersChangedNotifDelegate(Api::Lobby::FV2GameSessionMembersChangedNotif::CreateLambda(
    [&](const FAccelByteModelsV2GameSessionMembersChangedEvent& Notif)
    {
        // Do something when notification is received
    }));

ApiClient->Lobby.SetV2GameSessionJoinedNotifDelegate(Api::Lobby::FV2GameSessionJoinedNotif::CreateLambda(
    [&](const FAccelByteModelsV2GameSessionUserJoinedEvent& Notif)
    {
        // Do something when notification is received
    }));

ApiClient->Lobby.SetV2GameSessionRejectedNotifDelegate(Api::Lobby::FV2GameSessionRejectedNotif::CreateLambda(
    [&](const FAccelByteModelsV2GameSessionUserRejectedEvent& Notif)
    {
        // Do something when notification is received
    }));

ApiClient->Lobby.SetV2GameSessionKickedNotifDelegate(Api::Lobby::FV2GameSessionKickedNotif::CreateLambda(
    [&](const FAccelByteModelsV2GameSessionUserKickedEvent& Notif)
    {
        // Do something when notification is received
    }));

ApiClient->Lobby.SetV2GameSessionUpdatedNotifDelegate(Api::Lobby::FV2GameSessionUpdatedNotif::CreateLambda(
    [&](const FAccelByteModelsV2GameSession& Notif)
    {
        // Do something when notification is received
    }));

ApiClient->Lobby.SetV2DSStatusChangedNotifDelegate(Api::Lobby::FV2DSStatusChangedNotif::CreateLambda(
    [&](const FAccelByteModelsV2DSStatusChangedNotif& Notif)
    {
        // Do something when notification is received
    }));

var lobby = AccelByteSDK.GetClientRegistry().GetApi().GetLobby();

// Triggered when a game session is updated
lobby.SessionV2GameSessionUpdated += (Result<SessionV2GameSessionUpdatedNotification> result) =>
{
    if (result.IsError)
    {
        // Do something if SessionV2GameSessionUpdated has an error
        Debug.Log($"Error SessionV2GameSessionUpdated, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Do something if SessionV2GameSessionUpdated is successfully received
};

// Triggered when a game session member has changed
lobby.SessionV2GameSessionMemberChanged += (Result<SessionV2GameMembersChangedNotification> result) =>
{
    if (result.IsError)
    {
        // Do something if SessionV2GameSessionMemberChanged has an error
        Debug.Log($"Error SessionV2GameSessionMemberChanged, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Do something if SessionV2GameSessionMemberChanged is successfully received
};

// Triggered when a user joined the game session
lobby.SessionV2UserJoinedGameSession += (Result<SessionV2GameJoinedNotification> result) =>
{
    if (result.IsError)
    {
        // Do something if SessionV2UserJoinedGameSession has an error
        Debug.Log($"Error SessionV2UserJoinedGameSession, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Do something if SessionV2UserJoinedGameSession is successfully received
};

// Triggered when a user is kicked from a game session
lobby.SessionV2UserKickedFromGameSession += (Result<SessionV2GameUserKickedNotification> result) =>
{
    if (result.IsError)
    {
        // Do something if SessionV2UserKickedFromGameSession has an error
        Debug.Log($"Error SessionV2UserKickedFromGameSession, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Do something if SessionV2UserKickedFromGameSession is successfully received
};

// Triggered when a game session invite is rejected
lobby.SessionV2UserRejectedGameSessionInvitation += (Result<SessionV2GameInvitationRejectedNotification> result) =>
{
    if (result.IsError)
    {
        // Do something if SessionV2UserRejectedGameSessionInvitation has an error
        Debug.Log($"Error SessionV2UserRejectedGameSessionInvitation, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Do something if SessionV2UserRejectedGameSessionInvitation is successfully received
};

// Triggered when a user is invited to a game session
lobby.SessionV2InvitedUserToGameSession += (Result<SessionV2GameInvitationNotification> result) =>
{
    if (result.IsError)
    {
        // Do something if SessionV2InvitedUserToGameSession has an error
        Debug.Log($"Error SessionV2InvitedUserToGameSession, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Do something if SessionV2InvitedUserToGameSession is successfully received
};

Overview​

Integrate a game session using the AGS Game SDK​

Create a game session​

Query a game session list​

Retrieve the current user's game sessions​

Retrieve game session details​

Update a game session​

Delete a game session​

Invite a player to a game session​

Join a game session​

Reject a game session invitation​

Leave a game session​

Promote a game session leader​

Listen to game session notifications​

On this page