Skip to main content
Version: v4

API Reference

Important Notes​

Initialization Requirement

You must successfully call TapSDK_Init before calling any Online Multiplayer API. Calling Online Multiplayer functions without initialization or after initialization failure will return errors or unexpected results.

String Encoding

All string parameters (char*) accepted and returned by Online Multiplayer APIs are UTF-8 encoded. Convert as needed for your project.

Data Type Definitions​

Enumeration Types​

TapOnlineBattleEventID​

Online multiplayer event type enumeration: [1, 1000) is reserved for async request callbacks (Response), [1000, 2000) for server-pushed notifications (Notification).

enum {
    TapOnlineBattleEventID_Unknown = 0,

    // [1, 1000) reserved for async request callbacks (Response)
    TapOnlineBattleEventID_ConnectResponse = 1,                  // Connect callback; on success cast event_data to TapOnlineBattleConnectResponse*
    TapOnlineBattleEventID_DisconnectResponse = 2,                // Disconnect callback; always success, event_data is NULL
    TapOnlineBattleEventID_CreateRoomResponse = 3,               // Create room callback; on success cast event_data to TapOnlineBattleCreateRoomResponse*
    TapOnlineBattleEventID_MatchRoomResponse = 4,                // Match room callback; on success cast event_data to TapOnlineBattleMatchRoomResponse*
    TapOnlineBattleEventID_GetRoomListResponse = 5,             // Get room list callback; on success cast event_data to TapOnlineBattleGetRoomListResponse*
    TapOnlineBattleEventID_JoinRoomResponse = 6,                 // Join room callback; on success cast event_data to TapOnlineBattleJoinRoomResponse*
    TapOnlineBattleEventID_LeaveRoomResponse = 7,                // Leave room callback; event_data is NULL
    TapOnlineBattleEventID_UpdatePlayerCustomStatusResponse = 8, // Update player custom status callback; event_data is NULL
    TapOnlineBattleEventID_UpdatePlayerCustomPropertiesResponse = 9, // Update player custom properties callback; event_data is NULL
    TapOnlineBattleEventID_UpdateRoomPropertiesResponse = 10,    // Update room properties callback; event_data is NULL
    TapOnlineBattleEventID_SendCustomMessageResponse = 11,      // Send custom message callback; event_data is NULL
    TapOnlineBattleEventID_KickRoomPlayerResponse = 12,          // Kick player callback; event_data is NULL
    TapOnlineBattleEventID_StartFrameSyncResponse = 13,          // Start frame sync callback; event_data is NULL
    TapOnlineBattleEventID_SendFrameInputResponse = 14,          // Send frame input callback; event_data is NULL
    TapOnlineBattleEventID_StopFrameSyncResponse = 15,           // Stop frame sync callback; event_data is NULL

    // [1000, 2000) reserved for server-pushed notifications (Notification)
    TapOnlineBattleEventID_ServiceErrorNotification = 1000,     // Server error; game should restore to a state as it has just finished a successfully Connect (all states are lost at server-side)
    TapOnlineBattleEventID_DisconnectNotification = 1001,       // Kicked or unexpected disconnect; check error field. Reconnect on disconnect; do not reconnect when kicked
    TapOnlineBattleEventID_PlayerOfflineNotification = 1002,    // Player offline; cast event_data to TapOnlineBattlePlayerOfflineNotification*
    TapOnlineBattleEventID_EnterRoomNotification = 1003,        // Player entered room; cast event_data to TapOnlineBattlePlayerEnterRoomNotification*
    TapOnlineBattleEventID_LeaveRoomNotification = 1004,       // Player left room; cast event_data to TapOnlineBattlePlayerLeaveRoomNotification*
    TapOnlineBattleEventID_PlayerCustomStatusNotification = 1005,   // Player custom status changed; cast event_data to TapOnlineBattlePlayerCustomStatusNotification*
    TapOnlineBattleEventID_PlayerCustomPropertiesNotification = 1006, // Player custom properties changed; cast event_data to TapOnlineBattlePlayerCustomPropertiesNotification*
    TapOnlineBattleEventID_RoomPropertiesNotification = 1007,    // Room properties updated; cast event_data to TapOnlineBattleRoomPropertiesNotification*
    TapOnlineBattleEventID_CustomMessageNotification = 1008,    // Custom message received; cast event_data to TapOnlineBattleCustomMessageNotification*
    TapOnlineBattleEventID_RoomPlayerKickedNotification = 1009,   // Player kicked from room; cast event_data to TapOnlineBattleRoomPlayerKickedNotification*
    TapOnlineBattleEventID_FrameSyncStartNotification = 1010,    // Frame sync started; cast event_data to TapOnlineBattleFrameSyncStartNotification*
    TapOnlineBattleEventID_FrameNotification = 1011,             // Latest match frame; cast event_data to TapOnlineBattleFrame*
    TapOnlineBattleEventID_FrameSyncStopNotification = 1012,    // Frame sync stopped; cast event_data to TapOnlineBattleFrameSyncStopNotification*
};
// Online multiplayer event type; see TapOnlineBattleEventID_* for values
typedef uint32_t TapOnlineBattleEventID;

