Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.

Nakama Cocos2d-x C++ Client SDK

GitHub release Forum Client guide Reference License

Cocos2d-x C++ client for Nakama server.

Nakama is an open-source server designed to power modern games and apps. Features include user accounts, chat, social, matchmaker, realtime multiplayer, and much more.

This client implements the full API and socket options with the server. It's written in C++ with minimal dependencies to support Cocos2d-x, Unreal and other custom engines and frameworks.

If you experience any issues with the client, it can be useful to enable debug logs (see Logging section) and open an issue.

Full documentation is online -


DO NOT download source code from this repo if you are not intended to create pull request. This is not for end users.

Supported platforms

Nakama Cocos2d-x C++ SDK is released with prebuilt libraries for following platforms and architectures:

  • Windows - Visual Studio 2015, 2017, 2019 (x86, x64, Debug, Release)
  • Android - Android 4.1 (armeabi-v7a, arm64-v8a, x86, x86_64)
  • Linux - Ubuntu 18.04 (x64)
  • Mac - 10.10+
  • iOS - 8.0+ (arm64, armv7, armv7s, x86_64), Bitcode is off

Getting Started

You'll need to setup the server and database before you can connect with the client. The simplest way is to use Docker but have a look at the server documentation for other options.

  1. Install and run the servers. Follow these instructions.

  2. Download the SDK from the releases page.

  3. Integrate the SDK into your project:

When you've downloaded the SDK archive and extracted it to NAKAMA_COCOS2D_SDK folder, you should include it in your project.

Copy cocos2d-x specific files: NAKAMA_COCOS2D_SDK/NakamaCocos2d folder to Classes folder of your project.

We don't recommend to copy the SDK to your project because it's quite big in size (~1 Gb).

Setup for Mac and iOS projects

  1. Add NAKAMA_COCOS2D_SDK/include in Build Settings > Header Search Paths
  2. Add libs folder in Build Settings > Library Search Paths:
    • NAKAMA_COCOS2D_SDK/libs/ios - for iOS
    • NAKAMA_COCOS2D_SDK/libs/mac - for Mac
  3. Add all .a files located in libs folder to General > Frameworks, Libraries, and Embedded Content
  4. Add Classes/NakamaCocos2d folder to your XCode project as group (not a reference).

Setup for Android projects

If you use CMake then see Setup for CMake projects section.

If you use ndk-build then add following to your file:

# add this to your module

# add this after $(call import-add-path, $(LOCAL_PATH)/../../../cocos2d)
$(call import-add-path, NAKAMA_COCOS2D_SDK)

# add this after $(call import-module, cocos)
$(call import-module, nakama-cpp-android)

Android uses a permissions system which determines which platform services the application will request to use and ask permission for from the user. The client uses the network to communicate with the server so you must add the "INTERNET" permission.

<uses-permission android:name="android.permission.INTERNET"/>

Setup for CMake projects

Open for edit your CMakeLists.txt file and find following existing code:

# mark app complie info and libs info

add next code before:

# Cocos2d Nakama sources
# Cocos2d Nakama headers

At bottom of your CMakeLists.txt file add following:

add_subdirectory(NAKAMA_COCOS2D_SDK ${CMAKE_CURRENT_BINARY_DIR}/nakama-cpp)
target_link_libraries(${APP_NAME} ext_nakama-cpp)

Setup for Visual Studio projects

In Project Settings add following:

  1. Add NAKAMA_COCOS2D_SDK/include to C/C++ > General > Additional Include Directories
  2. Add folder to Linker > General > Additional Library Directories:
    • NAKAMA_COCOS2D_SDK/libs/win32/v140 - for VS 2015 x86
    • NAKAMA_COCOS2D_SDK/libs/win64/v140 - for VS 2015 x64
    • NAKAMA_COCOS2D_SDK/libs/win32/v141 - for VS 2017 x86
    • NAKAMA_COCOS2D_SDK/libs/win64/v141 - for VS 2017 x64
    • NAKAMA_COCOS2D_SDK/libs/win32/v142 - for VS 2019 x86
    • NAKAMA_COCOS2D_SDK/libs/win64/v142 - for VS 2019 x64
  3. Add all .lib files located in above folder to Linker > Input > Additional Dependencies
  4. Add sources from Classes/NakamaCocos2d to your Visual Studio project.

