Server Data Models

Enums

BackfillStrategy

The player filling strategy when backfilling.

// namespace: pgos::server
enum class BackfillStrategy : uint8_t

member	value	description
Dummy	0
Custom	1	In this mode, the target player count of each team needs to be specified. However, the number of players per team must comply with the ruleset constraint.
MaxPossible	2	Backfill matchmaking will target max players as defined in ruleset and ignore expansions on player count.

BackfillStatus

Backfill matchmaking request status.

// namespace: pgos::server
enum class BackfillStatus : uint8_t

member	value	description
Dummy	0	No ongoing or ended backfill request.
Searching	1	Searching player to backfill with.
Paused	2	Means that the backfill is suspended, normally because the battle is full. If any player leaves the battle session after the backfill is paused, the backfill status will turn to searching again.
Canceled	3	The backfill request is canceled.
Completed	4	Means that the backfill reaches target and stopped, which only happens when using Custom strategy.
Error	5	Means that the backfill is terminated due to mathcmaking engine failure, submit bug to us when this happened.

CreationPolicy

The player battle session creation policy.

// namespace: pgos::server
enum class CreationPolicy : uint8_t

member	value	description
ALLOW_ALL	0
DENY_ALL	1

EctStatus

The status of ECT.

// namespace: pgos::server
enum class EctStatus : uint8_t

member	value	description
Uncompleted	0	The ECT is in an 'Uncompleted' state, indicating that it has not yet reached the 'Done', 'Canceled', or 'Expired' state. This status implies that the ECT is still in progress or has not been completed.
Done	1	The status of all the actions were updated to 'SUCCESS'; consequently, the ECT's status will become 'Done'
Canceled	2	The ECT is canceled.
Expired	3	The ECT is Expired.

EctActionStatus

The status of ECT action.

// namespace: pgos::server
enum class EctActionStatus : uint8_t

member	value	description
Init	0	The default action status when an ECT is created.
Success	1	The action is succeeded.
Failed	2	The action is failed.

PartyJoinStrategy

The strategy controls the rules who could join the party

// namespace: pgos::server
enum class PartyJoinStrategy : uint8_t

member	value	description
Public	0	Open to anyone, it's the default strategy
OnlyFriendsOfLeader	1	Only friends of the leader could join the party
OnlyFriendsOfMembers	2	Only friends of any member could join the party
OnlyInvited	3	Only invited players could join the party
NotAllowed	4	No one can join

PartyInviteStrategy

The strategy controls the rules who could invite others to the party

// namespace: pgos::server
enum class PartyInviteStrategy : uint8_t

member	value	description
AllMembersCanInvite	0	All members of the party can invite others, it's the default strategy
OnlyLeaderCanInvite	1	Only the party leader can invite others

Structs

WorldTeamInfo

Information of a team in a world battle session.

// namespace: pgos::server
struct WorldTeamInfo

field	type	description
team_name	pgos::pstring	The world team name
player_ids	pgos::pvector<pgos::pstring>	Players of the world team
team_capacity	uint32_t	Max number of players in the world team

Balance

The currency in the player's wallet.

// namespace: pgos::server
struct Balance

field	type	description
currency_code	pgos::pstring	The code of the currency.
currency_name	pgos::pstring	The name of the currency.
currency_icon	pgos::pstring	The uri of the currency.
currency_type	CurrencyType	Currency type.
amount	int64_t	The balance of the currency.
max_deposit	int64_t	The maximum balance that a player can hold for this currency. A value of 0 represents no limitation.

BatchGetPlayerInfoSvrRsp

Response that server batch getting playerInfo.

// namespace: pgos::server
struct BatchGetPlayerInfoSvrRsp

field	type	description
data	pgos::pmap<pgos::pstring, PlayerDetail>	Player infos, key: player_id, value: player detail.
fail_players	pgos::pmap<pgos::pstring, pgos::pstring>	Players who totally failed, key: player_id, value: failed reason.

BatchIncrOneOfPlayerKVDataRsp

The response that Performs atomic increment operation on a specific kvdata item for multiple players.

// namespace: pgos::server
struct BatchIncrOneOfPlayerKVDataRsp

field	type	description
data	pgos::pmap<pgos::pstring, OnePlayerKVData>	data after the increment, key: player_id, value: the player's new kvdata value after the updated.
failed_players	pgos::pmap<pgos::pstring, PgosResult>	Players who totally failed, key: player_id, value: failed reason.

KVDataGroupWithResult

A set of kvdata items.

// namespace: pgos::server
struct KVDataGroupWithResult

field	type	description
result	PgosResult	The result corresponding to the data in the structure: If the result.err_code is 0 (success), then the operation for the player is successful and the kvdata is the latest data. If the result.err_code is 11108 (kBackendKVDataVersionMismatched (11108)), then the operation for the player is failed and the kvdata is the latest data, you may try again with the latest version. For other values of the result.err_code, the kvdata is invalid, you can check the result.msg for detail.
version	uint32_t	The player-wide version of the versioned kvdata
kvdata	pgos::pmap<pgos::pstring, KVDataValue>	KVData items, key: item key, value: item value.

BatchSetPlayerVersionedKVDataRsp

Response that updates versioned kvdata for multiple players.

// namespace: pgos::server
struct BatchSetPlayerVersionedKVDataRsp

field	type	description
data	pgos::pmap<pgos::pstring, KVDataGroupWithResult>	Results and data for each player, key: player_id, value: kvdata with result.

