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​

TapOnlineGameEventID​

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

enum {
    TapOnlineGameEventID_Unknown = 0,

    // [1, 1000) reserved for async request callbacks (Response)
    TapOnlineGameEventID_ConnectResponse = 1,                  // Connect callback; on success cast event_data to TapOnlineGameConnectResponse*
    TapOnlineGameEventID_DisconnectResponse = 2,                // Disconnect callback; always success, event_data is NULL
    TapOnlineGameEventID_CreateRoomResponse = 3,               // Create room callback; on success cast event_data to TapOnlineGameCreateRoomResponse*
    TapOnlineGameEventID_MatchRoomResponse = 4,                // Match room callback; on success cast event_data to TapOnlineGameMatchRoomResponse*
    TapOnlineGameEventID_GetRoomListResponse = 5,             // Get room list callback; on success cast event_data to TapOnlineGameGetRoomListResponse*
    TapOnlineGameEventID_JoinRoomResponse = 6,                 // Join room callback; on success cast event_data to TapOnlineGameJoinRoomResponse*
    TapOnlineGameEventID_LeaveRoomResponse = 7,                // Leave room callback; event_data is NULL
    TapOnlineGameEventID_UpdatePlayerCustomStatusResponse = 8, // Update player custom status callback; event_data is NULL
    TapOnlineGameEventID_UpdatePlayerCustomPropertiesResponse = 9, // Update player custom properties callback; event_data is NULL
    TapOnlineGameEventID_UpdateRoomPropertiesResponse = 10,    // Update room properties callback; event_data is NULL
    TapOnlineGameEventID_SendCustomMessageResponse = 11,      // Send custom message callback; event_data is NULL
    TapOnlineGameEventID_KickRoomPlayerResponse = 12,          // Kick player callback; event_data is NULL
    TapOnlineGameEventID_StartFrameSyncResponse = 13,          // Start frame sync callback; event_data is NULL
    TapOnlineGameEventID_SendFrameInputResponse = 14,          // Send frame input callback; event_data is NULL
    TapOnlineGameEventID_StopFrameSyncResponse = 15,           // Stop frame sync callback; event_data is NULL

    // [1000, 2000) reserved for server-pushed notifications (Notification)
    TapOnlineGameEventID_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)
    TapOnlineGameEventID_DisconnectNotification = 1001,       // Kicked or unexpected disconnect; check error field. Reconnect on disconnect; do not reconnect when kicked
    TapOnlineGameEventID_PlayerOfflineNotification = 1002,    // Player offline; cast event_data to TapOnlineGamePlayerOfflineNotification*
    TapOnlineGameEventID_EnterRoomNotification = 1003,        // Player entered room; cast event_data to TapOnlineGamePlayerEnterRoomNotification*
    TapOnlineGameEventID_LeaveRoomNotification = 1004,       // Player left room; cast event_data to TapOnlineGamePlayerLeaveRoomNotification*
    TapOnlineGameEventID_PlayerCustomStatusNotification = 1005,   // Player custom status changed; cast event_data to TapOnlineGamePlayerCustomStatusNotification*
    TapOnlineGameEventID_PlayerCustomPropertiesNotification = 1006, // Player custom properties changed; cast event_data to TapOnlineGamePlayerCustomPropertiesNotification*
    TapOnlineGameEventID_RoomPropertiesNotification = 1007,    // Room properties updated; cast event_data to TapOnlineGameRoomPropertiesNotification*
    TapOnlineGameEventID_CustomMessageNotification = 1008,    // Custom message received; cast event_data to TapOnlineGameCustomMessageNotification*
    TapOnlineGameEventID_RoomPlayerKickedNotification = 1009,   // Player kicked from room; cast event_data to TapOnlineGameRoomPlayerKickedNotification*
    TapOnlineGameEventID_FrameSyncStartNotification = 1010,    // Frame sync started; cast event_data to TapOnlineGameFrameSyncStartNotification*
    TapOnlineGameEventID_FrameNotification = 1011,             // Latest match frame; cast event_data to TapOnlineGameFrame*
    TapOnlineGameEventID_FrameSyncStopNotification = 1012,    // Frame sync stopped; cast event_data to TapOnlineGameFrameSyncStopNotification*
};
// Online multiplayer event type; see TapOnlineGameEventID_* for values
typedef uint32_t TapOnlineGameEventID;

Structure Types​

Alignment

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

TapOnlineGameEvent​

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
    TapOnlineGameEventID 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
} TapOnlineGameEvent;

TapOnlineGameConnectResponse​

Returned when TapOnlineGame_AsyncConnect() succeeds:

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

TapOnlineGameMatchParam​

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
} TapOnlineGameMatchParam;

