Core Implementation: Turn Based

Core Implementation Turn-Based

Now that the Skillz SDK is imported into your XCode project, it’s time to add multiplayer tournaments to the game using the Skillz API.

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 non-turn-based tournaments instead, refer to Core Implementation. You may support both types of tournaments in one app; just have your delegate implement all the necessary callbacks for both tournament types.


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: Implement delegate methods

Since control of your application is given over to Skillz once you launch the Skillz portal, the SDK provides a SkillzTurnBasedDelegate interface that can be implemented to tie into key events that can be fired by your users.

The majority of these methods are optional and are provided as a way to allow your application with an opportunity to cleanup state and allocate/deallocate resources. However, there are a few required methods.

Where these methods are best implemented depends on the structure of your application. Here is an example of an implementation inside of AppDelegate:

#import <Skillz/Skillz.h>

@implementation AppDelegate

- (void)turnBasedTournamentWillBegin:(NSDictionary *)gameParameters
                 withTurnInformation:(SKZTurnBasedMatchInfo *)currentGameStateInfo
    // This code is called when a player starts a game in the Skillz portal.
    NSLog(@"Current turn information: %@", currentGameStateInfo);
    NSLog(@"Game Parameters: %@", gameParameters);
    NSLog(@"Now starting a game…");

    // …..
    // …..
    // …..

- (void)skillzWillExit
    // This code is called when exiting the Skillz portal
    //back to the normal game.
    NSLog(@"Skillz exited.");

- (SkillzOrientation)preferredSkillzInterfaceOrientation
    // return SkillzPortrait for portrait based applications
    // return SkillzLandscape for landscape based applications
    return SkillzPortrait;

The import statement:

#import <Skillz/Skillz.h>

will include all of the needed methods to use Skillz in your game.

The example also has stub implementations of the following required methods:

  • The turnBasedTournamentWillBegin method will be called when a player begins a Skillz match and should be used to launch your game. The method gets called with two parameters:
    • NSDictionary gameParameters is a dictionary that is passed in to this method by the Skillz framework, and contains the Game Parameters configured for the tournament the player is about to start. You can use these Game Parameters to configure different types of games for different tournaments.
    • SKZTurnBasedMatchInfo currentGameStateInfo is an object that will give information relevant to the current turn.
  • The skillzWillExit method is called when the Skillz portal is exited; it should be used to load the menu state of your game.
  • The final required method, preferredSkillzInterfaceOrientation, is used to set the orientation of your game.

Further information on the SkillzTurnBasedDelegate interface can be found in the Skillz Apple docs.


Step 3: Lock the app’s orientation

Due to certain features of the SDK, your app must stick with a single orientation – either Portrait or Landscape. This is done by overriding your app delegate’ssupportedInterfaceOrientationsForWindow method like so:

@implementation AppDelegate

- (NSUInteger)application:(UIApplication *)application supportedInterfaceOrientationsForWindow:(UIWindow *)window
    //If your app uses landscape:
    return UIInterfaceOrientationMaskLandscape;
    //If your app uses portrait:
    return UIInterfaceOrientationMaskPortrait;

Step 4: Initialize Skillz in your game

Here is an example of how to initialize Skillz:

#import <Skillz/Skillz.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions

    // This class will depend on where the SkillzDelegate is implemented
    // In this case, it's AppDelegate
    AppDelegate *delegate = self;

    // 156 is the game ID that was given to us by the Skillz Developer Portal.
    // SkillzSandbox specifies that we will use the sandbox server since we
    // are still developing the game.
    // SkillzProduction specifies that we will use the production server since
    // the game is ready for release to the AppStore
    [[Skillz skillzInstance] initWithGameId:@"156"
    return YES;

Your game ID is given in the “Go Live” step of the Developer Portal Game Wizard.

SkillzProduction should only be used when your app is ready to be uploaded to the app store.

The call to the initWithGameId:forDelegate:withEnvironment: method is what will start up the Skillz SDK inside your game. Note, this will not launch the Skillz interface.

Optionally: If your game launches directly into the Skillz SDK and contains only the Skillz UI for playing, you may specify that a user should not be given the option to exit the Skillz SDK.

Here is an example of how to initialize Skillz so that it cannot be exited:

 [[Skillz skillzInstance] initWithGameId:@"156"

Step 5: Launch the Skillz portal

Here is an example of how to launch Skillz when the player hits the multiplayer button you added earlier:

#import <Skillz/Skillz.h>

    NSLog(@"Multiplayer button pressed, launching Skillz!");
    [[Skillz skillzInstance] launchSkillz];

Step 6: Report score to Skillz when a turn finishes

Here is an example of reporting the turn result to Skillz and exiting to the Skillz portal:

if (isGameOver) {
    if ([[Skillz skillzInstance] tournamentIsInProgress]) {
        // The game ended and it was in a Skillz tournament,
        // so report the score and go back to Skillz.
        [[Skillz skillzInstance] completeTurnWithGameData:gameData
                // Code in this block is called when exiting to Skillz
                // and reporting the score.
                NSLog(@"Reporting score to Skillz…");

There are a few key aspects to this example.

The first is:

[[Skillz skillzInstance] tournamentIsInProgress]

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

The next is the method:


which is how you will report the player’s score to the Skillz servers at the end of a turn. This method takes in several parameters that are crucial for turn-based play:

  • gameData is a Base64 NSString representing your current game state. This string is part of the SDKTurnBasedMatchInfo struct given to you in theturnBasedTournamentWillBegin callback. Details of the implementation will vary depending on the game, but it is recommended that only essential information is stored in gameData.
  • playerScore is the score the for the current player on the current turn. This is used for display purposes only; if your game doesn’t have a score, a nil value should be passed.
  • playerCurrentTotalScore is the total score for the player. This is also for display purposes only, and a nil value can be used in place of a score.
  • opponentCurrentTotalScore is exactly like playerCurrentTotalScore, but with the opponent’s score.
  • roundOutcome determines the outcome of the round. If your game doesn’t have the concept of per-round winners, just always returnkSKZRoundOutcomeRoundNoOutcome.
  • matchOutcome determines the outcome of the match. If anything other than kSKZMatchOutcomeMatchNoOutcome is passed, the match immediately ends.

Refer to the apple docs for more information about round outcomes and match outcomes.


Step 7: Handle players leaving during active tournaments

If your game allows players to quit before the game ends normally, Skillz provides a special API that will notify the Skillz server that the player has forfeit, and return to the Skillz portal. Here is an example of how this call might be used:

-(void) abortButtonPressed:(id)sender
    NSLog(@"Player is quitting the game.");
    if ([[Skillz skillzInstance] tournamentIsInProgress]) {
        // We are in a Skillz tournament, so abort the game using Skillz API
        // This will report an auto-loss to the Skillz server,
        // and return the player to the Skillz portal.
        [[Skillz skillzInstance] notifyPlayerAbortWithCompletion:^() {
          // Code in this block is run when Skillz aborts the game,
          // reports a forfeiture to the server,
          // and returns to the Skillz portal.
          // This can typically be used to clean up/reset the game.
          NSLog(@"Player is forfeiting the game");

Here we use

[[Skillz skillzInstance] tournamentIsInProgress]

again to make sure we are playing a Skillz tournament, and if so, we report the abort to Skillz.

You will want to add an additional check around how the player can quit the game, warning them that if they quit, they will automatically lose. This can ensure players don’t accidentally quit out of tournaments where they have money at stake.


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.