跳到主要内容
版本：v4

API 参考

注意事项​

初始化要求

调用多人联机任何 API 函数前，必须先成功调用 TapSDK_Init 进行初始化。未初始化或初始化失败时，调用多人联机函数将返回错误或者非预期结果。

字符串编码

多人联机所有 API 函数接受和返回的字符串参数（char*），都是 UTF-8 编码，请根据项目实际情况自行转换。

数据类型定义​

枚举类型​

TapOnlineGameEventID​

多人联机事件类型枚举值：[1, 1000) 预留给异步请求的回调 (Response)，[1000, 2000) 预留给服务端主动推送的通知 (Notification)。

enum {
    TapOnlineGameEventID_Unknown = 0,

    // [1, 1000) 预留给异步请求的回调 (Response)
    TapOnlineGameEventID_ConnectResponse = 1,                  // 建连请求回调，成功时使用 TapOnlineGameConnectResponse* 强转 event_data
    TapOnlineGameEventID_DisconnectResponse = 2,               // 断连请求回调，必定成功，event_data 为 NULL
    TapOnlineGameEventID_CreateRoomResponse = 3,                // 创建房间请求回调，成功时使用 TapOnlineGameCreateRoomResponse* 强转 event_data
    TapOnlineGameEventID_MatchRoomResponse = 4,                 // 匹配房间请求回调，成功时使用 TapOnlineGameMatchRoomResponse* 强转 event_data
    TapOnlineGameEventID_GetRoomListResponse = 5,              // 获取房间列表请求回调，成功时使用 TapOnlineGameGetRoomListResponse* 强转 event_data
    TapOnlineGameEventID_JoinRoomResponse = 6,                 // 加入房间请求回调，成功时使用 TapOnlineGameJoinRoomResponse* 强转 event_data
    TapOnlineGameEventID_LeaveRoomResponse = 7,                // 离开房间请求回调，event_data 为 NULL
    TapOnlineGameEventID_UpdatePlayerCustomStatusResponse = 8, // 更新玩家自定义状态请求回调，event_data 为 NULL
    TapOnlineGameEventID_UpdatePlayerCustomPropertiesResponse = 9, // 更新玩家自定义属性请求回调，event_data 为 NULL
    TapOnlineGameEventID_UpdateRoomPropertiesResponse = 10,    // 更新房间属性请求回调，event_data 为 NULL
    TapOnlineGameEventID_SendCustomMessageResponse = 11,        // 发送自定义消息请求回调，event_data 为 NULL
    TapOnlineGameEventID_KickRoomPlayerResponse = 12,           // 踢玩家出房间请求回调，event_data 为 NULL
    TapOnlineGameEventID_StartFrameSyncResponse = 13,           // 开始帧同步请求回调，event_data 为 NULL
    TapOnlineGameEventID_SendFrameInputResponse = 14,           // 发送操作数据请求回调，event_data 为 NULL
    TapOnlineGameEventID_StopFrameSyncResponse = 15,            // 结束帧同步请求回调，event_data 为 NULL

    // [1000, 2000) 预留给服务端主动推送的通知 (Notification)
    TapOnlineGameEventID_ServiceErrorNotification = 1000,       // 对战服务异常通知。收到该通知时，游戏需要恢复成 Connect 成功的初始状态（房间、对战等状态在服务端已丢失）
    TapOnlineGameEventID_DisconnectNotification = 1001,        // 被踢、异常断线时通知，通过 error 字段获取具体错误信息。断线可重连；被踢不要重连
    TapOnlineGameEventID_PlayerOfflineNotification = 1002,     // 玩家离线通知，使用 TapOnlineGamePlayerOfflineNotification* 强转 event_data
    TapOnlineGameEventID_EnterRoomNotification = 1003,          // 新玩家进入房间通知，使用 TapOnlineGamePlayerEnterRoomNotification* 强转 event_data
    TapOnlineGameEventID_LeaveRoomNotification = 1004,          // 玩家离开房间通知，使用 TapOnlineGamePlayerLeaveRoomNotification* 强转 event_data
    TapOnlineGameEventID_PlayerCustomStatusNotification = 1005,    // 玩家自定义状态变更通知，使用 TapOnlineGamePlayerCustomStatusNotification* 强转 event_data
    TapOnlineGameEventID_PlayerCustomPropertiesNotification = 1006, // 玩家自定义属性变更通知，使用 TapOnlineGamePlayerCustomPropertiesNotification* 强转 event_data
    TapOnlineGameEventID_RoomPropertiesNotification = 1007,     // 房间属性更新通知，使用 TapOnlineGameRoomPropertiesNotification* 强转 event_data
    TapOnlineGameEventID_CustomMessageNotification = 1008,      // 收到自定义消息时回调，使用 TapOnlineGameCustomMessageNotification* 强转 event_data
    TapOnlineGameEventID_RoomPlayerKickedNotification = 1009,   // 玩家被踢出房间通知，房间内所有玩家都会收到，使用 TapOnlineGameRoomPlayerKickedNotification* 强转 event_data
    TapOnlineGameEventID_FrameSyncStartNotification = 1010,     // 帧同步开始通知，使用 TapOnlineGameFrameSyncStartNotification* 强转 event_data
    TapOnlineGameEventID_FrameNotification = 1011,              // 最新对战帧同步，使用 TapOnlineGameFrame* 强转 event_data
    TapOnlineGameEventID_FrameSyncStopNotification = 1012,      // 帧同步结束通知，使用 TapOnlineGameFrameSyncStopNotification* 强转 event_data
};
// 多人联机事件类型，取值请参考枚举值 TapOnlineGameEventID_*
typedef uint32_t TapOnlineGameEventID;

