In-game Items

1. What Are In-game Items?

With in-game items, games can build collections of items in the in-game economy, which can be used in multiple scenarios.

In the portal, you can create and maintain item definitions. All types of items can be sold in stores or granted to players under gameplay mechanisms through dedicated server and virtual server APIs. Some types of items can be instantiated in the player inventory, giving the player possession of them.

We provide the following types of in-game items:

• Normal item: Normal items are individual in-game items. When a normal item is obtained by a player, a normal item instance is created in the player inventory. A normal item can be a helmet or armor.
• Bundle: Bundles are collections of in-game items or virtual currencies. They can contain multiple items of various types or bunch of virtual currencies. When a player obtains a bundle, PGOS will automatically grant the contents of the bundle to the player. The bundle itself is not instantiated in the player inventory. For example, you can define a bundle that contains one helmet and one suit of armor.
• Container: Containers are collections of in-game items or virtual currencies. They can contain multiple items of various types or bunch of virtual currencies. When a player obtains a container, a container instance is created in the player inventory. The player can open a container, in which case PGOS automatically grants the contents of the container to the player. Once opened, the container is removed from the inventory. For example, you can define a container that contains one helmet and one suit of armor.

The figure below shows the structures of the three types of in-game items and the process by which players obtain them:

2. Property Reference

This section introduces the properties of in-game items, which are used to create and manage in-game items.

• Item ID: The item identifier must be unique within the title region. Once submitted, it cannot be changed.
• Display Name: The display name of the item.
• Icon: Used to record the resource address of the item icon shown to players.
• Description: The description of the item.
• Tags: You can use this field to store information used to classify items in the format of custom K-V pairs.
• Default Prices: Default price information. You can use multiple virtual currencies to set the item price. When the item is sold in store, this field is used as the store price, unless you set a different price for the item in the store.
• Valid Duration: This field specifies the period a normal item remains in the player inventory after it is instantiated. A value of 0, the default value, indicates that the item never expires unless the user voluntarily uses or deletes it. When the set time expires, the status of the item instance becomes expired. See Item Instances for more information about item statuses.
• Default Custom Data: You can use this field to add custom property information for the item, such as the armor bonus provided by a helmet. You can access this field in the item instance. In later versions, we will provide an SDK API to update custom data.
• Is Unique: False/True, cannot be changed once submitted. This field indicates whether a normal item instance is unique in the player inventory. If True, it means that the player inventory can only contain one valid instance of this item. The user will not be able to obtain additional duplicates of this item. We recommend that you enable this property for items that players can only hold one of, such as character skins.
• Is Stackable: False/True, cannot be changed once submitted. This field indicates whether the instance of a normal item can be stacked in the player inventory. Stackable items that share an instance ID. Only item instances that have completely identical properties can be stacked. For example, identical items with non-zero Valid Duration that are granted separately cannot be stacked since their remaining validity will not be the same. See Item Instances for more information about item statuses.
• Stack Limit: The limitation of stack count for stackable item instance. 0 means no limit.
• Is Consumable: False/True. This field indicates whether a normal item instance can be consumed. You can call the ConsumeInstance API in the Client SDK to consume the instance of this consumable item. In addition, PGOS allows you to bind a virtual function to a consumable item to set the effect when it is consumed. This virtual function will be implemented synchronously when the item instance is consumed. See Consumable for more information.
• Content: A list of in-game items, virtual currencies, and their quantities. There are no direct restrictions on the types of items that can be included in the content as long as your configuration is self-consistent. However, we do not allow more than five nested layers for collection-type items.

Not every in-game item requires all the properties above. See the table below for specific requirements:

	Normal item	Bundle	Container
Item ID	Y	Y	Y
Display Name	Y	Y	Y
Icon	Y	Y	Y
Description	Y	Y	Y
Tags	Y	Y	Y
Default Prices	Y	Y	Y
Valid Duration	Y
Default Custom Data	Y	Y	Y
Is Unique	Y
Is Stackable	Y
Is Consumable	Y
Content		Y	Y
Support instantiation	Y		Y

3. Define Your In-game Items

PGOS does not provide default definitions for in-game items, so you must configure custom in-game items based on your needs. Go to Portal -> Economy -> In-game Items and click Add Item/Bundle/Container to create an item of the selected type.

3.1 Item Definition Constraints

You can design complex item schemes through nesting and joining multiple types of items. We do not impose many restrictions. However, you must make sure your item definitions are self-consistent. Therefore, we impose a number of constraints during item creation to avoid unintelligible or contradictory item definitions:

