NetFrames

重要 注意 提醒

Coding Style wiki

---

NetFrames 是 NetFrame 模块的统一调用入口（Facade），以节点（NetNode）为单位管理多组网络连接。每个节点可搭配独立的传输实现（INetProvider）与连接选项（NetOption），涵盖节点注册、连接、发送数据与关闭，并提供驱动网络轮询的更新器控制。

命名空间	OxGFrame.NetFrame
类型	public static class
源码	NetFrames.cs

using OxGFrame.NetFrame;

注意 调用连接相关 API 前，需先自行创建 NetNode 并通过 AddNetNode 注册至管理器，完整搭建流程请参考 NetFrame 介绍。

快速上手

// 创建网络节点（使用内置 TCP Provider；NetTipsExample 为自定义的 INetTips 实现）
var netNode = new NetNode(new TcpNetProvider(), new NetTipsExample());
netNode.SetResponseBinaryHandler(recvData => Debug.Log($"接收到 {recvData.Length} bytes"));

// 注册节点（单一连接使用默认 nnId = 0 即可）
NetFrames.AddNetNode(netNode);

// 连接至服务器
NetFrames.Connect(new TcpNetOption("127.0.0.1", 8888));

// 发送二进制数据
NetFrames.Send(new byte[] { 0x01, 0x02 });

// 关闭连接并移除节点
NetFrames.Close(0, removeNetNode: true);

通用规则

多节点管理 (nnId)

NetFrame 以节点（NetNode）为单位组织网络连接，每个节点拥有各自独立的传输实现（INetProvider）、连接选项（NetOption）与状态提示（INetTips），并以 nnId（Node ID）作为唯一标识码进行管理，所有操作方法皆以 nnId 指定目标节点。

注意 大多数单一连接的场景，直接使用默认的 nnId = 0 即可；若需同时连接多个服务器（如 Login Server 与 Game Server），请为各节点分配独立的 nnId。

提醒 NetNode 本身还支持心跳、超时检测与重连等回调设置（SetHeartBeatAction、SetOutReceiveAction、SetReconnectAction 等），详细搭建流程请参考 NetFrame 介绍。

内置 Provider

内置三种 INetProvider 实现，连接时搭配对应的 NetOption 派生类使用；也可自行实现 INetProvider 扩展其他传输协议。

Provider	底层库	对应 NetOption	字符串发送
TcpNetProvider	Telepathy	TcpNetOption	不支持
KcpNetProvider	kcp2k	KcpNetOption	不支持
WebSocketNetProvider	UnityWebSocket	WebSocketNetOption	支持

注意 TcpNetProvider 与 KcpNetProvider 仅支持二进制发送，对其调用字符串重载的 Send 会抛出异常。

更新器 (Updater)

NetManager 使用独立的 RTUpdater（Real-time Updater）驱动所有节点的轮询逻辑（数据接收、心跳、超时与重连计时）。首次调用任一 NetFrames API 时，管理器会自动初始化并在主线程启动更新器。

提醒 RTUpdater 为实时刷新器，不受 Unity Time.timeScale 影响，即使游戏暂停，网络通信依然正常运作。

重要 若通过 StartUpdaterOnThread 或 ResetUpdaterOnThread 改以独立线程驱动，所有网络回调（如 Binary 接收回调）会在非主线程触发，若需操作 Unity 组件，请务必注意线程安全并使用 UMT 调度回主线程。

---

节点管理

节点的注册、获取与移除。NetNode 需以 new NetNode(INetProvider, INetTips) 自行创建后注册至管理器（参考多节点管理）。

方法总览

初始化

方法	说明
InitInstance	初始化 NetManager 单例实例。

节点注册与获取

方法	说明
AddNetNode	注册网络节点至管理器。
RemoveNetNode	释放并移除指定节点。
GetNetNode	获取已注册的网络节点。
Count	获取已注册的节点总数。

---

InitInstance

public static void InitInstance()

说明

主动初始化 NetManager 单例实例，初始化时会一并创建更新器并在主线程启动。建议在游戏启动阶段调用一次，确保管理器提前就绪。

提醒 所有 NetFrames API 在首次调用时皆会自动完成初始化，此方法仅用于提前初始化。

