Setting Up the Item Catalog #

In this section, we’ll demonstrate how to create a custom unique instanced item type called “pets” that can evolve into a new pet using a Crafting Plugin. To create and evolve pets, we’ll go over the following steps:

  • Create the pet’s ext instanced item template (ExtInstancedSpec) and ext item mold (ExtInstancedItem) in protos.

  • Create the ext data for each crafting entry, purchase requirement, craft request, and instanced item server grant for evolving pets.

  • Define the catalog of pet instanced items, stackable item materials used for evolving each pet, and crafting entries in JSON.

  • Customize an InstancedItemPlugin and CraftingPlugin in Kotlin that builds and evolves ext data for pet instanced items.


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 protobuf definitions involved in our pet crafting scenario. We’ll define 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.

We’ll also define four protobuf defintions that make up the ext data for our crafting endpoints:

  • ExtCraftingEntry templates custom data for crafting entries utilized in the CraftingPlugin.

  • ExtPurchaseRequirements contains additional data requirements for a crafting scenario to occur.

  • ExtCraftRequest adds additional data information for a craft request called by client RPCs.

  • ExtInstancedItemServerGrant allows item grants specified as an RPC endpoint from the server.

Edit the inventory content ext file #

Define the ExtInstancedSpec templates for the pet-type items’ custom ext data, as well as the ExtPurchaseRequirements and ExtCraftingEntrys that go into evolving a Pet.

  1. Open 5-ext/ext-protos/src/main/proto/shared/inventoryContentExt.proto.

  2. In the ExtInstancedSpec message, add the following code to define the PetSpec:

message ExtInstancedSpec {
  string name = 1;
  oneof data {
      PetSpec pet_spec = 2;
  }
}
  1. Define custom PetSpec components by inserting the following message and PetBonus enum below the ExtInstancedSpec message. This message lists the required values when creating ext data for a pet-type item.
message PetSpec {
  repeated PetBonus bonuses = 1;
  int64 bonus_min = 2;
  int64 bonus_max = 3;
}

enum PetBonus {
  UNUSED = 0;
  XP_BONUS = 1;
  GOLD_BONUS = 2;
  LUCK_BONUS = 3;
}
  1. In the ExtPurchaseRequirements message, add the following code to define PetEvolutionRequirements:
message ExtPurchaseRequirements {
  oneof data {
    PetEvolutionRequirements pet_evolution_requirements = 1;
  }
}
  1. Define custom PetEvolutionRequirements by inserting the following message below the ExtPurchaseRequirements message. This templates the structure of requirements that must be true from the client in order to perform the craft.
message PetEvolutionRequirements {
  string required_pet_catalog_id = 1;
  string required_player_location = 2;
}
  1. In the ExtCraftingEntry message, add the following code to define PetEvolutionSpec:
message ExtCraftingEntry {
  oneof data {
    PetEvolutionSpec pet_evolution_spec = 1;     
  }
}
  1. Define custom PetEvolutionSpec components by inserting the following message below the ExtCraftingEntry message. This templates the specifications that need to go into particular crafting entries.
message PetEvolutionSpec {
  string target_pet_catalog_id = 1;
  int64 bonus_increment = 2;
}

Edit the inventory ext file #

Define the ExtInstancedItem mold that contains the ext data for pet-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 {
    Pet pet = 2;
  }
}
  1. Define Pets by inserting the following message below the ExtInstancedItem message:
message Pet {
  PetBonus bonus = 1;
  int64 bonus_amount = 2;
}

Edit the inventory RPC ext file #

Define the ExtCraftRequest template and ExtInstancedItemServerGrant endpoints used by untrusted (game clients) and trusted sources (admin operator of APIs) to request crafting scenarios and item grants.

  1. Open 5-ext/ext-protos/src/main/proto/shared/inventoryRpcExt.proto.

  2. Insert the following import:

import "shared/inventoryExt.proto";
  1. Edit the ExtCraftRequest message by inserting the following code:
message ExtCraftRequest {
  oneof data {
    PetEvolutionRequest pet_evolution_request = 1;
  }
}
  1. Define PetEvolutionRequest by inserting the following message below the ExtCraftRequest message. Whenever the client requests this specific craft request they must be in a specific crafting location according to the request.
message PetEvolutionRequest {
  string crafting_location = 1;
}
  1. Edit ExtInstancedItemServerGrant message by inserting the following code:
