Skillz Quantum Package (Unity)

In this article, we will walk through how to create a Photon Quantum powered real-time Skillz game using the Skillz Quantum Package. We recommend reviewing the documentation for Standard Gameplay in order to understand the basics of the Skillz SDK integration.

Overview

Skillz provides fair matchmaking based on player ratings. Once a match is confirmed, Skillz provides each client with a matchmakerMatchID which can be used for connecting to any game server (Photon, custom, or Skillz server).

Photon Quantum is a high-performance deterministic framework for online multiplayer games made with Unity. Developers can use Photon Quantum to add real-time capabilities to games that lend themselves to a deterministic predict-rollback model. You can access the documentation specific to the current stable version of Quantum here to learn more. The Skillz Quantum Package is aimed to make it easy for game developers to integrate a Photon Quantum game with Skillz by handling some of the Skillz specific integration points, such as:

• Using the Skillz-provided matchmakerMatchID to create and join the Photon room
• Displaying the player connection info in the Lobby scene
• Submitting scores
• Handling disconnects

It is encouraged to modify the scripts, scenes, and configuration files provided in the SKillz Quantum package to fit your specific use case.

Setup

Import

Follow the steps below to import the Skillz Quantum Package into your Quantum powered game.

1. Download and setup the Photon Quantum SDK. This step can be skipped if you already have a quantum project.
2. Open the Unity project included in your Quantum project. Make sure you are using a supported version of Unity.
3. Enter your Photon App ID in your Assets/Resources/PhotonServerSettings file.
4. Import the Skillz Unity SDK.
5. Download the Skillz Quantum Package and unzip the file.
6. Go to Assets > Import Package > Custom Package and import the skillz_quantum-X.X.unitypackage
7. Go to Window > TextMeshPro > Import TMP Essential Resources.

Setup Start Menu

In the Skillz Unity SDK, the Skillz Manager is configured to launch a game scene when a player starts a match. In a Quantum powered real-time Skillz game, the game scene will instead launch a lobby scene. The lobby scene will then connect the players for real-time play then launch a Quantum Game Scene. The Skillz Quantum Package provides you with an example Lobby scene that you should configure in the Skillz Manager.

An example start menu scene with this configuration can be found Under Assets/Skillz - Quantum/Scenes/SkillzQuantumStartMenu.

Lobby Setup

The lobby scene will then in turn handle connecting the player to a Photon master server, joining a room, waiting for all the players to join, then starting the Quantum game. It should do this automatically without player input.

The core loop flow for a Skillz Quantum powered game using the Skillz Quantum Lobby:

The Skillz Quantum Lobby can be found under Assets/Skillz - Quantum/Scenes/SkillzQuantumLobby. To add this to your game, add this scene under File > Build Settings > Scenes In Build. It is recommended to start with this lobby scene and modify it to suit your specific use case.

Open the SkillzQuantumLobby scene and click on the Skillz Quantum Lobby gameobject in the hierarchy. On this gameobject there is a SkillzQuantumLobby component. The SkillzQuantumLobby has a few configurable options:

Players In Match: The number of players in this match. This can be hardcoded here, but if your game supports matches with various player counts, this can be changed dynamically based on Skillz Match Parameters.

Runtime Config: The runtime configuration for the Quantum game.

Seed: The seed value is set programmatically in SkillzQuantumLobby.cs using the SkillzCrossPlatform.Random API. This will help ensure fairness when adding randomness to your simulation.

Map: The Quantum Map Asset for your game. This should contain a reference to the Quantum game scene you would like to launch.

Simulation Config: The configuration for the simulation settings for your game.

note

Depending on the project, your runtime config might have other parameters that need to be populated.

Use Dummy Room Name: Select this option to use a dummy room name for the Photon room. This can be useful for testing. Make sure to disable this for production and for testing Mobile vs Mobile.

Dummy Room Name: The value for the room name if using a dummy room name.

Sending Player Data

The SkillzQuantumLobby scene also contains a SendPlayerData Script. This can be found on the SendPlayerData GameObject in the Quantum lobby scene.

Either replace or edit this script to send the player data associated with players in your game.

More information on player data and player spawning in quantum can be found here.

Lobby Explanation

The Skillz Quantum Lobby Assets/Skillz - Quantum/Scripts/SkillzQuantumLobby.cs has the basic logic needed to start a Quantum Skillz match. A few things need to happen before the players can start playing, this should be handled without any player input as Skillz provides the matchmaking for the game. The basic logic flow is as follows:

When the Quantum Lobby is loaded it first calls Connect(). This will connect the player to the Photon Master Server for your application.

Upon successful connection the OnConnectedToMaster callback is then called. This will in turn call JoinRoom(). The JoinRoom function will then Create or Join a Photon Room with the name specified by SkillzCrossPlatform.GetMatchInfo().CustomServerConnectionInfo.MatchId. This is important as it ensures the players who are matched against each other will all join the same room.

The master client will then wait until all the players are in the room, the CheckForMatchStart() function will poll for this. When the number of players specified in the Players In Match field is reached the Master server will set a START_MATCH custom room property then call QuantumRunner.StartGame passing the runtime config as a parameter. This will load the Quantum game scene and hide the lobby UI.

