Core Implementation: Turn Based

Core Implementation Turn-Based

Now that the Skillz SDK is imported into your project, it’s time to add multiplayer tournaments to the game using the Skillz API. Please note, you cannot run the Skillz interface directly in the Unity editor; you will need to rebuild and run your XCode project to test your changes.

After following these steps, you will be able to enter the Skillz portal from your game, join and play in tournaments, finish those games, and return to the Skillz portal while reporting scores to our server.

If you wish to support the more common non-turn-based tournaments instead, refer to Core Implementation. You may support both types of tournaments in one app.


Step 1: Add a multiplayer button to your game’s menu

Players will need a place to enter Skillz from the main menu of your game. The most effective way to do this is to have a button that clearly explains to the user they are entering the Skillz multiplayer interface. Commonly developers choose button labels such as Multiplayer or Tournaments.


Step 2: Launch the Skillz portal from the multiplayer button

All code for the Skillz plugin is in the SkillzSDK namespace, and all calls to the API are done through the SkillzSDK.Api class. Here is an example of how to launch Skillz when the player hits a button:

UnityEngine; using System.Collections; public class Multiplayer : MonoBehavior { void OnGUI() { if (GUI.Button(new Rect(Screen.width / 2 - 25, 25, 50, 25), "Multiplayer")) { SkillzSDK.Api.LaunchSkillz(SkillzSDK.Orientation.Landscape); } } }

As you can see, launching Skillz itself is just a single line of code!

Skillz will be automatically initialized on Awake() in the first scene, so make sure not to launch Skillz before then! If you really want to immediately launch Skillz instead of adding a button, do it on Start().

The parameter for SkillzSDK.Api.LaunchSkillz() is a SkillzSDK.Orientation, which can be either Landscape or Portrait. Your game must always use the same orientation due to certain features of the SDK.


Step 3: Report score to Skillz when the turn is over

When a turn is over, the game needs to give control back to the Skillz UI and tell it what happened during the turn. The code to do that should look something like this:

if (turnIsOver)
    // if in a Skillz game, submit to Skillz.
    if (SkillzSDK.Api.IsTournamentInProgress)
        //If your game has scoring, use the following method:
        SkillzSDK.Api.FinishTurn(gameData, roundOutcome, matchOutcome,
                                 playerTotalScore, opponentTotalScore);
        //Otherwise, if you only have objectives (e.x. Chess), use this method:
        SkillzSDK.Api.FinishTurn(gameData, roundOutcome, matchOutcome)

There are a few key aspects to this example.

The first is:


which will return a bool that signifies whether the player is in a Skillz tournament.

The next is:


which is how you will report the state of the match after the player finished their turn. This method takes in several parameters that are crucial for turn-based play:

  • gameData is a Base64 string representing your current game state. When the next turn starts, this string will be given back to the game to set up the match’s state.
  • roundOutcome describes the outcome of this round. A “round” is a set of two turns – one for each player – and if your game has the concept of individual winners for each round, you can use this argument to display that data. If your game doesn’t support this, just always pass SkillzSDK.TurnBasedRoundOutcome.NoOutcome.
  • matchOutcome determines the outcome of the match. If anything other than SkillzSDK.TurnBasedMatchOutcome.NoOutcome is passed, the match immediately ends.
  • playerTurnScoreStr is the score the for the current player for the current turn, as a string. This is used for display purposes only; if the player doesn’t have a score, then pass null.
  • playerTotalScore is the total score for the player across all turns. This is also used for display only, and can take float.NaN as a value if the player doesn’t have a score.
  • opponentTotalScore is just like playerTotalScore, but for the opponent.

Step 4: Handle players leaving during active tournaments

If your game allows players to forfeit before the game ends normally, Skillz provides a special API that will notify the Skillz server that the player has forfeited, and return to the Skillz portal. This is done by calling the AbortGame method.

Here is an example of how this call might be used:

if (GUI.Button(new Rect(800, 10, 100, 100), "Abort Game"))
    if (SkillzSDK.Api.IsTournamentInProgress)

When this method is called, the player automatically loses the game they are currently in, and they are taken back to the Skillz portal.

