Setting up Limited Grants #

In this section, we’ll be defining the item catalog, associated type definitions, and the limited grants catalog.

Get started #

Run the following commands in the terminal from the platform directory:

  1. make skip-tests protos engine
  2. make ext

Define the item catalog #

The ItemCatalog defines shared identifiers and configurations for all game content managed by the platform. This is where designers create player inventory specifications.

This section will cover creating instanced and stackable item specs, which are customizable by filling in ext (extension) fields.

Define item types with protobufs #

The structure of instanced and stackable items are created in protobuf files defined by the engine. Custom protobuf definitions can be added to ext fields. These are predefined protobuf types that can be modified to extend engine functionality.

In this section, we’ll be defining the instanced item spec for laser swords, which is the template used when creating a laser sword. For the purposes of this quick guide, we’ll be editing two protobuf definitions.

Note: Pragma Engine supports defining protobufs for stackable items as well.

Edit the inventory content ext file #

This is where we’ll define the laser sword specification.

  1. Open 5-ext/ext-protos/src/main/proto/shared/inventoryContentExt.proto.
  2. Edit extInstancedSpec by inserting the following oneof:
message ExtInstancedSpec {
  oneof data {
    LaserSwordSpec laser_sword_spec = 1;
  1. Define LaserSwordSpec by inserting the following message below extInstancedSpec:
message LaserSwordSpec {
  int64 min_damage = 1;
  int64 max_damage = 2;
  repeated string awesomeness = 3;

Edit the inventory ext file #

This is where we’ll define attributes for specific laser swords.

  1. Open 5-ext/ext-protos/src/main/proto/shared/inventoryExt.proto.
  2. Edit ExtInstancedItem by inserting the following code:
message ExtInstancedItem  {
  oneof data {
    LaserSword laser_sword = 2;
  1. Define LaserSword by inserting the following message below ExtInstancedItem:
message LaserSword {
  int64 damage = 1;
  string awesomeness = 2;

Run make ext using a terminal from the platform directory.

Define item specs #

Now that we’ve finished defining the item structure, we can author the actual item specifications.

Define instanced item specs #

Add the following code to the contents of platform/5-ext/content/src/InstancedSpecs.json:

    "catalogId": "laserSword",
    "name": "laser sword",
    "tags": [],
    "ext": {
      "laserSwordSpec": {
        "minDamage": 21,
        "maxDamage": 42,
        "awesomeness": ["a little", "somewhat", "AWESOME!!!"]

In this section, we’re defining a laser sword instanced item specification. In the ext field, we’ve defined a minDamage of 21, a maxDamage of 42, and an awesomeness list. In a later step, we’ll author an instanced item plugin that will use this data to generate specific laser sword instances.

Define stackable item specs #

Add the following code to the contents of platform/5-ext/content/src/StackableSpecs.json:

    "catalogId": "coins",
    "name": "coins",
    "limit": 1000000,
    "tags": ["currency"],
    "removeIfNone": false
    "catalogId": "StarterPack",
    "name": "Starter pack granted on login",
    "limit": 1,
    "tags": []

We’ve defined two different stackable items. coins are “regular” stackable items that are used in a game. However, the StarterPack is a special stackable item that is used to track whether a player has received their grant.

The presence of the StarterPack item is how Pragma Engine distinguishes whether a player has already received their limited grant. Therefore, do not allow the player to acquire the StarterPack by any means other than receiving a limited grant.

Define limited grants #

Add the following code to the contents of platform/5-ext/content/src/LimitedGrants.json:

    "trackingCatalogId": "StarterPack",
    "instancedGrants": [
        "catalogId": "laserSword"
    "stackableGrants": [
        "catalogId": "coins",
        "amount": 50

Here, we are granting a laserSword as our instanced item grant and 50 coins as our stackable item grant. We are using the StarterPack stackable item to track whether a user has already received their limited grant.

Apply content data #

In order to register the instanced items, stackable items, and store you just defined with Pragma Engine, you must apply your content data changes.

In a terminal with platform as the working directory, run:

java -jar 5-ext/target/pragma.jar contentdata apply -d 5-ext/content

At the prompt, confirm that you wish to apply content changes.