Structure Types​

Alignment

All structure types used by Online Multiplayer use 8-byte alignment: #pragma pack(push, 8).

TapOnlineBattleEvent​

Common event structure for online multiplayer:

typedef struct {
    int64_t request_id;             // Request ID; same as passed to async API; 0 for server notifications
    const TapSDK_Error* error;      // Error info; NULL on success, non-NULL on failure
    TapOnlineBattleEventID event_id;  // Use correct struct to cast event_data according to event_id
    const void* event_data;         // Event payload, e.g. async result or server notification
} TapOnlineBattleEvent;

TapOnlineBattleConnectResponse​

Returned when TapOnlineBattle_AsyncConnect() succeeds:

typedef struct {
    const char* player_id; // Player ID
} TapOnlineBattleConnectResponse;

TapOnlineBattleMatchParam​

Match parameter key-value pair:

typedef struct {
    const char* key;   // Match param key, max 32 bytes
    const char* value; // Match param value, max 64 bytes
} TapOnlineBattleMatchParam;

TapOnlineBattleRoomConfig​

Room configuration:

typedef struct {
    uint32_t max_player_count;                    // Max players, [1,20], required
    const char* room_type;                        // Room type, max 32 bytes, required
    uint32_t match_param_count;                   // Length of match_params array, up to 3 rules
    const TapOnlineBattleMatchParam* match_params;  // Custom match params; match requires max_player_count+room_type+match_params
    const char* name;                             // Room name
    const char* custom_properties;                // Room custom properties, max 2048 bytes
} TapOnlineBattleRoomConfig;

TapOnlineBattlePlayerConfig​

Player configuration:

typedef struct {
    int32_t custom_status;         // Player custom status
    const char* custom_properties; // Player custom properties, max 2048 bytes
} TapOnlineBattlePlayerConfig;

TapOnlineBattleCreateRoomRequest​

Create room request for TapOnlineBattle_AsyncCreateRoom():

typedef struct {
    TapOnlineBattleRoomConfig room_cfg;    // Room config
    TapOnlineBattlePlayerConfig player_cfg; // Player config
} TapOnlineBattleCreateRoomRequest;

TapOnlineBattlePlayerInfo​

Player information:

typedef struct {
    const char* id; // Player ID
    int32_t status; // Player status: 0-offline, 1-online
    int32_t custom_status; // Player custom status
    const char* custom_properties; // Player custom properties, max 2048 bytes
} TapOnlineBattlePlayerInfo;

TapOnlineBattleRoomInfo​

Room information:

typedef struct {
    const char* id; // Room ID
    const char* name; // Room name
    const char* room_type; // Room type
    const char* owner_id; // Room owner ID
    int32_t status; // Room status: 0-frame sync not started, 1-frame sync in progress
    const char* custom_properties; // Room custom properties, max 2048 bytes
    uint32_t max_player_count; // Max players, [1,20]
    uint32_t player_count; // Current player count
    const TapOnlineBattlePlayerInfo* players; // Player list, length player_count
    int64_t create_time; // Room creation time, seconds since 1970
} TapOnlineBattleRoomInfo;