message ExtInstancedItemServerGrant {
  oneof data {
    PetEvolution pet_evolution = 1;
  }
}
  1. Define PetEvolution by inserting the following message below the ExtInstancedItemServerGrant. This allows a trusted source to grant items to the client and will be used to give the client a new and upgraded Pet when they evolve a previous one.
message PetEvolution {
  ext.Pet pet = 1;
}

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 and stackable items, as well as crafting entries, 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 the pet-type items fire_dragon and fire_dragon_2 in the instanced specs JSON catalog.

  1. Open 5-ext/content/src/InstancedSpecs.json.

  2. Insert the following code block into the JSON catalog:

[
  {
    "catalogId": "fire_dragon",
    "name": "fire dragon",
    "tags": ["avatar", "dragon", "fire"],
    "ext": {
      "petSpec": {
        "bonuses": ["XP_BONUS", "GOLD_BONUS", "LUCK_BONUS"],
        "bonusMin": 5,
        "bonusMax": 10
      }
    }
  },
  {
    "catalogId": "fire_dragon_2",
    "name": "fire dragon 2",
    "tags": ["avatar", "dragon", "fire"],
    "ext": {
      "petSpec": {
        "bonuses": [
          "XP_BONUS",
          "GOLD_BONUS",
          "LUCK_BONUS"
        ],
        "bonusMin": 7,
        "bonusMax": 12
      }
    }
  }
]
Instanced Specs Overview

In this JSON catalog we’re defining two different pets: fire_dragon and fire_dragon_2.

  • fire_dragon has additional properties defined in the ext field using the petSpec template. This ext data will be used by the Instanced Item Plugin to generate specific instances of fire_dragon with custom content, such as a bonus of XP, gold, or luck.

  • fire_dragon_2 does not have an ext field for the purposes of this example. In a future step we’ll author the Crafting Plugin to make fire_dragon_2 available only through crafting.

Edit the stackable specs catalog #

Define the in-game currency and materials required to evolve a pet fire_dragon in the stackable specs JSON catalog.

  1. Go to 5-ext/content/src/StackableSpecs.json.

  2. Insert the following code block to create gold_coins, fire_shards, and fire_gems:

[
  {
    "catalogId": "gold_coins",
    "name": "gold coins",
    "limit": 1000000,
    "tags": ["currency"],
    "removeIfNone": false
  },
  {
    "catalogId": "fire_shard",
    "name": "fire shard",
    "limit": 10000,
    "tags": ["material"]
  },
  {
    "catalogId": "fire_gem",
    "name": "fire gem",
    "limit": 10,
    "tags": ["material"]
  }
]

Edit the crafting entries catalog #

Define the crafting entry API endpoint for evolving a pet in the crafting entries JSON catalog.

  1. Go to 5-ext/content/src/CraftingEntries.json

  2. Insert the following code block to create the CraftingEntry for evolving a fire_dragon into a fire_dragon_2.

[
  {
    "id": "fire_dragon_2_evolution",
    "stackableCostByCatalogId": {
      "gold_coins": {
        "cost": 2000
      },
      "fire_shard": {
        "cost": 2000
      },
      "fire_gem": {
        "cost": 2
      }
    },
    "ext": {
      "petEvolutionSpec": {
        "targetPetCatalogId": "fire_dragon_2",
        "bonusIncrement": 2
      }
    },
    "requirements": {
      "ext": {
        "petEvolutionRequirements": {
          "requiredPetCatalogId": "fire_dragon",
          "requiredPlayerLocation": "fire_lake"
        }
      }
    }
  }
]
Crafting Entries Overview

In this JSON catalog we’re defining the crafting entry to evolve a fire_dragon into a fire_dragon_2.

  • stackableCostByCatalogId uses stackable items as a cost requirement to complete the crafting entry. In this case, evolving a fire_dragon into a fire_dragon_2 costs 2000 gold_coins, 2000 fire_shards, and 2 fire_gems.

  • ext contains all the custom data for a crafting entry as defined in protos. For this crafting entry we’re using the defined petEvolutionSpec which has a field for the targetPetCatalogId that will be granted at the end of the craft and bonusIncrement which will upgrade the pet’s bonus value.

  • requirements allows any additional crafting entry requirements defined in protos to be included in the entry. For this example, our petEvolutionRequirements needs a requiredPetCatalogId of fire_dragon and a requiredPlayerLocation of fire_lake.

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.

Applying content data using Make

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

make ext-contentdata-apply
Applying content data using IntelliJ
From the IntelliJ toolbar in the upper right, ensure contentdata apply is selected, then click the play button.