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
) andext
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 eachpet
, and crafting entries in JSON.Customize an
InstancedItemPlugin
andCraftingPlugin
in Kotlin that builds and evolvesext
data forpet
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:
make skip-tests protos engine
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 customext
dataExtInstancedItem
contains theext
data of instanced items built in theInstancedItemPlugin
.
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 theCraftingPlugin
.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 ExtCraftingEntry
s that go into evolving a Pet
.
Open
5-ext/ext-protos/src/main/proto/shared/inventoryContentExt.proto
.In the
ExtInstancedSpec
message, add the following code to define thePetSpec
:
message ExtInstancedSpec {
string name = 1;
oneof data {
PetSpec pet_spec = 2;
}
}
- Define custom
PetSpec
components by inserting the following message andPetBonus
enum below theExtInstancedSpec
message. This message lists the required values when creatingext
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;
}
- In the
ExtPurchaseRequirements
message, add the following code to definePetEvolutionRequirements
:
message ExtPurchaseRequirements {
oneof data {
PetEvolutionRequirements pet_evolution_requirements = 1;
}
}
- Define custom
PetEvolutionRequirements
by inserting the following message below theExtPurchaseRequirements
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;
}
- In the
ExtCraftingEntry
message, add the following code to definePetEvolutionSpec
:
message ExtCraftingEntry {
oneof data {
PetEvolutionSpec pet_evolution_spec = 1;
}
}
- Define custom
PetEvolutionSpec
components by inserting the following message below theExtCraftingEntry
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.
Open
5-ext/ext-protos/src/main/proto/shared/inventoryExt.proto
.Edit the
ExtInstancedItem
message by inserting the following code:
message ExtInstancedItem {
oneof data {
Pet pet = 2;
}
}
- Define
Pet
s by inserting the following message below theExtInstancedItem
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.
Open
5-ext/ext-protos/src/main/proto/shared/inventoryRpcExt.proto
.Insert the following import:
import "shared/inventoryExt.proto";
- Edit the
ExtCraftRequest
message by inserting the following code:
message ExtCraftRequest {
oneof data {
PetEvolutionRequest pet_evolution_request = 1;
}
}
- Define
PetEvolutionRequest
by inserting the following message below theExtCraftRequest
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;
}
- Edit
ExtInstancedItemServerGrant
message by inserting the following code:
message ExtInstancedItemServerGrant {
oneof data {
PetEvolution pet_evolution = 1;
}
}
- Define
PetEvolution
by inserting the following message below theExtInstancedItemServerGrant
. This allows a trusted source to grant items to the client and will be used to give the client a new and upgradedPet
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, runmake init-inventory-content
using a terminal from theplatform
directory.
Edit the instanced specs catalog #
Define the pet-type items fire_dragon
and fire_dragon_2
in the instanced specs JSON catalog.
Open
5-ext/content/src/InstancedSpecs.json
.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.
Go to
5-ext/content/src/StackableSpecs.json.
Insert the following code block to create
gold_coins
,fire_shard
s, andfire_gem
s:
[
{
"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.
Go to
5-ext/content/src/CraftingEntries.json
Insert the following code block to create the
CraftingEntry
for evolving afire_dragon
into afire_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.