TapOnlineBattleCreateRoomResponse​

Returned when TapOnlineBattle_AsyncCreateRoom() succeeds:

typedef struct {
    const TapOnlineBattleRoomInfo* room_info; // Created room info
} TapOnlineBattleCreateRoomResponse;

TapOnlineBattleMatchRoomRequest​

Match room request for TapOnlineBattle_AsyncMatchRoom():

typedef struct {
    TapOnlineBattleRoomConfig room_cfg;    // Room config, used to create room when no match
    TapOnlineBattlePlayerConfig player_cfg; // Player config
} TapOnlineBattleMatchRoomRequest;

TapOnlineBattleMatchRoomResponse​

Returned when TapOnlineBattle_AsyncMatchRoom() succeeds:

typedef struct {
    const TapOnlineBattleRoomInfo* room_info; // Matched or created room info
} TapOnlineBattleMatchRoomResponse;

TapOnlineBattleGetRoomListRequest​

Get room list request for TapOnlineBattle_AsyncGetRoomList():

typedef struct {
    const char* room_type; // Room type; omit to fetch all types
    uint32_t offset;       // Offset, 0 for first request
    uint32_t limit;        // Number of rooms to fetch, default 20, max 100
} TapOnlineBattleGetRoomListRequest;

TapOnlineBattleRoomBasicInfo​

Basic room information:

typedef struct {
    const char* id; // Room ID
    const char* name; // Room name
    const char* room_type; // Room type
    int32_t status; // Room status: 0-frame sync not started, 1-frame sync in progress
    const char* custom_properties; // Room custom properties, max 2048 bytes
    uint32_t max_player_count; // Max players
    uint32_t player_count; // Current player count
    int64_t create_time; // Room creation time, seconds since 1970
} TapOnlineBattleRoomBasicInfo;

TapOnlineBattleGetRoomListResponse​

Returned when TapOnlineBattle_AsyncGetRoomList() succeeds:

typedef struct {
    uint32_t room_count; // Length of rooms array
    const TapOnlineBattleRoomBasicInfo* rooms; // Joinable room list, length room_count
    uint32_t offset; // Offset for next page
    bool has_more; // Whether more rooms are available
} TapOnlineBattleGetRoomListResponse;

TapOnlineBattleJoinRoomRequest​

Join room request for TapOnlineBattle_AsyncJoinRoom():

typedef struct {
    const char* room_id; // Room ID, cannot be null
    TapOnlineBattlePlayerConfig player_cfg; // Player config
} TapOnlineBattleJoinRoomRequest;

TapOnlineBattleJoinRoomResponse​

Returned when TapOnlineBattle_AsyncJoinRoom() succeeds:

typedef struct {
    const TapOnlineBattleRoomInfo* room_info; // Joined room info
} TapOnlineBattleJoinRoomResponse;

TapOnlineBattleUpdateRoomPropertiesRequest​

Update room properties request for TapOnlineBattle_AsyncUpdateRoomProperties():

typedef struct {
    const char* name;              // Room name, max 64 bytes
    const char* custom_properties; // Room custom properties, max 2048 bytes
} TapOnlineBattleUpdateRoomPropertiesRequest;

TapOnlineBattleSendCustomMessageRequest​

Send custom message request for TapOnlineBattle_AsyncSendCustomMessage():

typedef struct {
    const char* msg;         // Custom message, non-empty, UTF-8, max 2048 bytes
    uint32_t receiver_type;  // Receiver type: 0-all in room (excluding sender), 1-specific players
    uint32_t receiver_count; // Length of receivers array, max 20 player IDs
    const char** receivers;  // Receiver ID array, valid when receiver_type is 1
} TapOnlineBattleSendCustomMessageRequest;

TapOnlineBattleSendFrameInputRequest​

Send frame input for TapOnlineBattle_AsyncSendFrameInput():

typedef struct {
    const char* data; // Game input, UTF-8 string, max 1024 bytes
} TapOnlineBattleSendFrameInputRequest;

TapOnlineBattlePlayerOfflineNotification​

Player offline notification (only sent when player goes offline after frame sync has started):

