Client World API Reference

World is an entity that players can move in and out of freely and smoothly. PGOS divides players who enter the world into several world buckets based on the world filter. PGOS will allocate players from the world bucket to multiple battle sessions based on factors such as player count, player latency, and the configured capacity of battle sessions in the world.

API List

API	Description
JoinWorld	Request to join a world. Tips: In order to enhance the reliability of the service event reception, after calling this API, the SDK will automatically invoke relevant APIs to poll the event status from the backend within a certain time period. This ensures that the service continues to function even when the persistent connection is disconnected.
InviteJoinWorld	Invite other players to join a world together. Tips: In order to enhance the reliability of the service event reception, after calling this API, the SDK will automatically invoke relevant APIs to poll the event status from the backend within a certain time period. This ensures that the service continues to function even when the persistent connection is disconnected.
LeaveWorld	Request to leave a world
InviteLeaveWorld	Invite other players to leave a world together.
JoinWorldBattleSession	Request to join a world battle session directly. The API will return failure when there are not enough slots left in the battle session. The API will return failure when the battle session is locked.
InviteJoinWorldBattleSession	Invite other players to join a world battle session directly together. The API will return failure when there are not enough slots left in the battle session. The API will return failure when the battle session is locked.
AcceptJoinWorldInvitation	Accept the join world invitation when receive the 'OnJoinWorldInvitationUpdated' event. Note: Once you have made your choice, you cannot change your decision. Tips: In order to enhance the reliability of the service event reception, after calling this API, the SDK will automatically invoke relevant APIs to poll the event status from the backend within a certain time period. This ensures that the service continues to function even when the persistent connection is disconnected.
RejectJoinWorldInvitation	Reject the join world invitation when receive the 'OnJoinWorldInvitationUpdated' event. Note: Once you have made your choice, you cannot change your decision.
AcceptLeaveWorldInvitation	Accept the leave world invitation when receive the 'OnLeaveWorldInvitationUpdated' event. Note: Once you have made your choice, you cannot change your decision.
RejectLeaveWorldInvitation	Reject the join world invitation when receive the 'OnLeaveWorldInvitationUpdated' event. Note: Once you have made your choice, you cannot change your decision.
QueryMyWorldBattleSessions	Specify the world config names to query if the current player has joined them. Corresponding battle session id will be returned for the worlds in which the player has joined.
QueryPlayerWorldBattleSessions	Specify the world config names to query if a player has joined them. Corresponding battle session id will be returned for the worlds in which the player has joined.
QueryJoinWorldInvitation	Query the detail information of the join world invitation for the specified invitation ticket.

Event List

Event	Description
SetOnWorldBattleSessionUpdated	The event will be triggered when battle session status changed.
SetOnWorldBattlePropertiesUpdated	The event will be triggered when battle properties updated.
SetOnJoinWorldInvitationUpdated	The event is triggered when someone invites you to join a world or the invitation info has been updated.
SetOnLeaveWorldInvitationUpdated	The event is triggered when someone invites you to leave a world or the invitation info has been updated.

API Details

JoinWorld

Request to join a world. Tips: In order to enhance the reliability of the service event reception, after calling this API, the SDK will automatically invoke relevant APIs to poll the event status from the backend within a certain time period. This ensures that the service continues to function even when the persistent connection is disconnected.