Ask the player whether they’re sure they want to abort. Otherwise, the game could be forfeited by accident, which is bad when money is at stake.


Step 5: Create callbacks for the Skillz UI

Now that we have the in-game behavior for Skillz, we need scripts that respond to messages from the SDK so that we know when a tournament starts, when the Skillz UI is exiting, etc. You will want to respond to these kinds of messages to control the game. For example, you should return to the main menu when the player quits the Skillz UI.

Skillz provides abstract base classes that help you respond to these messages. The first class is SkillzDelegateBase. This class reacts to the messages about the Skillz UI itself. You must create a script that inherits from it and override any callbacks you find useful.

The most important callback to override is OnSkillzWillExit(). After quitting Skillz, the player should always return to the main menu (or whatever scene he was in when the Skillz UI first loaded). You could implement this function as follows:

class MyDelegateBase : SkillzSDK.SkillzDelegateBase
    public override void OnSkillzWillExit()

Step 6: Create callbacks for Skillz tournaments

You should make another script, this time inheriting from SkillzDelegateTurnBased to respond to messages about Skillz tournaments. The most important callback offered by this class is OnTurnBasedTournamentWillBegin(), which is called when a match is about to start. This callback provides you with quite a lot of information about the match being played, including:

  • A dictionary of the custom Game Parameters you set in your game’s settings in the developer portal
  • The gameData string you passed in at the end of the last turn (assuming at least one turn has already been taken)
  • The results of every round played so far


If your game also supports standard (non-turn-based) tournaments, please refer to Core Implementation to also create a SkillzDelegateStandard script before moving on to Step 7.

class MyDelegateTurnBased : SkillzSDK.SkillzDelegateTurnBased
    public override void OnTurnBasedTournamentWillBegin(SkillzSDK.TurnBasedMatch m)
        //Assume that on the Developer Portal, I gave each tournament type a Game
        //Parameter called "level" whose value is the level to use for that match.

        //If at least one player has already taken a turn in this match...
        if (m.ContinueMatchData.HasValue)
            //...get the game state from the end of the last turn.

Another useful callback is OnTurnEnd(), which is called when a player successfully finishes a turn. You could use it to clean up state or resources from the game scene.

An optional but highly-recommended feature is the ability for a player to review the state of an ongoing match while waiting for their opponent to take a turn. If you decide to implement this ability, you should implement the callbacks OnTurnBasedReviewWillBegin() and OnReviewEnd() in the same way you implementedOnTurnBasedTournamentWillBegin() and OnTurnEnd().


Step 7: Add a Skillz delegate GameObject to your game.

Now that we have scripts to respond to messages, you need to create an object that will use these scripts. Fortunately, our SDK can handle this task for you! Just open up the initial game scene that Unity will load when starting a new game, and select Skillz -> Generate Delegate in the menu to create an object that has your skillz delegate scripts.

This object automatically prevents itself from being deleted when switching to a new scene. Additionally, don’t worry if the starting scene for your game will be loaded multiple times; the object knows how to manage itself and delete any duplicates. Just make sure to never delete or disable the object yourself!

You may notice that this new object already has the scripts you created. It also has two other scripts, including SkillzDelegateInit. SkillzDelegateInit contains two properties in the Inspector that you should customize:

  • Game ID is your Skillz game ID; this is given in the “Go Live” step of the Developer Portal Game Wizard.
  • Skillz Environment is the environment Skillz should run in:
    • Sandbox is the testing environment when developing your game.
    • Production is the final environment when releasing your game, which allows you to play tournaments for real cash.

Now that you have completed all the steps to finish your core Skillz implementation, all the pieces are in place for fun, competitive play between people. At this point, you should be able to enter the Skillz portal from your game, enter and compete in tournaments, finish those tournaments, and get the results. You can also quit your game early, if applicable.


Play Your First Game!

Congratulations! After completing the above steps, the Skillz SDK should be properly integrated into your project. Using XCode, you should now be able to put a build on your device and play your first Skillz tournament!

The next step is to make sure your tournaments are fair to all players.