Items #

There are two item types in the Player Data service: instanced items and stackable items. They are assigned unique instance IDs, creating addressable IDs that are used to manage simple or complex workflows.

Stackable items represent stacks of items with a count and limit, such as currencies, item counts, or stacked inventories.

Instanced items are created based on an item specification and plugin code. Custom protobuf definitions provide strongly typed data. Two items of the same type are created individually such that each holds individual attributes unique to it.

Item Specifications #

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

Content files are stored as JSON and support versioning and live data migration to enable evolving player data throughout content and patch cycles. See the Content Data overview for more details.

Stackable Item Specs #

Here is a stackable spec for an in-game currency.

  {
    "catalogId": "gold-coins", // id, cannot be changed

    "name": "Gold Coins", // display name, can be changed.

    "limit": 10000,       // the maximum amount of gold a player
                          // can have

    "tags": ["currency"], // used to group and filter content

    "removeIfNone": false // determines if a stack is deleted
                          // when the amount goes to 0. Useful
                          // for consumables. 
  }

Instanced Item Specs #

Instanced items are a general purpose container for an unlimited number of content types and systems. Exts support subtypes to allow any kind of live data content without wasted storage or overly constrained type definitions. The engine manages the lifecycle of items, while plugins are used to initialize and update the content.

The combination of instanced items and plugins is a powerful combination. See our Workflow Guides for sample implementations of crafting, in-game stores, progression systems, battle passes, and more. The engine handles data lifecycle, caching, and transactions, leaving game developers free to focus on game content and features.

 {
    "catalogId": "fire-dragon", // id, cannot be changed

    "name": "Fire Dragon",      // display name, can be changed.

    "tags": ["pet"],            // used to group and filter content

    "ext": {                    // extension field for custom data

      "petSpec": {              // example spec for a pet system

        "bonuses": [            // strongly typed data defined in 
          "XP_BONUS",           // proto. This data is used by
          "GOLD_BONUS",         // plugin code to initialize pet
          "LUCK_BONUS"          // instances
        ],
        "bonusMin": 5,
        "bonusMax": 10
      }
    }
  }

For a full example, see the Items User Guide.

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 service calls return inventory information and will respect hidden items.

Service callCalled byDescription
craftV1, storePurchaseV4, updateItemV4, and updateItemsV0Game clientsreturned segments/deltas won’t contain items with tags that match the configuration
getStoresV0Game clientsreturn stores will not contain store entries with tags that match the configuration
getInventoryV2Game clientsreturned inventory will not contain instanced and stackables whose corresponding content specs contain tags that match the configuration
GameDataService.GetLoginDataV1 which uses InventoryService.GetLoginDataGame clientsreturned player inventory and content items (stores, update entries, item catalog, crafting entries, etc) are all filtered based on the tags in the configuration
GetInventoryServiceV3Servicesinventory data split by hidden and player visible items
UpdateItemsPartnerV2, UpdateItemsServiceV2, and GrantItemsServiceV2Game servers or servicessegments/deltas split by hidden and player visible items

Quick Guides #

Viewing items in Portal #

  1. From the Game Pragma Portal, click Services, then click Content Catalogs.

Navigate to Content Catalogs

  1. View the searchable content catalogs for instanced items and stackable items.

Portal Content Catalogs

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 CommonConfig.yml or LocalConfig.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.