BatchOpenIDToPlayerIDRsp

Response of transform playerIDs of PGOS to account openIDs of external platform.

// namespace: pgos::server
struct BatchOpenIDToPlayerIDRsp

field	type	description
data	pgos::pmap<pgos::pstring, pgos::pstring>	Result of successful conversion, key: account openID, value: player id.
fails	pgos::pmap<pgos::pstring, pgos::pstring>	Account openIDs who failed, key: account openID, value: failed reason.

BattleSession

A battle session corresponds a accessible battle

// namespace: pgos::server
struct BattleSession

field	type	description
battle_session_id	pgos::pstring	The battle session id to query
fleet_id	pgos::pstring	The DS fleet that battle sessions located in
battle_source_data	BattleSourceData	Creation source data of a battle session, contains information about the source type of the battle and player information filled in by the battle creator.
battle_properties	pgos::pvector<BattleProperty>	Custom K-V pairs of a battle session. Preset in matchmaking or world configuration of filled with lobby data
battle_session_data	pgos::pstring	Custom string data of a battle session. Preset in matchmaking or world configuration
port	int32_t	The port of the DS holding the battle session.
ip_address	pgos::pstring	The IP address of the DS holding the battle session.
backfill_status	BackfillStatus	Backfill request status.
bucket_path	pgos::pmap<pgos::pstring, pgos::pstring>	Mapping from bucket filter attribute name to attribute value. [for WORLD battle session only]
source_type	BattleSourceType	What service that the battle session generated from
configuration_name	pgos::pstring	Configuration name of matchmaking, lobby or world service
max_players	int32_t	Maximum number of players in the battle session If the source of the battle session is Matchmaking, the max_players is calculated from the teams section of ruleset script If the source of the game is Lobby, the max_players is calculated from the teams section of lobby config
max_teams	int32_t	Maximum number of teams in the battle session Only filled when the battle session source type is BattleSourceType::World
total_players	int32_t	Total number of players in the battle session. Only players with a player battle session status of COMPLETED will be excluded
ruleset_name	pgos::pstring	Ruleset name hit. Filled when battle session source type is BattleSourceType::Matchmaking
locked	bool	True if the battle session is locked by game server A battle session generated from world service could be locked/unlocked by calling Lock/UnlockWorldBattleSession.
zone	pgos::pstring	Zone where the battle session placed.
teams	pgos::pmap<pgos::pstring, WorldTeamInfo>	Teams info in a world battle session. Only filled when the battle session source type is BattleSourceType::World

PlayerBattleSession

A player-battle-session is a session between a player and a activated battle-session

// namespace: pgos::server
struct PlayerBattleSession

field	type	description
player_battle_session_id	pgos::pstring	The id of player session in the battle, !!! NOT BATTLE SESSION ID !!!
player_id	pgos::pstring	The player id
battle_session_id	pgos::pstring	The battle session id
status	pgos::pstring	PENDING The player battle session requires DS to call the ReservePlayerBattleSession interface for approval. RESERVED Reserved players can be validated through the AcceptPlayerBattleSession interface. ACTIVE Player battle session status turn to ACTIVE after AcceptPlayerBattleSession is called successfully. COMPLETED This is the terminal status of player battle session. The status will turn to COMPLETED after RemovePlayerBattleSession is called or player actively leave the battle session.
payload	pgos::pstring	Payload data set be game client when calling interface JoinWorldBattleSession.
created_time	int64_t	The Unix timestamp(in seconds) when the battle session was created.
team_name	pgos::pstring	Team name in a world battle session.

PlayerBattleSessionParams

// namespace: pgos::server
struct PlayerBattleSessionParams

field	type	description
battle_session_id	pgos::pstring	The battle session in which the player is participating.
player_battle_session_id	pgos::pstring	The session ID of the player within the battle session. Please note that this parameter is different from the battle session ID. PGOS assigns different player battle session IDs to players who join the same battle session multiple times.
player_id	pgos::pstring	Player ID.

DescribePlayerBattleSessionsParams

Request info to describe player battle sessions

// namespace: pgos::server
struct DescribePlayerBattleSessionsParams

field	type	description
battle_session_id	pgos::pstring	The battle session id to query
player_battle_session_id	pgos::pstring	The id of player session in the battle, !!! NOT BATTLE SESSION ID !!!
offset	uint32_t	The next token
count	uint32_t	The limit of the player battle sessions request

DescribePlayerBattleSessionsResult

Information about the players in the battle session.

// namespace: pgos::server
struct DescribePlayerBattleSessionsResult

field	type	description
next_offset	uint32_t	The next offset.
has_more	bool	If has more players.
total_num	uint32_t	None-completed players count in the battle session.
player_battle_sessions	pgos::pvector<PlayerBattleSession>	A list of player battle sessions. Empty if there's no more sessions.

GrantItem

// namespace: pgos::server
struct GrantItem

field	type	description
item_id	pgos::pstring	The id of the item will be granted.
amount	uint32_t	The number of the item will be granted.
mutable_custom_data	pgos::pmap<pgos::pstring, KVDataValue>	The mutable kv data of the instance. The key must be prefixed with "int", "flt", or "str_", which respectively indicate that the value type is integer, float, or string. Max 32 keys, each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).

BatchRevokeInstancesParams

Request struct for revoke instances.

// namespace: pgos::server
struct BatchRevokeInstancesParams : public BaseBackendEventParams

parent: BaseBackendEventParams

