Setting Up the Item Catalog and Store #

In this section, we’ll be defining the item catalog The various catalogs are where game content such as items, crafting recipes, grants/rewards, or stores is defined. , store, and associated type definitions.

Get started #

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

make skip-tests protos engine 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;
  }
}

3. 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;
  }
}

3. Define LaserSword by inserting the following message below ExtInstancedItem:

message LaserSword {
  int64 damage = 1;
  string awesomeness = 2;
}

Build #

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. First step is to initalize the Inventory service content source files.

Run make init-inventory-content using a terminal from the platform directory.

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 5-ext/content/src/StackableSpecs.json:

[
  {
    "catalogId": "coins",
    "name": "coins",
    "limit": 1000000,
    "tags": ["currency"],
    "removeIfNone": false
  },
  {
    "catalogId": "diamonds",
    "name": "diamonds",
    "limit": 10000,
    "tags": ["material"]
  },
  {
    "catalogId": 3,
    "name": "health potions",
    "limit": 100,
    "tags": ["potion"]
  }
]

Stackable items are items with no special properties. Each item in the stack is identical.

Define the store #

In order for items defined in the ItemCatalog to be purchasable by players they must be referenced in the Store.

In this example, we’ll define two vendors:

• The first vendor is giving away 1000 coins and 100 diamonds.
• The second vendor is selling laser swords (catalogId laserSword) for 100 coins and 10 diamonds.

Define the store in the following file 5-ext/content/src/Stores.json:

[
  {
    "id": "freeVendor",
    "name": "Free Vendor",
    "storeEntries": [
      {
        "id": "starterBundle",
        "receivedQuantityByCatalogId": {
          "coins": 1000,
          "diamonds": 100
        }
      }
    ]
  },
  {
    "id": "shopkeeper",
    "name": "Shopkeeper",
    "storeEntries": [
      {
        "id": "laserSword",
        "receivedQuantityByCatalogId": {
          "laserSword": 1
        },
        "costByCatalogId": {
          "coins": {
            "cost": 100
          },
          "diamonds": {
            "cost": 10
          }
        }
      }
    ]
  }
]

Apply content data #

In order to register the content you just defined with Pragma Engine, you must apply your content data changes. You may apply content data either using the command line with make or via an IntelliJ run configuration.

make ext-contentdata-apply