Set up the Skillz Delegate

Now that the Skillz SDK is imported in to your Marmalade project, it’s time to add multiplayer tournaments to your 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 tournament matches, finish those matches, and return to the Skillz portal while reporting scores to our server.

 

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: Initialize Skillz in your game

Here is an example of how to initialize Skillz:

#include "SkillzSDK.h"

int main(int argc, char* argv[])
{
    // 156 is the game ID that was given to us by the Skillz Developer Portal.
    // S3eSkillzSandbox specifies that we will use the sandbox server since we
    // are still developing the game.
    // S3eSkillzProduction specifies that we will use the production server since
    // the game is ready for release to the AppStore
    SkillzInit("156", S3eSkillzSandbox);
}

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

S3eSkillzProduction should only be used when your app is ready to be uploaded to the app store. Use Sandbox when testing.

Two important lines of this snippet are:

#include "SkillzSDK.h"

which includes all the needed methods to use Skillz, and:

SkillzInit("156", S3eSkillzSandbox);

which starts up the SDK inside your game. Note that this will not actually launch the Skillz portal.

 

Step 3: Launch the Skillz portal from the multiplayer button

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

#include "SkillzSDK.h"

void MultiplayerButtonPressed()
{
    // Launching Skillz in landscape mode
    SkillzLaunch(S3eSkillzLandscape);
}

Skillz requires your game to only ever use one orientation due to certain features of the SDK.

S3eSkillzLandscape is a member of the S3eSkillzEnvironment enumeration. The other value is S3eSkillzPortrait.

 

Step 4: Handle the start of a tournament

Since control of your application is given over to Skillz once you launch, Skillz uses a callback system to handle important events that happen when a player is in the Skillz portal. The majority of these events are optional and will be covered later on this page. One required event is SKILLZSDK_CALLBACK_TOURNAMENT_WILL_START.

Here is an example of how to register that callback:

#include "SkillzSDK.h"

int main(int argc, char* argv[])
{
    // Unrelated start up code here

    // Register a method as a the callback handler
    SkillzSDKRegister(SKILLZSDK_CALLBACK_TOURNAMENT_WILL_START_WITH_MATCH_DATA, TournamentWillStart, NULL);

    // Initialize Skillz here
}

// Callback handler implementation
int32 TournamentWillStart(void* systemData, void* userData)
{
    // Start the game part of your application
    return S3E_RESULT_SUCCESS;
}

There are a few key aspects to this example. The first is:

SkillzSDKRegister(SKILLZSDK_CALLBACK_TOURNAMENT_WILL_START_WITH_MATCH_DATA,
                  TournamentWillStart, NULL);

This call is what registers the TournamentWillStart method as the callback for the SKILLZSDK_CALLBACK_TOURNAMENT_WILL_START_WITH_MATCH_DATA event. The second parameter on SkillzSDKRegister is what is passed to the userData parameter, described below.

The next part is:

int32 TournamentWillStart(void* systemData, void* userData)

This method signature is needed for Skillz callbacks, which obey the method signature required by Marmalade’s s3eCallbacks. For your implementation, S3E_RESULT_SUCCESS should be returned. Of the two parameters, systemData contains a SkillzMatchInfo struct that includes a string of Game Parameters and userData is defined by the register method described directly above.

 

Step 5: Handle exits from the Skillz portal

Another event that will need to be handled by a callback is the SKILLZSDK_CALLBACK_SKILLZ_WILL_EXIT event. This event is fired when a user exits from the Skillz portal back into the menu menu of your game. You should use this callback to transition your application back to its home state.

This callback is registered in the same way as in the last example:

#include "SkillzSDK.h"

int main(int argc, char* argv[])
{
    // Unrelated start up code here

    // Register a method as a the callback handler
    SkillzSDKRegister(SKILLZSDK_CALLBACK_SKILLZ_WILL_EXIT, SkillzWillExit, NULL);

    // Initialize Skillz here
}

// Callback handler implementation
int32 SkillzWillExit(void* systemData, void* userData)
{
    // Load your games menu state
    return S3E_RESULT_SUCCESS;
}

The method signature for this callback is similar as well:

int32 SkillzWillExit(void* systemData, void* userData)

Once again, S3E_RESULT_SUCCESS should be returned at the end of the function. systemData in this case, can be ignored, anduserData will be whatever is passed into the register function.

 

Step 6: 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 SkillzUpdatePlayersCurrentScore 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 SkillzUpdatePlayersCurrentScorecall in the same place within the game loop.

For example:

// update the player score
score +=1;

// if in a skillz game
if (SkillzTournamentIsInProgress()) {
    // update the current score
    SkillzUpdatePlayersCurrentScore(score);
}

You will notice that the SkillzTournamentIsInProgress method is used in many of these examples. This method returns a s3eBool that signifies if the player is in a Skillz tournament or not. Commonly, this is used to test if Skillz-specific functionality should be called.

 

Step 7: Report the final 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 (SkillzTournamentIsInProgress()) {
        // The game ended and it was in a Skillz tournament,
        // so report the score and go back to Skillz.
         SkillzReportScore(score);
    }
}

Note the line:

SkillzReportScore(score, NULL);

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

 

Step 8: Handle players leaving during tournament games

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()
{
    if (SkillzTournamentIsInProgress()) {
        // 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.
        SkillzNotifyPlayerAborted();
    }
}

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.

Here we use

SkillzTournamentIsInProgress()

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

 

Step 9: Lock the Marmalade orientation

We recommend locking the orientation on your game with s3eSurfaceSetInt() to enforce the use of only one orientation. This can be done simply by invoking s3eSurfaceSetInt when your game starts up.

For example:

int main(int argc, char* argv[])
{
    // Use S3E_SURFACE_PORTRAIT for portrait applications and
    // S3E_SURFACE_LANDSCAPE for landscape applications
    s3eSurfaceSetInt(S3E_SURFACE_DEVICE_ORIENTATION_LOCK, S3E_SURFACE_PORTRAIT);
}

Step 10: (Optional) Register additional Skillz callbacks

The Skillz Marmalade wrapper provides additional events that may be useful to your application. You can register callbacks for these with SkillzSDKRegister(). While none of the optional events are required, they can be used to hook into key events and provide your application with an opportunity to cleanup state and allocate / deallocate resources.

These optional events are contained in the SkillzSDKCallback enum and includes the following:

  • SKILLZSDK_CALLBACK_SKILLZ_DID_LAUNCH
  • SKILLZSDK_CALLBACK_REPORT_SCORE_HAS_COMPLETED
  • SKILLZSDK_CALLBACK_NOTIFY_ABORT_HAS_COMPLETED
 

Next Steps

Congratulations! After completing the above steps, the Skillz SDK should be properly integrated in your project. Using Xcode or the Marmalade Hub, 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 for all players.