In-game Currencies

1. What is In-game Currencies

In-game currencies are general equivalents in the game economy. It is a medium used by players to purchase In-game items and engage in other economic activities. You can use in-game currencies to set prices for items and store items and enrich the gameplay through activities that add to or subtract from the virtual currency of players.

Multiple virtual currencies could be defined in each title region. Common virtual currencies include gold, diamond, and so on.

2. Property Reference

This section introduces the properties for in-game currencies:

• Currency Type: Two in-game currency types are supported,

  • Virtual Currency: Generally, virtual currency refers to in-game currency that players cannot directly purchase with real money.

  • Premium Currency(only Midas Global Token now): In contrast to virtual currency, premium Currency refers to in-game currency that players can directly purchase with real money. Premium Currency cannot exist independently and must rely on the paid currency provided by the payment provider, which is Midas Token when the game uses Midas payment service.

    PGOS allows games to use Premium Currency as same as Virtual Currency, but the balance of Premium Currency is managed by the payment provider (such as Midas). PGOS will shield users from this difference and keep the relevant functions, interfaces, and business processes consistent with Virtual Currency.

• Currency Code: The unique identifier of a currency within the title region, must use uppercase letters. RM and COIN are reserved fields, cannot be used.

• Currency Name: The display name of the currency.

• Currency Icon: Used to record the icon resource address of the currency.

• Initial Deposit: ONLY for virtual currency. The starting balance of this currency in players' wallets, default value: 0.

• Max Deposit: ONLY for virtual currency. The max deposit of a player, default 0 means no limit, max number is 4,294,967,295 (uint32 max value).

3. Configure In-game Currencies

3.1 Create & Edit

PGOS does not provide default virtual currency definitions. You must configure custom virtual currencies based on your needs.

Go to the Economy -> Currencies page. Click Add Currency to create a new virtual currency.

3.2 Delete

You can delete a currency that you have created based on your operation needs. When you try to delete a currency, we will check its use in the economy system. Currencies cannot be deleted in the following situations:

• The currency is used to set the prices of items in a store.
• The currency serves as the content in a bundle/container.

The deletion operation is irreversible, so proceed with caution.

4. Using In-game Currencies

4.1 Pricing Items or Store Items

Configure the Default Prices of Items

You can configure default prices for each item with both virtual or premium currencies . Go to Portal -> Economy -> In-game Items and select the desired item to go to the editing page. Click Add Price in the Default Prices list to add a default price for the selected item. In the pop-up that appears, configure the default price parameters:

• Currency: Select the currency type and code.
• Amount: The price, which is the amount of this currency required to purchase the item. 0 is a valid value.

Configure Store Prices in Virtual Currency

To learn more about configuring the prices of store items in virtual currency, click here.

4.2 Using as Bundle/Container Content

Both virtual currency and premium currency can be included as contents in bundles/containers.

• When included as contents in a bundle, the currency will be granted to the player's wallet upon acquiring the bundle.
• When included as contents in a container, the currency will be granted to the player's wallet upon opening the container.

As shown in the image below, simply select the "Currencies" tab when choosing contents.

4.3 Access Player Balance with PGOS SDK

4.3.1 Query Player Balances

Player balances can be queried in both the game client and game server. Here is an example code:

#include "PgosSDKCpp.h"

// Queyr player balance form game client
void SomeUObjectClass::SomeFunction()
{
   auto Economy = IPgosSDKCpp::Get().GetClientEconomyAPI();
   if (Economy)
   {
       Economy->GetBalances([](const FPgosResult& Ret, const FClientGetBalancesResult* Data) {
           if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
           {
               UE_LOG(LogTemp, Log, TEXT("GetBalances Success"));
           }
           else
           {
               UE_LOG(LogTemp, Log, TEXT("GetBalances Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
           }
       });
   }
}

// Queyr player balance form game server
void SomeUObjectClass::SomeFunction()
{
   auto Economy = IPgosSDKCpp::Get().GetServerEconomyAPI();
   if (Economy)
   {
       FServerGetPlayerBalanceParams Params;
       // fill Params
       Economy->GetPlayerBalance(Params, [](const FPgosResult& Ret, const FServerGetPlayerBalanceResult* Data) {
           if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
           {
               UE_LOG(LogTemp, Log, TEXT("GetPlayerBalance Success"));
           }
           else
           {
               UE_LOG(LogTemp, Log, TEXT("GetPlayerBalance Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
           }
       });
   }
}

4.3.2 Subtract/Grant Player Balance

PGOS only allows granting/deducting player balances in the game server. The following interfaces support both virtual currency (VC) and premium currency (PC) operations. Taking the Grant operation as an example:

#include "PgosSDKCpp.h"

void SomeUObjectClass::SomeFunction()
{
   auto Economy = IPgosSDKCpp::Get().GetClientEconomyAPI();
   if (Economy)
   {
       FServerGrantCurrencyToPlayerParams Params;
       // Fill params
       Economy->GrantCurrencyToPlayer(Params, [](const FPgosResult& Ret, const FServerGrantCurrencyResult* Data) {
           if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
           {
               UE_LOG(LogTemp, Log, TEXT("GrantCurrencyToPlayer Success"));
           }
           else
           {
               UE_LOG(LogTemp, Log, TEXT("GrantCurrencyToPlayer Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
           }
       });
   }
}

4.3.3 Batch Subtract/Grant Balance

PGOS provides batch interfaces for granting/deducting player balances, specifically for use in the game server. Due to data consistency reasons, the batch interfaces do not support modifying player PC balances. Please take note of this. Taking the Grant operation as an example:

#include "PgosSDKCpp.h"

void SomeUObjectClass::SomeFunction()
{
   auto Economy = IPgosSDKCpp::Get().GetClientEconomyAPI();
   if (Economy)
   {
       FBatchGrantVirtualCurrenciesToPlayerParams Params;
       // Fill params
       Economy->BatchGrantVirtualCurrenciesToPlayer(Params, [](const FPgosResult& Ret, const FBatchGrantVirtualCurrenciesToPlayerResult* Data) {
           if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
           {
               UE_LOG(LogTemp, Log, TEXT("BatchGrantVirtualCurrenciesToPlayer Success"));
           }
           else
           {
               UE_LOG(LogTemp, Log, TEXT("BatchGrantVirtualCurrenciesToPlayer Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
           }
       });
   }
}