A new Player Data service has been released that is more up to date and supported with this current release of Pragma Engine. We recommend you check it out by viewing the Player Data Overview page.

Items #

Inventory data consists of two main data types: instanced items and stackable items. All items are assigned UUIDs and belong to the player they’re created for. Items are saved off in our Inventory service, and are managed by engine and inventory plugins.

Stackable items represent stacks of items with a count and limit such as currencies or health potions. Stackable items of the same type only vary in their amount and do not behave differently from one another (i.e. one stack of gold coins acts the same as another stack of gold coins).

Instanced items are items that can hold individual attributes that differ between items of the same type (i.e. upgraded versions of the same sword). They’re created based on an instanced spec defined by strongly typed protobufs and plugin code that informs how the item needs to be constructed/managed. Because instanced items can be used to define and hold arbitrary data, they can be used to power complex systems like battlepasses and missions.

Item bundles can be any combination of stackable and instanced items. For example, a single item bundle can contain gold coins, a sword, and armor.

Specifications #

To manage custom game data, the Content Data system allows designers to define item specifications that are used by the engine and plugin code to initialize and update inventory data.

Content files are stored in JSON and support versioning and live data migration. This enables the evolution of inventory data throughout content and patch cycles.

If you do not already have the content source files initialized, run make init-inventory-content from the platform directory. This generates inventory content files used to define the specs for your instanced and stackable items.

Specifications vs items #

While specifications and items are closely connected, they’re distinct from one another. An item is something tangible saved in the Inventory service which belongs to a player. A specification is JSON-defined content that provides a definition or blueprint for its related item.

For example, if a car sales site allows a customer to pick the color, fabric, and traffic features, this array of options are similar to a specification. Meanwhile a red car with leather seats that has blind spot detection is the item itself.

Filtering by tags #

When using getInventory, all inventory data is returned by default. The Inventory service supports optional filtering of inventory data by tags on GetInventoryServiceV3, GetInventoryPartnerV2, and GetInventoryOperatorV1.

Tags are defined on the item’s corresponding instanced or stackable spec. If the item’s spec contains any tags from the request and the player has the item in their inventory, the item will be returned.

Hidden inventory items #

In addition to traditional in-game items, player information can also be stored as stackable or instanced items. Some information, such as matchmaking rating (stored as an instanced item), is sensitive and should not be shown to players. Pragma Engine supports hiding items from being sent down to the player.

The following Inventory service endpoints return inventory information and will respect hidden items.

Quick Guides #

Storing matchmaking rating as a hidden item #

Here is an item we’ve defined to hold matchmaking information in InstancedSpecs.json:

[
  {
    "catalogId": "playerRating",
    "name": "MMR",
    "tags": ["mmr"]
  }
]

To keep things simple, we’re omitting the ext field here. In an actual game, the ext field would contain all matchmaking information and be fully customized according to the game’s design.

Note that we’ve tagged this item with the mmr tag. We can hide items by specifying a list of tags to hide from the player. All items containing a tag on this list will not be sent by the platform to the game client. We specify this list in a configuration file such as common.yml or local-dev.yml:

game:
  serviceConfigs:
    InventoryServiceConfig:
      contentAccessByTags:
        "hidden":
          "1": "mmr"
          "2": "hiddenTag"
          "3": "futureContent"

In this example, we’ve specified mmr, hiddenTag, and futureContent as tags that should be hidden. Any item containing at least one of those tags will not be sent to the game client.

Contents #