Server Economy API Reference

PGOS provides a series of services to help you build a in-game economy, including virtual currencies, in-game items, stores, and inventory.

API List

API	Description
GrantItemToPlayer	Grant specified items to the player's inventory. The PGOS backend events event_item_granted/event_currency_changed will be triggered.
BatchRevokeInstances	Batch revoke the specified item instances in the player's inventory. The PGOS virtual server event event_item_revoked will be triggered.
GrantCurrencyToPlayer	Grant currency to player's balance. The PGOS backend event event_currency_changed will be triggered.
BatchGrantVirtualCurrenciesToPlayer	Batch grant virtual currencies to player's balance. NOTE: Premium currency can not be granted by this API.
SubtractPlayerCurrency	Subtract currency form player's balance. The PGOS backend event event_currency_changed will be triggered.
BatchSubtractPlayerVirtualCurrencies	Batch subtract virtual currencies from player's balance. NOTE: Premium currency can not be subtracted by this API.
GetPlayerBalance	Get player's balance.
GetPlayerInventory	Query item instances in the specified player's inventory.
GetPlayerInventoryWithFilter	Get all item instances in the player's inventory.
SetInstanceCustomData	Update the mutable_custom_data of the specified item instance in the player's inventory. The key must be prefixed with "int", "flt", or "str_", which respectively indicate that the value type is integer, float, or string. Instance mutable_custom_data can have up to 32 keys, with each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).
BatchSetInstanceCustomData	Batch update the mutable_custom_data of the specified item instance in the player's inventory. The key must be prefixed with "int", "flt", or "str_", which respectively indicate that the value type is integer, float, or string. Instance mutable_custom_data can have up to 32 keys, with each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).
SetInstanceCustomDataWithVersion	Update the mutable_custom_data of the specified item instance in the player's inventory. The key must be prefixed with "int", "flt", or "str_", which respectively indicate that the value type is integer, float, or string. The 'version' that needs to be passed in can be obtained from the mutable_custom_data of the ItemInstance. If the 'version' passed in is the latest, the callback will return success along with the latest data after updated. If the 'version' passed in is not the latest, the callback will return failure(err_code=11108, kBackendKVDataVersionMismatched (11108)) along with the current latest data, you may try again with the latest version. Instance mutable_custom_data can have up to 32 keys, with each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).
IncrInstanceCustomData	Perform atomic increment operation on mutable_custom_data kvdata for the instance. [Only keys with the prefixes "int" and "flt" are supported]
SetInstanceTags	Update the tags data of the specified item instance in the player's inventory. Instance tags can have up to 32 keys, with each key limited to 128 bytes and each value limited to 1024 bytes(in a narrow-character string).
BatchSetInstanceTags	Batch update the tags data of the specified item instance in the player's inventory. Instance tags can have up to 32 keys, with each key limited to 128 bytes and each value limited to 1024 bytes(in a narrow-character string).

API Details

GrantItemToPlayer

Grant specified items to the player's inventory. The PGOS backend events event_item_granted/event_currency_changed will be triggered.