Threading model

Nakama C++ is designed to use in one thread only.


The client object has many methods to execute various features in the server or open realtime socket connections with the server.

Include nakama helper header.

#include "NakamaCocos2d/NCocosHelper.h"

Initialize logger with debug logging level.

using namespace Nakama;


Use the connection credentials to build a client object.

NClientParameters parameters;
parameters.serverKey = "defaultkey"; = "";
parameters.port = DEFAULT_PORT;
NClientPtr client = NCocosHelper::createDefaultClient(parameters);

The createDefaultClient will create HTTP/1.1 client to use REST API.


The tick method pumps requests queue and executes callbacks in your thread. You must call it periodically (recommended every 50ms) in your thread.

auto tickCallback = [this](float dt)
    if (rtClient)

auto scheduler = Director::getInstance()->getScheduler();
scheduler->schedule(tickCallback, this, 0.05f /*sec*/, CC_REPEAT_FOREVER, 0, false, "nakama-tick");

Without this the default client and realtime client will not work, and you will not receive responses from the server.


There's a variety of ways to authenticate with the server. Authentication can create a user if they don't already exist with those credentials. It's also easy to authenticate with a social profile from Google Play Games, Facebook, Game Center, etc.

string email = "";
string password = "batsignal";

auto successCallback = [](NSessionPtr session)
    CCLOG("session token: %s", session->getAuthToken().c_str());

auto errorCallback = [](const NError& error)

client->authenticateEmail(email, password, "", false, {}, successCallback, errorCallback);


When authenticated the server responds with an auth token (JWT) which contains useful properties and gets deserialized into a NSession object.

CCLOG("%s", session->getAuthToken().c_str()); // raw JWT token
CCLOG("%s", session->getUserId().c_str());
CCLOG("%s", session->getUsername().c_str());
CCLOG("Session has expired: %s", session->isExpired() ? "yes" : "no");
CCLOG("Session expires at: %llu", session->getExpireTime());
CCLOG("Session created at: %llu", session->getCreateTime());

It is recommended to store the auth token from the session and check at startup if it has expired. If the token has expired you must reauthenticate. The expiry time of the token can be changed as a setting in the server.

string authtoken = "restored from somewhere";
NSessionPtr session = restoreSession(authtoken);
if (session->isExpired()) {
    CCLOG("Session has expired. Must reauthenticate!");


The client includes lots of builtin APIs for various features of the game server. These can be accessed with the async methods. It can also call custom logic as RPC functions on the server. These can also be executed with a socket object.

All requests are sent with a session object which authorizes the client.

auto successCallback = [](const NAccount& account)
    CCLOG("user id : %s",;
    CCLOG("username: %s", account.user.username.c_str());
    CCLOG("wallet  : %s", account.wallet.c_str());

client->getAccount(session, successCallback, errorCallback);

Realtime client

The client can create one or more realtime clients with the server. Each realtime client can have it's own events listener registered for responses received from the server.

bool createStatus = true; // if the socket should show the user as online to others.
// define realtime client in your class as NRtClientPtr rtClient;
rtClient = NCocosHelper::createRtClient(client, DEFAULT_PORT);
// define listener in your class as NRtDefaultClientListener listener;
    CCLOG("Socket connected");
rtClient->connect(session, createStatus);

Don't forget to call tick method. See Tick section for details.


Client logging is off by default.

To enable logs output to console with debug logging level:



The development roadmap is managed as GitHub issues and pull requests are welcome. If you're interested to enhance the code please open an issue to discuss the changes or drop in and discuss it in the community forum.

Source Builds

The cocos2d-x C++ SDK is based on General C++ SDK

Nakama Cocos2d-x Client guide

You can find Nakama Cocos2d-x Client guide here.

Full Cocos2d-x C++ Client example

You can find the Cocos2d-x C++ Client example here


This project is licensed under the Apache-2 License.

Special Thanks

Thanks to @dimon4eg for this excellent support on developing Nakama C++, Cocos2d-x and Unreal client libraries.