Making your game social with Scoreloop

Game Development

In my last blog post, you got Up and Running with Cocos2d-x library on BlackBerry 10. Assuming you are well ahead in porting your game, may I suggest a wonderful idea to make your game go viral? Make use of Scoreloop and the power of our Social Gaming hub.

BlackBerry 10 comes with a lot of surprises for gamers including the introduction of the BlackBerry Social Gaming Hub via the Games app. Gamers can now meet new friends, discover popular games and share their experience through the Games app.

It doesn’t stop there. The Games app enables Scoreloop-integrated games to automatically post activities such as achievements, challenge results and high scores to a gamer’s timeline. With over 250 Million users already playing Scoreloop-powered games across platforms, this gives any game a great chance make a viral impact. There are also some good featuring opportunities in the “Games” section of the games app.

In this post, I will walk you through the process of integrating Scoreloop into the cocos2d-x BBTemplate project we setup in my last blog post. The instructions are generic enough and can applied to any other open library with minor modifications.

Set up Scoreloop account

First, create a Scoreloop developer account at https://developer.Scoreloop.com. If you already are a BlackBerry user and have a BlackBerry ID, there is no need to create a new account. Simply choose “Login with BlackBerry ID” and enter your BlackBerry ID credentials.

After logging in, you will see three options. You can skip the first option as the BlackBerry 10 Native SDK comes preloaded with the Scoreloop SDK and there is no need to download any external libraries. Now create a game title and choose “BlackBerry” option. If the game’s name is not already taken, a profile will be created.

Once the game account is created, you will see various options to customize your game’s social gaming options. If you already have an account and have already published titles using Scoreloop, you can choose the newly created game from the drop down menu.

Getting started

Follow the instructions below to include the Scoreloop library to the BBTemplateProject.

  1. Right click the game project settings
  2. Select C/C++ Build -> Settings -> Tool Settings -> QCC Linker
  3. Add “scoreloopcore” library to the list of Libraries

To be able to make use of Scoreloop’s features, the infrastructure need to be setup and it all starts with creating an instance of Scoreloop client. Add Scoreloop’s main header file in HelloWorldScene.h and add the below mentioned Scoreloop variables in the “HelloWorld” class.

#include <Scoreloop/Scoreloopcore.h>

In your Scoreloop account, fetch the application data corresponding to your game title from the “Game Overview” section. It should look something like this:

Platforms	BlackBerry
Game ID	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx
Game Secret	Xxxxxxxxxx
Game Currency Code	IBI

Add this information to your code along with the game version and language:

static const char SCORELOOP_GAME_ID[] = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx";
static const char SCORELOOP_GAME_SECRET[] = "xxxxxxxxxx";
static const char SCORELOOP_GAME_VERSION[] = "1.0";
static const char SCORELOOP_GAME_CURRENCY[] = "IBI";
static const char SCORELOOP_GAME_LANGUAGE[] = "en";

In the init() method, initialize the Scoreloop client and its data components as shown below:

SC_InitData_Init(&scData);
SC_Error_t errCode = SC_Client_New(&client, &scData, SCORELOOP_GAME_ID, SCORELOOP_GAME_SECRET, 
SCORELOOP_GAME_VERSION, SCORELOOP_GAME_CURRENCY, SCORELOOP_GAME_LANGUAGE);

Note: If the user had not already setup his Social Gaming Hub account, he may be prompted to sign in with his BlackBerry ID and credentials.

Fetching information from the Scoreloop server

To fetch user information from the Scoreloop server, a Scoreloop user controller needs to be created. Queries receive asynchronous response and needs a callback function to be registered. In the snippet below, fetchUserComplete will be called upon a response from the server.

SC_Client_CreateUserController(client, &userController, fetchUserComplete, this);

For example: if the game needs to query the current session user’s information call

SC_UserController_LoadUser(userController);

Once a user controller is successfully created, it can be used to query information. There are two approaches to get the desired information from the server.

  1. Via BlackBerry Platform Services (BPS) events.
  2. Using a custom events

Approach 1: Via BlackBerry Platform Services (BPS) events

