Integrate challenges

Models and controllers

Challenges are modeled using SC_Challenge. The contender and the contestant are modeled using SC_User. Other important objects include SC_Score and SC_Money, which are used to model the challenge scores and stake respectively.

Scoreloop challenges use two data controllers: the SC_ChallengeController which manages individual instances of the SC_Challenge class, and the SC_ChallengesController, which manages lists of SC_Challenge objects.

Controller Tasks
SC_ChallengeController Create a challenge, accept a challenge, reject a challenge, submit a challenge
SC_ChallengesController Retrieve open challenges, retrieve the past challenges/challenge history of a user

Basic integration

Use cases to integrate challenges:

  • Create challenge.
  • Retrieve challenge(s).
  • Accept/reject challenge.

Use case 1: Create challenge

  1. Use the SC_Client instance to create an instance of SC_ChallengeController by calling SC_Client_CreateChallengeController().
  2. Create new challenge instance by calling SC_Client_CreateChallenge().
  3. Set the challenge on the SC_ChallengeController by calling SC_ChallengeController_SetChallenge().
SC_Error_t errCode;
SC_Client_h client;
unsigned long stake_value;
SC_ChallengeController_h myChallengeController;
SC_Challenge_h myChallenge;
SC_Money_h myStake;

// Step 1
// client - assumes the handle to the client exists
// aCallback is the callback to be registered
errCode = SC_Client_CreateChallengeController(client, &myChallengeController, aCallback, aCookie);

//Step 2
//Create the stake object if not present already.
//stake_value: amount of currency that the object will have in cents.
errCode = SC_Client_CreateMoney(client, &myStake, stake_value);

//Passing null as the contestant argument creates an open challenge.
//The contender is automatically equal to the current session user.
errCode = SC_Client_CreateChallenge(client, myStake, NULL, aMode, aLevel, &myChallenge);

//Step 3
//Setup new challenge on the challenge-controller.
SC_ChallengeController_SetChallenge(myChallengeController, myChallenge);

After the challenge is created, the contender plays the game and obtains a score. Once a score is available, the challenge is submitted to Scoreloop using SC_ChallengeController. Now, the challenge is available to other Scoreloop users to accept and play.

//Submit the challenge
//aScore is the score associated with the challenge
errCode = SC_ChallengeController_SubmitChallengeScore(myChallengeController, ascore);

Use case 2: Retrieve challenge(s)

SC_ChallengesController manages lists of SC_Challenge objects. You can use this controller to retrieve 2 lists:

  • List of challenges currently available to the user to play.
  • List of past challenges associated with the user (This list consists of all challenges completed by the user, and also any direct challenges created by the user).
  1. Create an instance of SC_ChallengesController.
  2. To request the appropriate challenge list, you can call one of the methods below:
  3. Await a successful server response using callbacks.
  4. After a successful request, the challenges will be loaded into SC_ChallengeList which can be accessed by calling SC_ChallengesController_GetChallenges().

int mode;
SC_Error_t errCode;
SC_Range_t aRange;
SC_Client_h client = ..;
SC_ChallengesController_h myChallengesController;
SC_ChallengeList_h myChallengeList;

// Step 1
// client - assumes the handle to the client exists
// aCallback is the callback to be registered
errCode = SC_Client_CreateChallengesController (client, &myChallengesController, aCallback, aCookie);

//Step 2
//Request challenges for the user to play
errCode = SC_ChallengesController_LoadOpenChallenges(myChallengesController);

errCode = SC_ChallengesController_LoadPastChallenges(myChallengesController, aRange);

//Step 3
//To be written by the developer to get the server response
void controllerCallback( void* userData, SC_Error_t completionStatus) {
    // Write code

//Step 4
//Access the retrieved list
myChallengeList = SC_ChallengesController_GetChallenges(myChallengesController);

You could also navigate or page through additional challenges, steps include:

  • Call SC_ChallengesController_HasNextRange() or SC_ChallengesController_HasPreviousRange() to determine if it is possible to page.
  • Use SC_ChallengesController_LoadNextRange() or SC_ChallengesController_LoadPreviousRange() to request the next or previous list of challenges from the server.
  • After a successful server response, access the SC_ChallengeList that was returned, by calling SC_ChallengesController_GetChallenges().

Use case 3: Accept/reject challenge

  1. Call SC_ChallengesController_LoadOpenChallenges() to request the list of challenges for the user.
  2. Await notification of success using asynchronous callback.
  3. Call SC_ChallengesController_GetChallenges() to access the list of challenges retrieved.
  4. Look for the individual challenge to be accepted or rejected.
  5. To accept or reject the challenge, call:
SC_Error_t errCode;
int index;
SC_ChallengeList_h myChallengeList;

//Step 1
//Use the ChallengesController to request the list of challenges
errCode = SC_ChallengesController_LoadOpenChallenges(myChallengesController);

//Step 2
//Await notification of success using asynchronous callback.
//To be written by the developer

// Step 3
//On receiving a success notification, access the list.
myChallengeList = SC_ChallengesController_GetChallenges(myChallengesController);

//Step 4
//To Access individual challenges.
//index points to an entry in the list. index = 0 reads the first entry from the list
myChallenge = SC_ChallengeList_GetAt(myChallengeList, index);

//ChallengeController sets the selected challenge for the next step
SC_ChallengeController_SetChallenge(myChallengeController, myChallenge);

//Step 5
//To accept the challenge
errCode = SC_ChallengeController_AcceptChallenge(myChallengeController);

//To reject the challenge
errCode = SC_ChallengeController_RejectChallenge(myChallengeController);

Attach a challenge context

SC_Challenge object is used to set/retreive a challenge context.

Context is not taken into an account when evaluating the winner.

Controller Task
SC_Challenge_SetContext() Set a challenge context.
SC_Challenge_GetContext() Retreive a challenge context.

Click here to see if your implementation covers the essential features.

Default UI: Challenges

  • Create direct/open challenges.
  • Display challenge inbox and history.
  • Option of a rematch at the end of gameplay.
  • Virtual currencies at stake for every challenge.

For details on implementation, see Integrate Default UI.

Last modified: 2014-05-14

Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus