Core Implementation

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 turn-based tournaments instead, refer to Core Implementation Turn-Based. 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 SkillzDelegateinterface 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)tournamentWillBegin:(NSDictionary *)gameParameters
              withMatchInfo:(SKZMatchInfo *)matchInfo
{
    // This code is called when a player starts a game in the Skillz portal.
    NSLog(@"Game Parameters: %@", gameParameters);
    NSLog(@"Now starting a game…");

    // INCLUDE CODE HERE TO START YOUR GAME
    // …..
    // …..
    // …..
    // END OF CODE TO START GAME
}

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

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 tournamentWillBegin:withMatchInfo: method will be called when a player begins a Skillz match and should be used to launch your game. The tournamentWillBegin:withMatchInfo: 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.
    • SKZMatchInfo matchInfo is a data structure that contains information about the current match and the player in it. The data contained within can be used to display information to players or to power external analytics.
  • The skillzWillExit method is called when the Skillz portal is exited; it should be used to load the menu state of your game.

Further information on the SkillzDelegate 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’s supportedInterfaceOrientationsForWindow 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
{
    // INITIALIZE SKILLZ HERE

    // 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"
                                forDelegate:delegate
                            withEnvironment:SkillzSandbox];
    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"
                             forDelegate:delegate
                         withEnvironment:SkillzSandbox
                               allowExit:NO];

 

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>

-(void)multiplayerButtonPressed:(id)sender
{
    NSLog(@"Multiplayer button pressed, launching Skillz!");
    [[Skillz skillzInstance] launchSkillz];
}

Step 6: Using Game Parameters

You can use the game parameters that you set in Developer Portal by calling getMatchRules. This will return an NSDictionary of your game parameters which can provide each tournament a different experience for your users.

#import <Skillz/Skillz.h>

[[Skillz skillzInstance] getMatchRules];

 

Step 7: Report in-progress score to Skillz

To detect people cheating in your game, Skillz requires that you update the player’s score as it changes. This is accomplished by calling the updatePlayersCurrentScore method. This method must be called each time the current player’s score changes during a Skillz match.

For example, in many games this method is called when the player scores points, when the player is penalized, and whenever a time bonus is applied. It is OK for this method to be called very often. If a continuous in-game score is displayed to the player, this method is generally called as often as that score display is updated - usually by placing the updatePlayersCurrentScore call in the same place within the game loop.

For example:

// update the player score
self.score +=1;

// if in a skillz game
if ([[Skillz skillzInstance] tournamentIsInProgress]) {
    // update the current score
    [[Skillz skillzInstance] updatePlayersCurrentScore:self.score];
}

Calling this method is not required for turn-based games with objective-based win conditions.

 

Step 8: Report score to Skillz when a game finishes

Here is an example of reporting the score 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] displayTournamentResultsWithScore:score
            withCompletion:^{
                // 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:

[[Skillz skillzInstance] displayTournamentResultsWithScore:score
    withCompletion:^{
        // Code in this block is called when exiting to Skillz
        // and reporting the score.
        NSLog(@"Reporting score to Skillz…");
    }];

which is how you will report the player’s score to the Skillz servers at the end of a game.

 

Step 9: 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.