Customizing the Instanced Item Plugin #
In this section, we’ll go over writing an Instanced Item Plugin that builds unique gear-type instanced items with custom ext
data.
Prerequisites:
- The previous Instanced Items tutorial section for Creating Instanced Items must be completed.
Write the Instanced Item Plugin #
- Go to
5-ext/ext/src/main/kotlin
. - Create a Kotlin file called
InstancedItemTutorialPlugin.kt
. - Copy the following code into the
InstancedItemTutorialPlugin.kt
file to create a class that implements theInstancedItemPlugin
’s interface:
Even thoughnewInstanced()
is the only function utilized,update()
must still be implemented in order for the plugin to run.
import kotlin.random.Random
import pragma.content.ContentDataNodeService
import pragma.inventory.InstancedItem
import pragma.inventory.InstancedItemPlugin
import pragma.inventory.InventoryContent
import pragma.inventory.InventoryData
import pragma.inventory.InventoryModifications
import pragma.inventory.InventoryServiceContent
import pragma.inventory.ext.ExtInstancedItem
import pragma.inventory.ext.ExtInstancedItemServerGrant
import pragma.inventory.ext.ExtInstancedItemServerUpdate
import pragma.inventory.ext.ExtInstancedItemUpdate
import pragma.inventory.ext.ExtInstancedSpec
import pragma.inventory.ext.ExtPurchaseRequest
import pragma.inventory.ext.ExtUpdateEntry
import pragma.inventory.ext.Gear
import pragma.inventory.ext.GearSpec
import pragma.services.Service
@Suppress("unused")
class InstancedItemTutorialPlugin(
val service: Service,
val contentDataNodeService: ContentDataNodeService
) : InstancedItemPlugin {
override suspend fun newInstanced(
instancedSpec: InventoryContent.InstancedSpec,
inventoryContent: InventoryServiceContent,
startingInventory: InventoryData,
pendingInventory: InventoryData,
clientRequestExt: ExtPurchaseRequest?,
serverRequestExt: ExtInstancedItemServerGrant?
): InstancedItemPlugin.InstancedItemPluginResult {
val extInstancedItemBuilder = ExtInstancedItem.newBuilder()
val specExt: ExtInstancedSpec = instancedSpec.ext
return when (specExt.dataCase) {
ExtInstancedSpec.DataCase.GEAR_SPEC -> {
val gearSpec: GearSpec = specExt.gearSpec
// Calculates the attribute value for this piece of gear
// based on the content spec min and max.
val randomAttributeValue = Random.nextInt(
gearSpec.primaryAttributeValueMin,
gearSpec.primaryAttributeValueMax
)
// Builds the proto message that will be persisted and returns it.
val gearBuilder = Gear.newBuilder()
.setAttributeValue(randomAttributeValue)
.build()
val gearInstance =
extInstancedItemBuilder
.setGear(gearBuilder)
.build()
InstancedItemPlugin.InstancedItemPluginResult(gearInstance)
}
else -> {
error("Unknown item!")
}
}
}
override suspend fun update(
initialInstancedItem: InstancedItem,
instancedSpec: InventoryContent.InstancedSpec,
updateEntry: InventoryContent.UpdateEntry,
inventoryContent: InventoryServiceContent,
startingInventory: InventoryData,
pendingInventory: InventoryData,
clientRequestExt: ExtInstancedItemUpdate?,
serverRequestExt: ExtInstancedItemServerUpdate?
): InstancedItemPlugin.InstancedItemPluginResult {
TODO("Not yet implemented")
}
}
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
InstancedItemTutorialPlugin
by ensuring the game section of the config file matches the following:
game:
pluginConfigs:
InventoryService.instancedItemPlugin:
class: "InstancedItemTutorialPlugin"
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 builds unique gear items with custom ext
data 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
.
Simulate service calls #
Test the InstancedItemTutorialPlugin
by running the required authentication calls and granting three gear-type instanced items to a player. Granting these items causes the InstancedItemSeriesPlugin
to run for each item and builds out each item’s ext
fields via the InstancedItemPluginResult
.
- Open Postman.
- Navigate to the two service calls
PragmaDev ➨ Public ➨ Operator - AuthenticateOrCreateV2
andPragmaDev ➨ Public ➨ Player - AuthenticateOrCreateV2
. - Click Send for both service calls and check that the response body for each call has
pragmaTokens
with a filledpragmaGameToken
andpragmaSocialToken
. - Open
PragmaDev ➨ Game ➨ RPC - Operator ➨ Inventory ➨ GrantItemsOperatorV1
and open the service call’s body. - Insert the following code block to add three instanced grants (
metal_sword_1
,metal_chest_2
, andmetal_hat_3
) to the test player:
{
"requestId": 1,
"type": "InventoryRpc.GrantItemsOperatorV1Request",
"payload": {
"playerId": "{{test01PlayerId}}",
"itemGrants": [
{
"instanced": {
"ext": {},
"catalogId": "metal_sword_1",
"tags" : []
}
},
{
"instanced": {
"ext": {},
"catalogId": "metal_chest_2",
"tags" : []
}
},
{
"instanced": {
"ext": {},
"catalogId": "metal_hat_3",
"tags" : []
}
},
{
"stackable": {
"catalogId": "",
"amount": 1,
"tags": []
}
}
]
}
}
- Click Send to grant the player their gear.
- Confirm the player has their three instanced items by using the call
PragmaDev ➨ Game ➨ RPC - Operator ➨ Inventory ➨ GetInventoryOperatorV1
.