The GameBench Native Package

Current version: v1.2.1

GameBench SDK (Native)

This directory contains files for integrating GameBench into native projects. The principal files are:

• Gamebench.aar - native library for Android
• GameBench.framework - native library for iOS
• GameBench.h - header file containing declarations for the native API
• GameBench_example.cpp - example integration code to be added to a native project

1. Integrating with Cocos Creator

Cocos Creator is a popular game development platform that we can use to demonstrate native integration. The following uses Cocos Creator 3.0 and uses the “simple-games” project in the samples repository, which may be found at https://github.com/cocos-creator/example-3d/tree/master/simple-games

1.1. Generate the native projects

In Cocos Creator, use the “Build” UI to generate Android Studio and XCode projects. The native projects will be generated at build\android\proj and build\ios\proj relative to the project root.

1.2. Copy integration example code into app

As part of generating the native projects there will now be a directory at native/engine/common in your project. This seems a good location for adding new platform-independent native code, so copy the files GameBench_example.cpp and GameBench.h into this folder.

1.3. Customize the integration code

The code in GameBench_example.cpp contains placeholders for your upload credentials. Put your GameBench credentials into the copy you just made of this file and take the opportunity to review the metrics being captured.

1.4. Edit Android build files

Open the file native/engine/android/app/build.gradle (relative to the project root) and add GameBench.aar to the dependencies block:

dependencies {
    ...
+   implementation(files:'/path/to/Gamebench.aar')
}

Open native/engine/android/CMakeLists.txt and insert these lines before the add_library line:

...

+    list(APPEND PROJ_SOURCES
+      ${CMAKE_CURRENT_LIST_DIR}/../common/GameBench_example.cpp
+    )

add_library(${LIB_NAME} SHARED ${PROJ_SOURCES})

1.5. Build Android

Start Android Studio and select the “Open an Existing Project” command, then point it at build\android\proj under the project root. You should be able to build and run the project normally.

2. C API reference

The API declared in GameBench.h is largely contained by the IGameBench interface (i.e. a struct containing function pointers), which is obtainable through the global helper function getGameBench(). This interface has a number of methods considered in the following sections:

2.1 Configuration

Configuration is write-only and must be set one item at a time with these methods:

void setIntConfigItem(const char* name, int value);

void setStringConfigItem(const char* name, const char* value);

The available config items are:

2.2 Session start/stop

int sessionStart(const char* title);
int sessionStop();

2.3 Capturing data

int scheduleCapture(int metricType, float freq);
int captureNow(int metricType);

2.4 Tags

void setTag(const char* name, const char* val);

2.5 Markers

int writeMarker(double timestampInSeconds, const char* name, int step, int type, const char* group);

2.6 Uploading data

int upload(GameBenchUploadCallback callback, void* callbackToken);