This sample demonstrates how to implement the join match lobby feature. It allows a player (known as the guest) to connect to an existing match lobby in order to play against another player.
Also, this sample implements the match lobby locking feature. Here we explain how the the invitation code is validated during the Join process.
For more information about how invitation code is managed during match lobby creation, check the Match Lobby Creation document.
- Read and complete the PlayFab configuration.
- Read and complete the Azure Function configuration.
- Read and complete the Cosmos DB configuration.
- Read the Search Match Lobby implementation guide.
- Read the Creation Match Lobby implementation guide.
Before starting explaining how this feature works, lets see how the game was implemented:
The implementation of the Match Lobby creation feature has the following steps:
The Unity Game is the first layer involved, once the game has retrieved the lobbies list the player clicks the Join button of the desired Match Lobby.
In case the lobby is locked, the game asks the guest for the invitation code, to include it into join the match lobby request. This invitation code corresponds to the invitation ID created during the Party network creation, and that is included in the network ID.
After that, the JoinMatchLobby method of the MatchLobbyHandler is executed, triggering the JoinMatchLobby Azure Function.
The Azure Function JoinMatchLobby is responsible for:
- Retrieving from Cosmos DB the match lobby by its ID.
- Validating the match lobby:
- It must exist. In another way, it returns the error
404 Not found. - It must not be full. In another way, it returns the error
502 Lobby full. - The guest trying to join must not be its creator. In another way, it returns the error
513 Requester is lobby creator. - If the lobby is locked:
- The invitation code must be included. In another way, it returns the error
432 Not invitation code included. - The invitation code must match with the
invitation IDextracted from the match lobby network ID. In another way, it returns the error514 Invalid invitation code.
- The invitation code must be included. In another way, it returns the error
- It must exist. In another way, it returns the error
- Updating the match lobby in Cosmos DB:
- Updates the current availability to zero.
The function receives the match lobby ID and optionally the invitation ID. Then, it will retrieve the match lobby from Cosmos DB by its ID, and finally, makes the validation described above.
Between the errors mentioned before, the code error 432 Not invitation code included is a special case: it means that the host has locked the lobby between the time that the guest listed the lobbies and tried to join. On the first try, the guest's game won't ask for the invitation code and won't send the Join request.
Considering this, the joining function returns a specific error, hence the game can handle it and restarts the joining flow asking for the invitation code and requesting again the joining to the match lobby.
Another topic to clarify is the getting of the invitation ID - the invitation code from the guest game perspective - from the network ID. During the lobby creation, the host includes the network ID returned by the PlayFab SDK into the request to create the match lobby and store it in Cosmos DB. Inside this network ID, which is a string, PlayFab includes the invitation ID, a pipe character - | - as a separator, and the network descriptor serialized.
In the joining process, the invitation ID is retrieved from the NetworkdId attribute of the match lobby taking the substring from the start until the | separator to be used in the validation of the invitation code sent by the guest.
After passing the validations, it sets the current availability to zero, and the match lobby is updated in Cosmos DB with its new state.
Finally, the Join function returns the network ID included in a wrapper, which includes the status code of the execution.
With this ID, the game joins to the Party network, which triggers an event on the host (OnRemotePlayersJoined event) that will end up rendering a new player in the match lobby players list.
For more details, you can read the documents about the match lobby creation and match start process.