Unity 多人联机 API

SDK 简介

Unity 多人联机 SDK 是专为 Unity 游戏开发者设计的多人联机解决方案，提供房间管理、玩家通信、确定性随机数等核心功能，让开发者能够快速实现多人联机游戏。

核心特性：

• 🎮 简单易用 - 自动管理 Manager 实例，开发者只需关注游戏逻辑
• 📡 灵活通信 - 通过 SendCustomMessage 实现玩家间数据交互
• 🏠 房间管理 - 支持创建房间、自动匹配和加入房间
• 📊 事件驱动 - 基于事件处理器的异步通知机制

快速开始

基本接入流程

快速示例代码

// 1. 创建事件处理器
public class MyBattleEventHandler : ITapBattleEventHandler
{
    public void OnCustomMessageReceived(CustomMessageNotification info) {
        Debug.Log($"收到玩家 {info.playerId} 的消息：{info.msg}");
        // 处理游戏数据
    }

    public void OnPlayerEntered(EnterRoomNotification info) {
        Debug.Log($"玩家 {info.playerInfo.id} 进入房间");
    }

    // 实现其他事件方法...
}

// 2. 初始化 SDK
var eventHandler = new MyBattleEventHandler();
TapBattleClient.Initialize(eventHandler);

// 3. 连接服务
TapBattleClient.Connect(new BattleConnectOption {
    success = (result) => {
        string myPlayerId = result.playerId; // 保存 playerId 用于后续判断
        Debug.Log($"连接成功，playerId: {myPlayerId}");
    }
});

// 4. 匹配房间
TapBattleClient.MatchRoom(new MatchRoomOption {
    data = new MatchRoomConfig {
        roomCfg = new RoomConfig {
            maxPlayerCount = 2,
            type = "休闲模式",
            matchParams = new Dictionary <string, string> {
                { "level", "5" },
                { "score", "1000" }
            }
        }
    },
    success = (result) => Debug.Log($"匹配成功，房间ID：{result.roomInfo.id}")
});

// 5. 等待对手加入后，发送游戏数据
var gameData = new { action = "move", x = 10, y = 20 };
TapBattleClient.SendCustomMessage(new SendCustomMessageOption {
    data = new SendCustomMessageData {
        msg = JsonUtility.ToJson(gameData),
        type = 0  // 发送给房间内所有玩家
    }
});

// 6. 游戏结束后离开房间
TapBattleClient.LeaveRoom(new LeaveRoomOption {
    success = (result) => Debug.Log("离开房间")
});

API 分类总览

一、SDK 生命周期

用于 SDK 的初始化和资源清理。

API	功能描述
TapBattleClient.Initialize	初始化 SDK，自动创建 Manager 实例，注册事件处理器
TapBattleClient.FinalizeSDK	终止化 SDK，自动销毁 Manager 实例，释放所有资源

二、连接管理

管理与多人联机服务器的连接，获取玩家全局唯一 ID。

API	功能描述
TapBattleClient.Connect	连接多人联机服务器，返回 playerId（玩家全局唯一标识）
TapBattleClient.Disconnect	断开与服务器的连接

三、房间管理

创建房间、匹配房间、离开房间等房间相关操作。

API	功能描述
TapBattleClient.CreateRoom	创建新房间，设置房间配置和玩家配置
TapBattleClient.MatchRoom	自动匹配房间，根据匹配参数查找或创建房间
TapBattleClient.GetRoomList	获取房间列表，查看当前可用房间
TapBattleClient.JoinRoom	加入指定房间，通过房间 ID 直接加入
TapBattleClient.LeaveRoom	离开当前房间
TapBattleClient.KickRoomPlayer	踢出指定玩家（仅房主，未开战时可用）

四、属性更新

更新玩家状态、玩家属性和房间属性。

API	功能描述
TapBattleClient.UpdatePlayerCustomStatus	更新玩家自定义状态（如准备/未准备）
TapBattleClient.UpdatePlayerCustomProperties	更新玩家自定义属性（如昵称、等级、头像）
TapBattleClient.UpdateRoomProperties	更新房间属性（如房间名称、地图、模式）

五、玩家通信

在房间内发送自定义消息，实现玩家间数据交互。

API	功能描述
TapBattleClient.SendCustomMessage	发送自定义消息给房间内玩家（与 UpdateRoomProperties 共享每秒 15 次调用限制）

六、高级功能

针对高实时性竞技游戏提供的高级 API。

API	功能描述
TapBattleClient.StartFrameSync	开始帧同步（仅房主，高级功能）
TapBattleClient.SendFrameInput	发送玩家操作数据（高级功能）
TapBattleClient.StopFrameSync	停止帧同步（仅房主，高级功能）

七、确定性随机数

创建和使用确定性随机数生成器，确保多端随机结果一致。

API	功能描述
TapBattleClient.NewRandomNumberGenerator	创建确定性随机数生成器，返回RandomNumberGenerator实例

八、事件处理器