field	type	description
player_id	pgos::pstring	The player whose item instance will be revoked from inventory.
instance_ids	pgos::pvector<pgos::pstring>	The item instance ids. Maximum array size: 99.

BatchRevokeInstancesResult

Request struct for batch revoke instances.

// namespace: pgos::server
struct BatchRevokeInstancesResult

field	type	description
left_amounts	pgos::pmap<pgos::pstring, uint32_t>	The number of instance remaining after this operation. key: item instance id, value: left amount.
fails	pgos::pmap<pgos::pstring, PgosResult>	Item instances that failed to revoke. key: item instance id, value: failed reason.

GrantCurrency

// namespace: pgos::server
struct GrantCurrency

field	type	description
currency_code	pgos::pstring	The code of the currency will be granted.
amount	uint32_t	The amount of the currency will be granted.

GrantItemToPlayerParams

Request struct for grant item to player.

// namespace: pgos::server
struct GrantItemToPlayerParams : public BaseBackendEventParams

parent: BaseBackendEventParams

field	type	description
player_id	pgos::pstring	The player id who will be granted items to.
items	pgos::pvector<GrantItem>	The items will be granted.
idempotency_token	pgos::pstring	[Optional] Used to ensure the idempotence of the function. Idempotence means that regardless of how many times the function is called, the result remains the same. By passing a unique idempotency_token, it ensures that the function does not produce duplicate side effects or results when called repeatedly. Note: To avoid generating the same idempotency_token as other players, it is recommended to concatenate it with the player_id.
pay_platform_data	PayPlatformData	The necessary information required by the payment platform, which must be filled out when granting items contents premium currency.

GrantItemResult

// namespace: pgos::server
struct GrantItemResult

field	type	description
player_id	pgos::pstring	The player id who has been successfully granted.
item_insts	ItemInstPack	The item instances that have been granted.
currencies	pgos::pvector<Currency>	The currencies that have been granted. (such as granting bundle that contains currencies)
conflict_unique_items	pgos::pvector<ConflictUniqueItem>	Unique items that already in inventory cause failed to be granted.
failed_currencies	pgos::pmap<pgos::pstring, pgos::pstring>	Currencies that failed to grant. Mapping from currency code to failure reason.
replayed	bool	Whether the request is replayed. When it is True, it indicates that the result of the function is obtained by replaying with the same idempotency_token. This means that the result of the function has been generated in a previous call and is being reused in the current call.

GrantCurrencyToPlayerParams

Request struct for grant currency to player.

// namespace: pgos::server
struct GrantCurrencyToPlayerParams : public BaseBackendEventParams

parent: BaseBackendEventParams

field	type	description
player_id	pgos::pstring	The player id who will be granted currencies to.
currencies	GrantCurrency	The currencies will be granted.
idempotency_token	pgos::pstring	[Optional] Used to ensure the idempotence of the function. Idempotence means that regardless of how many times the function is called, the result remains the same. By passing a unique idempotency_token, it ensures that the function does not produce duplicate side effects or results when called repeatedly. Note: To avoid generating the same idempotency_token as other players, it is recommended to concatenate it with the player_id.
pay_platform_data	PayPlatformData	The necessary information required by the payment platform, which must be filled out when granting premium currency.

GrantCurrencyResult

// namespace: pgos::server
struct GrantCurrencyResult

field	type	description
player_id	pgos::pstring	The player id who have been successfully granted.
replayed	bool	Whether the request is replayed. When it is True, it indicates that the result of the function is obtained by replaying with the same idempotency_token. This means that the result of the function has been generated in a previous call and is being reused in the current call.

GetPlayerInventoryResult

// namespace: pgos::server
struct GetPlayerInventoryResult

field	type	description
player_id	pgos::pstring	The player id whose inventory will be queried.
item_insts	ItemInstPack	The item instances of the query instance ids.
fails	pgos::pmap<pgos::pstring, pgos::pstring>	The instance ids which was failed to query.

GetPlayerInventoryWithFilterResult

// namespace: pgos::server
struct GetPlayerInventoryWithFilterResult

field	type	description
player_id	pgos::pstring	The player id whose inventory will be queried.
item_insts	ItemInstPack	The item instances of the query instance ids.

SetInstanceCustomDataParams

// namespace: pgos::server
struct SetInstanceCustomDataParams

field	type	description
player_id	pgos::pstring	The player whose item instance mutable_custom_data will be updated.
instance_id	pgos::pstring	The item instance id.
update_data	pgos::pmap<pgos::pstring, KVDataValue>	Update the data of the specified keys in the mutable_custom_data. If the key does not exist, it indicates inserting new data.
delete_keys	pgos::pvector<pgos::pstring>	Delete the data of specified keys in the mutable_custom_data. The key from update_data cannot be included.

SetInstanceCustomDataResult

// namespace: pgos::server
struct SetInstanceCustomDataResult

field	type	description
mutable_custom_data	pgos::pmap<pgos::pstring, KVDataValue>	Latest mutable_custom_data of item instance.
version	uint32_t	Latest mutable_custom_data_version of item instance.

UpdatedInstanceCustomData

// namespace: pgos::server
struct UpdatedInstanceCustomData

field	type	description
update_data	pgos::pmap<pgos::pstring, KVDataValue>	Update the data of the specified keys in the mutable_custom_data. If the key does not exist, it indicates inserting new data.
delete_keys	pgos::pvector<pgos::pstring>	Delete the data of specified keys in the mutable_custom_data. The key from update_data cannot be included.

BatchSetInstanceCustomDataParams