The other clients will detect the START_MATCH room parameter and also call QuantumRunner.StartGame. This will load the Quantum game scene and hide the lobby UI.

The Skillz Quantum Lobby also handles disconnect callbacks in a simplistic way, as well as retries for connection and room joining.

Quantum Game Scene

Once the match is complete the Quantum game scene must submit a score by calling SubmitScore(). Before calling ReturnToSkillz() the Quantum simulation should be shut down, the room left, and disconnected from the Photon Master Server.

There is an example quantum game scene Assets/Skillz - Quantum/Scenes/SkillzQuantumGame.unity included with the Skillz Quantum Package.

In the Assets/Skillz - Quantum/Scripts/SkillzExampleQuantumMatchController.cs file, After the score is submitted, The Quantum Runner is Shutdown and the room is left.

void SubmitScore()
{
  SkillzCrossPlatform.SubmitScore(GetScore(), OnSuccess, OnFailure);
}

void OnSuccess()
{
  EndQuantumGame();
}

void OnFailure(string reason)
{
  SkillzCrossPlatform.DisplayTournamentResultsWithScore(GetScore());
  EndQuantumGame();
}
void EndQuantumGame()
{
  QuantumRunner.ShutdownAll();
  SkillzQuantumLobby.quantumClient.OpLeaveRoom(false);
}

Then in SkillzQuantumLobby.cs, the room being left is detected and a disconnect is triggered.

public void OnLeftRoom()
{
  Debug.Log("[Skillz Quantum Lobby] Left room");
  quantumClient?.Disconnect();
}

Then the client triggered disconnect is detected and ReturnToSkillz() is called. This will take the player back to the Skillz UI.

public void OnDisconnected(DisconnectCause cause)
{
  Debug.Log($"[Skillz Quantum Lobby] Disconnected: {cause}");
  lobbyStatus = SkillzLobbyStatus.DISCONNECTED;

  if (cause != DisconnectCause.DisconnectByClientLogic)
  {
    Debug.LogWarning("[Skillz Quantum Lobby] Connection Failed: " + cause.ToString());

    // Abort the match if a player disconnects during a match
    SkillzCrossPlatform.AbortMatch();
  }
  else
  {
   SkillzCrossPlatform.ReturnToSkillz();
  }
}

Handling Disconnects

When a player disconnects from the match, either on purpose or due to network or other issues, your game will have to handle this in a fair way. Disconnects must be handled in a way such that disconnecting during a match does not give a player an advantage.

SkillzQuantumLobby.cs contains a basic example of how to handle disconnects. It is encouraged to modify this if you would like to support reconnects or score submission on disconnection. Handling disconnects in a more advanced way can be tricky to implement but can substantially increase the quality of the player experience.

In the OnDisconnect callback we have some basic logic. If the player disconnects and it is not triggered by the client logic, we call SkillzCrossPlatform.AbortMatch().

public void OnDisconnected(DisconnectCause cause)
{
  Debug.Log($"[Skillz Quantum Lobby] Disconnected: {cause}");
  lobbyStatus = SkillzLobbyStatus.DISCONNECTED;

  if (cause != DisconnectCause.DisconnectByClientLogic)
  {
    Debug.LogWarning("[Skillz Quantum Lobby] Connection Failed: " + cause.ToString());

    // Abort the match if a player disconnects during a match
    SkillzCrossPlatform.AbortMatch();
  }
  else
  {
   SkillzCrossPlatform.ReturnToSkillz();
  }
}

Regions

Photon has a concept of regions. Players can only connect to each other if they are in the same region. Currently Skillz matchmaking does not support multiple regions. It is advised to choose one Photon region and use this for all matches.

Testing with Multiple Instances on Mac/PC

During development, it is convenient to test your game by launching multiple instances of your game on your Mac/PC/Linux. To do this follow the instructions below:

1. In the Skillz Quantum Lobby component, check the Use Dummy Room Name option. Enter a name in the Dummy Room Name field. (make sure to disable this for production builds and testing mobile vs mobile).
2. Go to File > Build Settings. Then set the SkillzQuantumLobby scene as the scene with index 0.
3. You can then build to PC/Mac/Linux and run multiple instances of your game.

Testing on Mobile

To test your game on mobile vs mobile, you will need to have sync enabled tournament templates set up on the developer console. More information on this can be found here.

Running the Skillz Quantum Example

Follow the steps below to run the Quantum Example project included in the Skillz Quantum Package:

1. Download and setup the Photon Quantum SDK. This step can be skipped if you already have a quantum project.
2. Open the Unity project included in your Quantum project. Make sure you are using a supported version of Unity.
3. Import the Skillz Unity SDK.
4. Download the Skillz Quantum Package and unzip the file.
5. Go to Assets > Import Package > Custom Package and import the skillz_quantum-X.X.unitypackage
6. Go to Window > TextMeshPro > Import TMP Essential Resources.
7. Go to Quantum > Show AssetDB Inspector. Click Generate Quantum Asset DB.
8. Go to file > build settings.
9. Add the three scenes under Assets/Skillz - Quantum/Scenes to the scenes in build. Make sure the SkillzQuantumStartMenu scene is at index 0.
10. Run the project by either Launching the game with SIDEkick in the editor or building to a mobile device.