typedef struct {
    const char* room_id; // Room ID of offline player
    const char* room_owner_id; // Room owner ID; if offline player was owner, this is new owner; otherwise unchanged
    const char* player_id; // Offline player ID
} TapOnlineBattlePlayerOfflineNotification;

TapOnlineBattlePlayerEnterRoomNotification​

Player entered room notification:

typedef struct {
    const char* room_id; // Room ID the player entered
    const TapOnlineBattlePlayerInfo* player_info; // Player info
} TapOnlineBattlePlayerEnterRoomNotification;

TapOnlineBattlePlayerLeaveRoomNotification​

Player left room notification:

typedef struct {
    const char* room_id; // Room ID the player left
    const char* room_owner_id; // Room owner ID; if leaver was owner, this is new owner; otherwise unchanged
    const char* player_id; // Player ID
} TapOnlineBattlePlayerLeaveRoomNotification;

TapOnlineBattlePlayerCustomStatusNotification​

Player custom status change notification:

typedef struct {
    const char* player_id; // Player ID
    int32_t status; // Player custom status
} TapOnlineBattlePlayerCustomStatusNotification;

TapOnlineBattlePlayerCustomPropertiesNotification​

Player custom properties change notification:

typedef struct {
    const char* player_id; // Player ID
    const char* properties; // Player custom properties
} TapOnlineBattlePlayerCustomPropertiesNotification;

TapOnlineBattleRoomPropertiesNotification​

Room properties change notification:

typedef struct {
    const char* id; // Room ID
    const char* name; // Room name
    const char* custom_properties; // Room custom properties
} TapOnlineBattleRoomPropertiesNotification;

TapOnlineBattleCustomMessageNotification​

Custom message notification:

typedef struct {
    const char* player_id; // Sender player ID
    const char* msg;       // Custom message, UTF-8, max 2048 bytes
} TapOnlineBattleCustomMessageNotification;

TapOnlineBattleRoomPlayerKickedNotification​

Player kicked from room notification:

typedef struct {
    const char* room_id;   // Room ID of kicked player
    const char* player_id; // Kicked player ID
} TapOnlineBattleRoomPlayerKickedNotification;

TapOnlineBattleFrameSyncStartNotification​

Frame sync start notification:

typedef struct {
    const TapOnlineBattleRoomInfo* room_info; // Room info when frame sync started
    int32_t frame_sync_id;                  // Frame sync ID, unique in room, changes each start
    int32_t seed;                           // Seed for consistent random number generation, such as TapSDK_CreateRandomNumberGenerator()
    int64_t server_tms;                     // Server time when match started, ms since 1970
} TapOnlineBattleFrameSyncStartNotification;

TapOnlineBattleFrameInput​

Player input in one frame:

typedef struct {
    const char* player_id; // Player ID
    const char* data;      // One input, UTF-8 string
    int64_t server_tms;    // Server time when input was received, ms since 1970
} TapOnlineBattleFrameInput;

TapOnlineBattleFrame​

Frame sync data structure:

typedef struct {
    uint32_t id;                           // Frame ID, starting from 1
    uint32_t input_count;                  // Length of inputs array
    const TapOnlineBattleFrameInput* inputs; // All player inputs this frame, server receive order
} TapOnlineBattleFrame;

TapOnlineBattleFrameSyncStopNotification​

Frame sync stop notification:

typedef struct {
    const char* room_id;     // Room ID where frame sync stopped
    int32_t frame_sync_id;   // Frame sync ID, unique in room
    int32_t reason;          // Reason: 0-owner stopped, 1-timeout
} TapOnlineBattleFrameSyncStopNotification;

ITapOnlineBattle​

Online multiplayer interface object, obtained via TapOnlineBattle():

typedef struct ITapOnlineBattle ITapOnlineBattle;

Callback​

Async request results and server notifications are delivered through the callback.

Memory
  • Event object memory in the callback is managed by the SDK; do not free it
  • After the callback returns, the SDK frees that memory; copy if you need to keep it

TapOnlineBattleCallback​

Callback type for online multiplayer:

typedef void (*TapOnlineBattleCallback)(const TapOnlineBattleEvent*);

TapOnlineBattle_RunCallbacks​

