Use Photon Multiplayer with AGS Matchmaking

Last updated on July 20, 2024

Overview

AccelByte Gaming Services (AGS) uses a uniquely generated session ID for the multiplayer network room name, which allows for the use of Photon Multiplayer. The services used to make this possible are AGS Authentication, Lobby (for matchmaking websocket events), Matchmaking (for matchmaking API), and Session (for tracking game sessions).

This article provides information on how Photon works with AGS, along with steps on how to integrate it.

Prerequisites

To complete all the steps in this article, you will need:

• AGS Authentication, Lobby, Matchmaking, and Session have all been integrated into your game and configured properly.

Photon with AGS flow

See the following flow diagram to understand how Photon works with AGS:

Authentication

To be able to use the services within AGS required for matchmaking, the player must be authenticated and logged in. This can be done using the User service wrapper.

 public void Login()
{
    var userWrapper = AccelByteSDK.GetClientRegistry().GetApi().GetUser();

    userWrapper.LoginWithDeviceId((Result<TokenData, OAuthError> result) =>
    {
        if (result.IsError)
        {
            Debug.Log($"Error- [{result.Error.error}]{result.Error.error_description}");
             // Handle login error
        }

         // Login success, continue with flow.
    
    });
}

Connect and set up relevant Lobby events

AGS Matchmaking uses websocket for events. The websocket connection and adding listeners to events is done through the AGS Lobby service wrapper.

 public void ConnectAndSetupLobby()
{
    var lobbyWrapper = AccelByteSDK.GetClientRegistry().GetApi().GetLobby();

    lobbyWrapper.Connect();

    // Make sure that lobbyWrapper.IsConnected == true before calling StartMatchmaking()
    // Alternatively, you can also trigger StartMatchmaking via an event

    lobbyWrapper.Connected += () =>
    {
        StartMatchmaking();
    }

    // Matchmaking events
    lobbyWrapper.MatchmakingV2MatchmakingStarted += OnMatchmakingStarted;
    lobbyWrapper.MatchmakingV2MatchFound += OnMatchFound;
    lobbyWrapper.MatchmakingV2TicketExpired += OnTicketExpired;
    lobbyWrapper.SessionV2InvitedUserToGameSession += OnReceivedSessionInvite;
}

Start matchmaking

To start matchmaking, you will need to create a matchmaking ticket. This can be done using the AGS Matchmaking service wrapper.

public void StartMatchmaking()
{
    var lobbyWrapper = AccelByteSDK.GetClientRegistry().GetApi().GetLobby();
    if (!lobbyWrapper.IsConnected)
    {
        Debug.LogWarning("Lobby is not connected, unable to start matchmaking");
        return;
    }

    var matchmakingWrapper = AccelByteSDK.GetClientRegistry().GetApi().GetMatchmakingV2();

    var optionalParams = new MatchmakingV2CreateTicketRequestOptionalParams()
    {
        // Keep this null if the player is solo.
        // If the player is in a party, put the party session ID here.
        sessionId = null,

        // Keep this null if you don't plan for the player
        // to be able to select/prioritize gameplay options.
        // You can put any value here and matchmaking will
        // try to match players with the same attribute values.

        attributes = new Dictionary<string, object>()
        {
            { "map", 1 },
            { "difficulty", "normal" }
        }
    };

    matchmakingWrapper.CreateMatchmakingTicket("yourMatchPoolName", optionalParams, result =>
    {
        if (result.IsError)
        {
            Debug.Log($"Error- [{result.Error.Code}] {result.Error.Message}");
            // Handle matchmaking API error here
        }

        // Matchmaking started, continue with flow.
    });
}

Photon integration via matchmaking event callbacks

These are the suggested implementations for the callbacks to the AGS Lobby matchmaking events from above. You are free to extend or modify them as per your needs. Photon integration is done after the player has joined the AGS game session (end of matchmaking process, OnReceivedSessionInvite). You will be using the game session's ID as the room name to create or join depending on your chosen Photon framework.

private void OnMatchmakingStarted(Result<MatchmakingV2MatchmakingStartedNotification> result)
{
    // Called when the party leader has successfully started matchmaking.
    // Do your setup for other party members here.
    // (for example, notify players that matchmaking has started, show timer UI, etc.)

    if (result.IsError)
    {
        Debug.Log($"Error- [{result.Error.Code}] {result.Error.Message}");
        // Handle matchmaking event error here

        return;
    }
}

private void OnMatchFound(Result<MatchmakingV2MatchFoundNotification> result)
{
    // Called when a match has been found.
    // Do your setup/preparations here.
    // (for example, preloading assets in background, show match found UI, etc.)

     if (result.IsError)
     {
        Debug.Log($"Error- [{result.Error.Code}] {result.Error.Message}");
        // Handle matchmaking event error here

        return;
     }
}

private void OnTicketExpired(Result<MatchmakingV2TicketExpiredNotification> result)
{
    // Called when ticket has reached the set
    // expiration timeout duration without finding a match.
    // You can safely call StartMatchmaking() again here
    // to automatically restart the process (for party leader only, if in a party),
    // or notify the players that no match has been found (if they ever have restricting attributes).

    if (result.IsError)
    {
        Debug.Log($"Error- [{result.Error.Code}] {result.Error.Message}");
        // Handle matchmaking event error here

        return;
    }

    StartMatchmaking();
}

private void OnReceivedSessionInvite(Result<SessionV2GameInvitationNotification> result)
{
    // Called when a match session is ready and has invited the player to join.
    // You can use the sessionId from the result as the room
    // name for your Photon room to join.

    if (result.IsError)
    {
        Debug.Log($"Error- [{result.Error.Code}] {result.Error.Message}");
        // Handle matchmaking event error here

        return;
    }

    // Store this somewhere persistent
    // as it will be used later on to clean up the session after the game ends or the player has left/disconnected.
    string sessionId = result.Value.sessionId;
    var sessionWrapper = AccelByteSDK.GetClientRegistry().GetApi().GetSession();

    sessionWrapper.JoinGameSession(sessionId, joinResult =>
    {
        if (joinResult.IsError)
        {
            Debug.Log($"Error- [{result.Error.Code}] {result.Error.Message}");
            // Handle session API error here

            return;
        }

        // Join session success, proceed with Photon networking.

        // Photon PUN:
        // PhotonNetwork.JoinOrCreateRoom(sessionId, roomOptions, typedLobby);

        // Photon Realtime / Quantum:
        // loadBalancingClient.OpJoinOrCreateRoom(new EnterRoomParams {
        //      RoomName = accelByteSessionIdFromLobbyEvent
        // });

        // Photon Fusion:
        // networkRunner.StartGame(new StartGameArgs {
        // SessionName = accelByteSessionIdFromLobbyEvent
        // });
    });
}

Session cleanup

Once your game has finished or if the player has left/disconnected, be sure to also call leave on the AccelByte session service wrapper for clean up.

private void OnGameEnd()
{
    var sessionWrapper = AccelByteSDK.GetClientRegistry().GetApi().GetSession();

    sessionWrapper.LeaveGameSession("sessionIdFromMatchmaking", result =>
    {
        if (result.IsError)
        {
            Debug.Log($"Error- [{result.Error.Code}] {result.Error.Message}");
            // Handle session API error here

            return;
        }
    });
}