Nanolink Unity 接入概要

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 时使用。如图：

Unity SDK 导入

在 Unity 编译器中选择 Assets -> Import Package -> Custom Package 找到本地目录下的 nanolink_unity_sdk.unitypackage 文件 点击 Open 按钮，然后 Import 即可导入成功。

(快速导入：打开 Unity 工程后，直接双击本地的 .unitypackage 文件，然后 Import 即可。)

导入成功完成后，可以看到 Assets/Demo/Scenes/ 目录中有 1V1 和 多人对战的小例子，可以体验。

快速接入

概要

Nanolink SDK 提供10多个 nano_xxx 形式的接口, 例如 nano_send, nano_recv, 开发者可以直接使用这些基础接口实现联网对战。

同时, Nanolink SDK通过NanoClient封装了基础接口, 开发者只需要继承 NanoClient 并实现必要的事件接口, 大大简化开发复杂度。

Nanolink SDK提供 C++, C#, JS, Lua 形式的 NanoClient 实现代码以及演示项目的参考实现代码, 开发者可以用事件接口快速开发联网对战游戏。

接入步骤

1，实现一个MyClient, 提供必要的事件接口。

2，实现一个MyNetwork, 管理 MyClien。

3，发送/接收数据。

4，序列化与反序列化。

实现 MyClient 事件接口

从 NanoClient 继承并实现一个 MyClient, 实现必要的事件接口。

发送数据: MyClient.send 发送序列化的数据。

接收数据: MyClient.onMessage 接收到数据后派发给具体处理逻辑。

						
public class MyClient : NanoClient {
    protected override void onMessage (byte[] data, byte fromIndex) {
	// 重点: 收到数据, 解析后派发给具体处理代码
    }

    protected override void onResync (byte fromIndex) {
	// 多人联网时, 中途进入或重连, 重新请求
	// 发送当前客户端的完整数据, 例如 昵称, 头像 等数据
    }

    protected override void onStatusChanged (string newStatus,string oldStatus) {
	// 状态变化时
    }

    protected override void onConnected () {
	// 连接成功时
    }

    protected override void onDisconnected (int error) {
	// 根据错误代码等信息判断断开原因, 具体参考示例代码
    }
    protected override void onPlayer (byte clientIndex, string e) {
	// 玩家新加入房间"new", 离开房间"left", 重连回到房间"return"
    }
}
					

实现一个 MyNetwork.cs 运行 MyClient

初始化: 在 MyNetwork.Start 中调用 myClient.init。

运行: 在 MyNetwork.FixedUpdate 中调用 myClient.doUpdate。

						
public class MyNetwork: MonoBehaviour {
	MyClient myClient = new MyClient ();

	void Start() {
		MyClient.init ("appKey", mode);

		MyClient.config ("time-machine", "true"); // 可选, 用于支持存档回放

		// 获得连接方式和参数
		MyClient.connect (...);
	}

	void FixedUpdate () {
		// 运行 myClient 的处理逻辑
		myClient.doUpdate ();
	}
}
					

发送与接收数据

发送事件: 在 MyPlayer.cs 中获得用户操作并发送操作事件。

接收事件: 定义事件处理接口 MyPlayer.onEvent。

派发事件: 在 MyClient.onMessage中派发事件数据到 MyPlayer.onEvent。

						
public class MyPlayer : MonoBehaviour {
	void Update () {
		// 获得键盘或鼠标操作
		Hashtable values = new Hashtable ();
		values.Add ("name", "move");
		values.Add ("target", targetPosition);
	
		// 序列化, 具体序列化在 MySerialize.toBytes 中实现
		MyClient.send (MySerialize.toBytes  (values));
	}

	public void onEvent(Hashtable values) {
		string name = (string) values["name"];

		switch (name) {
		case "move":
			targetPosition = (Vector3) values ["target"];
			break;

		default:
			Debug.Log("未支持的 Player::onEvent 事件: " + name);
			break;
		}
	}
}
					

Unity 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, 表明加载失败。