// namespace: pgos::server
struct BatchSetInstanceCustomDataParams

field	type	description
player_id	pgos::pstring	The player whose item instance mutable_custom_data will be updated.
data	pgos::pmap<pgos::pstring, UpdatedInstanceCustomData>	The item instances to be updated. key: item instance id, value: custom data to be updated. Maximum map entries: 99.

InstanceCustomData

// namespace: pgos::server
struct InstanceCustomData

field	type	description
mutable_custom_data	pgos::pmap<pgos::pstring, KVDataValue>	Latest mutable_custom_data of item instance.
version	uint32_t	Latest mutable_custom_data_version of item instance.

BatchSetInstanceCustomDataResult

// namespace: pgos::server
struct BatchSetInstanceCustomDataResult

field	type	description
data	pgos::pmap<pgos::pstring, InstanceCustomData>	Latest mutable_custom_data of item instance. key: item instance id, value: latest custom data
fails	pgos::pmap<pgos::pstring, PgosResult>	Item instances that failed to update. key: item instance id, value: failed reason.

SetInstanceCustomDataWithVersionParams

// namespace: pgos::server
struct SetInstanceCustomDataWithVersionParams : public SetInstanceCustomDataParams

parent: SetInstanceCustomDataParams

field	type	description
version	uint32_t	The latest mutable_custom_data_version.

IncrInstanceCustomDataParams

// namespace: pgos::server
struct IncrInstanceCustomDataParams

field	type	description
player_id	pgos::pstring	The player id whose item instance mutable_custom_data will be updated.
instance_id	pgos::pstring	The item instance id.
increments	pgos::pmap<pgos::pstring, KVDataValue>	Increments to update, key: kvdata key, value: increment of the value.
idempotency_token	pgos::pstring	[Optional] Used to ensure the idempotence of the function. By passing a unique idempotency_token, it ensures that the function does not produce duplicate side effects or results when called repeatedly.

IncrInstanceCustomDataResult

// namespace: pgos::server
struct IncrInstanceCustomDataResult

field	type	description
mutable_custom_data	pgos::pmap<pgos::pstring, KVDataValue>	Latest mutable_custom_data of item instance.
version	uint32_t	Latest mutable_custom_data_version of item instance.
replayed	bool	Whether the request is replayed. When it is true, it indicates that the previously used idempotency_token was used, and the increment operation did not take effect. The result returns the latest mutable_custom_data and mutable_custom_data_version of the instance.

SetInstanceTagsParams

// namespace: pgos::server
struct SetInstanceTagsParams

field	type	description
player_id	pgos::pstring	The player id whose item instance tags will be updated.
instance_id	pgos::pstring	The item instance id.
update_data	pgos::pmap<pgos::pstring, pgos::pstring>	Update the data of the specified keys in the tags. If the key does not exist, it indicates inserting new data.
delete_keys	pgos::pvector<pgos::pstring>	Delete the data of specified keys in the tags. The key from update_data cannot be included.

SetInstanceTagsResult

// namespace: pgos::server
struct SetInstanceTagsResult

field	type	description
tags	pgos::pmap<pgos::pstring, pgos::pstring>	Latest tags of item instance.

UpdatedInstanceTags

// namespace: pgos::server
struct UpdatedInstanceTags

field	type	description
update_data	pgos::pmap<pgos::pstring, pgos::pstring>	Update the data of the specified keys in the tags. If the key does not exist, it indicates inserting new data.
delete_keys	pgos::pvector<pgos::pstring>	Delete the data of specified keys in the tags. The key from update_data cannot be included.

BatchSetInstanceTagsParams

// namespace: pgos::server
struct BatchSetInstanceTagsParams

field	type	description
player_id	pgos::pstring	The player id whose item instance tags will be updated.
data	pgos::pmap<pgos::pstring, UpdatedInstanceTags>	The item instances to be updated. key: item instance id, value: tags to be updated. Maximum map entries: 99.

InstanceTags

// namespace: pgos::server
struct InstanceTags

field	type	description
tags	pgos::pmap<pgos::pstring, pgos::pstring>	Latest tags of item instance.

BatchSetInstanceTagsResult

// namespace: pgos::server
struct BatchSetInstanceTagsResult

field	type	description
data	pgos::pmap<pgos::pstring, InstanceTags>	Latest tags of item instance.
fails	pgos::pmap<pgos::pstring, PgosResult>	Item instances that failed to update. key: item instance id, value: failed reason.

DelBattleDataRsp

Response that delete battle data.

// namespace: pgos::server
struct DelBattleDataRsp

field	type	description
fails	pgos::pmap<pgos::pstring, pgos::pstring>	Keys failed to delete, key: battle data keys, value: failed reason.

StartBackfillParams

// namespace: pgos::server
struct StartBackfillParams

field	type	description
battle_session_id	pgos::pstring	Battle session to be backfilled.
backfill_strategy	BackfillStrategy	The player filling strategy when backfilling.
custom_team_map	pgos::pmap<pgos::pstring, uint32_t>	The target player count of each team.

CancelBackfillResult

Cancel a backfill matchmaking request

// namespace: pgos::server
struct CancelBackfillResult

field	type	description
canceled	bool	Whether the player has canceled the backfill matchmaking request

BattlePlayerOfflineEvt

The event will be triggered when the player in the battle-session is offline.

// namespace: pgos::server
struct BattlePlayerOfflineEvt