结构体类型​

字节对齐

多人联机使用的所有结构体类型，均使用 8 字节对齐：#pragma pack(push, 8)。

TapOnlineGameEvent​

多人联机通用事件结构体：

typedef struct {
    int64_t request_id;             // 请求 ID。原样返回开发者调用异步接口时传入的 ID；服务端通知时该字段为 0
    const TapSDK_Error* error;      // 错误信息。NULL 表示请求成功；非 NULL 表示请求失败
    TapOnlineGameEventID event_id;  // 根据事件 ID，使用正确的结构体强转 event_data
    const void* event_data;         // 事件数据，如异步请求结果或服务端通知消息
} TapOnlineGameEvent;

TapOnlineGameConnectResponse​

TapOnlineGame_AsyncConnect() 请求成功时的返回：

typedef struct {
    const char* player_id; // 玩家 ID
} TapOnlineGameConnectResponse;

TapOnlineGameMatchParam​

匹配参数键值对：

typedef struct {
    const char* key;   // 匹配参数键，最大 32 字节
    const char* value; // 匹配参数值，最大 64 字节
} TapOnlineGameMatchParam;

TapOnlineGameRoomConfig​

房间配置：

typedef struct {
    uint32_t max_player_count;                    // 房间最大人数，[1,20]，必填
    const char* room_type;                        // 房间类型，最大 32 字节，必填
    uint32_t match_param_count;                   // match_params 数组长度，最多 3 条匹配规则
    const TapOnlineGameMatchParam* match_params;  // 自定义匹配参数数组。匹配时需同时满足 max_player_count+room_type+match_params
    const char* name;                             // 房间名称
    const char* custom_properties;                // 房间自定义属性，最大 2048 字节
} TapOnlineGameRoomConfig;

TapOnlineGamePlayerConfig​

玩家配置：

typedef struct {
    int32_t custom_status;         // 玩家自定义状态
    const char* custom_properties; // 玩家自定义属性，最大 2048 字节
} TapOnlineGamePlayerConfig;

TapOnlineGameCreateRoomRequest​

创建房间请求，用于 TapOnlineGame_AsyncCreateRoom()：

typedef struct {
    TapOnlineGameRoomConfig room_cfg;    // 房间配置
    TapOnlineGamePlayerConfig player_cfg; // 玩家配置
} TapOnlineGameCreateRoomRequest;

TapOnlineGamePlayerInfo​

玩家信息：

typedef struct {
    const char* id; // 玩家 ID
    int32_t status; // 玩家状态：0-离线、1-在线
    int32_t custom_status; // 玩家自定义状态
    const char* custom_properties; // 玩家自定义属性，最大 2048 字节
} TapOnlineGamePlayerInfo;

TapOnlineGameRoomInfo​

房间信息：

typedef struct {
    const char* id; // 房间 ID
    const char* name; // 房间名称
    const char* room_type; // 房间类型
    const char* owner_id; // 房主 ID
    int32_t status; // 房间状态，0-未开始帧同步，1-帧同步中
    const char* custom_properties; // 房间自定义属性，最大 2048 字节
    uint32_t max_player_count; // 房间最大人数，[1,20]
    uint32_t player_count; // 房间内玩家数量
    const TapOnlineGamePlayerInfo* players; // 房间内玩家列表，长度为 player_count
    int64_t create_time; // 房间创建时间，1970 年开始的秒数
} TapOnlineGameRoomInfo;

TapOnlineGameCreateRoomResponse​

TapOnlineGame_AsyncCreateRoom() 请求成功时的返回：