---

AddNetNode

public static void AddNetNode(NetNode netNode, int nnId = 0)

参数

参数	类型	说明
netNode	NetNode	要注册的网络节点实例。
nnId	int	节点的唯一标识码。 默认值：0

说明

将网络节点注册至管理器，之后即可通过 nnId 对该节点进行连接、发送与关闭等操作。

注意 若 nnId 已存在，旧节点会先被 Dispose（关闭连接并释放资源），再以新节点取代。

示例

public enum NNID
{
    WebSocket = 0,
    TCP = 1,
    KCP = 2
}

// 注册 WebSocket 节点
var wsNode = new NetNode(new WebSocketNetProvider(), new NetTipsExample());
NetFrames.AddNetNode(wsNode, (int)NNID.WebSocket);

// 注册 TCP 节点
var tcpNode = new NetNode(new TcpNetProvider(), new NetTipsExample());
NetFrames.AddNetNode(tcpNode, (int)NNID.TCP);

---

RemoveNetNode

public static void RemoveNetNode(int nnId = 0)

参数

参数	类型	说明
nnId	int	节点的唯一标识码。 默认值：0

说明

将指定节点从管理器移除，移除前会先 Dispose 该节点（关闭连接并释放回调与计时器等资源）。未找到节点时不动作。

---

GetNetNode

public static NetNode GetNetNode(int nnId = 0)

参数

参数	类型	说明
nnId	int	节点的唯一标识码。 默认值：0

返回值

NetNode — 已注册的节点实例；未找到时返回 null。

说明

获取已注册的网络节点，可对节点进行高级设置（如心跳、超时、重连回调），或通过 GetNetProvider<T>() 获取底层 Provider 进行高级操作。

示例

// 检查节点是否已注册
if (NetFrames.GetNetNode() == null)
{
    // 尚未注册，先行创建节点
}

// 获取底层 Provider，改以 KCP Unreliable 通道发送
NetFrames.GetNetNode((int)NNID.KCP)
         .GetNetProvider<KcpNetProvider>()
         .SendBinary(kcp2k.KcpChannel.Unreliable, buffer);

---

Count

public static int Count()

返回值

int — 当前已注册的网络节点总数。

说明

获取管理器中已注册的节点数量。

---

连接与通信

针对指定节点执行连接、发送与关闭等网络操作。

方法总览

连接

方法	说明
Connect	开启指定节点的连接。
IsConnected	检查指定节点的连接状态。

发送与关闭

方法	说明
Send	通过指定节点发送二进制或字符串数据。
Close	断开指定节点的连接。
CloseAll	断开所有节点的连接。

---

Connect

public static void Connect(NetOption netOption, int nnId = 0)

参数

参数	类型	说明
netOption	NetOption	连接选项。依节点的 Provider 传入对应的派生类（如 TcpNetOption、KcpNetOption、WebSocketNetOption）。
nnId	int	目标节点的唯一标识码。 默认值：0

说明

开启指定节点的连接。连接流程启动时会触发 INetTips.OnConnecting 与节点的 Connecting 回调；连接成功后触发 INetTips.OnConnected 与 Connected 回调。未找到节点时输出错误日志。

注意

• netOption 的类型必须与节点的 Provider 相对应，实现内部会将其转换以获取连接参数。
• 节点仅在未连接（DISCONNECTED）或重连中（RECONNECTING）状态下才会启动连接流程，重复调用不会建立第二条连接。

示例

// TCP 连接（断线后自动重连 3 次）
NetFrames.Connect(new TcpNetOption("127.0.0.1", 8888, autoReconnectCount: 3), (int)NNID.TCP);

// WebSocket 连接
NetFrames.Connect(new WebSocketNetOption("ws://127.0.0.1:8080/ws"), (int)NNID.WebSocket);

---

IsConnected

public static bool IsConnected(int nnId = 0)

参数

参数	类型	说明
nnId	int	目标节点的唯一标识码。 默认值：0

返回值

bool — 节点已连接返回 true；未找到节点或未连接返回 false。

说明

检查指定节点底层 Provider 的连接状态。

---

Send

public static bool Send(byte[] buffer, int nnId = 0)
public static bool Send(string text, int nnId = 0)

