Home > Services & APIs > Engage > GameCircle

Using the GameCircle C++ API

Introduction

Introduction

Amazon GameCircle provides a companion C++ API that enables developers to integrate GameCircle features more rapidly into cross-platform games that include C++ code.

The Amazon C++ API offers a developer-facing header interface that lists the calls that you can make to GameCircle achievements, leaderboards, and Whispersync for Games 2.x.

Android Setup

GameCircle provides the JNI API as a shared library built for Android ARM platforms.

Build Setup

Follow these steps to incorporate the JNI API:

Step 1: Copy the files

  1. Create an _/includes_ folder in your existing _/jni_ folder.
  2. Copy the provided header files into this new folder.
  3. Create a _/libs_ folder in your existing _/jni_ folder.
  4. Copy the shared library file into this new folder.

Step 2: Modify your existing Android.mk file

This example Android.mk file shows the integrated library files.

LOCAL_PATH := $(call my-dir)

PATH_TO_LIBS = libs

include $(CLEAR_VARS)
LOCAL_MODULE := AmazonGamesJni
LOCAL_SRC_FILES := $(PATH_TO_LIBS)/libAmazonGamesJni.so
include $(PREBUILT_SHARED_LIBRARY)

include $(CLEAR_VARS)
LOCAL_MODULE := TestJni

TARGET_PLATFORM := android-10
LOCAL_LDLIBS := -llog

LOCAL_C_INCLUDES := \
    $(LOCAL_PATH)/../includes \

LOCAL_SRC_FILES := \
    TestJni.cpp \

LOCAL_SHARED_LIBRARIES := AmazonGamesJni
include $(BUILD_SHARED_LIBRARY)

Step 3: Example library loading code

The following sample code loads the AmazonGamesJNI library and then (as required) loads your game’s native library. Do not reverse the loading order, even if you load the libraries by using onResume() or some other method.

@Override
public void onCreate(Bundle savedInstanceState) {
    // App initialization code

    // Load AGS JNI SDK
    System.loadLibrary("AmazonGamesJni");

    // Load your game library
    System.loadLibrary("YourGameLibrary");
}

Step 4: Example initialization code

The following sample code initializes AmazonGamesClient.

AmazonGamesClient.initialize(this, new AmazonGamesCallback() {

  @Override
  public void onServiceReady(AmazonGamesClient amazonGamesClient) {
		    //Ready to use Amazon GameCircle SDK
  }

  @Override
  public void onServiceNotReady(AmazonGamesStatus reason) {
  }

}, AmazonGamesFeature.all());

Step 5: Continue to C++ Implementation

If you are implementing GameCircle only on Android, continue to the C++ Implementation section.

C++ Implementation

The C++ API provides many of the same methods that the Java/Objective-C API provides. Most of these methods have a handle or callback for you to use. The provided header files define these methods, handles, and callback interfaces.

To use the callback interface, create your own implementation of the interface and supply this implementation to the API function.

Example Get Achievement callback implementation

GetAchCbImpl.h

#ifndef __GET_ACH_CB_IMPL_H_INCLUDED__
#define __GET_ACH_CB_IMPL_H_INCLUDED__

#include "includes/AchievementsClientInterface.h"

class GetAchCbImpl : public AmazonGames::IGetAchievementCb {

public:
    GetAchCbImpl();
    ~GetAchCbImpl();

    void onGetAchievementCb(
        AmazonGames::ErrorCode errorCode,
        const AmazonGames::AchievementData* responseStruct,
        int developerTag);
    };

#endif

GetAchCbImpl.cpp

#include "GetAchCbImpl.h"
#include <androidlog.h>

using namespace AmazonGames;

GetAchCbImpl::GetAchCbImpl() {

    // Your constructor code

}

GetAchCbImpl::~GetAchCbImpl() {

    // Your destructor code

}

void GetAchCbImpl::onGetAchievementCb(

    ErrorCode errorCode,

    const AchievementData* responseStruct,

    int developerTag) {

    // Your callback action code
    //
    // Example struct access:

    android log write(ANDROID LOG DEBUG, "GetAchCbImpl", responseStruct->id);
}

Example handle usage

#include "includes/LeaderboardsClientInterface.h"

public void someFunction() {
    int devTag = 0;
    HandleWrapper<IGetLeaderboardsHandle> getLbsHandle =
        LeaderboardsClientInterface::getLeaderboards(devTag);

    int loopCount = 0;

    bool resultReceived = false;

    while (loopCount < 20) {

        if (getLbsHandle.handle()->getHandleStatus() != HANDLE_WAITING) {
            resultReceived = true;
            break;
        }

        usleep(100000);
        loopCount++;
    }
}