Invoke the callback to process request results and server notifications. Call every frame.

uint32_t TapOnlineBattle_RunCallbacks(
    ITapOnlineBattle* self,
    TapOnlineBattleCallback cb,
    uint32_t maxEvents,
    uint32_t* leftEvents
);

Parameters:

  • self: Online multiplayer singleton from TapOnlineBattle()
  • cb: Event handler
  • maxEvents: Max events to process this call; 0 = all. Typically 10
  • leftEvents: Output; number of events left. Use to decide whether to call again

Return value:

  • Number of events processed this call

Usage example:

void onlineBattleEventHandler(const TapOnlineBattleEvent* event);

int main() {
    // Assume SDK initialized successfully

    bool running = true;
    while (running) {
        uint32_t leftEvents;
        auto handledEvents = TapOnlineBattle_RunCallbacks(TapOnlineBattle(), onlineBattleEventHandler, 10, &leftEvents);

        // Your game logic
        // ...

        Sleep(33);
    }

    TapSDK_Shutdown();
    return 0;
}

void onlineBattleEventHandler(const TapOnlineBattleEvent* event)
{
    // Note: event and referenced memory are freed by SDK after callback returns; copy if you need to keep
    switch (event->event_id) {
    case TapOnlineBattleEventID_ConnectResponse:
        handleConnectResponse(event);
        break;
    case TapOnlineBattleEventID_CreateRoomResponse:
        handleCreateRoomResponse(event);
        break;
    // other cases...
    default:
        break;
    }
}

API Reference​

TapOnlineBattle​

Get the online multiplayer singleton.

ITapOnlineBattle* TapOnlineBattle();

Return value:

  • Online multiplayer singleton

Usage example:

static int64_t gRequestID = 0;
ITapOnlineBattle* onlineBattle = TapOnlineBattle();
TapSDK_Result ret = TapOnlineBattle_AsyncConnect(onlineBattle, ++gRequestID);

TapOnlineBattle_AsyncConnect​

Start an async request to connect to the online multiplayer service. Result is delivered via TapOnlineBattleEventID_ConnectResponse.

TapSDK_Result TapOnlineBattle_AsyncConnect(
    ITapOnlineBattle* self,
    int64_t request_id
);

Parameters:

  • self: Singleton from TapOnlineBattle()
  • request_id: Developer-defined request ID, echoed in callback

Return value:

  • TapSDK_Result; if not TapSDK_Result_OK, request was not started and callback will not be invoked

Note: After connect success is delivered, you can call create room, match room, etc.

TapOnlineBattle_AsyncDisconnect​

Start an async request to disconnect. Result via TapOnlineBattleEventID_DisconnectResponse.

TapSDK_Result TapOnlineBattle_AsyncDisconnect(
    ITapOnlineBattle* self,
    int64_t request_id
);

Parameters: self, request_id

Return value: Same as above

Note: After disconnect, create room / match room etc. are not allowed until connect succeeds again.

TapOnlineBattle_AsyncCreateRoom​

Start async create room. Result via TapOnlineBattleEventID_CreateRoomResponse.

TapSDK_Result TapOnlineBattle_AsyncCreateRoom(
    ITapOnlineBattle* self,
    int64_t request_id,
    const TapOnlineBattleCreateRoomRequest* request
);

Parameters: self, request_id, request (non-null)

Return value: Same as above

Usage example:

TapOnlineBattleCreateRoomRequest createRoomRequest;
// Zero-initialize struct to avoid wild pointers
// C++11+: TapOnlineBattleCreateRoomRequest createRoomRequest{};
memset(&createRoomRequest, 0, sizeof(createRoomRequest));
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 = TapOnlineBattle_AsyncCreateRoom(TapOnlineBattle(), ++gRequestID, &createRoomRequest);
if (ret != TapSDK_Result_OK) {
    return -1;
}

TapOnlineBattle_AsyncMatchRoom​

Start async match room. Result via TapOnlineBattleEventID_MatchRoomResponse.

TapSDK_Result TapOnlineBattle_AsyncMatchRoom(
    ITapOnlineBattle* self,
    int64_t request_id,
    const TapOnlineBattleMatchRoomRequest* request
);

