Nanolink Cocos2d-x 接入概要

Nanolink 是基于 UDP 的实时联网对战服务。

Nanolink SDK支持"1对1"和"多人" 联网对战, 支持回放。

主要接口以 C/C++ 形式定义, C#, Lua, JS 版有相应语言接口实现。

初始化接口

int32_t init (const char* appKey, int mode=2);

接口调用结构

						
init // 初始化
config // 参数配置，可选
    
connect // 连接指定设备
    send, recv // 接收与发送
disconnect // 断开连接
					

获取 APPKEY

1，登录 天梯实时对战服务 后台，在 游戏列表 界面，点击 “创建游戏”。如图：

2，输入游戏的相关信息后，点击 “提交”，即可。如图：

3，在 游戏列表，可以点击“编辑”某个游戏，查看唯一的 APPKEY，接入 SDK 时使用。如图：

iOS SDK 导入

Cocos 导入, Xcode 环境配置

下载 SDK 解压至本地，demos/*/sdk 目录下包含下面文件:

nanolink.h

// Cocos-C++ 环境下加入
nanoclient.h
nanoclient.cpp

// Cocos-Lua 环境下加入
nanolink_lua.h
nanolink_lua.cpp

// Cocos-JS 环境下加入
nanolink_js.h
nanolink_js.cpp

1，在工程中加入 SDK 接口文件 和 nanolink.h 头文件

把 demos/*/sdk 目录中 nanolink.h 文件加入工程中。

2，设置库路径

在 Build Settings -> Search Paths 加入 libs/iOS 库路径。(Header Search Paths 和 Library Search Paths 具体配置的路径根据自身环境配置即可)

Header Search Paths 添加 $(SRCROOT)/../../nanolink/sdk

Library Search Paths 添加 $(SRCROOT)/../../nanolink/libs/iOS

3，设置链接库

在 Build Phases -> Link Binary With Libraries 添加 nanolink 静态库。

Android SDK 导入

编译配置

在 Android 工程加载自己项目 .so 的地方，添加对 libnanolink.so 的引用。

						
static {
    System.loadLibrary("nanolink");
    System.loadLibrary("your_app_lib");
}
					

Cocos-C++ 开发环境

下载 SDK 解压至本地，demos/c++/sdk 目录下包含下面文件，将文件导入到工程中:

nanolink.h
nanoclient.h
nanoclient.cpp

1，修改 Android.mk 文件

/frameworks/runtime-src/proj.android/jni/Android.mk

						
LOCAL_PATH := $(call my-dir)
#——— 开始添加, 加载 libnanolink.so ———
#——— 确保加载的 .so 文件（路径） 正确加载 ———
include $(CLEAR_VARS)
LOCAL_MODULE:=libnanolink
LOCAL_SRC_FILES:=../../../nanolink/libs/android/$(TARGET_ARCH_ABI)/libnanolink.so
include $(PREBUILT_SHARED_LIBRARY)
#——— 结束添加 ———

include $(CLEAR_VARS)

...


#——— 开始添加, Cocos-C++ 开发环境加入以下接口文件 ———

LOCAL_SRC_FILES := hellolua/main.cpp \
                   ../../Classes/AppDelegate.cpp \
                   ../../../nanolink/sdk/nanoclient.cpp

LOCAL_C_INCLUDES := $(LOCAL_PATH)/../../Classes \
                   $(LOCAL_PATH)/../../../nanolink/sdk
#——— 结束添加 ———

...

#——— 开始添加, 设置链接库 ———
#放在 BUILD_SHARED_LIBRARY 前
LOCAL_SHARED_LIBRARIES := libnanolink
#——— 结束添加 ———

include $(BUILD_SHARED_LIBRARY)

					

Cocos-Lua 开发环境

下载 SDK 解压至本地，demos/lua/sdk 目录下包含下面文件，将文件导入到工程中:

nanolink.h
nanolink_lua.h
nanolink_lua.cpp

1，修改 Android.mk 文件

						
LOCAL_PATH := $(call my-dir)
#——— 开始添加, 加载 libnanolink.so ———
#——— 确保加载的 .so 文件（路径） 正确加载 ———
include $(CLEAR_VARS)
LOCAL_MODULE:=libnanolink
LOCAL_SRC_FILES:=../../../nanolink/libs/android/$(TARGET_ARCH_ABI)/libnanolink.so
include $(PREBUILT_SHARED_LIBRARY)
#——— 结束添加 ———

include $(CLEAR_VARS)

...

ifeq ($(USE_ARM_MODE),1)
LOCAL_ARM_MODE := arm
endif

#——— 开始添加, Cocos-Lua 开发环境加入以下接口文件 ———

LOCAL_SRC_FILES := hellolua/main.cpp \
                   ../../Classes/AppDelegate.cpp \
                   ../../../nanolink/sdk/nanolink_lua.cpp

LOCAL_C_INCLUDES := $(LOCAL_PATH)/../../Classes \
                   $(LOCAL_PATH)/../../../nanolink/sdk