/**
 * Request to join a world.
 * Tips: In order to enhance the reliability of the service event reception, after calling this API, 
 *       the SDK will automatically invoke relevant APIs to poll the event status from the backend within a certain time period. 
 *       This ensures that the service continues to function even when the persistent connection is disconnected.
 * 
 * @param params Request struct for join a world.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void JoinWorld(
    const JoinWorldParams& params,
    PgosDataCallback<JoinWorldResult> result_callback);

Parameters:

Param	Type	Description
params	const JoinWorldParams&	Request struct for join a world.
result_callback	PgosDataCallback<JoinWorldResult>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

InviteJoinWorld

Invite other players to join a world together. Tips: In order to enhance the reliability of the service event reception, after calling this API, the SDK will automatically invoke relevant APIs to poll the event status from the backend within a certain time period. This ensures that the service continues to function even when the persistent connection is disconnected.

/**
 * Invite other players to join a world together.
 * Tips: In order to enhance the reliability of the service event reception, after calling this API, 
 *       the SDK will automatically invoke relevant APIs to poll the event status from the backend within a certain time period. 
 *       This ensures that the service continues to function even when the persistent connection is disconnected.
 * 
 * @param params Request struct for inviting other players to join a world together.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void InviteJoinWorld(
    const InviteJoinWorldParams& params,
    PgosDataCallback<InviteJoinWorldResult> result_callback);

Parameters:

Param	Type	Description
params	const InviteJoinWorldParams&	Request struct for inviting other players to join a world together.
result_callback	PgosDataCallback<InviteJoinWorldResult>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

LeaveWorld

Request to leave a world

/**
 * Request to leave a world
 * 
 * @param params Request struct for leave a world.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void LeaveWorld(
    const LeaveWorldParams& params,
    PgosCallback result_callback);

Parameters:

Param	Type	Description
params	const LeaveWorldParams&	Request struct for leave a world.
result_callback	PgosCallback	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

InviteLeaveWorld

Invite other players to leave a world together.

/**
 * Invite other players to leave a world together.
 * 
 * @param params Request struct for inviting other players to leave a world together.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void InviteLeaveWorld(
    const InviteLeaveWorldParams& params,
    PgosDataCallback<InviteLeaveWorldResult> result_callback);

Parameters:

Param	Type	Description
params	const InviteLeaveWorldParams&	Request struct for inviting other players to leave a world together.
result_callback	PgosDataCallback<InviteLeaveWorldResult>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

JoinWorldBattleSession

Request to join a world battle session directly. The API will return failure when there are not enough slots left in the battle session. The API will return failure when the battle session is locked.

/**
 * Request to join a world battle session directly.
 * The API will return failure when there are not enough slots left in the battle session.
 * The API will return failure when the battle session is locked.
 * 
 * @param params Request struct for join a world battle session.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void JoinWorldBattleSession(
    const JoinWorldBattleSessionParams& params,
    PgosDataCallback<JoinWorldBattleSessionResult> result_callback);

Parameters:

Param	Type	Description
params	const JoinWorldBattleSessionParams&	Request struct for join a world battle session.
result_callback	PgosDataCallback<JoinWorldBattleSessionResult>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

InviteJoinWorldBattleSession

Invite other players to join a world battle session directly together. The API will return failure when there are not enough slots left in the battle session. The API will return failure when the battle session is locked.

/**
 * Invite other players to join a world battle session directly together.
 * The API will return failure when there are not enough slots left in the battle session.
 * The API will return failure when the battle session is locked.
 * 
 * @param params Request struct for inviting other players to join a world battle session.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void InviteJoinWorldBattleSession(
    const InviteJoinWorldBattleSessionParams& params,
    PgosDataCallback<InviteJoinWorldBattleSessionResult> result_callback);

Parameters:

Param	Type	Description
params	const InviteJoinWorldBattleSessionParams&	Request struct for inviting other players to join a world battle session.
result_callback	PgosDataCallback<InviteJoinWorldBattleSessionResult>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

AcceptJoinWorldInvitation

Accept the join world invitation when receive the 'OnJoinWorldInvitationUpdated' event. Note: Once you have made your choice, you cannot change your decision. Tips: In order to enhance the reliability of the service event reception, after calling this API, the SDK will automatically invoke relevant APIs to poll the event status from the backend within a certain time period. This ensures that the service continues to function even when the persistent connection is disconnected.

/**
 * Accept the join world invitation when receive the 'OnJoinWorldInvitationUpdated' event.
 * Note: Once you have made your choice, you cannot change your decision.
 * Tips: In order to enhance the reliability of the service event reception, after calling this API, 
 *       the SDK will automatically invoke relevant APIs to poll the event status from the backend within a certain time period. 
 *       This ensures that the service continues to function even when the persistent connection is disconnected.
 * 
 * @param params Request params for accept the join world invitation.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void AcceptJoinWorldInvitation(
    const AcceptJoinWorldInvitationParams& params,
    PgosCallback result_callback);

Parameters:

Param	Type	Description
params	const AcceptJoinWorldInvitationParams&	Request params for accept the join world invitation.
result_callback	PgosCallback	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

RejectJoinWorldInvitation

Reject the join world invitation when receive the 'OnJoinWorldInvitationUpdated' event. Note: Once you have made your choice, you cannot change your decision.

/**
 * Reject the join world invitation when receive the 'OnJoinWorldInvitationUpdated' event.
 * Note: Once you have made your choice, you cannot change your decision.
 * 
 * @param params Request params for reject the join world invitation.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void RejectJoinWorldInvitation(
    const RejectJoinWorldInvitationParams& params,
    PgosCallback result_callback);

Parameters:

Param	Type	Description
params	const RejectJoinWorldInvitationParams&	Request params for reject the join world invitation.
result_callback	PgosCallback	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

AcceptLeaveWorldInvitation

Accept the leave world invitation when receive the 'OnLeaveWorldInvitationUpdated' event. Note: Once you have made your choice, you cannot change your decision.

/**
 * Accept the leave world invitation when receive the 'OnLeaveWorldInvitationUpdated' event.
 * Note: Once you have made your choice, you cannot change your decision.
 * 
 * @param params Request params for accept the leave world invitation.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void AcceptLeaveWorldInvitation(
    const AcceptLeaveWorldInvitationParams& params,
    PgosCallback result_callback);

Parameters:

Param	Type	Description
params	const AcceptLeaveWorldInvitationParams&	Request params for accept the leave world invitation.
result_callback	PgosCallback	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

RejectLeaveWorldInvitation

Reject the join world invitation when receive the 'OnLeaveWorldInvitationUpdated' event. Note: Once you have made your choice, you cannot change your decision.

/**
 * Reject the join world invitation when receive the 'OnLeaveWorldInvitationUpdated' event.
 * Note: Once you have made your choice, you cannot change your decision.
 * 
 * @param params Request params for reject the leave world invitation.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void RejectLeaveWorldInvitation(
    const RejectLeaveWorldInvitationParams& params,
    PgosCallback result_callback);

Parameters:

Param	Type	Description
params	const RejectLeaveWorldInvitationParams&	Request params for reject the leave world invitation.
result_callback	PgosCallback	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

QueryMyWorldBattleSessions

Specify the world config names to query if the current player has joined them. Corresponding battle session id will be returned for the worlds in which the player has joined.

/**
 * Specify the world config names to query if the current player has joined them.
 * Corresponding battle session id will be returned for the worlds in which the player has joined.
 * 
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void QueryMyWorldBattleSessions(
    const QueryMyWorldBattleSessionsParams& params,
    PgosDataCallback<QueryMyWorldBattleSessionsResult> result_callback);

Parameters:

Param	Type	Description
params	const QueryMyWorldBattleSessionsParams&
result_callback	PgosDataCallback<QueryMyWorldBattleSessionsResult>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

QueryPlayerWorldBattleSessions

Specify the world config names to query if a player has joined them. Corresponding battle session id will be returned for the worlds in which the player has joined.

/**
 * Specify the world config names to query if a player has joined them.
 * Corresponding battle session id will be returned for the worlds in which the player has joined.
 * 
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void QueryPlayerWorldBattleSessions(
    const QueryPlayerWorldBattleSessionsParams& params,
    PgosDataCallback<QueryPlayerWorldBattleSessionsResult> result_callback);

Parameters:

Param	Type	Description
params	const QueryPlayerWorldBattleSessionsParams&
result_callback	PgosDataCallback<QueryPlayerWorldBattleSessionsResult>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

QueryJoinWorldInvitation

Query the detail information of the join world invitation for the specified invitation ticket.

/**
 * Query the detail information of the join world invitation for the specified invitation ticket.
 * 
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void QueryJoinWorldInvitation(
    const QueryJoinWorldInvitationParams& params,
    PgosDataCallback<QueryJoinWorldInvitationResult> result_callback);

Parameters:

Param	Type	Description
params	const QueryJoinWorldInvitationParams&
result_callback	PgosDataCallback<QueryJoinWorldInvitationResult>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

Event Details

SetOnWorldBattleSessionUpdated

The event will be triggered when battle session status changed.

/**
 * OnSetOnWorldBattleSessionUpdated:
 * The event will be triggered when battle session status changed.
 * 
 * @param event Event result.
 */