Parameters: self, request_id, request (non-null)

Return value: Same as above

Usage example:

TapOnlineBattleMatchRoomRequest matchRoomRequest;
// Zero-initialize; C++11+: matchRoomRequest{}
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 = TapOnlineBattle_AsyncMatchRoom(TapOnlineBattle(), ++gRequestID, &matchRoomRequest);
if (ret != TapSDK_Result_OK) { return -1; }

TapOnlineBattle_AsyncGetRoomList​

Start async get room list. Result via TapOnlineBattleEventID_GetRoomListResponse.

TapSDK_Result TapOnlineBattle_AsyncGetRoomList(
    ITapOnlineBattle* self,
    int64_t request_id,
    const TapOnlineBattleGetRoomListRequest* request
);

Usage example:

TapOnlineBattleGetRoomListRequest getRoomListRequest;
memset(&getRoomListRequest, 0, sizeof(getRoomListRequest));
getRoomListRequest.room_type = "ranked";
getRoomListRequest.offset = 0;
getRoomListRequest.limit = 20;
auto ret = TapOnlineBattle_AsyncGetRoomList(TapOnlineBattle(), ++gRequestID, &getRoomListRequest);
if (ret != TapSDK_Result_OK) { return -1; }

TapOnlineBattle_AsyncJoinRoom​

Start async join room. Result via TapOnlineBattleEventID_JoinRoomResponse.

TapSDK_Result TapOnlineBattle_AsyncJoinRoom(
    ITapOnlineBattle* self,
    int64_t request_id,
    const TapOnlineBattleJoinRoomRequest* request
);

Usage example:

TapOnlineBattleJoinRoomRequest joinRoomRequest;
memset(&joinRoomRequest, 0, sizeof(joinRoomRequest));
joinRoomRequest.room_id = "room_id_from_list";
joinRoomRequest.player_cfg.custom_status = 0;
joinRoomRequest.player_cfg.custom_properties = "{}";
auto ret = TapOnlineBattle_AsyncJoinRoom(TapOnlineBattle(), ++gRequestID, &joinRoomRequest);
if (ret != TapSDK_Result_OK) { return -1; }

TapOnlineBattle_AsyncLeaveRoom​

Start async leave room. Result via TapOnlineBattleEventID_LeaveRoomResponse.

TapSDK_Result TapOnlineBattle_AsyncLeaveRoom(
    ITapOnlineBattle* self,
    int64_t request_id
);

Note: Not allowed during frame sync; error returned via event.

TapOnlineBattle_AsyncUpdatePlayerCustomStatus​

Start async update player custom status. Result via TapOnlineBattleEventID_UpdatePlayerCustomStatusResponse.

TapSDK_Result TapOnlineBattle_AsyncUpdatePlayerCustomStatus(
    ITapOnlineBattle* self,
    int64_t request_id,
    int32_t status
);

Note: Not allowed during frame sync. Shared rate limit of 15 calls/sec with UpdatePlayerCustomProperties, UpdateRoomProperties, SendCustomMessage.

Rate limit

TapOnlineBattle_AsyncUpdatePlayerCustomStatus, TapOnlineBattle_AsyncUpdatePlayerCustomProperties(), TapOnlineBattle_AsyncUpdateRoomProperties(), TapOnlineBattle_AsyncSendCustomMessage() share a limit of 15 calls per second.

TapOnlineBattle_AsyncUpdatePlayerCustomProperties​

Start async update player custom properties. Result via TapOnlineBattleEventID_UpdatePlayerCustomPropertiesResponse.

TapSDK_Result TapOnlineBattle_AsyncUpdatePlayerCustomProperties(
    ITapOnlineBattle* self,
    int64_t request_id,
    const char* properties
);

Note: Not allowed during frame sync. Shared 15/sec limit with UpdatePlayerCustomStatus, UpdateRoomProperties, SendCustomMessage.

TapOnlineBattle_AsyncUpdateRoomProperties​

Start async update room properties. Result via TapOnlineBattleEventID_UpdateRoomPropertiesResponse.

