Use the SDK for matchmaking - Introduction to Session - (Unity module)

Last updated on March 15, 2024

Unwrap the wrapper​

In this section, you will learn how to create and leave a session using the AccelByte Gaming Services (AGS) Game SDK. Within the Byte Wars project, an SDK wrapper named SessionEssentialsWrapper.cs has been created. This C# class holds the session-related functionalities and will later be inherited by several other classes. In this tutorial, you will use a starter version of that wrapper so you can implement session functionalities from scratch.

What's in the Starter Pack​

To follow this tutorial, a starter wrapper class called SessionEssentialsWrapper_Starter has been prepared for you and has several functionalities provided:

  • You will use Session, which contains session-related functions, and Lobby, which logs in to the lobby to access notifications. You can find these lines of code in SessionEssentialsWrapper_Starter.

    protected Session _session;
    protected Lobby _lobby;

  • In the Awake() function, Session and Lobby are defined using MultiRegistry to get them and store them to the variables _session and _lobby. It sets the access modifier for this function as protected to make it accessible from the inheritor class.

    protected void Awake()
    {
        _session = MultiRegistry.GetApiClient().GetSession();
        _lobby = MultiRegistry.GetApiClient().GetLobby();
    }

  • In Start(), LoginToLobby is assigned to the login completing event.

    private void Start()
    {
        LoginHandler.onLoginCompleted += LoginToLobby;
    }

Implement create, join, and leave session​

In this section, you will implement functionality to create, join, and leave a session using the AGS Game SDK.

Create Session​

You can access any session-related functions from the _session field that has the Session class type. To create a session, use the _session.CreateGameSession function. You will use a class model called SessionRequestPayload as a parameter. It comes predefined so you can use it without any modification.

  1. Create an event that will be used in a callback function later. Open the SessionEssentialsWrapper_Starter.cs and add the code below.

    public event Action<SessionResponsePayload> OnCreateSessionCompleteEvent;

  2. Write a function to create a session. Open the SessionEssentialsWrapper_Starter.cs file and create a function called CreateSession. _session.CreateGameSession is already used in this function, which will call an API endpoint and send a request to the backend to create a game session.

    protected internal void CreateSession(SessionRequestPayload sessionRequest, [CallerFilePath] string? sourceFilePath=null)
    {
        var gameSessionRequest = SessionUtil.CreateGameSessionRequest(sessionRequest);
        var tutorialType = SessionUtil.GetTutorialTypeFromClass(sourceFilePath);
        _session.CreateGameSession(gameSessionRequest, result =>  OnCreateSessionCompleted(result, tutorialType));
    }

  3. As mentioned, SessionRequestPayload is used as a parameter, and [CallerFilePath] string? sourceFilePath=null is also used. The second parameter is to get the file path of the caller class; leave this parameter as empty.

  4. To establish a session with _session.CreateGameSession, you need to provide an argument of type SessionV2GameSessionCreateRequest. A utility class, SessionUtil, has been created to map a SessionRequestPayload object to SessionV2GameSessionCreateRequest.

  5. Create a callback function to handle the result when the session creation is complete.

    private void OnCreateSessionCompleted(Result<SessionV2GameSession> result, TutorialType? tutorialType = null)
    {
        var response = new SessionResponsePayload();

        if (!result.IsError)
        {
            BytewarsLogger.Log($"Successfully created game session");
            response.Result = result;
            response.TutorialType = tutorialType;
        }
        else
        {
            BytewarsLogger.LogWarning($"{result.Error.Message}");
            response.IsError = result.IsError;
        }
        OnCreateSessionCompleteEvent?.Invoke(response);
    }

The callback function will trigger the OnCreateSessionCompleteEvent event and pass the result to the class that has subscribed to this event. The object type of this event is SessionResponsePayload, which is a class model that wraps the result obtained from the API response and includes the TutorialType enum. This enum will later serve as a flag to filter for the event subscribers.

Join Session​

  1. To address joining sessions, you need the session ID that was created before. Create an event for leaving a session. Underneath the OnCreateSessionCompleteEvent, put the code below.

    public event Action<SessionResponsePayload> OnJoinSessionCompleteEvent;

  2. Write a function for joining a session. You will use _session.JoinGameSession from the AGS Game SDK.

    protected void JoinSession(string sessionId, [CallerFilePath] string? sourceFilePath=null)
    {
        var tutorialType = SessionUtil.GetTutorialTypeFromClass((sourceFilePath));
        _session.JoinGameSession(sessionId, result => OnJoinSessionCompleted(result, tutorialType));
    }

  3. Write a callback function to notify when the player joins.

    private void OnJoinSessionCompleted(Result<SessionV2GameSession> result, TutorialType? tutorialType = null)
    {
        var response = new SessionResponsePayload();
        
        if (!result.IsError)
        {
            BytewarsLogger.Log($"Successfully joined the game session");
            response.Result = result;
            response.TutorialType = tutorialType;
        }
        else
        {
            BytewarsLogger.LogWarning($"{result.Error.Message}");
            response.IsError = result.IsError;
        }
        OnJoinSessionCompleteEvent?.Invoke(response);
    }

Leave session​

  1. Similar to creating and joining sessions, you first need to define the event.

    public event Action<SessionResponsePayload> OnLeaveSessionCompleteEvent;

  2. Write a function to leave a session.

    protected internal void LeaveSession(string sessionId, [CallerFilePath] string? sourceFilePath=null)
    {
        var tutorialType = SessionUtil.GetTutorialTypeFromClass(sourceFilePath);
        _session.LeaveGameSession(sessionId, result => OnLeaveSessionCompleted(result, tutorialType));
    }

  3. The LeaveSession() function uses sessionId as a parameter to be passed to the SDK function _session.LeaveGameSession that calls the API to leave a session. As you can see, the function above has a callback function which requires the tutorial type similar to OnCreateSessionCompleted.

  4. Create a callback for LeaveSession(), which calls OnLeaveSessionCompleted.

    private void OnLeaveSessionCompleted(Result<SessionV2GameSession> result, TutorialType? tutorialType = null)
    {
        var response = new SessionResponsePayload();

        if (!result.IsError)
        {
            BytewarsLogger.Log($"Successfully left the game session");
            response.Result = result;
            response.TutorialType = tutorialType;
        }
        else
        {
            BytewarsLogger.LogWarning($"{result.Error.Message}");
            response.IsError = result.IsError;
        }
        OnLeaveSessionCompleteEvent?.Invoke(response);
    }

Resources​

Last updated on

On this page