#——— 结束添加 ———

...

#——— 开始添加, 设置链接库 ———
#放在 BUILD_SHARED_LIBRARY 前
LOCAL_SHARED_LIBRARIES := libnanolink
#——— 结束添加 ———

include $(BUILD_SHARED_LIBRARY)

					

2，初始化代码 (Cocos2d-Lua)，修改 AppDelegate.cpp

在开始位置加上 #include "nanolink_lua.h" 。

在 register_all_packages() 后加入 nanolink_lua_init(L); 。其中 L 为当前 LuaEngine 的 lua_State。

Cocos-JS 开发环境

下载 SDK 解压至本地，demos/js/sdk 目录下包含下面文件，将文件导入到工程中:

nanolink.h
nanolink_js.h
nanolink_js.cpp

1，修改 Android.mk 文件

						
LOCAL_PATH := $(call my-dir)
#——— 开始添加, 加载 libnanolink.so ———
#——— 确保加载的 .so 文件（路径） 正确加载 ———
include $(CLEAR_VARS)
LOCAL_MODULE:=libnanolink
LOCAL_SRC_FILES:=../../../nanolink/libs/android/$(TARGET_ARCH_ABI)/libnanolink.so
include $(PREBUILT_SHARED_LIBRARY)
#——— 结束添加 ———

include $(CLEAR_VARS)

...

ifeq ($(USE_ARM_MODE),1)
LOCAL_ARM_MODE := arm
endif

#——— 开始添加, Cocos-JS 开发环境加入以下接口文件 ———

LOCAL_SRC_FILES := hellojavascript/main.cpp \
                   ../../Classes/AppDelegate.cpp \
                   ../../../nanolink/sdk/nanolink_js.cpp

LOCAL_C_INCLUDES := $(LOCAL_PATH)/../../Classes \
                   $(LOCAL_PATH)/../../../nanolink/sdk
#——— 结束添加 ———

...

#——— 开始添加, 设置链接库 ———
#放在 BUILD_SHARED_LIBRARY 前
LOCAL_SHARED_LIBRARIES := libnanolink
#——— 结束添加 ———

include $(BUILD_SHARED_LIBRARY)

					

2，初始化代码 (Cocos2d-JS)，修改 AppDelegate.cpp

在开始位置加上 #include "nanolink_js.h" 。

在 sc->start () 前加入 sc->addRegisterCallback(nanolink_js::registerJSFunctions); 。

快速接入

SDK 初始化

定义

int32_t init (const char* appKey, int mode=2);

功能

初始化 Nanolink SDK，确保在调用其它接口之前正确调用。

返回值

成功返回 0, 失败返回 -1 (mode无效)

连接

等级匹配 connect

定义

void connect (uint8_t level, uint8_t mode = 0, int32_t timeout=15000);

功能

指定等级匹配，可以指定匹配玩家的等级，等级会根据一定的宽容度匹配。

如果当前游戏没有玩家等级的概念，匹配完全随机的话，直接指定一个固定的等级即可，比如：8。

局域网匹配 和 房间号匹配 connect2

定义

void connect2 (const char* group, int32_t timeout=15000);

功能

局域网对战 或 创建房间号（或邀请好友）的对战方式。

断开连接 disconnect

定义

void disconnect ();

功能

断开已经建立的连接 或 取消正在进行的匹配。

数据收发

发送数据 send

定义

int32_t send (const uint8_t* data, uint32_t size, uint8_t strength=255);

功能

发送指定长度 size 的 data 数据到目标设备。

返回值

成功: >= 0, 发送数据的索引值

失败：-1, 无法添加发送任务(发送队列满)

发送协议“标记” sendmark

定义

int32_t sendmark (uint8_t mark=0);

功能

用在多人联网对战, 用于和 resync 指令配合使用

发送一个标记指令, 用于告知其他客户端该数据之后可以重构本客户端完整状态。

返回值

无法添加发送任务(发送队列满), 返回 -1。

接收数据 recv

定义

int32_t recv (uint8_t* data, uint32_t size, uint8_t& from);

功能

接收新任务的数据。

返回值

返回接收数据长度。

更新玩家位置 update

定义

int32_t update (uint8_t x, uint8_t y, uint8_t z = 0, uint8_t k = 1);

功能

更新客户端的位置(x,y), 空间(z), 接收增益(k), 用于配合 send 实现区域广播。

用法

返回值

成功返回 0

获取协议参数

整型参数 getInt

定义

int32_t getInt (const char* name, int n = -1);

功能

获得指定名称(name)的字符串类型参数值(value)。

name 参数明细：

字符串参数 getString

定义

int32_t getString (const char* name, char* data, uint32_t size); //C++接口
string getString (string name); // C#, Lua, JS接口

功能

获得指定名称(name)的字符串类型参数值(value)。

name 参数明细：

协议配置 config

定义

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

功能

配置协议的参数。

name 参数明细：

房间配置 config