Cocos2d-x absorbs all the BPS events in its implementation and you can modify the cocos2d-x source code directly and have it call back whenever a BPS event arrives. CCEGLView::handleEvents() is where the event handling takes place and it calls the callback function that was registered through the “setEventCallback()”. The advantage of this approach is that it does not have event-polling overhead. The code snippets below show the changes made to the cocos2d-x library and the BBTemplate project to accomplish Scoreloop event handling via BPS events.

CCEGLView.h

void * m_eventCookie;
CEGLViewEventCallback m_eventCallback;
void setEventCallback(CCEGLViewEventCallback callback, void *cookie);

CCEGLView.cpp

void CCEGLView::setEventCallback(CCEGLViewEventCallback callback, void *cookie) {
	m_eventCookie = cookie;
	m_eventCallback = callback;
}
bool CCEGLView::handleEvents() {
	...

	for (;;) {

		if (m_eventCallback != NULL)
		m_eventCallback(m_eventCookie, event);
...
    }
}

HelloWorldScene.h

void fetchUserComplete(SC_Error_t result);
static void fetchUserComplete(void* userData, SC_Error_t result) {
 (reinterpret_cast(userData))->fetchUserComplete(result);
}

HelloWorldScene.cpp

bool HelloWorld::init() {
...
scData.runLoopType = SC_RUN_LOOP_TYPE_BPS;
SC_Error_t errCode = SC_Client_New(&client, &scData, SCORELOOP_GAME_ID, SCORELOOP_GAME_SECRET, SCORELOOP_GAME_VERSION, SCORELOOP_GAME_CURRENCY, SCORELOOP_GAME_LANGUAGE);

CCEGLView::sharedOpenGLView()->setEventCallback(StaticOnScoreloopUIEvent, (&_scInitData);
...
}

static void OnScoreloopUIEvent(void *cookie, void *event) {
SC_HandleBPSEvent((SC_InitData_t  *)cookie, (bps_event_t *)event);
}
void HelloWorld::fetchUserComplete(SC_Error_t result) {
...
}

Approach 2: Via custom events

An alternative approach to handle Scoreloop events is to use the Scoreloop custom event queue. The difference here is that incoming Scoreloop responses are processed by periodic polling. The good news is that cocos2d-x already has an infrastructure to support scheduling and the disadvantage of this approach is that polling takes place periodically and sometimes even when no Scoreloop event is expected.

The custom event handler can be called in game’s update() function or scheduled via cocos2d-x schedule() function.

HelloWorldScene.h

void OnScoreloopCustomEvent(float o);
void fetchUserComplete(SC_Error_t result);
static void fetchUserComplete(void* userData, SC_Error_t result) {
 (reinterpret_cast(userData))->fetchUserComplete(result);
}

HelloWorldScene.cpp

bool HelloWorld::init() {
...
scData.runLoopType = SC_RUN_LOOP_TYPE_CUSTOM;
SC_Error_t errCode = SC_Client_New(&client, &scData, SCORELOOP_GAME_ID, SCORELOOP_GAME_SECRET, SCORELOOP_GAME_VERSION, SCORELOOP_GAME_CURRENCY, SCORELOOP_GAME_LANGUAGE);

// schedule to call this method with every frame
this->schedule(schedule_selector(HelloWorld::OnScoreloopCustomEvent));
...
}

void HelloWorld::OnScoreloopCustomEvent(float o) {
SC_HandleCustomEvent(&scData, SC_FALSE);
}

void HelloWorld::fetchUserComplete(SC_Error_t result) {
...
}

Well, there you have it – you are up and running with cocos2d-x and Scoreloop. Here are some great resources available to you to get more out of Scoreloop SDK:

Scoreloop SDK Guide

Scoreloop Integration Sample -101 Scoreloop Integration sample

Belligerent Blocks – A Sample 1 level game that showcases great use cases of Scoreloop

About Ramprasad Madhavan

Ram was a Senior Gaming Consultant at BlackBerry's Developer Relations Team. With years of Advanced Graphics and Gaming Experience, he managed technical partnerships with Industry's Top notch Game Engines and Middleware partners. Indie Gaming has always been his passion and he strives to make available all the tools necessary for Indie Game developers be successful on new BlackBerry Platform. Prior to joining Developer Relations team, Ram was part of Gaming R&D team at BlackBerry where he helped design and develop the open-source gaming framework, Gameplay3D.

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus