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.

/// <summary>
/// Grant specified items to the player's inventory.
/// The PGOS backend events `event_item_granted`/`event_currency_changed` will be triggered.
/// </summary>
/// <param name="pgos_params">Request params.</param>
public void GrantItemToPlayer(GrantItemToPlayerParams pgos_params, EconomyDelegate0 callback);

Parameters:

Param	Type	Description
pgos_params	GrantItemToPlayerParams	Request params.
callback	EconomyDelegate0

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.

/// <summary>
/// Batch revoke the specified item instances in the player's inventory.
/// The PGOS virtual server event `event_item_revoked` will be triggered.
/// </summary>
/// <param name="pgos_params">Request params.</param>
public void BatchRevokeInstances(BatchRevokeInstancesParams pgos_params, EconomyDelegate1 callback);

Parameters:

Param	Type	Description
pgos_params	BatchRevokeInstancesParams	Request params.
callback	EconomyDelegate1

Return: void

GrantCurrencyToPlayer

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

/// <summary>
/// Grant currency to player's balance.
/// The PGOS backend event `event_currency_changed` will be triggered.
/// </summary>
/// <param name="pgos_params">Request params.</param>
public void GrantCurrencyToPlayer(GrantCurrencyToPlayerParams pgos_params, EconomyDelegate2 callback);

Parameters:

Param	Type	Description
pgos_params	GrantCurrencyToPlayerParams	Request params.
callback	EconomyDelegate2

Return: void

BatchGrantVirtualCurrenciesToPlayer

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

/// <summary>
/// Batch grant virtual currencies to player's balance.
/// NOTE: Premium currency can not be granted by this API.
/// </summary>
/// <param name="pgos_params">Result params.</param>
public void BatchGrantVirtualCurrenciesToPlayer(BatchGrantVirtualCurrenciesToPlayerParams pgos_params, EconomyDelegate3 callback);

Parameters:

Param	Type	Description
pgos_params	BatchGrantVirtualCurrenciesToPlayerParams	Result params.
callback	EconomyDelegate3

Return: void

SubtractPlayerCurrency

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

/// <summary>
/// Subtract currency form player's balance.
/// The PGOS backend event `event_currency_changed` will be triggered.
/// </summary>
/// <param name="pgos_params">Request params.</param>
public void SubtractPlayerCurrency(SubtractPlayerCurrencyParams pgos_params, EconomyDelegate4 callback);

Parameters:

Param	Type	Description
pgos_params	SubtractPlayerCurrencyParams	Request params.
callback	EconomyDelegate4

Return: void

BatchSubtractPlayerVirtualCurrencies

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

/// <summary>
/// Batch subtract virtual currencies from player's balance.
/// NOTE: Premium currency can not be subtracted by this API.
/// </summary>
/// <param name="pgos_params">Result params.</param>
public void BatchSubtractPlayerVirtualCurrencies(BatchSubtractPlayerVirtualCurrenciesParams pgos_params, EconomyDelegate5 callback);

Parameters:

Param	Type	Description
pgos_params	BatchSubtractPlayerVirtualCurrenciesParams	Result params.
callback	EconomyDelegate5

Return: void

GetPlayerBalance

Get player's balance.

/// <summary>Get player's balance.</summary>
/// <param name="pgos_params">Request params.</param>
public void GetPlayerBalance(GetPlayerBalanceParams pgos_params, EconomyDelegate6 callback);

Parameters:

Param	Type	Description
pgos_params	GetPlayerBalanceParams	Request params.
callback	EconomyDelegate6

Return: void

GetPlayerInventory

Query item instances in the specified player's inventory.

/// <summary>Query item instances in the specified player's inventory.</summary>
/// <param name="player_id">The specified player id.</param>
/// <param name="instance_ids">
/// Item instance ids to query.
/// If the 'instance_ids' is empty, it will return all instances in the player's inventory.
/// </param>
public void GetPlayerInventory(string player_id, List<string> instance_ids, EconomyDelegate7 callback);

Parameters:

Param	Type	Description
player_id	string	The specified player id.
instance_ids	List<string>	Item instance ids to query. If the 'instance_ids' is empty, it will return all instances in the player's inventory.
callback	EconomyDelegate7

Return: void

GetPlayerInventoryWithFilter

Get all item instances in the player's inventory.

/// <summary>Get all item instances in the player's inventory.</summary>
/// <param name="pgos_params">Request params.</param>
public void GetPlayerInventoryWithFilter(GetPlayerInventoryWithFilterParams pgos_params, EconomyDelegate8 callback);