定义

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

功能

配置房间的参数。

name 参数明细：

应用协议事件处理

NanoClient 类定义了 onConnected, onDisconnected, onStatusChanged, onMessage, onResync, onPlayer 等事件处理函数接口, 开发者继承 NanoClient 类并实现以上接口可以快速实现实时对战。

连接建立 onConnected

连接建立完成, 可以开始进行数据收发。

onConnected ()

连接断开 onDisconnected

连接断开时，触发的事件。会返回连接断开时的错误码。

onDisconnected (int error)

状态变化 onStatusChanged

连接状态发生改变时触发。

onStatusChanged (string newStatus, string oldStatus)

接收数据事件 onMessage [必须]

接收到一个事件时的处理接口。

onMessage (byte[] data, byte fromIndex)

resync 指令

当某个客户端遇到不可修复的传输故障，向其他客户端请求重新发送当前最新数据。例如，某个玩家中途进入游戏，之前的数据没有接收到，SDK 会自动发送一个 resync 指令，向其他客户端请求数据。

通常在多人对战模式中使用，客户端通常在 onResync 中发送包括玩家昵称等初始信息。

onResync (byte fromIndex)

玩家事件 onPlayer

玩家新加入房间"new", 离开房间"left", 重连回到房间"return"。

onPlayer (byte clientIndex, string e)

序列化与反序列化 NanoBuffers

Nanolink 传输二进制数据, 开发者可以使用熟悉的序列化方式, 例如 Protobuf, JSON, XML, ....

在实时联网时, 数据收发频率高, 发送数据越小越好, 建议使用 protobuf 等二进制序列化工具, 也可以使用 Nanolink SDK 内置的 NanoBuffers 序列化工具。

NanoBuffers 是个简单的二进制序列化工具

NanoBuffers 的基本用法

						
// 1, 编码
NanoWriter nanoWriter = new NanoWriter ();
nanoWriter.putInt (123)
	.putFloat(3.1415927f, 3)
	.putString("Hello")
	.put (new Vector3 (0.1f, 0.12f, 0.123f), 3);
myClient.send (nanoWriter.getBytes ());

// 2, 解码
NanoReader nanoReader = new NanoReader (buf); // buf 是接收到的数据

int v1;
float v2;
String v3;
Vector3 v4;
nanoReader.getInt (out v1).getFloat (out v2, 3).getString (out v3).get (out v4);
					

区域广播

什么是区域广播

在多人联网的时候, 服务器把每个客户端发送的数据直接广播(转发)给其他客户端, 当一个房间人数较多的时候, 完全广播的方式消息会导致流量消耗巨大。Nanolink 多人联网服务支持区域广播特性, 即客户端发送的数据可以仅发送给特定范围的部分客户端

如果房间人数在12人以下建议用全局广播模式, 编程相对比较简单。

如果房间人数在16人以上, 建议支持区域广播, 节约流量

如何实现区域广播

1, 每个玩家向服务器注册自己所在的位置, 空间

NanoClient.update (x, y, z, k) 更新位置, 空间, 接收增益

x, y 是玩家的虚拟坐标, 是个256*256的网格, 通常由玩家在游戏中的实际坐标转换而来

空间(z) 和 接收增益(k) 用于实现高级的区域广播特性, 建议先用默认参数

2, 玩家发送数据时, 可以指定"发送强度", 来决定多大范围内的玩家可以接收到数据

NanoClient.send (data, strength) 其中 strength 指定"发送强度"

玩家的不同事件的影响范围不一样, 例如, 走路的强度是3, 跑步的强度是5, 枪声的强度是8, 手榴弹15...

send 的 strength 参数补充说明:

3, 玩家发送数据时, 服务器根据玩家间的相互位置计算数据的接收者

// a 是发送者, b 是接收者
// strength 是a玩家发送数据的强度, 缺省为255, 全局广播模式
// k 是 b玩家的接收增益, 缺省为1
bool 判断b玩家是否在a玩家的发送范围内 (a, b, strength, k) {
    int dx = abs (a.x - b.x);
    int dy = abs (a.y - b.y);
    if (dx <= strength*k && dy >= strength*k) {
        // 在接收范围内
    }
}
					

存档回放

数据保存 (录制) save

记录网络传输数据（录制）功能默认是关闭的，如果需要开启录制功能，需要 config("time-machine", "true") 开启。

定义

int32_t save (uint8_t* data, int32_t size = -1);

功能

保存协议收发等数据。

返回值

保存的数据长度，如果返回值大于参数 size, 表明 data 空间不够。

保存的数据包括收发数据和其他重要事件, 经过编码和压缩, 数据大小大约是客户端实际 发送流量+接收流量 的 1/4 - 1/3。

加载回放 load

定义

int32_t load (uint8_t* data, int32_t size = -1);

功能

加载协议数据或保存协议数据，支持从文件或内存中加载/保存数据。

返回值

加载的数据长度。

如果返回值为-1, 表明加载失败。