TapOnlineGameRoomConfig​

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 TapOnlineGameMatchParam* 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
} TapOnlineGameRoomConfig;

TapOnlineGamePlayerConfig​

Player configuration:

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

TapOnlineGameCreateRoomRequest​

Create room request for TapOnlineGame_AsyncCreateRoom():

typedef struct {
    TapOnlineGameRoomConfig room_cfg;    // Room config
    TapOnlineGamePlayerConfig player_cfg; // Player config
} TapOnlineGameCreateRoomRequest;

TapOnlineGamePlayerInfo​

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
} TapOnlineGamePlayerInfo;

TapOnlineGameRoomInfo​

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 TapOnlineGamePlayerInfo* players; // Player list, length player_count
    int64_t create_time; // Room creation time, seconds since 1970
} TapOnlineGameRoomInfo;

TapOnlineGameCreateRoomResponse​

Returned when TapOnlineGame_AsyncCreateRoom() succeeds:

typedef struct {
    const TapOnlineGameRoomInfo* room_info; // Created room info
} TapOnlineGameCreateRoomResponse;

TapOnlineGameMatchRoomRequest​

Match room request for TapOnlineGame_AsyncMatchRoom():

typedef struct {
    TapOnlineGameRoomConfig room_cfg;    // Room config, used to create room when no match
    TapOnlineGamePlayerConfig player_cfg; // Player config
} TapOnlineGameMatchRoomRequest;

TapOnlineGameMatchRoomResponse​

Returned when TapOnlineGame_AsyncMatchRoom() succeeds:

typedef struct {
    const TapOnlineGameRoomInfo* room_info; // Matched or created room info
} TapOnlineGameMatchRoomResponse;

TapOnlineGameGetRoomListRequest​

Get room list request for TapOnlineGame_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
} TapOnlineGameGetRoomListRequest;

TapOnlineGameRoomBasicInfo​

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
} TapOnlineGameRoomBasicInfo;

TapOnlineGameGetRoomListResponse​

Returned when TapOnlineGame_AsyncGetRoomList() succeeds:

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

TapOnlineGameJoinRoomRequest​

Join room request for TapOnlineGame_AsyncJoinRoom():

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

TapOnlineGameJoinRoomResponse​

Returned when TapOnlineGame_AsyncJoinRoom() succeeds:

typedef struct {
    const TapOnlineGameRoomInfo* room_info; // Joined room info
} TapOnlineGameJoinRoomResponse;

TapOnlineGameUpdateRoomPropertiesRequest​

Update room properties request for TapOnlineGame_AsyncUpdateRoomProperties():

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

TapOnlineGameSendCustomMessageRequest​

Send custom message request for TapOnlineGame_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
} TapOnlineGameSendCustomMessageRequest;

TapOnlineGameSendFrameInputRequest​

Send frame input for TapOnlineGame_AsyncSendFrameInput():

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

TapOnlineGamePlayerOfflineNotification​

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
} TapOnlineGamePlayerOfflineNotification;

TapOnlineGamePlayerEnterRoomNotification​

Player entered room notification:

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

TapOnlineGamePlayerLeaveRoomNotification​

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
} TapOnlineGamePlayerLeaveRoomNotification;

TapOnlineGamePlayerCustomStatusNotification​

Player custom status change notification:

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

TapOnlineGamePlayerCustomPropertiesNotification​

Player custom properties change notification:

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

TapOnlineGameRoomPropertiesNotification​

Room properties change notification:

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

TapOnlineGameCustomMessageNotification​

Custom message notification:

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

TapOnlineGameRoomPlayerKickedNotification​

Player kicked from room notification:

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

TapOnlineGameFrameSyncStartNotification​

Frame sync start notification:

typedef struct {
    const TapOnlineGameRoomInfo* 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
} TapOnlineGameFrameSyncStartNotification;

TapOnlineGameFrameInput​

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
} TapOnlineGameFrameInput;

TapOnlineGameFrame​

Frame sync data structure:

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

TapOnlineGameFrameSyncStopNotification​

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
} TapOnlineGameFrameSyncStopNotification;

ITapOnlineGame​

Online multiplayer interface object, obtained via TapOnlineGame():

typedef struct ITapOnlineGame ITapOnlineGame;

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

TapOnlineGameCallback​

Callback type for online multiplayer:

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

TapOnlineGame_RunCallbacks​

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

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

Parameters:

  • self: Online multiplayer singleton from TapOnlineGame()
  • 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 onlineGameEventHandler(const TapOnlineGameEvent* event);

int main() {
    // Assume SDK initialized successfully

    bool running = true;
    while (running) {
        uint32_t leftEvents;
        auto handledEvents = TapOnlineGame_RunCallbacks(TapOnlineGame(), onlineGameEventHandler, 10, &leftEvents);

        // Your game logic
        // ...

        Sleep(33);
    }

    TapSDK_Shutdown();
    return 0;
}

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