typedef struct {
    const TapOnlineGameRoomInfo* room_info; // 成功创建的房间信息
} TapOnlineGameCreateRoomResponse;

TapOnlineGameMatchRoomRequest​

匹配房间请求，用于 TapOnlineGame_AsyncMatchRoom()：

typedef struct {
    TapOnlineGameRoomConfig room_cfg;    // 房间配置，用于匹配不到时创建房间
    TapOnlineGamePlayerConfig player_cfg; // 玩家配置
} TapOnlineGameMatchRoomRequest;

TapOnlineGameMatchRoomResponse​

TapOnlineGame_AsyncMatchRoom() 请求成功时的返回：

typedef struct {
    const TapOnlineGameRoomInfo* room_info; // 成功匹配/创建的房间信息
} TapOnlineGameMatchRoomResponse;

TapOnlineGameGetRoomListRequest​

拉取房间列表请求，用于 TapOnlineGame_AsyncGetRoomList()：

typedef struct {
    const char* room_type; // 房间类型。不填则拉取全部类型
    uint32_t offset;       // 偏移量，首次请求为 0
    uint32_t limit;        // 请求获取的房间数量，默认 20，最大 100
} TapOnlineGameGetRoomListRequest;

TapOnlineGameRoomBasicInfo​

房间基本信息：

typedef struct {
    const char* id; // 房间 ID
    const char* name; // 房间名称
    const char* room_type; // 房间类型
    int32_t status; // 房间状态，0-未开始帧同步，1-帧同步中
    const char* custom_properties; // 房间自定义属性，最大 2048 字节
    uint32_t max_player_count; // 房间最大人数
    uint32_t player_count; // 房间当前人数
    int64_t create_time; // 房间创建时间，1970 年开始的秒数
} TapOnlineGameRoomBasicInfo;

TapOnlineGameGetRoomListResponse​

TapOnlineGame_AsyncGetRoomList() 请求成功时的返回：

typedef struct {
    uint32_t room_count; // rooms 数组长度
    const TapOnlineGameRoomBasicInfo* rooms; // 可加入房间列表，长度为 room_count
    uint32_t offset; // 用于请求下一页的偏移量
    bool has_more; // 是否还有更多房间
} TapOnlineGameGetRoomListResponse;

TapOnlineGameJoinRoomRequest​

加入房间请求，用于 TapOnlineGame_AsyncJoinRoom()：

typedef struct {
    const char* room_id; // 房间 ID，不允许空
    TapOnlineGamePlayerConfig player_cfg; // 玩家配置
} TapOnlineGameJoinRoomRequest;

TapOnlineGameJoinRoomResponse​

TapOnlineGame_AsyncJoinRoom() 请求成功时的返回：

typedef struct {
    const TapOnlineGameRoomInfo* room_info; // 成功进入的房间信息
} TapOnlineGameJoinRoomResponse;

TapOnlineGameUpdateRoomPropertiesRequest​

更新房间属性请求，用于 TapOnlineGame_AsyncUpdateRoomProperties()：

typedef struct {
    const char* name;              // 房间名称，最大 64 字节
    const char* custom_properties; // 房间自定义属性，最大 2048 字节
} TapOnlineGameUpdateRoomPropertiesRequest;

TapOnlineGameSendCustomMessageRequest​

发送自定义消息请求，用于 TapOnlineGame_AsyncSendCustomMessage()：

typedef struct {
    const char* msg;         // 自定义消息，不能为空，UTF-8 字符串，最大 2048 字节
    uint32_t receiver_type;  // 消息接收者类型。0-房间内所有人（不含发送者），1-指定玩家
    uint32_t receiver_count; // receivers 数组长度，最多 20 个玩家 ID
    const char** receivers;  // 消息接收者 ID 数组，receiver_type 为 1 时有效
} TapOnlineGameSendCustomMessageRequest;

TapOnlineGameSendFrameInputRequest​

发送操作数据，用于 TapOnlineGame_AsyncSendFrameInput()：

typedef struct {
    const char* data; // 游戏操作，UTF-8 字符串格式，最大 1024 字节
} TapOnlineGameSendFrameInputRequest;

TapOnlineGamePlayerOfflineNotification​

玩家离线通知（仅帧同步开始后离线才会发送）：

typedef struct {
    const char* room_id; // 离线玩家所属房间 ID
    const char* room_owner_id; // 房主 ID。若离线的是房主则为新房主 ID，否则为原房主 ID
    const char* player_id; // 离线玩家 ID
} TapOnlineGamePlayerOfflineNotification;

TapOnlineGamePlayerEnterRoomNotification​