/**
 * Grant specified items to the player's inventory.
 * 
 * The PGOS backend events `event_item_granted`/`event_currency_changed` will be triggered.
 * 
 * @param params Request params.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GrantItemToPlayer(
    const GrantItemToPlayerParams& params,
    PgosDataCallback<GrantItemResult> result_callback);

Parameters:

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

Return: void

BatchRevokeInstances

Batch revoke the specified item instances in the player's inventory. The PGOS virtual server event event_item_revoked will be triggered.

/**
 * Batch revoke the specified item instances in the player's inventory.
 * 
 * The PGOS virtual server event `event_item_revoked` will be triggered.
 * 
 * @param params Request params.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void BatchRevokeInstances(
    const BatchRevokeInstancesParams& params,
    PgosDataCallback<BatchRevokeInstancesResult> result_callback);

Parameters:

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

Return: void

GrantCurrencyToPlayer

Grant currency to player's balance. The PGOS backend event event_currency_changed will be triggered.

/**
 * Grant currency to player's balance.
 * 
 * The PGOS backend event `event_currency_changed` will be triggered.
 * 
 * @param params Request params.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GrantCurrencyToPlayer(
    const GrantCurrencyToPlayerParams& params,
    PgosDataCallback<GrantCurrencyResult> result_callback);

Parameters:

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

Return: void

BatchGrantVirtualCurrenciesToPlayer

Batch grant virtual currencies to player's balance. NOTE: Premium currency can not be granted by this API.

/**
 * Batch grant virtual currencies to player's balance.
 * NOTE: Premium currency can not be granted by this API.
 * 
 * @param params Result params.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void BatchGrantVirtualCurrenciesToPlayer(
    const BatchGrantVirtualCurrenciesToPlayerParams& params,
    PgosDataCallback<BatchGrantVirtualCurrenciesToPlayerResult> result_callback);

Parameters:

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

Return: void

SubtractPlayerCurrency

Subtract currency form player's balance. The PGOS backend event event_currency_changed will be triggered.

/**
 * Subtract currency form player's balance.
 * The PGOS backend event `event_currency_changed` will be triggered.
 * 
 * @param params Request params.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void SubtractPlayerCurrency(
    const SubtractPlayerCurrencyParams& params,
    PgosDataCallback<SubtractPlayerCurrencyResult> result_callback);

Parameters:

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

Return: void

BatchSubtractPlayerVirtualCurrencies

Batch subtract virtual currencies from player's balance. NOTE: Premium currency can not be subtracted by this API.

/**
 * Batch subtract virtual currencies from player's balance.
 * NOTE: Premium currency can not be subtracted by this API.
 * 
 * @param params Result params.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void BatchSubtractPlayerVirtualCurrencies(
    const BatchSubtractPlayerVirtualCurrenciesParams& params,
    PgosDataCallback<BatchSubtractPlayerVirtualCurrenciesResult> result_callback);

Parameters:

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

Return: void

GetPlayerBalance

Get player's balance.

/**
 * Get player's balance.
 * 
 * @param params Request params.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GetPlayerBalance(
    const GetPlayerBalanceParams& params,
    PgosDataCallback<GetPlayerBalanceResult> result_callback);

Parameters:

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

Return: void

GetPlayerInventory

Query item instances in the specified player's inventory.

/**
 * Query item instances in the specified player's inventory.
 * 
 * @param player_id The specified player id.
 * @param instance_ids Item instance ids to query.  If the 'instance_ids' is empty, it will return all instances in the player's inventory.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GetPlayerInventory(
    const pgos::pstring& player_id,
    const pgos::pvector<pgos::pstring>& instance_ids,
    PgosDataCallback<GetPlayerInventoryResult> result_callback);

Parameters:

Param	Type	Description
player_id	const std::string&	The specified player id.
instance_ids	const std::vector<std::string>&	Item instance ids to query. If the 'instance_ids' is empty, it will return all instances in the player's inventory.
result_callback	PgosDataCallback<GetPlayerInventoryResult>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

GetPlayerInventoryWithFilter

Get all item instances in the player's inventory.

/**
 * Get all item instances in the player's inventory.
 * 
 * @param params Request params.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GetPlayerInventoryWithFilter(
    const GetPlayerInventoryWithFilterParams& params,
    PgosDataCallback<GetPlayerInventoryWithFilterResult> result_callback);

Parameters:

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

Return: void

SetInstanceCustomData

Update the mutable_custom_data of the specified item instance in the player's inventory. The key must be prefixed with "int", "flt", or "str_", which respectively indicate that the value type is integer, float, or string. Instance mutable_custom_data can have up to 32 keys, with each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).

/**
 * Update the `mutable_custom_data` of the specified item instance in the player's inventory.
 * The key must be prefixed with "int_", "flt_", or "str_", which respectively indicate that the value type is integer, float, or string.
 * Instance `mutable_custom_data` can have up to 32 keys, with each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).
 * 
 * @param params Request params.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void SetInstanceCustomData(
    const SetInstanceCustomDataParams& params,
    PgosDataCallback<SetInstanceCustomDataResult> result_callback);

Parameters:

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

Return: void

BatchSetInstanceCustomData

Batch update the mutable_custom_data of the specified item instance in the player's inventory. The key must be prefixed with "int", "flt", or "str_", which respectively indicate that the value type is integer, float, or string. Instance mutable_custom_data can have up to 32 keys, with each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).

/**
 * Batch update the `mutable_custom_data` of the specified item instance in the player's inventory.
 * The key must be prefixed with "int_", "flt_", or "str_", which respectively indicate that the value type is integer, float, or string.
 * Instance `mutable_custom_data` can have up to 32 keys, with each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).
 * 
 * @param params Request params.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void BatchSetInstanceCustomData(
    const BatchSetInstanceCustomDataParams& params,
    PgosDataCallback<BatchSetInstanceCustomDataResult> result_callback);

Parameters:

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

Return: void

SetInstanceCustomDataWithVersion

Update the mutable_custom_data of the specified item instance in the player's inventory. The key must be prefixed with "int", "flt", or "str_", which respectively indicate that the value type is integer, float, or string. The 'version' that needs to be passed in can be obtained from the mutable_custom_data of the ItemInstance. If the 'version' passed in is the latest, the callback will return success along with the latest data after updated. If the 'version' passed in is not the latest, the callback will return failure(err_code=11108, kBackendKVDataVersionMismatched (11108)) along with the current latest data, you may try again with the latest version. Instance mutable_custom_data can have up to 32 keys, with each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).

/**
 * Update the `mutable_custom_data` of the specified item instance in the player's inventory.
 * The key must be prefixed with "int_", "flt_", or "str_", which respectively indicate that the value type is integer, float, or string.
 * The 'version' that needs to be passed in can be obtained from the `mutable_custom_data` of the `ItemInstance`.
 * If the 'version' passed in is the latest, the callback will return success along with the latest data after updated.
 * If the 'version' passed in is not the latest, the callback will return failure(err_code=11108, kBackendKVDataVersionMismatched (11108)) along with the current latest data, you may try again with the latest version.
 * Instance `mutable_custom_data` can have up to 32 keys, with each key limited to 128 bytes and each value limited to 4096 bytes(in a narrow-character string).
 * 
 * @param params Request params.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void SetInstanceCustomDataWithVersion(
    const SetInstanceCustomDataWithVersionParams& params,
    PgosDataCallback<SetInstanceCustomDataResult> result_callback);

Parameters:

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

Return: void

IncrInstanceCustomData

Perform atomic increment operation on mutable_custom_data kvdata for the instance. [Only keys with the prefixes "int" and "flt" are supported]

/**
 * Perform atomic increment operation on `mutable_custom_data` kvdata for the instance. [Only keys with the prefixes "int_" and "flt_" are supported]
 * 
 * @param params Request params.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void IncrInstanceCustomData(
    const IncrInstanceCustomDataParams& params,
    PgosDataCallback<IncrInstanceCustomDataResult> result_callback);

Parameters:

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

Return: void

SetInstanceTags

Update the tags data of the specified item instance in the player's inventory. Instance tags can have up to 32 keys, with each key limited to 128 bytes and each value limited to 1024 bytes(in a narrow-character string).

/**
 * Update the `tags` data of the specified item instance in the player's inventory.
 * Instance `tags` can have up to 32 keys, with each key limited to 128 bytes and each value limited to 1024 bytes(in a narrow-character string).
 * 
 * @param params Request params.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void SetInstanceTags(
    const SetInstanceTagsParams& params,
    PgosDataCallback<SetInstanceTagsResult> result_callback);

Parameters:

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

Return: void

BatchSetInstanceTags

Batch update the tags data of the specified item instance in the player's inventory. Instance tags can have up to 32 keys, with each key limited to 128 bytes and each value limited to 1024 bytes(in a narrow-character string).

/**
 * Batch update the `tags` data of the specified item instance in the player's inventory.
 * Instance `tags` can have up to 32 keys, with each key limited to 128 bytes and each value limited to 1024 bytes(in a narrow-character string).
 * 
 * @param params Request params.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void BatchSetInstanceTags(
    const BatchSetInstanceTagsParams& params,
    PgosDataCallback<BatchSetInstanceTagsResult> result_callback);

Parameters:

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

Return: void