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.

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.

1. 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.

make ext-contentdata-apply

Write the Stackable Item Plugin #

1. Go to 5-ext/ext/src/main/kotlin.
2. Create a Kotlin file called StackableItemTutorialPlugin.kt.
3. 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.

1. Open 5-ext/config/local-dev.yml.
2. 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.

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

Grant silver coins #

1. Open Postman.
2. Navigate to the two service calls PragmaDev ➨ Public ➨ Operator - AuthenticateOrCreateV2 and PragmaDev ➨ Public ➨ Player - AuthenticateOrCreateV2.
3. Click Send for both service calls and check that the response body for each call has pragmaTokens with a filled pragmaGameToken and pragmaSocialToken.
4. 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.

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