Parameters:

Param	Type	Description
pgos_params	GetPlayerInventoryWithFilterParams	Request params.
callback	EconomyDelegate8

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).

/// <summary>
/// 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).
/// </summary>
/// <param name="pgos_params">Request params.</param>
public void SetInstanceCustomData(SetInstanceCustomDataParams pgos_params, EconomyDelegate9 callback);

Parameters:

Param	Type	Description
pgos_params	SetInstanceCustomDataParams	Request params.
callback	EconomyDelegate9

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).

/// <summary>
/// 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).
/// </summary>
/// <param name="pgos_params">Request params.</param>
public void BatchSetInstanceCustomData(BatchSetInstanceCustomDataParams pgos_params, EconomyDelegate10 callback);

Parameters:

Param	Type	Description
pgos_params	BatchSetInstanceCustomDataParams	Request params.
callback	EconomyDelegate10

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).

/// <summary>
/// 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).
/// </summary>
/// <param name="pgos_params">Request params.</param>
public void SetInstanceCustomDataWithVersion(SetInstanceCustomDataWithVersionParams pgos_params, EconomyDelegate9 callback);

Parameters:

Param	Type	Description
pgos_params	SetInstanceCustomDataWithVersionParams	Request params.
callback	EconomyDelegate9

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]

/// <summary>Perform atomic increment operation on `mutable_custom_data` kvdata for the instance. [Only keys with the prefixes "int_" and "flt_" are supported]</summary>
/// <param name="pgos_params">Request params.</param>
public void IncrInstanceCustomData(IncrInstanceCustomDataParams pgos_params, EconomyDelegate11 callback);

Parameters:

Param	Type	Description
pgos_params	IncrInstanceCustomDataParams	Request params.
callback	EconomyDelegate11

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).

/// <summary>
/// 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).
/// </summary>
/// <param name="pgos_params">Request params.</param>
public void SetInstanceTags(SetInstanceTagsParams pgos_params, EconomyDelegate12 callback);

Parameters:

Param	Type	Description
pgos_params	SetInstanceTagsParams	Request params.
callback	EconomyDelegate12

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).

/// <summary>
/// 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).
/// </summary>
/// <param name="pgos_params">Request params.</param>
public void BatchSetInstanceTags(BatchSetInstanceTagsParams pgos_params, EconomyDelegate13 callback);

Parameters:

Param	Type	Description
pgos_params	BatchSetInstanceTagsParams	Request params.
callback	EconomyDelegate13

Return: void

All Delegates

public delegate void EconomyDelegate0(PgosResult a0, GrantItemResult a1);
public delegate void EconomyDelegate1(PgosResult a0, BatchRevokeInstancesResult a1);
public delegate void EconomyDelegate2(PgosResult a0, GrantCurrencyResult a1);
public delegate void EconomyDelegate3(PgosResult a0, BatchGrantVirtualCurrenciesToPlayerResult a1);
public delegate void EconomyDelegate4(PgosResult a0, SubtractPlayerCurrencyResult a1);
public delegate void EconomyDelegate5(PgosResult a0, BatchSubtractPlayerVirtualCurrenciesResult a1);
public delegate void EconomyDelegate6(PgosResult a0, GetPlayerBalanceResult a1);
public delegate void EconomyDelegate7(PgosResult a0, GetPlayerInventoryResult a1);
public delegate void EconomyDelegate8(PgosResult a0, GetPlayerInventoryWithFilterResult a1);
public delegate void EconomyDelegate9(PgosResult a0, SetInstanceCustomDataResult a1);
public delegate void EconomyDelegate10(PgosResult a0, BatchSetInstanceCustomDataResult a1);
public delegate void EconomyDelegate11(PgosResult a0, IncrInstanceCustomDataResult a1);
public delegate void EconomyDelegate12(PgosResult a0, SetInstanceTagsResult a1);
public delegate void EconomyDelegate13(PgosResult a0, BatchSetInstanceTagsResult a1);

Type Reference:

• PgosResult
• GrantItemResult
• BatchRevokeInstancesResult
• GrantCurrencyResult
• BatchGrantVirtualCurrenciesToPlayerResult
• SubtractPlayerCurrencyResult
• BatchSubtractPlayerVirtualCurrenciesResult
• GetPlayerBalanceResult
• GetPlayerInventoryResult
• GetPlayerInventoryWithFilterResult
• SetInstanceCustomDataResult
• BatchSetInstanceCustomDataResult
• IncrInstanceCustomDataResult
• SetInstanceTagsResult
• BatchSetInstanceTagsResult