玩家进入房间通知：

typedef struct {
    const char* room_id; // 玩家进入的房间 ID
    const TapOnlineGamePlayerInfo* player_info; // 玩家信息
} TapOnlineGamePlayerEnterRoomNotification;

TapOnlineGamePlayerLeaveRoomNotification​

玩家离开房间通知：

typedef struct {
    const char* room_id; // 玩家离开的房间 ID
    const char* room_owner_id; // 房主 ID。若离开的是房主则为新房主 ID，否则为原房主 ID
    const char* player_id; // 玩家 ID
} TapOnlineGamePlayerLeaveRoomNotification;

TapOnlineGamePlayerCustomStatusNotification​

玩家自定义状态变更通知：

typedef struct {
    const char* player_id; // 玩家 ID
    int32_t status; // 玩家自定义状态
} TapOnlineGamePlayerCustomStatusNotification;

TapOnlineGamePlayerCustomPropertiesNotification​

玩家自定义属性变更通知：

typedef struct {
    const char* player_id; // 玩家 ID
    const char* properties; // 玩家自定义属性
} TapOnlineGamePlayerCustomPropertiesNotification;

TapOnlineGameRoomPropertiesNotification​

房间属性变更通知：

typedef struct {
    const char* id; // 房间 ID
    const char* name; // 房间名称
    const char* custom_properties; // 房间自定义属性
} TapOnlineGameRoomPropertiesNotification;

TapOnlineGameCustomMessageNotification​

自定义消息通知：

typedef struct {
    const char* player_id; // 消息发送者玩家 ID
    const char* msg;       // 自定义消息，UTF-8 字符串，最大 2048 字节
} TapOnlineGameCustomMessageNotification;

TapOnlineGameRoomPlayerKickedNotification​

玩家被踢出房间通知：

typedef struct {
    const char* room_id;   // 被踢玩家所属房间 ID
    const char* player_id; // 被踢玩家 ID
} TapOnlineGameRoomPlayerKickedNotification;

TapOnlineGameFrameSyncStartNotification​

帧同步开始通知：

typedef struct {
    const TapOnlineGameRoomInfo* room_info; // 开始帧同步的房间信息
    int32_t frame_sync_id;                  // 帧同步 ID，房间内唯一，每次开始帧同步都会变化
    int32_t seed;                           // 用于初始化一致性随机数生成器的随机数种子，比如初始化 TapSDK_CreateRandomNumberGenerator() 时使用
    int64_t server_tms;                     // 对战开始的服务端时间，1970 年开始的毫秒数
} TapOnlineGameFrameSyncStartNotification;

TapOnlineGameFrameInput​

单个玩家在一帧内的一个操作数据：

typedef struct {
    const char* player_id; // 玩家 ID
    const char* data;      // 玩家的一个操作数据，UTF-8 字符串格式
    int64_t server_tms;    // 服务器收到该输入的时间，1970 年开始的毫秒数
} TapOnlineGameFrameInput;

TapOnlineGameFrame​

帧同步数据结构体：

typedef struct {
    uint32_t id;                           // 当前帧 ID，从 1 开始递增
    uint32_t input_count;                  // inputs 数组长度
    const TapOnlineGameFrameInput* inputs; // 当前帧所有玩家操作，按服务端收到顺序排序
} TapOnlineGameFrame;

TapOnlineGameFrameSyncStopNotification​

帧同步结束通知：

typedef struct {
    const char* room_id;     // 帧同步结束的房间 ID
    int32_t frame_sync_id;   // 帧同步 ID，房间内唯一
    int32_t reason;          // 结束原因。0-房主主动结束，1-帧同步因超时结束
} TapOnlineGameFrameSyncStopNotification;

ITapOnlineGame​

多人联机接口对象，通过 TapOnlineGame() 获取：

typedef struct ITapOnlineGame ITapOnlineGame;

回调功能​

多人联机的异步请求结果和服务端主动通知，均通过回调函数获取。

内存管理
  • 回调函数中的事件对象的内存由 SDK 管理，调用者无需释放
  • 回调函数返回后，SDK 会自动释放该内存，如需长期使用，请自行复制一份

TapOnlineGameCallback​

多人联机回调函数类型定义：

typedef void (*TapOnlineGameCallback)(const TapOnlineGameEvent*);

TapOnlineGame_RunCallbacks​

触发回调函数，处理请求结果和服务端主动通知，建议每帧调用。

uint32_t TapOnlineGame_RunCallbacks(
    ITapOnlineGame* self,
    TapOnlineGameCallback cb,
    uint32_t maxEvents,
    uint32_t* leftEvents
);