实现 ITapBattleEventHandler 接口接收异步事件通知。

事件回调	触发时机
OnDisconnected	连接断开时触发
OnPlayerEntered	玩家进入房间时触发
OnPlayerLeft	玩家离开房间时触发
OnPlayerKicked	玩家被踢出房间时触发
OnPlayerOffline	玩家掉线时触发
OnPlayerCustomStatusChanged	玩家状态变更时触发
OnPlayerCustomPropertiesChanged	玩家属性变更时触发
OnRoomPropertiesChanged	房间属性变更时触发
OnFrameSyncStarted	帧同步开始时触发（高级功能）
OnFrameReceived	接收帧同步数据（高级功能）
OnFrameSyncStopped	帧同步停止时触发（高级功能）
OnCustomMessageReceived	收到自定义消息时触发
OnBattleServiceError	多人联机服务发生错误时触发

接入流程详解

核心概念：playerId

playerId 是多人联机系统最重要的概念！

• playerId 在 Connect() 成功时由服务器返回
• 用于判断"我是谁"和"谁是房主"
• 通过 player.id == myPlayerId 判断房间中哪个玩家是"我"

// 保存 playerId
string myPlayerId = connectResult.playerId;

// 判断我是否是房主
bool isOwner = (player.id == myPlayerId) && (player.id == roomInfo.ownerId);

完整业务流程

玩家间通信

数据流转过程

实现方式

玩家通过 SendCustomMessage 发送游戏操作数据，其他玩家通过 OnCustomMessageReceived 事件接收并处理。

适用场景：

• ✅ 棋牌游戏（五子棋、象棋、斗地主等）
• ✅ 回合制游戏（战棋、策略游戏等）
• ✅ 休闲游戏（你画我猜、狼人杀等）
• ✅ 合作游戏（简单的多人闯关、合作解谜等）

这种方式适合绝大多数多人小游戏！

使用示例

// 1. 发送游戏操作（如移动、落子、出牌）
public void SendPlayerAction(string actionType, object actionData)
{
    var message = new {
        type = actionType,
        data = actionData,
        timestamp = System.DateTimeOffset.Now.ToUnixTimeMilliseconds()
    };

    TapBattleClient.SendCustomMessage(new SendCustomMessageOption {
        data = new SendCustomMessageData {
            msg = JsonUtility.ToJson(message),
            type = 0  // 发送给房间内其他玩家
        }
    });
}

// 2. 接收并处理其他玩家的操作
public void OnCustomMessageReceived(CustomMessageNotification info)
{
    var message = JsonUtility.FromJson<GameMessage>(info.msg);
    string senderId = info.playerId;  // 从 CustomMessageNotification 中获取发送者 ID

    // 根据消息类型处理不同的游戏逻辑
    switch (message.type) {
        case "move":
            ApplyMove(senderId, message.data);
            break;
        case "play_card":
            ApplyCard(senderId, message.data);
            break;
        case "place_chess":
            ApplyPlaceChess(senderId, message.data);
            break;
    }
}

使用技巧

1. 消息格式设计：使用统一的消息结构（type、data、timestamp）
2. 频率控制：合理控制发送频率，避免超过每秒 15 次的限制
3. 本地立即响应：发送消息后立即在本地显示，提升体验
4. 添加时间戳：可用于检测网络延迟

高级功能

SDK 还提供了针对高实时性竞技游戏的高级 API（如格斗、射击类游戏）。一般游戏无需使用这些功能。

高级 API：

• StartFrameSync / StopFrameSync - 控制帧同步
• SendFrameInput - 发送操作指令
• OnFrameReceived - 接收帧数据

完整 Demo 源码

我们提供了完整的 Unity Demo 工程，包含多人联机的实现示例和高级功能的使用方法。

下载 Unity Demo (opens new window)

注意事项

最佳实践建议

1. 始终保存 playerId - Connect 成功后立即保存 playerId，后续判断身份都依赖它
2. 房主判断 - 某些操作只有房主才能执行（如踢人、开始对战）
3. 使用确定性随机数 - 如需多端随机结果一致，使用 SDK 提供的随机数生成器
4. 错误处理 - 监听 OnBattleServiceError 事件，及时处理服务异常
5. 网络异常 - 建议提供友好的错误提示和重新匹配功能
6. 频率限制 - SendCustomMessage 和 UpdateRoomProperties 共享每秒 15 次的调用频率限制

API 调用频率限制

API	频率限制	说明
SendCustomMessage	与 UpdateRoomProperties 共享 15 次/秒	玩家通信核心 API
UpdateRoomProperties	与 SendCustomMessage 共享 15 次/秒	更新房间属性
UpdatePlayerCustomStatus	无特殊限制	更新玩家状态
UpdatePlayerCustomProperties	无特殊限制	更新玩家属性
SendFrameInput	无特殊限制	高级功能 API

技术支持

如有问题，请通过以下方式联系我们：

• 开发者工单：https://developer.taptap.cn/user-center/create-ticket (opens new window)