This article was written on Pragma Engine version 0.0.94.

Creating Stackable Items #

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.

In this article, we’ll take a look at how to create a stackable item using Pragma Engine. In future articles, we’ll use these items to demonstrate store purchasing and item updates.

Pragma Engine has two kinds of items: stackables (identical items that can be stacked) and instanced (unique items with different qualities). For this tutorial, we’ll be making one stackable item: gold coins.

Understanding Stackables #

Stackables are an essential part of game economies, crafting systems, and gameplay loops. These items are completely identical, and as inferred by their name, stack on top of one another. They can be used for in-game currencies, crafting materials that never change, and even experience points.

In this example, a player’s inventory contains instanced items (armor), stackable resource items (with numbers), and stackable gold coins (currency).

Stackable items don’t require custom protobuf files because they have no special properties. All of their information is written in one JSON file, making them very simple to edit and create.

The next sections will show you how to create a gold coin stackable item and how to test it with service calls.

Before we begin our item building fun… #

You’ll want to get your engine built and your 5-ext directory created. 5-ext is where you can define custom content, which we’ll be doing in this example to create our gold coins.

First, build the engine by running the following command in the terminal from the platform directory:

make skip-tests protos engine

Now run the next command to create a 5-ext folder (if you don’t have one already):

make ext

Making a Stackable Item #

Go to 5-ext/content/src/StackableSpecs.json and add the following code to create a gold_coins stackable item.

[
  {
    "catalogId": "gold_coins",
    "name": "gold coins",
    "limit": 1000000,
    "tags": ["currency"],
    "removeIfNone": false
  }
]

In this code block, the stackable item gold_coins is given five very important parameters. Before we move on, let’s explain what each one means:

Now that we’ve defined our stackable gold coins, we need to apply our new content data changes to the engine.

clink clink clink

Register content changes #

To register the stackables we just made, we need to run Pragma Engine with a fresh build and apply our content data changes. We can do this with one simple command that runs make ext first, and then a contentdata apply command after. Run the following line of code in a terminal using platform as the working directory:

make ext-contentdata-apply

After our changes have been applied, it’s time to make sure our gold_coins item is up and running by simulating service calls with Postman.

Testing the Stackable Item with Service Calls #

Now, let’s see our gold coins in action!

Before you start, make sure you’re running a MySQL database and have Postman installed. If you don’t already have Postman installed, check out our Postman Setup guide in the initial setup README.

In the next few sections, we’ll use Postman to test our newly added gold coins.

Simulate service calls with Postman #

Before we test our gold coins with Postman, enter the following code in a terminal with platform as our working directory. This command gets the engine up and running so we can run calls against it.

make run

After opening and setting up Postman, let’s test our stackable gold coin item by authenticating our test Operator, granting gold coins to a player, and confirming the coins exist in the player’s inventory.

Authenticating a test login #

In the PragmaDev folder, navigate to the two service calls: Public>Operator - AuthenticateOrCreateV2 and Public>Player - AuthenticateOrCreateV2. Then click Send for both service calls and check that the response body for each call has given us pragmaTokens with a filled pragmaGameToken and pragmaSocialToken.

Both calls help Pragma Engine authenticate logins for Operators and a Player. Without running these two calls, Postman won’t be able to grant any sort of item to a player or check a player’s inventory.

Grant the gold coins #

In the PragmaDev folder, locate the service call: Game>RPC - Operator>Inventory>GrantItemsOperatorV1. Then open the service call’s body which displays the code that makes the GrantItems call work.

To simulate a player receiving some of our gold_coins, edit the payload section of the body and find the stackable object. Now, we’re going to fill in the stackable’s catalogId with gold_coins after the colon. This goes back to our content database to find the gold_coins we just created in our StackableSpecs.json file. We’re also going to fill in the amount with 1. This grants 1 gold coin to the player.

Once you’ve made this edit, click Send and check the response body to see if gold_coins are visible in the stackables object’s delta A delta represents the changes that occurred to an item as the result of an operation. and segment A segment represents the current state of an item in the player's inventory after a change. payloads, and if the amount of gold_coins has increased by 1. If so, it means we’ve granted our coins to our player!

Check an inventory for gold coins #

To confirm that the GrantItemsOperatorV1 call successfully gave a player gold coins, we can check our player inventory to see if the newly added coins appear.

Navigate to the service call location: Game>RPC - Operator>Inventory>GetInventoryOperatorV1. There is no need to make any edits to the body code–simply click Send and check the response.

If the response contains a payload that includes gold_coins as the catalogId with an amount value incremented by 1, you’ve just created a stackable currency!

For more information, check out the rest of the articles in this series:

Part I: Creating Stackable Items (this article)
Part II: Purchasing Stackable Items in a Store
Part III: Creating a Crafting System Using Stores