参数：

  • self：TapOnlineGame() 返回的多人联机单例对象
  • cb：事件处理函数
  • maxEvents：本次调用最多处理事件数量，传 0 表示全量处理。一般传 10 即可
  • leftEvents：输出参数，返回剩余未处理的事件数。可据此判断是否需要多次调用以处理完所有事件

返回值：

  • 本次调用处理的事件数

使用示例：

// 多人联机事件处理回调函数
void onlineGameEventHandler(const TapOnlineGameEvent* event);

int main() {
    // 假设已经成功初始化SDK

    bool running = true;
    while (running) {
        // 处理多人联机回调事件
        // 开发者可以指定每次调用该接口最多触发的事件数量，传 0 表示触发队列中所有事件
        // 建议每帧至少执行一次该接口，及时处理队列中的实时事件
        uint32_t leftEvents; // 用于获取队列中未处理事件个数。开发者可以根据未处理事件数量，决定是否需要循环调用该接口
        auto handledEvents = TapOnlineGame_RunCallbacks(TapOnlineGame(), onlineGameEventHandler, 10, &leftEvents) ;

        // 您的游戏逻辑
        // ...

        // 控制帧率，请按游戏实际需求调整
        Sleep(33);
    }

    TapSDK_Shutdown();
    return 0;
}

// 多人联机事件处理回调函数
void onlineGameEventHandler(const TapOnlineGameEvent* event)
{
    // 注意：event及其里面引用的其他内存，在回调函数返回后会被 SDK 释放。如需长期使用，请开发者自行复制一份
    switch (event->event_id) { // 根据 TapOnlineGameEventID，执行对应处理函数
    case TapOnlineGameEventID_ConnectResponse:
        // 和多人联机服务端的建连结果
        handleConnectResponse(event);
        break;
    case TapOnlineGameEventID_CreateRoomResponse:
        // 创建联机游戏房间的结果
        handleCreateRoomResponse(event);
        break;
    // 其他事件处理分支...
    default:
        break;
    }
}

函数说明​

TapOnlineGame​

获取多人联机接口单例对象。

ITapOnlineGame* TapOnlineGame();

返回值：

  • 多人联机接口单例对象

使用示例：

static int64_t gRequestID = 0;
ITapOnlineGame* onlineGame = TapOnlineGame();
TapSDK_Result ret = TapOnlineGame_AsyncConnect(onlineGame, ++gRequestID);

TapOnlineGame_AsyncConnect​

发起与多人联机服务建立长连接的异步请求。请求发起成功后，结果通过 TapOnlineGameEventID_ConnectResponse 事件返回。

TapSDK_Result TapOnlineGame_AsyncConnect(
    ITapOnlineGame* self,
    int64_t request_id
);

参数：

  • self：TapOnlineGame() 返回的多人联机单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回，用于对应原始请求

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调

注意事项：

  • 请求成功事件返回后，才能发起创建房间、匹配房间等请求

TapOnlineGame_AsyncDisconnect​

发起与多人联机服务断开连接的异步请求。请求发起成功后，结果通过 TapOnlineGameEventID_DisconnectResponse 事件返回。

TapSDK_Result TapOnlineGame_AsyncDisconnect(
    ITapOnlineGame* self,
    int64_t request_id
);

参数：

  • self：TapOnlineGame() 返回的多人联机单例对象
  • request_id：开发者生成的请求 ID

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调

注意事项：

  • 断连后，再次执行 TapOnlineGame_AsyncConnect 成功前，无法发起创建房间、匹配房间等请求

TapOnlineGame_AsyncCreateRoom​

发起创建房间的异步请求。请求发起成功后，结果通过 TapOnlineGameEventID_CreateRoomResponse 事件返回。

TapSDK_Result TapOnlineGame_AsyncCreateRoom(
    ITapOnlineGame* self,
    int64_t request_id,
    const TapOnlineGameCreateRoomRequest* request
);

参数：

  • self：TapOnlineGame() 返回的多人联机单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回
  • request：创建房间请求参数，不允许空指针

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调

使用示例：

TapOnlineGameCreateRoomRequest createRoomRequest;
// 结构体"零值化"，避免内存随机值导致的野指针问题
// C++11 及以上，可以使用 TapOnlineGameCreateRoomRequest createRoomRequest{};，无需 memset
memset(&createRoomRequest, 0, sizeof(createRoomRequest));
// 房间配置：最大人数 [1,20]，房间类型必填，最多 3 条匹配规则
createRoomRequest.room_cfg.max_player_count = 4;
createRoomRequest.room_cfg.room_type = "ranked";
createRoomRequest.room_cfg.name = "MyRoom";
createRoomRequest.room_cfg.custom_properties = "{}";
// 玩家配置
createRoomRequest.player_cfg.custom_status = 0;
createRoomRequest.player_cfg.custom_properties = "{}";
auto ret = TapOnlineGame_AsyncCreateRoom(
    TapOnlineGame(), // 多人联机模块单例对象
    ++gRequestID,    // 请求 ID，由开发者生成，用于在回调中对应到原始请求
    &createRoomRequest);