field	type	description
player_id	pgos::pstring	The player id of the player who is offline.
battle_session_id	pgos::pstring	The battle-session the player is in
offline_type	PlayerSessionEvt	The reason why the player is offline.
offline_msg	pgos::pstring	The detail message for the event.

BattlePlayerBannedEvt

The event will be triggered when the player in the battle-session is banned.

// namespace: pgos::server
struct BattlePlayerBannedEvt

field	type	description
player_id	pgos::pstring	The player id of the player who is baned.
battle_session_id	pgos::pstring	The battle-session the player is in
ban_reason	pgos::pstring	Reason for ban. The reason string comes from the reason string passed in when creating the ban.
ban_created_time	int64_t	Ban creation time.
ban_duration	int64_t	Ban duration
ban_expired_time	int64_t	Ban expiration time, 0 means forever

BattleSessionUpdatedEvt

The event will be triggered when new players are added to the battle session or when the backfill status changes.

// namespace: pgos::server
struct BattleSessionUpdatedEvt

field	type	description
update_reason	pgos::pstring	This is a string data enumeration: @BACKFILL_STATUS_CHANGED: backfill status changes @BACKFILL_ADDED_PLAYERS: new players backfilled to the battle session @WORLD_ADDED_PLAYERS: New players are added to the session by World service.
battle_session_id	pgos::pstring	Battle session id.
backfill_status	BackfillStatus	Status for the backfilling process to the battle session.
total_players	int32_t	Total number of players in the battle session. Note: players with a player battle session status of COMPLETED will be excluded.
max_players	int32_t	Max number of players in the battle session.
backedfilled_players	pgos::pvector<PlayerDesc>	New players add by backfill matchmaking.
new_player_battle_sessions	pgos::pvector<PlayerBattleSession>	New players added to the battle session. For example, by the World service.
locked	bool	Locked state of the battle session.

UpdateStatItemParams

// namespace: pgos::server
struct UpdateStatItemParams

field	type	description
item	StatItem	The stat item to update.
ignore_custom_data	bool	Whether update custom data. It won't overwrite the old one when updated if this is true.
ignore_tags	bool	Whether update tags. It won't overwrite the old one when updated if this is true.

BatchUpdateStatItemParams

// namespace: pgos::server
struct BatchUpdateStatItemParams

field	type	description
items	pgos::pvector<StatItem>	The stat items to update.
ignore_custom_data	bool	Whether update custom data. It won't overwrite the old one when updated if this is true.
ignore_tags	bool	Whether update tags. It won't overwrite the old one when updated if this is true.

UpdateStatItemFailInfo

Update stat item fail info.

// namespace: pgos::server
struct UpdateStatItemFailInfo

field	type	description
stat_name	pgos::pstring	Stat to update.
key	pgos::pstring	The key of the stat item to update.
err_code	PgosErrCode	update fail error code, view pgos_error.h or PgosErrorCode.h for details.
msg	pgos::pstring	Update fail error message, view pgos_error.h or PgosErrorCode.h for details.

StatItemAfterUpdate

Update stat item success info.

// namespace: pgos::server
struct StatItemAfterUpdate

