Typical Use Case

Here, we use a shooting game to illustrate how to define items, grant items, purchase items, and consume items.

1. Configure Your Game Economy

If this is your first time using PGOS Economy, we recommend you follow the configuration process below:

• Configure virtual currency
• Configure normal items
• Configure bundles and containers
• Configure stores

1.1 Configure Virtual Currency

In PGOS Economy, you can configure one or more virtual currencies based on the needs of your game. In this example, we have defined two virtual currencies, Gold and Diamond.

• We set a larger initial deposit for Gold to allow players to quickly start using this currency.
• Diamonds are obtained by winning battles, so we set the initial deposit as 0.

1.2 Configure Normal Items

Normal items are individual items used in the game that cannot be split up, such as a single piece of armor or scroll. Some examples are provided below:

• Character Skin

  Generally, there is no point in having multiple instances of a single skin item, so the is_unique property is set as "True" for skin items.

  item_id: "item_skin_1111"
  display_name: "Christmas style skin"
  is_unique: true
  is_stackable: false
  is_consumable: false
  tags: "class:skin"
  default_custom_data: "-"

• Bulletproof Vest

  item_id: "item_armor_2222"
  display_name: "Bulletproof vest"
  is_unique: false
  is_stackable: false
  is_consumable: false
  tags: "class:armor"
  default_custom_data: "armor_value:15"

• Submachine Gun

  item_id: "item_weapon_3333"
  display_name: "Submachine gun"
  is_unique: false
  is_stackable: false
  is_consumable: false
  tags: "class:weapon"
  default_custom_data: "attack_value:10"

• Experience Bonus Scroll

  item_id: "item_scroll_4444"
  display_name: "Experience bonus scroll"
  is_unique: false
  is_stackable: true
  is_consumable: true
  tags: "class::scroll"
  default_custom_data: "bonus_rate:1.5"

1.2.1 Using Tags

In this example, we use the Tags field to classify each item. You can customize Tags content to mark items as belonging to different classifications based on the design of your game.

1.2.2 Using Default Custom Data

In this example, we use the Default Custom Data field to store gameplay-related property information for each item, such as the defense bonus provided by armors, the attack bonus provided by weapons, and the experience bonus provided by scrolls.

This has the advantage of storing all item data in the PGOS Economy system. If you need to modify item properties, you will not have to recompile, deploy, and release the game client and server.

Of course, you may need to package detailed item information in the client as local resources. In this case, you can use the item_id field as the identifier for associating items in the player inventory with items in local resources.

1.3 Configure Bundle Items

• Gear Suits

  type: "bundle item"
  item_id: "item_suit_5555"
  display_name: "Equipments"
  content:
      - item_armor_2222: 1
      - item_weapon_3333: 1

• Beginner Chest

  type: "container item"
  item_id: "item_suit_5555"
  display_name: "Equipments"
  content:
      - item_scroll_4444: 5
      - DIAMOND: 25

1.4 Configure Stores

In PGOS Economy, you can configure one or more stores to sell different items in your game.We provide some examples below:

• Gear Store

  All the items in this store can be purchased with Gold or Diamonds. The prices in Gold are higher than those in Diamonds.This is because, in the actual game design, it is easier to obtain Gold than it is to obtain Diamonds.

• display_name: "Equipments store"
  item_list:
      - item_armor_2222:
          prices:
              GOLDCOIN: 250
              DIAMONDCOID: 25
      - item_weapon_3333:
          prices:
              GOLDCOIN: 250
              DIAMONDCOID: 25
      - item_scroll_4444:
          prices:
              GOLDCOIN: 25
              DIAMONDCOID: 5

• Skin Store

  Items in this store can only be purchased with Diamonds.

  display_name: "Skin store"
      - item_skin_1111:
          prices:
              DIAMONDCOID: 250

2. Case Purchase Items

Players could purchase in-game items in stores. In order to get the product information in the store, you need to know the store_id. There are many ways for game client to get store id, the following are two typical ways:

• Pack the store ids into the game configuration file.
• Storage store ids in PGOS Title Region Config Data.

Call UPgosEconomyAPI::GetStore to get the product information in a given store.

Then call UPgosEconomyAPI::CreateStoreOrder&UPgosEconomyAPI::CommitStoreOrder to purchase the store items. Such as item_armor_2222 x 1, item_suit_5555 x 1, item_scroll_4444* x 1.

The result of the purchase action will return by the call back of UPgosEconomyAPI::CreateStoreOrder&UPgosEconomyAPI::CommitStoreOrder:

• Virtual currency spent info.
• In-game items obtained info.
• Virtual currency obtained info.

3. Case Consume Items

The following example illustrates how to use item consume mechanism. Before entering a battle, use item_scroll_4444 x1 to gain an experience boost. Specific process:

• Start Consuming: The game client calls the UPgosEconomyAPI::ConsumeItemInstance API in the PGOS SDK to initiate an item instance consumption request.
• Wait consume complete: The Economy service implements the virtual server function associated with the item and waits for the implementation to be completed.
• Handle consume result: Based on the result data returned by the virtual server function, the game client can inform the player of the result and impact of the consume behavior through UI prompts.

4. Case Character Skins

You can create items that represent the character skins in the game. Instances of this type of item can be regarded as the token of a character skin. The acquisition of skin is the same as other items, so we won’t repeat it here. You may be more concerned about how to use skin items in the battle session. There're two typical cases as below.

1. Choose skin in the battle session.

   • Game client connect to DS.
   • DS calls UPgosEconomyAPI::GetPlayerInventory to get all skins owned by a player.
   • Player choose a skin.

2. Choose skin before the battle session.

   • Game client calls UPgosEconomyAPI::GetInventory to get all skins owned by the player.
   • Player choose a skin.
   • Game client connect to DS with skin data.
   • DS calls UPgosEconomyAPI::GetPlayerInventory to check if the player has this item instance in order to determine whether to apply the skin to the player's character in the battle.

5. Case Order Refund

1. Initiate refund: If a player purchases a Superman Suit but does use it, the player can initiate a refund.

2. Reclaim item and return funds: The 500 Gold paid by the player is returned to the player's wallet. If the refund is successful, it triggers an OnBalanceChanged event in the Client SDK. At the same time, the Superman Suit is reclaimed and an OnInventoryChanged event is triggered in the Client SDK.

6. Case Grant Item to Specified Player

In some scenarios, you may have to grant in-game items or virtual currency to a player. This can be done in several different ways.

• Call the DS SDK API to grant items to a player

  Pgos::Server::UPgosEconomyAPI::GrantCurrencyToPlayer
  Pgos::Server::UPgosEconomyAPI::BatchGetItemInstance

• Call the virtual server API to grant items to a player

  GrantCurrencyToPlayer
  GrantItemsToPlayer

• Use the Portal to grant items to a player