if (ret != TapSDK_Result_OK) {
    // 请求发起失败，不会触发回调，请根据返回值做相应处理
    return -1;
}

TapOnlineGame_AsyncMatchRoom​

发起匹配房间的异步请求。请求发起成功后，结果通过 TapOnlineGameEventID_MatchRoomResponse 事件返回。

TapSDK_Result TapOnlineGame_AsyncMatchRoom(
    ITapOnlineGame* self,
    int64_t request_id,
    const TapOnlineGameMatchRoomRequest* request
);

参数：

  • self：TapOnlineGame() 返回的多人联机单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回
  • request：匹配房间请求参数，不允许空指针

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调

使用示例：

TapOnlineGameMatchRoomRequest matchRoomRequest;
// 结构体"零值化"，避免内存随机值导致的野指针问题
// C++11 及以上，可以使用 TapOnlineGameMatchRoomRequest matchRoomRequest{};，无需 memset
memset(&matchRoomRequest, 0, sizeof(matchRoomRequest));
matchRoomRequest.room_cfg.max_player_count = 4;
matchRoomRequest.room_cfg.room_type = "ranked";
matchRoomRequest.room_cfg.name = "MyRoom";
matchRoomRequest.room_cfg.custom_properties = "{}";
matchRoomRequest.player_cfg.custom_status = 0;
matchRoomRequest.player_cfg.custom_properties = "{}";
auto ret = TapOnlineGame_AsyncMatchRoom(
    TapOnlineGame(),
    ++gRequestID,
    &matchRoomRequest);
if (ret != TapSDK_Result_OK) {
    // 请求发起失败，不会触发回调
    return -1;
}

TapOnlineGame_AsyncGetRoomList​

发起拉取房间列表的异步请求。请求发起成功后，结果通过 TapOnlineGameEventID_GetRoomListResponse 事件返回。

TapSDK_Result TapOnlineGame_AsyncGetRoomList(
    ITapOnlineGame* self,
    int64_t request_id,
    const TapOnlineGameGetRoomListRequest* request
);

参数：

  • self：TapOnlineGame() 返回的多人联机单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回
  • request：拉取房间列表请求参数

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调

使用示例：

TapOnlineGameGetRoomListRequest getRoomListRequest;
// 结构体"零值化"，避免内存随机值导致的野指针问题
// C++11 及以上，可以使用 TapOnlineGameGetRoomListRequest getRoomListRequest{};，无需 memset
memset(&getRoomListRequest, 0, sizeof(getRoomListRequest));
getRoomListRequest.room_type = "ranked"; // 不填则拉取全部类型
getRoomListRequest.offset = 0;           // 首次请求为 0，翻页时使用上次返回的 offset
getRoomListRequest.limit = 20;          // 默认 20，最大 100
auto ret = TapOnlineGame_AsyncGetRoomList(
    TapOnlineGame(),
    ++gRequestID,
    &getRoomListRequest);
if (ret != TapSDK_Result_OK) {
    // 请求发起失败，不会触发回调
    return -1;
}

TapOnlineGame_AsyncJoinRoom​

发起加入房间的异步请求。请求发起成功后，结果通过 TapOnlineGameEventID_JoinRoomResponse 事件返回。

TapSDK_Result TapOnlineGame_AsyncJoinRoom(
    ITapOnlineGame* self,
    int64_t request_id,
    const TapOnlineGameJoinRoomRequest* request
);

参数：

  • self：TapOnlineGame() 返回的多人联机单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回
  • request：加入房间请求参数

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调

使用示例：

TapOnlineGameJoinRoomRequest joinRoomRequest;
// 结构体"零值化"，避免内存随机值导致的野指针问题
// C++11 及以上，可以使用 TapOnlineGameJoinRoomRequest joinRoomRequest{};，无需 memset
memset(&joinRoomRequest, 0, sizeof(joinRoomRequest));
joinRoomRequest.room_id = "room_id_from_list"; // 拉取房间列表获得的房间 ID，不允许空
joinRoomRequest.player_cfg.custom_status = 0;
joinRoomRequest.player_cfg.custom_properties = "{}";
auto ret = TapOnlineGame_AsyncJoinRoom(
    TapOnlineGame(),
    ++gRequestID,
    &joinRoomRequest);
