Client 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
GetBalances	Get all balances of the player.
GetStore	Get the specified store defined on the portal.
GetStoreWithPlatform	Get the specified store defined on the portal. This interface can get the value of 'platform_item_mapping'.
GetStoreBriefs	Get brief information of specified stores.
GetStoreCategories	Get the specified store categories defined on the portal.
CreateStoreOrder	Create an order before purchase the specified store item in the store. After committing the order, the PGOS virtual server events event_item_granted/event_currency_changed will be triggered.
CommitStoreOrder	After committing the order, the payment will be deducted and the items will be dispatched. The PGOS virtual server events event_item_granted/event_currency_changed will be triggered. The event_custom_data filled in the parameter CreateStoreOrderParams will be passed to these events.
QueryStoreOrder	Query order status.
GetInventory	Get all item instances in the player's inventory.
GetInventoryWithFilter	Get all item instances in the player's inventory.
ConsumeInstance	Consume the specified item instance in the player's inventory. The virtual server function bound to the consumer action will be called.
OpenContainerInstance	Open the specified container instance in the player's inventory. The PGOS virtual server events event_item_revoked and event_item_granted/event_currency_changed will be triggered.
RevokeInstance	Revoke the specified item instance in the player's inventory. The PGOS virtual server event event_item_revoked will be triggered.
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).
CheckBeforePlatformPurchase	Check before purchasing items on 3rd-party platforms. Used to check situations where items cannot be purchased due to unique items, mapping configuration, etc.
SyncPlayerPlatformInventory	Synchronize the 3rd-party platform's inventory to PGOS. It is recommended to call it once after logging in to PGOS. The PGOS virtual server events event_item_granted/event_currency_changed will be triggered.
SyncSteamPlayerInventory	Synchronize the Steam platform's inventory to PGOS. It is recommended to call it once after logging in to PGOS. The PGOS virtual server events event_item_granted/event_currency_changed will be triggered.
SyncSteamPurchase	Synchronize item instances purchased by players from Steam to PGOS. The PGOS virtual server events event_item_granted/event_currency_changed will be triggered.
SyncXboxPlayerInventory	Synchronize the Xbox platform's inventory to PGOS. It is recommended to call it once after logging in to PGOS. The PGOS virtual server events event_item_granted/event_currency_changed will be triggered.
SyncXboxPurchase	Synchronize item instances purchased by players from Xbox to PGOS. The PGOS virtual server events event_item_granted/event_currency_changed will be triggered.

Event List

Event	Description
SetOnInventoryGranted	The event will be triggered when new item instances are granted to player's inventory.
SetOnBalanceUpdated	The event will be triggered when any currency amount changed.

API Details

GetBalances

Get all balances of the player.