• Constraint 1. Is Unique & Is Stackable cannot both be True as they are contradictory properties.
• Constraint 2. Multiple unique items with same Item ID cannot be directly or indirectly contained in a bundle, container, or other collection-type items. In such a case, the player could not acquire the item because a player cannot have multiple unique items with the same ID.
• Constraint 3. Bundles, containers cannot have more than five levels of nested items.
• Constraint 4. Bundles, containers cannot directly or indirectly contain themselves.

3.2 Create a Normal Item

Go to Portal -> Economy -> In-game Items -> Normal Item and click Add Item. Below are example properties for a normal item:

Type: Normal
ID: fish_jdbl81fr
Display Name: Fish
Icon: null
Default Prices: null
Valid Duration: 20 second
Description: A small fish, eat it to restore some life
Is Unique: False
Is Stackable: True
Is Consumable: True
Tags: { "category": "food" }
Default Custom Data: { "hp_restore_value": 5 }

3.3 Create a Bundle Item

Go to the Economy -> In-game Items page, select the Bundle tab, and click Add Bundle. Below are example properties for a bundle:

Type: Bundle
ID: gift_jdbl81fr
Display Name: Rookie gift
Icon: null
Default Prices: null
Content: [
    < fish_jdbl81fr, 10 >,
    < GAMEGOLD, 200 >
]
Description: A gift for rookies that contains a few fish and some gold coins.
Tags: null
Default Custom Data: null

3.4 Create a Container Item

Go to Portal -> Economy -> In-game Items -> Container and click Add Container. Below are example properties for a container:

Type: Bundle
ID: box_jdbl81fr
Display Name: Box
Icon: null
Default Prices: null
Content: [
    < gift_jdbl81fr, 2 >
]
Description: A box you can open at any time.
Tags: null
Default Custom Data: null

3.5 Delete

You can delete in-game items that you have created as needed. When you try to delete an item, we will check its use in the economy system. Items cannot be deleted in the following situations:

• The item is already purchasable in stores.
• The item serves as the content in a bundle/container.

The deletion operation is irreversible, so proceed with caution.

4. Consumable

Consumable items can be consumed from game client, such as a scroll that provides an experience bonus or a fish that increases health points. You can use virtual server to customize the effect of items consumption.

4.1 Consumption Process

• The game client calls the UPgosEconomyAPI::ConsumeInstance API to initiate a consumption request for an item instance.
• Economy service consume the item instance in player inventory. The consumed item instances are not visible to the player, but can be inspected in the Player Inventory section of the Portal.
• Then PGOS call the /pgos_economy URL of the bound virtual server.
  • The data schema required for the virtual server request can be found in doc.
  • PGOS will return the complete response data from the Consumption handler in the callback of the UPgosEconomyAPI::ConsumeInstance interface, without any constraints on its data format.

sequenceDiagram participant gc as Game Client participant es as Economy Service participant is as Inventory Service participant vs as Virtual Server gc->>es:ConsumeInstance activate es rect rgb(191, 222, 253) es->>is:Consume the item instance activate is is-->>es:Item instance consumed deactivate is es->>vs:Call bound virtual server activate vs vs-->>es:Virtual server response deactivate vs end es-->>gc:OnConsumeInstance deactivate es

4.2 Consumption Handler

4.2.1 Associate a Virtual Server

Go to Portal -> Economy -> In-game Items -> Normal Items, select the desired item, and modify the Is Consumable property.

• No/Yes: Set to Yes to allow further configuration.

• Virtual Server: Select a virtual to implement the item consumption effect.

4.2.2 Virtual Server Example

You can follow the to create a virtual server. Here is a simple node js snippet which just print the content of ItemConsumptionReq. Practically you can add any game specified logic in the virtual server to achieve different effect. To create the virtual server, please refer to this doc.

// pgos_economy handles the specific requests from PGOS economy service, please config the binding for the economy service on the portal in advance
router.post("/pgos_economy", async (ctx) => {
  var invoker = ctx.request.headers["invoker"];
  if (invoker != "economy") {
    ctx.status = 401;
    return;
  }
  // write your own code to handle
  console.log("/pgos_economy: " + ctx.request.rawBody);
  ctx.body = "";
});

4.3 Inspect Consumption on Portal

You can inspect the consumption of items in the player's inventory.

• Once an item is consumed, the status of the item instance will be changed to "Consumed".

  

• Additionally, a transaction record with an Operation Type of Consume will be generated in the inventory log.

  

If an HTTP call to the /pgos_economy URL of the bound virtual server returns an error, the consume action will be marked as a failure. However, regardless of the outcome, the status of the item instance will be marked as "Consumed" and it cannot be consumed again.