if (ret != TapSDK_Result_OK) {
    // 请求发起失败，不会触发回调
    return -1;
}

TapOnlineGame_AsyncLeaveRoom​

发起离开房间的异步请求。请求发起成功后，结果通过 TapOnlineGameEventID_LeaveRoomResponse 事件返回。

TapSDK_Result TapOnlineGame_AsyncLeaveRoom(
    ITapOnlineGame* self,
    int64_t request_id
);

参数：

  • self：TapOnlineGame() 返回的多人联机单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调

注意事项：

  • 处于帧同步状态时不允许调用，会通过 TapOnlineGameEventID_LeaveRoomResponse 返回对应错误

TapOnlineGame_AsyncUpdatePlayerCustomStatus​

发起更新玩家自定义状态的异步请求。请求发起成功后，结果通过 TapOnlineGameEventID_UpdatePlayerCustomStatusResponse 事件返回。

TapSDK_Result TapOnlineGame_AsyncUpdatePlayerCustomStatus(
    ITapOnlineGame* self,
    int64_t request_id,
    int32_t status
);

参数：

  • self：TapOnlineGame() 返回的多人联机单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回
  • status：玩家自定义状态

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调

注意事项：

  • 处于帧同步状态时不允许调用，会通过事件返回对应错误
  • 与 TapOnlineGame_AsyncUpdatePlayerCustomProperties()、TapOnlineGame_AsyncUpdateRoomProperties()、TapOnlineGame_AsyncSendCustomMessage() 共享每秒 15 次调用限制
频率限制

TapOnlineGame_AsyncLeaveRoom()、TapOnlineGame_AsyncUpdatePlayerCustomProperties()、TapOnlineGame_AsyncUpdateRoomProperties()、TapOnlineGame_AsyncSendCustomMessage()共享每秒 15 次调用限制。

TapOnlineGame_AsyncUpdatePlayerCustomProperties​

发起更新玩家自定义属性的异步请求。请求发起成功后，结果通过 TapOnlineGameEventID_UpdatePlayerCustomPropertiesResponse 事件返回。

TapSDK_Result TapOnlineGame_AsyncUpdatePlayerCustomProperties(
    ITapOnlineGame* self,
    int64_t request_id,
    const char* properties
);

参数：

  • self：TapOnlineGame() 返回的多人联机单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回
  • properties：玩家自定义属性，UTF-8 编码字符串，允许空

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调

注意事项：

  • 处于帧同步状态时不允许调用
  • 与 UpdatePlayerCustomStatus、UpdateRoomProperties、SendCustomMessage 共享每秒 15 次调用限制

TapOnlineGame_AsyncUpdateRoomProperties​

发起更新房间属性的异步请求。请求发起成功后，结果通过 TapOnlineGameEventID_UpdateRoomPropertiesResponse 事件返回。

TapSDK_Result TapOnlineGame_AsyncUpdateRoomProperties(
    ITapOnlineGame* self,
    int64_t request_id,
    const TapOnlineGameUpdateRoomPropertiesRequest* request
);

参数：

  • self：TapOnlineGame() 返回的多人联机单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回
  • request：更新房间属性请求参数，不允许空指针

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调

使用示例：

TapOnlineGameUpdateRoomPropertiesRequest updateRoomPropsRequest;
// 结构体"零值化"，避免内存随机值导致的野指针问题
// C++11 及以上，可以使用 TapOnlineGameUpdateRoomPropertiesRequest updateRoomPropsRequest{};，无需 memset
memset(&updateRoomPropsRequest, 0, sizeof(updateRoomPropsRequest));
updateRoomPropsRequest.name = "NewRoomName";           // 房间名称，最大 64 字节
updateRoomPropsRequest.custom_properties = "{}";     // 房间自定义属性，最大 2048 字节
auto ret = TapOnlineGame_AsyncUpdateRoomProperties(
    TapOnlineGame(),
    ++gRequestID,
    &updateRoomPropsRequest);
if (ret != TapSDK_Result_OK) {
    return -1;
}

注意事项：

  • 处于帧同步状态时不允许调用，且仅限房主调用
  • 与 UpdatePlayerCustomStatus、UpdatePlayerCustomProperties、SendCustomMessage 共享每秒 15 次调用限制

TapOnlineGame_AsyncSendCustomMessage​

发起发送自定义消息的异步请求。请求发起成功后，结果通过 TapOnlineGameEventID_SendCustomMessageResponse 事件返回。