/**
 * Get all balances of the player.
 * 
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GetBalances(
    PgosDataCallback<GetBalancesResult> result_callback);

Parameters:

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

Return: void

GetStore

Get the specified store defined on the portal.

/**
 * Get the specified store defined on the portal.
 * 
 * @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 GetStore(
    const GetStoreParams& params,
    PgosDataCallback<Store> result_callback);

Parameters:

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

Return: void

GetStoreWithPlatform

Get the specified store defined on the portal. This interface can get the value of 'platform_item_mapping'.

Deprecated, use GetStore instead.

/**
 * Get the specified store defined on the portal. This interface can get the value of 'platform_item_mapping'.
 * [DEPRECATED!!!] GetStoreWithPlatform was declared deprecated, consider using GetStore instead.
 * 
 * @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 GetStoreWithPlatform(
    const GetStoreWithPlatformParams& params,
    PgosDataCallback<Store> result_callback);

Parameters:

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

Return: void

GetStoreBriefs

Get brief information of specified stores.

/**
 * Get brief information of specified stores.
 * 
 * @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 GetStoreBriefs(
    const GetStoreBriefsParams& params,
    PgosDataCallback<GetStoreBriefsResult> result_callback);

Parameters:

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

Return: void

GetStoreCategories

Get the specified store categories defined on the portal.

/**
 * Get the specified store categories defined on the portal.
 * 
 * @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 GetStoreCategories(
    const GetStoreCategoriesParams& params,
    PgosDataCallback<GetStoreCategoriesResult> result_callback);

Parameters:

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

Return: void

CreateStoreOrder

Create an order before purchase the specified store item in the store. After committing the order, the PGOS virtual server events event_item_granted/event_currency_changed will be triggered.

/**
 * Create an order before purchase the specified store item in the store.
 * 
 * After committing the order, the PGOS virtual server 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 CreateStoreOrder(
    const CreateStoreOrderParams& params,
    PgosDataCallback<CreateStoreOrderResult> result_callback);

Parameters:

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

Return: void

CommitStoreOrder

After committing the order, the payment will be deducted and the items will be dispatched. The PGOS virtual server events event_item_granted/event_currency_changed will be triggered. The event_custom_data filled in the parameter CreateStoreOrderParams will be passed to these events.

/**
 * After committing the order, the payment will be deducted and the items will be dispatched.
 * 
 * The PGOS virtual server events `event_item_granted`/`event_currency_changed` will be triggered.
 * The `event_custom_data` filled in the parameter `CreateStoreOrderParams` will be passed to these events.
 * 
 * @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 CommitStoreOrder(
    const CommitStoreOrderParams& params,
    PgosDataCallback<CommitStoreOrderResult> result_callback);

Parameters:

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

Return: void

QueryStoreOrder

Query order status.

/**
 * Query order status.
 * 
 * @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 QueryStoreOrder(
    const QueryStoreOrderParams& params,
    PgosDataCallback<QueryStoreOrderResult> result_callback);

Parameters:

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

Return: void

GetInventory

Get all item instances in the player's inventory.

/**
 * Get all item 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 GetInventory(
    PgosDataCallback<ItemInstPack> result_callback);

Parameters:

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

Return: void

GetInventoryWithFilter

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 GetInventoryWithFilter(
    const GetInventoryWithFilterParams& params,
    PgosDataCallback<ItemInstPack> result_callback);

Parameters:

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

Return: void

ConsumeInstance

Consume the specified item instance in the player's inventory. The virtual server function bound to the consumer action will be called.

/**
 * Consume the specified item instance in the player's inventory.
 * 
 * The virtual server function bound to the consumer action will be called.
 * 
 * @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 ConsumeInstance(
    const ConsumeInstanceParams& params,
    PgosDataCallback<ConsumeInstanceResult> result_callback);

Parameters:

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

Return: void

OpenContainerInstance

Open the specified container instance in the player's inventory. The PGOS virtual server events event_item_revoked and event_item_granted/event_currency_changed will be triggered.

/**
 * Open the specified container instance in the player's inventory.
 * 
 * The PGOS virtual server events `event_item_revoked` and `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 OpenContainerInstance(
    const OpenContainerInstanceParams& params,
    PgosDataCallback<OpenContainerResult> result_callback);

Parameters:

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

Return: void

RevokeInstance

Revoke the specified item instance in the player's inventory. The PGOS virtual server event event_item_revoked will be triggered.

/**
 * Revoke the specified item instance 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 RevokeInstance(
    const RevokeInstanceParams& params,
    PgosDataCallback<InstanceOperationResult> result_callback);

Parameters:

Param	Type	Description
params	const RevokeInstanceParams&	Request params.
result_callback	PgosDataCallback<InstanceOperationResult>	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

CheckBeforePlatformPurchase

Check before purchasing items on 3rd-party platforms. Used to check situations where items cannot be purchased due to unique items, mapping configuration, etc.

/**
 * Check before purchasing items on 3rd-party platforms. Used to check situations where items cannot be purchased due to unique items, mapping configuration, etc.
 * 
 * @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 CheckBeforePlatformPurchase(
    const CheckBeforePlatformPurchaseParams& params,
    PgosCallback result_callback);

Parameters:

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

Return: void

SyncPlayerPlatformInventory

Synchronize the 3rd-party platform's inventory to PGOS. It is recommended to call it once after logging in to PGOS. The PGOS virtual server events event_item_granted/event_currency_changed will be triggered.

Deprecated, use SyncSteamPlayerInventory/SyncXboxPlayerInventory instead.

/**
 * Synchronize the 3rd-party platform's inventory to PGOS.
 * It is recommended to call it once after logging in to PGOS.
 * 
 * The PGOS virtual server events `event_item_granted`/`event_currency_changed` will be triggered.
 * [DEPRECATED!!!] SyncPlayerPlatformInventory was declared deprecated, consider using SyncSteamPlayerInventory/SyncXboxPlayerInventory instead.
 * 
 * @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 SyncPlayerPlatformInventory(
    const SyncPlayerPlatformInventoryParams& params,
    PgosDataCallback<SyncPlayerPlatformInventoryResult> result_callback);

Parameters:

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

Return: void

SyncSteamPlayerInventory

Synchronize the Steam platform's inventory to PGOS. It is recommended to call it once after logging in to PGOS. The PGOS virtual server events event_item_granted/event_currency_changed will be triggered.

/**
 * Synchronize the Steam platform's inventory to PGOS.
 * It is recommended to call it once after logging in to PGOS.
 * 
 * The PGOS virtual server 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 SyncSteamPlayerInventory(
    const SyncSteamPlayerInventoryParams& params,
    PgosDataCallback<SyncSteamPurchaseResult> result_callback);

Parameters:

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

Return: void

SyncSteamPurchase

Synchronize item instances purchased by players from Steam to PGOS. The PGOS virtual server events event_item_granted/event_currency_changed will be triggered.

/**
 * Synchronize item instances purchased by players from Steam to PGOS.
 * 
 * The PGOS virtual server 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 SyncSteamPurchase(
    const SyncSteamPurchaseParams& params,
    PgosDataCallback<SyncSteamPurchaseResult> result_callback);

Parameters:

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

Return: void

SyncXboxPlayerInventory

Synchronize the Xbox platform's inventory to PGOS. It is recommended to call it once after logging in to PGOS. The PGOS virtual server events event_item_granted/event_currency_changed will be triggered.

/**
 * Synchronize the Xbox platform's inventory to PGOS.
 * It is recommended to call it once after logging in to PGOS.
 * 
 * The PGOS virtual server 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 SyncXboxPlayerInventory(
    const SyncXboxPlayerInventoryParams& params,
    PgosDataCallback<SyncXboxPurchaseResult> result_callback);

Parameters:

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

Return: void

SyncXboxPurchase

Synchronize item instances purchased by players from Xbox to PGOS. The PGOS virtual server events event_item_granted/event_currency_changed will be triggered.

/**
 * Synchronize item instances purchased by players from Xbox to PGOS.
 * 
 * The PGOS virtual server 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 SyncXboxPurchase(
    const SyncXboxPurchaseParams& params,
    PgosDataCallback<SyncXboxPurchaseResult> result_callback);

Parameters:

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

Return: void

Event Details

SetOnInventoryGranted

The event will be triggered when new item instances are granted to player's inventory.

/**
 * OnSetOnInventoryGranted:
 * The event will be triggered when new item instances are granted to player's inventory.
 * 
 * @param event Event result.
 */
void SetOnInventoryGranted(
    const InventoryGrantedEvt& event);

Parameters:

Param	Type	Description
event	const InventoryGrantedEvt&	Event result.

SetOnBalanceUpdated

The event will be triggered when any currency amount changed.

/**
 * OnSetOnBalanceUpdated:
 * The event will be triggered when any currency amount changed.
 * 
 * @param event Event result.
 */
void SetOnBalanceUpdated(
    const BalanceUpdatedEvt& event);

Parameters:

Param	Type	Description
event	const BalanceUpdatedEvt&	Event result.