Customizing the Stackable Item Plugin #

In this section, we’ll go over creating a StackableItemPlugin and using it update silver coins to gold coins.

Prerequisites:

The previous Stackable Items tutorial section for Creating Stackable Items must be completed.

Define stackable item specs #

First we’ll need to add silver coins to the StackableSpecs.json.

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

{
    "catalogId": "silver_coins",
    "name": "silver_coins",
    "limit":  100000000,
    "tags": ["currency"],
    "removeIfNone": false
}

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.

Write the Stackable Item Plugin #

Go to 5-ext/ext/src/main/kotlin.
Create a Kotlin file called StackableItemTutorialPlugin.kt.
Copy the following code in the StackableItemTutorialPlugin.kt file to create a class that implements the StackableItemPlugin’s interface:

import pragma.content.ContentDataNodeService
import pragma.inventory.InventoryContent
import pragma.inventory.InventoryData
import pragma.inventory.InventoryModifications
import pragma.inventory.InventoryServiceContent
import pragma.inventory.StackableItemGrant
import pragma.inventory.StackableItemPlugin
import pragma.services.Service

@Suppress("unused")
class StackableItemTutorialPlugin(
    private val service: Service,
    private val contentDataNodeService: ContentDataNodeService
): StackableItemPlugin {
    override suspend fun onUpdate(
        preUpdateAmount: Long,
        delta: Long,
        stackableSpec: InventoryContent.StackableSpec,
        inventoryContent: InventoryServiceContent,
        startingInventory: InventoryData,
        pendingInventory: InventoryData
    ): InventoryModifications {

        // We only want to do update silver_coins.
        if (stackableSpec.catalogId != "silver_coins") {
            return InventoryModifications()
        }

        // Adds up how much silver a player has based on the
        // previous amount and this update.
        val totalSilver = preUpdateAmount + delta

        // If the player's total silver is less than ten, we 
        // don't need to do anything.
        if (totalSilver < 10) {
            return InventoryModifications()
        }

        // Every ten silver is a new gold coin.
        val newGold = totalSilver / 10

        // Any emaining silver is the remainder left over that's less than 10.
        val remainingSilver = totalSilver % 10

        // Calculates the amount of silver we need to remove 
        // from the player's total since it just became gold.
        val silverToDeduct = remainingSilver - totalSilver

        // Returns stackable grants to add the new gold coins 
        // and subtracts the right amount of silver.
        return InventoryModifications(
            stackableItemGrants = listOf(
                StackableItemGrant("gold_coins", newGold, listOf()),
                StackableItemGrant(
                    "silver_coins",
                    silverToDeduct,
                    listOf()
                )
            )
        )
    }
}

Configure the plugin #

Plugins must be configured in YAML configuration files before they can be utilized by Pragma Engine.

Open 5-ext/config/local-dev.yml.
Register the StackableItemTutorialPlugin by ensuring the game section of the config file matches the following:

game:
    pluginConfigs:
        InventoryService.stackableItemPlugin:
            class: "StackableItemTutorialPlugin"

Build plugin changes #

Run the following make command using platform as the working directory to register plugin changes:

make ext

Test the plugin #

In this section, we’ll test if the plugin logic successfully converts 10 silver_coins to 1 gold_coin by running API calls in Postman.

Start Pragma Engine #

Run Pragma Engine via one of the following methods.

Running via Make

Run make run to start the platform. Run this in a terminal with platform as the working directory.

Running in IntelliJ

From the IntelliJ toolbar in the upper right, ensure MainKt - LocalConfigured is selected, then click the play button.

If MainKt - LocalConfigured isn’t available, you will need to configure it. In the IntelliJ toolbar, click the dropdown next to the run button, then click Edit Configurations…. In the Run/Debug Configurations window that appears, expand Kotlin in the left hand side, then select MainKt - LocalConfigured. Click OK. Click the play button in the IntelliJ toolbar to start Pragma Engine.

Once the engine has started successfully, it prints the message [main] INFO main - Pragma server startup complete.

Grant silver coins #

Open Postman.
Navigate to the two service calls PragmaDev ➨ Public ➨ Operator - AuthenticateOrCreateV2 and PragmaDev ➨ Public ➨ Player - AuthenticateOrCreateV2.
Click Send for both service calls and check that the response body for each call has pragmaTokens with a filled pragmaGameToken and pragmaSocialToken.
Open Game➨RPC - Operator➨Inventory➨GrantItemsOperatorV1 and edit the body with the following payload:

Find the stackable object and fill the catalogId with the value silver_coins.
Then fill the amount with a value of 13.

Click Send and check the response body to see if silver_coins are present in the object’s delta and segment payloads. If the amount of silver_coins is 3 and gold_coins is now 1, we have successfully granted and converted coins for our player.