TapSDK_Result TapOnlineBattle_AsyncUpdateRoomProperties(
    ITapOnlineBattle* self,
    int64_t request_id,
    const TapOnlineBattleUpdateRoomPropertiesRequest* request
);

Usage example:

TapOnlineBattleUpdateRoomPropertiesRequest updateRoomPropsRequest;
memset(&updateRoomPropsRequest, 0, sizeof(updateRoomPropsRequest));
updateRoomPropsRequest.name = "NewRoomName";
updateRoomPropsRequest.custom_properties = "{}";
auto ret = TapOnlineBattle_AsyncUpdateRoomProperties(TapOnlineBattle(), ++gRequestID, &updateRoomPropsRequest);
if (ret != TapSDK_Result_OK) { return -1; }

Note: Not allowed during frame sync; room owner only. Shared 15/sec limit.

TapOnlineBattle_AsyncSendCustomMessage​

Start async send custom message. Result via TapOnlineBattleEventID_SendCustomMessageResponse.

TapSDK_Result TapOnlineBattle_AsyncSendCustomMessage(
    ITapOnlineBattle* self,
    int64_t request_id,
    const TapOnlineBattleSendCustomMessageRequest* request
);

Usage example:

TapOnlineBattleSendCustomMessageRequest sendMsgRequest;
memset(&sendMsgRequest, 0, sizeof(sendMsgRequest));
sendMsgRequest.msg = "hello";
sendMsgRequest.receiver_type = 0; // 0=all in room (excl. sender), 1=specific players
// When receiver_type==1: set receiver_count and receivers
// const char* targets[] = { "player_id_1" };
// sendMsgRequest.receiver_type = 1; sendMsgRequest.receiver_count = 1; sendMsgRequest.receivers = targets;
auto ret = TapOnlineBattle_AsyncSendCustomMessage(TapOnlineBattle(), ++gRequestID, &sendMsgRequest);
if (ret != TapSDK_Result_OK) { return -1; }

Note: Shared 15/sec limit with UpdatePlayerCustomStatus, UpdatePlayerCustomProperties, UpdateRoomProperties.

TapOnlineBattle_AsyncKickRoomPlayer​

Start async kick player from room. Result via TapOnlineBattleEventID_KickRoomPlayerResponse.

TapSDK_Result TapOnlineBattle_AsyncKickRoomPlayer(
    ITapOnlineBattle* self,
    int64_t request_id,
    const char* player_id
);

Note: Not allowed during frame sync; room owner only. Error returned via event.

TapOnlineBattle_AsyncStartFrameSync​

Start async start frame sync. Result via TapOnlineBattleEventID_StartFrameSyncResponse.

TapSDK_Result TapOnlineBattle_AsyncStartFrameSync(
    ITapOnlineBattle* self,
    int64_t request_id
);

TapOnlineBattle_AsyncSendFrameInput​

Start async send player input. Result via TapOnlineBattleEventID_SendFrameInputResponse.

TapSDK_Result TapOnlineBattle_AsyncSendFrameInput(
    ITapOnlineBattle* self,
    int64_t request_id,
    const TapOnlineBattleSendFrameInputRequest* request
);

Usage example:

TapOnlineBattleSendFrameInputRequest sendFrameInputRequest;
memset(&sendFrameInputRequest, 0, sizeof(sendFrameInputRequest));
sendFrameInputRequest.data = "{\"x\":1,\"y\":0}";
auto ret = TapOnlineBattle_AsyncSendFrameInput(TapOnlineBattle(), ++gRequestID, &sendFrameInputRequest);
if (ret != TapSDK_Result_OK) { return -1; }

Note: At most 5 inputs per frame; over limit returns error via event.

TapOnlineBattle_AsyncStopFrameSync​

Start async stop frame sync. Result via TapOnlineBattleEventID_StopFrameSyncResponse.

TapSDK_Result TapOnlineBattle_AsyncStopFrameSync(
    ITapOnlineBattle* self,
    int64_t request_id
);

Parameters:

  • self: Singleton from TapOnlineBattle()
  • request_id: Developer-defined request ID, echoed in callback

Return value:

  • TapSDK_Result; if not TapSDK_Result_OK, request was not started and callback will not be invoked