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.

Creating Instanced Items #

In this section, we’ll demonstrate how to create a custom unique instanced item type called “gear.” To create gear we’ll go over the following steps:

• Create the gear’s ext instanced item template (ExtInstancedSpec) and ext item mold (ExtInstancedItem) in protos.
• Define the catalog of gear instanced items in JSON.
• Customize an InstancedItemPlugin in Kotlin that builds ext data for gear.

Get started #

Run the following commands in the terminal from the platform directory to build the engine and make 5-ext if it doesn’t already exist:

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

Define the protos #

In this section, we’ll define the two protobuf definitions that make up ext data for instanced items:

• ExtInstancedSpec templates the item’s custom ext data
• ExtInstancedItem contains the ext data of instanced items built in the InstancedItemPlugin.

Edit the inventory content ext file #

Define the ExtInstancedSpec templates for the gear-type items’ custom ext data.

1. Open 5-ext/ext-protos/src/main/proto/shared/inventoryContentExt.proto.
2. In the ExtInstancedSpec message, add the following code to define the GearSpec:

message ExtInstancedSpec {
  oneof data {
    GearSpec gear_spec = 1;
  }
}

3. Define custom GearSpec components by inserting the following message below the ExtInstancedSpec message. This message lists the values required when creating an ext data for a gear-type item.

message GearSpec {
  int32 level_to_equip = 1;
  string primary_attribute_spec_id = 2;
  int32 primary_attribute_value_min = 3;
  int32 primary_attribute_value_max = 4;
}

Edit the inventory ext file #

Define the ExtInstancedItem mold that contains the ext data for gear-type items.

1. Open 5-ext/ext-protos/src/main/proto/shared/inventoryExt.proto.
2. Edit the ExtInstancedItem message by inserting the following code:

message ExtInstancedItem {
  oneof data {
    Gear gear = 1;
  }
}

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

message Gear {
  int32 attribute_value = 1;
  repeated string socketed_runestones = 2;
}

Apply proto changes #

Run the following make command using platform as the working directory to apply protobuf changes:

make ext-protos

Define the JSON catalog #

Instanced items are defined in a JSON item catalog with shared identifiers and configurations for all game content managed by the platform. This is where designers create player inventory specifications and include ext data with their items.

If you do not already have the content source files initialized, run make init-inventory-content using a terminal from the platform directory.

Edit the instanced specs catalog #

Define gear-type items metal_sword_1, metal_chest_2, and metal_hat_3 in the instanced specs JSON catalog.

1. Open 5-ext/content/src/InstancedSpecs.json.
2. Insert the following code into the JSON catalog:

[
  {
    "catalogId": "metal_sword_1",
    "name": "Copper Sword",
    "tags": [
      "weapon",
      "1h"
    ],
    "ext": {
      "gearSpec": {
        "levelToEquip": 1,
        "primaryAttributeSpecId": "damage_physical",
        "primaryAttributeValueMin": 5,
        "primaryAttributeValueMax": 10
      }
    }
  },
  {
    "catalogId": "metal_chest_2",
    "name": "Bronze Breastplate",
    "tags": [
      "armor",
      "chest",
      "heavy-armor"
    ],
    "ext": {
      "gearSpec": {
        "levelToEquip": 2,
        "primaryAttributeSpecId": "resistance_physical",
        "primaryAttributeValueMin": 35,
        "primaryAttributeValueMax": 40
      }
    }
  },
  {
    "catalogId": "metal_hat_3",
    "name": "Iron Helmet",
    "tags": [
      "armor",
      "head",
      "heavy-armor"
    ],
    "ext": {
      "gearSpec": {
        "levelToEquip": 3,
        "primaryAttributeSpecId": "resistance_physical",
        "primaryAttributeValueMin": 20,
        "primaryAttributeValueMax": 25
      }
    }
  }
]

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