参数

参数	类型	说明
buffer	byte[]	要发送的二进制数据。
text	string	要发送的字符串数据。
nnId	int	目标节点的唯一标识码。 默认值：0

返回值

bool — 成功交付底层 Provider 发送返回 true；未找到节点或未连接时返回 false。

说明

通过指定节点发送数据。二进制重载对应 Provider 的 SendBinary；字符串重载对应 SendMessage。

重要 内置的 TcpNetProvider 与 KcpNetProvider 不支持字符串发送，调用字符串重载会抛出异常；仅 WebSocketNetProvider 支持。

示例

// 发送二进制数据
bool sent = NetFrames.Send(new byte[] { 0x01, 0x02, 0x03 });

// 发送字符串数据（仅 WebSocket 支持）
NetFrames.Send("{\"cmd\":\"ping\"}", (int)NNID.WebSocket);

---

Close

public static void Close(int nnId = 0, bool removeNetNode = false)

参数

参数	类型	说明
nnId	int	目标节点的唯一标识码。 默认值：0
removeNetNode	bool	关闭后是否一并将节点从管理器移除（Dispose）。 默认值：false

说明

断开指定节点的连接。主动关闭属于强制关闭，不会触发自动重连；若 removeNetNode 为 false，节点仍保留在管理器中，可再次调用 Connect 重新连接。未找到节点时不动作。

示例

// 仅关闭连接（节点保留，可重新连接）
NetFrames.Close();

// 关闭连接并移除节点
NetFrames.Close((int)NNID.TCP, true);

---

CloseAll

public static void CloseAll(bool removeNetNode = false)

参数

参数	类型	说明
removeNetNode	bool	关闭后是否一并移除所有节点。 默认值：false

说明

断开所有已注册节点的连接，参数行为同 Close。适用于登出或退出游戏时的统一清理。

---

更新器控制

控制 NetManager 更新器的启停、重置与运作速率，更新器概念与线程注意事项请参考更新器 (Updater)。

方法总览

启动与停止

方法	说明
StartUpdater	在主线程启动更新器。
StartUpdaterOnThread	在独立线程启动更新器。
StopUpdater	停止更新器。
IsUpdaterRunning	检查更新器是否运行中。

重置与调速

方法	说明
ResetUpdater	重置并重启更新器。
ResetUpdaterOnThread	重置并在独立线程重启更新器。
SetUpdaterTimeScale	调整更新器的时间缩放倍率。

---

StartUpdater

public static void StartUpdater()

说明

在主线程启动更新器。管理器初始化时默认即以主线程模式启动，通常仅在调用过 StopUpdater 后需要手动重启。

---

StartUpdaterOnThread

public static void StartUpdaterOnThread()

说明

在独立线程启动更新器，适用于避免主线程阻塞或需要更实时轮询的场景。

重要 线程模式下，所有网络回调会在非主线程触发，操作 Unity 组件请务必注意线程安全（参考更新器 (Updater)）。

---

StopUpdater

public static void StopUpdater()

说明

停止更新器，所有节点的轮询逻辑（数据接收、心跳、超时与重连计时）将一并暂停，直到再次启动。

---

IsUpdaterRunning

public static bool IsUpdaterRunning()

返回值

bool — 更新器运行中返回 true。

说明

检查 NetManager 更新器当前是否正在运行。

---

ResetUpdater

public static void ResetUpdater()
public static void ResetUpdater(bool useThreadedUpdater)

参数

参数	类型	说明
useThreadedUpdater	bool	是否改以独立线程模式重启。true = 独立线程；false = 主线程。无参数重载等同传入 false。

说明

停止并销毁现有更新器后，重新创建并依指定模式启动。可用于切换线程模式或重置更新器状态。

---

ResetUpdaterOnThread

public static void ResetUpdaterOnThread()

说明

重置更新器并改以独立线程模式重启，等同调用 ResetUpdater(true)。

---

SetUpdaterTimeScale

public static void SetUpdaterTimeScale(float timeScale)

参数

参数	类型	说明
timeScale	float	时间缩放倍率。

说明

设置 NetManager 更新器的时间缩放倍率（RTUpdater.timeScale）。

---