API Reference​

TapOnlineGame​

Get the online multiplayer singleton.

ITapOnlineGame* TapOnlineGame();

Return value:

  • Online multiplayer singleton

Usage example:

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

TapOnlineGame_AsyncConnect​

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

TapSDK_Result TapOnlineGame_AsyncConnect(
    ITapOnlineGame* self,
    int64_t request_id
);

Parameters:

  • self: Singleton from TapOnlineGame()
  • 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.

TapOnlineGame_AsyncDisconnect​

Start an async request to disconnect. Result via TapOnlineGameEventID_DisconnectResponse.

TapSDK_Result TapOnlineGame_AsyncDisconnect(
    ITapOnlineGame* 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.

TapOnlineGame_AsyncCreateRoom​

Start async create room. Result via TapOnlineGameEventID_CreateRoomResponse.

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

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

Return value: Same as above

Usage example:

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

TapOnlineGame_AsyncMatchRoom​

Start async match room. Result via TapOnlineGameEventID_MatchRoomResponse.

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

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

Return value: Same as above

Usage example:

TapOnlineGameMatchRoomRequest 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 = TapOnlineGame_AsyncMatchRoom(TapOnlineGame(), ++gRequestID, &matchRoomRequest);
if (ret != TapSDK_Result_OK) { return -1; }

TapOnlineGame_AsyncGetRoomList​

Start async get room list. Result via TapOnlineGameEventID_GetRoomListResponse.

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

Usage example:

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

TapOnlineGame_AsyncJoinRoom​

Start async join room. Result via TapOnlineGameEventID_JoinRoomResponse.

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

Usage example:

TapOnlineGameJoinRoomRequest 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 = TapOnlineGame_AsyncJoinRoom(TapOnlineGame(), ++gRequestID, &joinRoomRequest);
if (ret != TapSDK_Result_OK) { return -1; }

TapOnlineGame_AsyncLeaveRoom​

Start async leave room. Result via TapOnlineGameEventID_LeaveRoomResponse.

TapSDK_Result TapOnlineGame_AsyncLeaveRoom(
    ITapOnlineGame* self,
    int64_t request_id
);

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

TapOnlineGame_AsyncUpdatePlayerCustomStatus​

Start async update player custom status. Result via TapOnlineGameEventID_UpdatePlayerCustomStatusResponse.

TapSDK_Result TapOnlineGame_AsyncUpdatePlayerCustomStatus(
    ITapOnlineGame* 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

TapOnlineGame_AsyncUpdatePlayerCustomStatus, TapOnlineGame_AsyncUpdatePlayerCustomProperties(), TapOnlineGame_AsyncUpdateRoomProperties(), TapOnlineGame_AsyncSendCustomMessage() share a limit of 15 calls per second.

TapOnlineGame_AsyncUpdatePlayerCustomProperties​

Start async update player custom properties. Result via TapOnlineGameEventID_UpdatePlayerCustomPropertiesResponse.

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

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

TapOnlineGame_AsyncUpdateRoomProperties​

Start async update room properties. Result via TapOnlineGameEventID_UpdateRoomPropertiesResponse.

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

Usage example:

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

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

TapOnlineGame_AsyncSendCustomMessage​

Start async send custom message. Result via TapOnlineGameEventID_SendCustomMessageResponse.

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

Usage example:

TapOnlineGameSendCustomMessageRequest 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 = TapOnlineGame_AsyncSendCustomMessage(TapOnlineGame(), ++gRequestID, &sendMsgRequest);
if (ret != TapSDK_Result_OK) { return -1; }

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

TapOnlineGame_AsyncKickRoomPlayer​

Start async kick player from room. Result via TapOnlineGameEventID_KickRoomPlayerResponse.

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

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

TapOnlineGame_AsyncStartFrameSync​

Start async start frame sync. Result via TapOnlineGameEventID_StartFrameSyncResponse.

TapSDK_Result TapOnlineGame_AsyncStartFrameSync(
    ITapOnlineGame* self,
    int64_t request_id
);

TapOnlineGame_AsyncSendFrameInput​

Start async send player input. Result via TapOnlineGameEventID_SendFrameInputResponse.

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

Usage example:

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

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

TapOnlineGame_AsyncStopFrameSync​

Start async stop frame sync. Result via TapOnlineGameEventID_StopFrameSyncResponse.

TapSDK_Result TapOnlineGame_AsyncStopFrameSync(
    ITapOnlineGame* self,
    int64_t request_id
);

Parameters:

  • self: Singleton from TapOnlineGame()
  • 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