TapSDK_Result TapOnlineGame_AsyncSendCustomMessage(
    ITapOnlineGame* self,
    int64_t request_id,
    const TapOnlineGameSendCustomMessageRequest* request
);

参数：

  • self：TapOnlineGame() 返回的多人联机单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回
  • request：发送自定义消息请求参数，不允许空指针

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调

使用示例：

TapOnlineGameSendCustomMessageRequest sendMsgRequest;
// 结构体"零值化"，避免内存随机值导致的野指针问题
// C++11 及以上，可以使用 TapOnlineGameSendCustomMessageRequest sendMsgRequest{};，无需 memset
memset(&sendMsgRequest, 0, sizeof(sendMsgRequest));
sendMsgRequest.msg = "hello";                    // 自定义消息，不能为空，UTF-8，最大 2048 字节
sendMsgRequest.receiver_type = 0;               // 0-房间内所有人（不含发送者），1-指定玩家
// receiver_type 为 1 时需设置 receiver_count 和 receivers
// const char* targets[] = { "player_id_1" };
// sendMsgRequest.receiver_type = 1;
// sendMsgRequest.receiver_count = 1;
// sendMsgRequest.receivers = targets;
auto ret = TapOnlineGame_AsyncSendCustomMessage(
    TapOnlineGame(),
    ++gRequestID,
    &sendMsgRequest);
if (ret != TapSDK_Result_OK) {
    return -1;
}

注意事项：

  • 与 UpdatePlayerCustomStatus、UpdatePlayerCustomProperties、UpdateRoomProperties 共享每秒 15 次调用限制

TapOnlineGame_AsyncKickRoomPlayer​

发起将玩家踢出房间的异步请求。请求发起成功后，结果通过 TapOnlineGameEventID_KickRoomPlayerResponse 事件返回。

TapSDK_Result TapOnlineGame_AsyncKickRoomPlayer(
    ITapOnlineGame* self,
    int64_t request_id,
    const char* player_id
);

参数：

  • self：TapOnlineGame() 返回的多人联机单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回
  • player_id：被踢玩家的 ID，UTF-8 编码字符串，不允许空

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调

注意事项：

  • 帧同步中不允许踢人，仅限房主调用，会通过事件返回对应错误

TapOnlineGame_AsyncStartFrameSync​

发起开始帧同步的异步请求。请求发起成功后，结果通过 TapOnlineGameEventID_StartFrameSyncResponse 事件返回。

TapSDK_Result TapOnlineGame_AsyncStartFrameSync(
    ITapOnlineGame* self,
    int64_t request_id
);

参数：

  • self：TapOnlineGame() 返回的多人联机单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调

TapOnlineGame_AsyncSendFrameInput​

发起发送玩家操作的异步请求。请求发起成功后，结果通过 TapOnlineGameEventID_SendFrameInputResponse 事件返回。

TapSDK_Result TapOnlineGame_AsyncSendFrameInput(
    ITapOnlineGame* self,
    int64_t request_id,
    const TapOnlineGameSendFrameInputRequest* request
);

参数：

  • self：TapOnlineGame() 返回的多人联机单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回
  • request：发送玩家操作请求参数，不允许空指针

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调

使用示例：

TapOnlineGameSendFrameInputRequest sendFrameInputRequest;
// 结构体"零值化"，避免内存随机值导致的野指针问题
// C++11 及以上，可以使用 TapOnlineGameSendFrameInputRequest sendFrameInputRequest{};，无需 memset
memset(&sendFrameInputRequest, 0, sizeof(sendFrameInputRequest));
sendFrameInputRequest.data = "{\"x\":1,\"y\":0}";  // 游戏操作，UTF-8 字符串格式
auto ret = TapOnlineGame_AsyncSendFrameInput(
    TapOnlineGame(),
    ++gRequestID,
    &sendFrameInputRequest);
if (ret != TapSDK_Result_OK) {
    return -1;
}

注意事项：

  • 同一帧允许最多发送 5 次操作，超限会通过事件返回对应错误

TapOnlineGame_AsyncStopFrameSync​

发起停止帧同步的异步请求。请求发起成功后，结果通过 TapOnlineGameEventID_StopFrameSyncResponse 事件返回。

TapSDK_Result TapOnlineGame_AsyncStopFrameSync(
    ITapOnlineGame* self,
    int64_t request_id
);

参数：

  • self：TapOnlineGame() 返回的多人联机单例对象
  • request_id：开发者生成的请求 ID，回调时原样返回

返回值：

  • TapSDK_Result：若非 TapSDK_Result_OK 表示请求发起失败，不会触发回调