void SetOnWorldBattleSessionUpdated(
    const WorldBattleSessionUpdatedEvt& event);

Parameters:

Param	Type	Description
event	const WorldBattleSessionUpdatedEvt&	Event result.

SetOnWorldBattlePropertiesUpdated

The event will be triggered when battle properties updated.

/**
 * OnSetOnWorldBattlePropertiesUpdated:
 * The event will be triggered when battle properties updated.
 * 
 * @param event Event result.
 */
void SetOnWorldBattlePropertiesUpdated(
    const WorldBattlePropertiesUpdatedEvt& event);

Parameters:

Param	Type	Description
event	const WorldBattlePropertiesUpdatedEvt&	Event result.

SetOnJoinWorldInvitationUpdated

The event is triggered when someone invites you to join a world or the invitation info has been updated.

/**
 * OnSetOnJoinWorldInvitationUpdated:
 * The event is triggered when someone invites you to join a world or the invitation info has been updated.
 * 
 * @param event Event result.
 */
void SetOnJoinWorldInvitationUpdated(
    const JoinWorldInvitationUpdatedEvt& event);

Parameters:

Param	Type	Description
event	const JoinWorldInvitationUpdatedEvt&	Event result.

SetOnLeaveWorldInvitationUpdated

The event is triggered when someone invites you to leave a world or the invitation info has been updated.

/**
 * OnSetOnLeaveWorldInvitationUpdated:
 * The event is triggered when someone invites you to leave a world or the invitation info has been updated.
 * 
 * @param event Event result.
 */
void SetOnLeaveWorldInvitationUpdated(
    const LeaveWorldInvitationUpdatedEvt& event);

Parameters:

Param	Type	Description
event	const LeaveWorldInvitationUpdatedEvt&	Event result.