field	type	description
latest_item	StatItem	Latest stat item.
is_inserted	bool	If the stat item is newly created (which means previously the key doesn't exist).
is_modified	bool	If the stat item is updated (which depends on aggregation type and min/max value range).

BatchUpdateStatItemResult

Response for batch update stat items.

// namespace: pgos::server
struct BatchUpdateStatItemResult

field	type	description
items	pgos::pvector<StatItemAfterUpdate>	Stat items after updated.
fails	pgos::pvector<UpdateStatItemFailInfo>	Stat items that failed to update.

SetBattlePropertiesParams

// namespace: pgos::server
struct SetBattlePropertiesParams

field	type	description
battle_session_id	pgos::pstring	Battle session id.
battle_properties	pgos::pvector<BattleProperty>	The new battle properties.

LockWorldBattleSessionParams

// namespace: pgos::server
struct LockWorldBattleSessionParams

field	type	description
battle_session_id	pgos::pstring	Battle session id.

UnlockWorldBattleSessionParams

// namespace: pgos::server
struct UnlockWorldBattleSessionParams

field	type	description
battle_session_id	pgos::pstring	Battle session id.

PlayerFriendsLimit

// namespace: pgos::server
struct PlayerFriendsLimit

field	type	description
player_id	pgos::pstring	Player id.
friends_limit	uint32_t	The maximum limit of friends player can have. (max 500 friends)

BatchSetPlayerFriendsLimitParams

// namespace: pgos::server
struct BatchSetPlayerFriendsLimitParams

field	type	description
player_friends_limit	pgos::pvector<PlayerFriendsLimit>	Friends limit of player.

BatchGetPlayerFriendsLimitParams

// namespace: pgos::server
struct BatchGetPlayerFriendsLimitParams

field	type	description
player_ids	pgos::pvector<pgos::pstring>	Player ids.

BatchGetPlayerFriendsLimitResult

// namespace: pgos::server
struct BatchGetPlayerFriendsLimitResult

field	type	description
player_friends_limit	pgos::pvector<PlayerFriendsLimit>	Friends limit of player.

SetBattleTagsParams

// namespace: pgos::server
struct SetBattleTagsParams

field	type	description
battle_session_id	pgos::pstring	The id of battle session.
tags	pgos::pvector<pgos::pstring>	The tags of battle.

KVDataItemsWithReplayed

// namespace: pgos::server
struct KVDataItemsWithReplayed

field	type	description
kvdata	pgos::pmap<pgos::pstring, KVDataValue>	KVData items, key: item key, value: value of the key.
replayed	bool	Whether the request is replayed. When it is True, it indicates that the result of the function is obtained by replaying with the same idepotency_token. This means that the result of the function has been generated in a previous call and is being reused in the current call.

KVDataIncrementsIdempotent

A set of kvdata items with a idempotency token.

// namespace: pgos::server
struct KVDataIncrementsIdempotent : public PlayerKVDataGroup

parent: PlayerKVDataGroup

field	type	description
idempotency_token	pgos::pstring	[Optional] Used to ensure the idempotence of the function. An idempotent operation produces the same outcome regardless of how many times it's executed, without causing any side effects or altering the system's state. The scope of the idempotent token is for each player.

BatchIncrPlayerKVDataIdempotentParams

// namespace: pgos::server
struct BatchIncrPlayerKVDataIdempotentParams

field	type	description
data	pgos::pvector<KVDataIncrementsIdempotent>	Key: player id, value: kvdata increments of the player.

BatchIncrPlayerKVDataIdempotentResult

// namespace: pgos::server
struct BatchIncrPlayerKVDataIdempotentResult

field	type	description
data	pgos::pmap<pgos::pstring, KVDataItemsWithReplayed>	players kvdata result values map: key is player id, value is result for increment operations.
failed_players	pgos::pmap<pgos::pstring, PgosResult>	Failed players map: key is player id, value is error code and message.

MachineInfo

// namespace: pgos::server
struct MachineInfo

field	type	description
machine_id	pgos::pstring	unique id of the machine
machine_model	pgos::pstring	instance type of the machine

BuildInfo

// namespace: pgos::server
struct BuildInfo

field	type	description
build_id	pgos::pstring	unique id of the build
build_name	pgos::pstring	name of the build

DeploymentInfo

// namespace: pgos::server
struct DeploymentInfo

field	type	description
public_ip	pgos::pstring	public ip of the game server
fleet_id	pgos::pstring	unique id of the fleet
data_center	pgos::pstring	name of the data center. the possible values can be viewed in the 'DataCenterName' definition.
machine_info	MachineInfo	detail information of the machine
build_info	BuildInfo	detail information of the build
title_id	pgos::pstring
title_region_id	pgos::pstring

EctActionInfo

Structure to hold information about an ECT action.

// namespace: pgos::server
struct EctActionInfo

field	type	description
id	pgos::pstring	The ID of ECT action.
name	pgos::pstring	The name of ECT action.
idempotency_token	pgos::pstring	Token for idempotency operation.
payload	pgos::pstring	The userdata of operation set by game, such as parameters in JSON.
result	pgos::pstring	The result of operation set by game.
status	EctActionStatus	The status of ECT action.
updated_time	int64_t	The last updated time of ECT action.

EctExpirationAndRetryPolicy

// namespace: pgos::server
struct EctExpirationAndRetryPolicy

field	type	description
expiration_duration	uint32_t	The expiration duration for an ECT is the time period in seconds from its creation until it expires. The ECT will be marked as expired if the duration has elapsed and the ECT is uncompleted. Minimum: 60 seconds; maximum: 604800 seconds (7 days).
trigger_auto_retry_event	bool	Whether the retry event of ECT is triggered to VS by PGOS if the ECT is uncompleted.
max_auto_retry_count	uint32_t	Maximum number of retry attempts. This is only meaningful when the 'trigger_auto_retry_event' is set to true.
auto_retry_interval	uint32_t	The time interval in seconds between each retry attempt. The timing of the first try starts counting from the creation of the ECT. This is only meaningful when the 'trigger_auto_retry_event' is set to true. Minimum: 60 seconds; maximum: 86400 seconds (24 hours).

EctInfo

Structure to hold information about an ECT (Eventual Consistent Transaction).

// namespace: pgos::server
struct EctInfo

field	type	description
id	pgos::pstring	The ID of ECT.
name	pgos::pstring	The name of ECT.
payload	pgos::pstring	The userdata of ECT set by game.
player_ids	pgos::pvector<pgos::pstring>	All players associated with the operation in this ECT.
status	EctStatus	The status of ECT.
expiration_and_retry_policy	EctExpirationAndRetryPolicy	Whether the retry event of ECT is triggered to VS by PGOS if the ECT is not done.
created_time	int64_t	The created time of ECT.
updated_time	int64_t	The last updated time of ECT.
actions	pgos::pvector<EctActionInfo>	The actions of ECT.

EctActionCreateParams

// namespace: pgos::server
struct EctActionCreateParams

field	type	description
name	pgos::pstring	The name of ECT action.
payload	pgos::pstring	The userdata of operation set by game, such as parameters in JSON.
idempotency_token	pgos::pstring	Token for idempotency operation.

CreateEctParams

// namespace: pgos::server
struct CreateEctParams

field	type	description
id	pgos::pstring	The ID of ECT.
name	pgos::pstring	The name of ECT.
payload	pgos::pstring	The userdata of ECT set by game.
player_ids	pgos::pvector<pgos::pstring>	All players associated with the operation in this ECT.
expiration_and_retry_policy	EctExpirationAndRetryPolicy	Whether the retry event of ECT will be triggered to VS by PGOS if the ECT is uncompleted.
actions	pgos::pvector<EctActionCreateParams>	The actions of ECT.

EctActionUpdateParam

// namespace: pgos::server
struct EctActionUpdateParam

field	type	description
payload	pgos::pstring	Update action's payload.
result	pgos::pstring	Update action's result.
status	EctActionStatus	Update action's status.

UpdateEctParams

// namespace: pgos::server
struct UpdateEctParams

field	type	description
id	pgos::pstring	ECT ID.
payload	pgos::pstring	Update action's payload.
action_updates	pgos::pmap<pgos::pstring, EctActionUpdateParam>	Update the results and status of actions. key: action ID.

UpdateEctActionsParams

// namespace: pgos::server
struct UpdateEctActionsParams

field	type	description
id	pgos::pstring	ECT ID.
action_updates	pgos::pmap<pgos::pstring, EctActionUpdateParam>	Update the results and status of actions. key: action ID.

CancelEctParams

// namespace: pgos::server
struct CancelEctParams

field	type	description
id	pgos::pstring	ECT ID.
reason	pgos::pstring	Reason for cancellation.

GetEctInfoParams

// namespace: pgos::server
struct GetEctInfoParams

field	type	description
id	pgos::pstring	ECT ID.

GetPlayerUncompletedEctsParams

// namespace: pgos::server
struct GetPlayerUncompletedEctsParams

field	type	description
player_id	pgos::pstring	The ID of the specified player.
offset	uint32_t	The start position.
count	uint32_t	The limit of the ECTs request.

GetPlayerUncompletedEctsResult

// namespace: pgos::server
struct GetPlayerUncompletedEctsResult

field	type	description
ect_list	pgos::pvector<EctInfo>	List of ECTs.
has_more	bool	Has more.
next_offset	uint32_t	The next starting position of the list.
total_num	uint32_t	The total number of uncompleted ECTs that this player has.

PushMsgToGameBackendParams

// namespace: pgos::server
struct PushMsgToGameBackendParams

field	type	description
msg_bus_tag	pgos::pstring	Optional, the tag of the message bus instance to which the message is sent. If this value is not set, the messge will be sent to a random message bus instance.
msg	pgos::pvector<uint8_t>	The message data to be sent.
extra	pgos::pvector<uint8_t>	Optional, extra data to be delivered. For example: it can be used as a header for routing.

RPCRequestToGameBackendParams

// namespace: pgos::server
struct RPCRequestToGameBackendParams

field	type	description
msg_bus_tag	pgos::pstring	Optional, the tag of the message bus instance to which the message is sent. If this value is not set, the messge will be sent to a random message bus instance.
msg	pgos::pvector<uint8_t>	The message data to be sent.
extra	pgos::pvector<uint8_t>	Optional, extra data to be delivered. For example: it can be used as a header for routing.
timeout_ms	uint32_t	Timeout period, in milliseconds. If this value is set to 0, the maximum value 60000 (60 seconds) will be used.

RPCResponse

// namespace: pgos::server
struct RPCResponse

field	type	description
response	pgos::pvector<uint8_t>	The response of an RPC request.

GameBackendMsgEvt

Event info when received msg from the game backend.

// namespace: pgos::server
struct GameBackendMsgEvt

field	type	description
msg_bus_tag	pgos::pstring	The tag of the message bus instance from which the message is received.
msg	pgos::pvector<uint8_t>	Message data sent by the game via PgosMsgBusSDK.

HTTPAPIMsgEvt

Event info when received msg the PGOS backend HTTP API.

// namespace: pgos::server
struct HTTPAPIMsgEvt

field	type	description
msg	pgos::pvector<uint8_t>	Message data sent by the game via backend HTTP API.
extra	pgos::pvector<uint8_t>	Extra data sent by the game via backend HTTP API.

SubtractCurrency

// namespace: pgos::server
struct SubtractCurrency

field	type	description
currency_code	pgos::pstring	The code of the currency will be subtracted.
amount	uint32_t	The amount of the currency will be subtracted.

SubtractPlayerCurrencyParams

// namespace: pgos::server
struct SubtractPlayerCurrencyParams : public BaseBackendEventParams

parent: BaseBackendEventParams

field	type	description
player_id	pgos::pstring	Players whose balance will be subtracted.
subtract_currency	SubtractCurrency	Information about the subtracted currency.
idempotency_token	pgos::pstring	[Optional] Used to ensure the idempotence of the function. Idempotence means that regardless of how many times the function is called, the result remains the same. By passing a unique idempotency_token, it ensures that the function does not produce duplicate side effects or results when called repeatedly. Note: To avoid generating the same idempotency_token as other players, it is recommended to concatenate it with the player_id.
pay_platform_data	PayPlatformData	The necessary information required by the payment platform, which must be filled out when deducting premium currency.

SubtractPlayerCurrencyResult

// namespace: pgos::server
struct SubtractPlayerCurrencyResult

field	type	description
player_id	pgos::pstring	The player id who have been successfully granted.
replayed	bool	Whether the request is replayed. When it is True, it indicates that the result of the function is obtained by replaying with the same idempotency_token. This means that the result of the function has been generated in a previous call and is being reused in the current call.

GetPlayerBalanceParams

// namespace: pgos::server
struct GetPlayerBalanceParams

field	type	description
player_id	pgos::pstring
pay_platform_data	PayPlatformData	The necessary information required by the payment platform, which must be filled out when deducting premium currency.

GetPlayerBalanceResult

// namespace: pgos::server
struct GetPlayerBalanceResult

field	type	description
currencies	pgos::pvector<Balance>	All virtual currency balance of the player.

BatchGrantVirtualCurrenciesToPlayerParams

Request struct for batch grant currency to player.

// namespace: pgos::server
struct BatchGrantVirtualCurrenciesToPlayerParams : public BaseBackendEventParams

parent: BaseBackendEventParams

field	type	description
player_id	pgos::pstring	The player id who will be granted currencies to.
granted_currencies	pgos::pvector<GrantCurrency>	The virtual currencies will be granted.
idempotency_token	pgos::pstring	[Optional] Used to ensure the idempotence of the function. Idempotence means that regardless of how many times the function is called, the result remains the same. By passing a unique idempotency_token, it ensures that the function does not produce duplicate side effects or results when called repeatedly. Note: To avoid generating the same idempotency_token as other players, it is recommended to concatenate it with the player_id.

BatchGrantVirtualCurrenciesToPlayerResult

// namespace: pgos::server
struct BatchGrantVirtualCurrenciesToPlayerResult

field	type	description
player_id	pgos::pstring	The player id who have been successfully granted.
replayed	bool	Whether the request is replayed. When it is True, it indicates that the result of the function is obtained by replaying with the same idempotency_token. This means that the result of the function has been generated in a previous call and is being reused in the current call.

BatchSubtractPlayerVirtualCurrenciesParams

// namespace: pgos::server
struct BatchSubtractPlayerVirtualCurrenciesParams : public BaseBackendEventParams

parent: BaseBackendEventParams

field	type	description
player_id	pgos::pstring	Players whose balance will be subtracted.
subtract_currencies	pgos::pvector<SubtractCurrency>	The virtual currencies to be granted.
idempotency_token	pgos::pstring	[Optional] Used to ensure the idempotence of the function. Idempotence means that regardless of how many times the function is called, the result remains the same. By passing a unique idempotency_token, it ensures that the function does not produce duplicate side effects or results when called repeatedly. Note: To avoid generating the same idempotency_token as other players, it is recommended to concatenate it with the player_id.

BatchSubtractPlayerVirtualCurrenciesResult

// namespace: pgos::server
struct BatchSubtractPlayerVirtualCurrenciesResult

field	type	description
player_id	pgos::pstring	The player id who have been successfully granted.
replayed	bool	Whether the request is replayed. When it is True, it indicates that the result of the function is obtained by replaying with the same idempotency_token. This means that the result of the function has been generated in a previous call and is being reused in the current call.

PartyCustomData

Custom data for party.

// namespace: pgos::server
struct PartyCustomData

field	type	description
version	int	Custom data version, always incremental over the lifetime of the party.
global_custom_data	pgos::pstring	Global custom data. Only Leader has permission to modify it.
player_custom_data	pgos::pmap<pgos::pstring, pgos::pstring>	Player custom data. The map key is party member's player ID, the map value is the party member's custom data. Each party member could modify it's player custom data.

PartyInfo

Detailed information of a party

// namespace: pgos::server
struct PartyInfo

field	type	description
party_id	pgos::pstring	The party id
name	pgos::pstring	Name of the party
leader	PlayerInfo	Player who is the leader of the party A leader can: Kick out members: a leader can kick out any member at any time. Dismiss the party. Transfer leadership to another member.
members	pgos::pvector<PlayerInfo>	Players of the party
created_time	int64_t	The Unix timestamp(in seconds) when the party was created.
max_player	uint32_t	Max number of players in the party, unlimited if it is 0.
custom_data	PartyCustomData	Custom data of the party(including global and player).
join_strategy	PartyJoinStrategy	The strategy controls the rules who could join the party.
invite_strategy	PartyInviteStrategy	The strategy controls the rules who could invite others to the party.

BatchGetPlayerCurrentPartyIdsParams

// namespace: pgos::server
struct BatchGetPlayerCurrentPartyIdsParams

field	type	description
player_ids	pgos::pvector<pgos::pstring>	The player ids.

BatchGetPlayerCurrentPartyIdsResult

// namespace: pgos::server
struct BatchGetPlayerCurrentPartyIdsResult

field	type	description
player_party_ids	pgos::pmap<pgos::pstring, pgos::pstring>	The map of player -> party ids, the empty value implies the player is not in any party.

GetPartyInfoParams

// namespace: pgos::server
struct GetPartyInfoParams

field	type	description
party_id	pgos::pstring	The player id.

GetPartyInfoResult

// namespace: pgos::server
struct GetPartyInfoResult

field	type	description
party_info	PartyInfo	The party info.

GetPlayerInventoryWithFilterParams

Get inventory with filter params.

// namespace: pgos::server
struct GetPlayerInventoryWithFilterParams

field	type	description
player_id	pgos::pstring	The player id.
item_types	pgos::pvector<InGameItemType>	Item types to get
item_tags	pgos::pvector<TagDataFilter>	Item tags to get
item_instance_tags	pgos::pvector<TagDataFilter>	Item instance tags to get
unique	BooleanFilter	Filter by unique item
stackable	BooleanFilter	Filter by stackable item
consumable	BooleanFilter	Filter by consumable item

Common Define

PgosCallback

The result callback after the API execution ends.

using PgosCallback = std::function<void(const PgosResult&)>;

Type Reference:

• PgosResult

PgosDataCallback

The result callback after the API execution ends.

template <typename T> 
using PgosDataCallback = std::function<void(const PgosResult&, const T*)>;

Type Reference:

• PgosResult

PgosInterCallback

Intermediate callback that may be executed multiple times during API execution.

template <typename T>
using PgosInterCallback = std::function<void(const T*)>;