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

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

4. In the ExtPurchaseRequirements message, add the following code to define PetEvolutionRequirements:

message ExtPurchaseRequirements {
  oneof data {
    PetEvolutionRequirements pet_evolution_requirements = 1;
  }
}

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

6. In the ExtCraftingEntry message, add the following code to define PetEvolutionSpec:

message ExtCraftingEntry {
  oneof data {
    PetEvolutionSpec pet_evolution_spec = 1;     
  }
}

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

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

3. Edit the ExtCraftRequest message by inserting the following code:

message ExtCraftRequest {
  oneof data {
    PetEvolutionRequest pet_evolution_request = 1;
  }
}

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

5. Edit ExtInstancedItemServerGrant message by inserting the following code:

message ExtInstancedItemServerGrant {
  oneof data {
    PetEvolution pet_evolution = 1;
  }
}

6. 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
      }
    }
  }
]

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"
        }
      }
    }
  }
]

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