Project setup and initialization

Project setup

General setup: Managed

Add the Scoreloop library into your project as a first step.
  • Right click Project properties

  • Go to C/C++ build -> Settings -> Tool Settings -> QCC Linker -> Libraries

  • Add "scoreloopcore" to Libraries (-l)

Screen showing how to add the Scoreloop library to a project in the Momentics IDE for BlackBerry.

General setup: Makefile

Add the Scoreloop library to the file in your project.

LDFLAGS += -lbps -lscoreloopcore -lscreen

Cascades environment

Modify the application's ".pro" file to include LIBS += -lscoreloopcore

Screen showing how to include the Scoreloop library in the .pro file of a Cascades project in the Momentics IDE for BlackBerry.

Take a look at our Sample Code before you build your project. Our repository is frequently updated with samples to help you!


Initialization consists of the following steps:

Step 1 Include the following Scoreloop header file in your application (all files that use Scoreloop API).

#include <scoreloop/scoreloopcore.h>

Step 2 Initialize the init-data structure by calling SC_InitData_Init(). The SC_InitData_t variable must have the same lifetime as the client variable.

Step 3 Create the SDK client instance by calling SC_Client_New(). Supply game id, game secret, game version and game-specific currency to the client instance. This step sets up the underlying infrastructure necessary to use Scoreloop in your game. An instance of the client should persist for the lifecycle of your game.

Only local game play is possible in CORPORATE LIABLE MODE. Here, the device forbids the use of Scoreloop. A connection request returns error code SC_DISABLED_DUE_TO_CORPORATE_LIABLE_MODE that needs to be handled and a suitable message displayed to the user.

A first time setup of the Games app will allow your game to post activities on it. If a user hasn’t setup the Games app on the device yet and starts your game, it will trigger the setup process of the Games app. Once the user finishes this setup, he will automatically return to your game. This mechanism requires that your game has posted a window; otherwise your game may be slayed by the operating system.
  • Before calling SC_Client_New a window needs to be posted. When no window is posted, your application could be slayed by the system as SC_Client_New might block for an unbounded amount of time.

  • Your game will not be brought to the foreground automatically, without a window posted beforehand.

  • Posting a window depends on the application environment (CoreNative, Cascades) you use. Please check the respective documentations on how to post a window in your environment. For example, with Core Native you would have to call screen_post_window() first, with Cascades you would have to wait for the posted() signal of Application::mainWindow().

  • In case the user chooses not to complete the Games app set-up, disable Scoreloop functionality (grey out the Scoreloop options on the menu with appropriate message) in your app. Posting a window as described above will get the user back to your app after hitting 'cancel' in the Games app set-up.

When creating the SC_Client the user might be prompted to enter BlackBerry ID credentials.

Sample code for creating the client instance:
//Step 2
SC_Error_t errCode;
SC_Client_h client;
SC_InitData_t initData;

// Initialize the platform adaptation object

// Optionally modify the following fields:
// initData.currentVersion = SC_INIT_CURRENT_VERSION;
// initData.minimumRequiredVersion = SC_INIT_VERSION_1_0;
// initData.runLoopType = SC_RUN_LOOP_TYPE_BPS;

//Step 3
// Create the client.
// aGameId, aGameSecret and aCurrency are const char strings that you obtain from Scoreloop.
// aGameVersion should be your current game version.
// aLanguageCode specifies the language support for localization in awards,
// for example, "en" for English, which is the default language.
errCode = SC_Client_New(&client, &initData, aGameId, aGameSecret, aGameVersion, aCurrency, aLanguageCode);

Always check the return value of errCode and handle the case where errCode!=SC_OK. For clarity of the samples, this comment is not included in all the code snippets.

Step 4 There are different ways to integrate Scoreloop into the main loop.

Core Native environment

  • Case 1: BPS event loop In the main loop of your application, dispatch bps events which have an event domain that equals SC_GetBPSEventDomain() to SC_HandleBPSEvent().
    while (true) {
    // Get next BPS event
    bps_event_t *event;
    bps_get_event(&event, -1);
    if (bps_event_get_domain(event) == SC_GetBPSEventDomain(&initData)) {
    SC_HandleBPSEvent(&initData, event);
    else {
    // Handle event like normal...
  • Case 2: Custom run loop In the main loop of your application, set run-loop-type to SC_RUN_LOOP_TYPE_CUSTOM before instantiating the client.
    // Do this before calling SC_Client_New:
    initData.runLoopType = SC_RUN_LOOP_TYPE_CUSTOM;
    // Your custom run loop
    while (true) {
    // Scoreloop event handling
    SC_HandleCustomEvent(&initData, SC_FALSE);
    // SC_FALSE will not block here, SC_TRUE will
    // Other event handling here...
    In this case, you must call SC_HandleCustomEvent() at regular intervals in your custom run loop.

Cascades environment

  • Create an instance of ScoreloopBpsEventHandler() in your main loop.
    ScoreloopBpsEventHandler::ScoreloopBpsEventHandler(SC_InitData_t initData) {
    initData_t = initData;
    // this only works after SC_Client_New was called
    void ScoreloopBpsEventHandler::event(bps_event_t *event) {
    SC_HandleBPSEvent(&initData_t, event);
    //In your Application pane object, create an instance of this class:
    eventHandler_ = new ScoreloopBpsEventHandler(initData_t);

Once the initialization is complete, you can integrate the Scoreloop features of your choice into your game.

Step 5 Release Scoreloop resources before closing your application.

Last modified: 2013-12-21

comments powered by Disqus