Instanced Items #

Instanced items are items that can hold individual attributes that differ between items of the same type (i.e. upgraded versions of the same sword). They’re created based on an instanced spec defined by strongly typed protobufs and plugin code that informs how the item needs to be constructed/managed. Because instanced items can be used to define and hold arbitrary data, they can be used to power complex systems like battlepasses and missions.

Instanced Specs #

Instanced specs are more complex because they’re used to communicate information about managing the lifecycle of an item to the engine and relevant plugins. The engine handles data lifecycle, caching, and transactions, leaving game developers free to focus on game content and features.

For example, ext specification of items allow custom information, such as determining which bonus to add to an item on creation or how many games a player needs to win to be awarded an achievement.

The combination of instanced items, specs, and plugins allows for endless flexibility.

Here’s an example of an instanced spec for a Fire Dragon pet.

 {
    "catalogId": "fire-dragon", // id, cannot be changed

    "name": "Fire Dragon",      // display name, can be changed.

    "tags": ["pet"],            // used to group and filter content

    "ext": {                    // extension field for custom data

      "petSpec": {              // example spec for a pet system

        "bonuses": [            // strongly typed data defined in
          "XP_BONUS",           // proto. This data is used by
          "GOLD_BONUS",         // plugin code to initialize pet
          "LUCK_BONUS"          // instances
        ],
        "bonusMin": 5,
        "bonusMax": 10
      }
    }
  }

Instanced Item Plugin #

The logic to create or update your custom instanced items is defined within the Instanced Item Plugin. There are many ways to trigger this plugin including granting an instanced item to a player as a reward.

In the following sections, we’ll take a look at the different components that make up the Instanced Item Plugin’s interface.

Member	Section
`newInstanced`	Creating an instanced item
`update`	Updating an instanced item
`onDelete`	Chaining inventory operations on delete
`InstancedItemPluginResult`	Returning the result

For more resources on instanced items, check out the Building Unique Instanced Items with Plugins Tech Blog article, and for an example of implementation see the Battlepass tutorial.

Creating an instanced item #

When granting a new instanced item, the newInstanced function allows you to generate ext data that is stored within each item. newInstanced is called through either a valid client sourced ext or server sourced ext.

Below are the parameters and their descriptions for newInstanced:

Parameter	Description
`instancedSpec`	An object that contains spec content for your instanced item catalog (JSON files).
`inventoryContent`	A reference object for all the content in the Inventory service. This can be used to look up specs for other related items.
`startingInventory`	A snapshot of the player’s inventory at the very start of the request.
`pendingInventory`	A snapshot of the player’s inventory including any item changes that have occurred during the request.
`clientRequestExt`	An object used for passing `ext` data from a client request.
`serverRequestExt`	An object used for passing `ext` data from a server request.

Updating an instanced item #

When modifying an existing instanced item, the update function allows you to interact with ext data for the existing item. Like the newInstanced function, update is only called through either a valid client sourced ext or server sourced ext.

Below are the parameters and their descriptions for update:

Parameter	Description
`initialInstancedItem`	An object containing information on the current state of the item.
`instancedSpec`	An object that contains spec content for your instanced item catalog (JSON files).
`updateEntry`	An object and type of Inventory service content that contains information about how to update the item. If not used, it will use the default instance `UpdateEntry` proto. This can be useful to model your item data including adding a stackable cost to your item data or storing data on how to update an item under the `ExtUpdateEntry`.
`inventoryContent`	A reference object for all the content in the Inventory service. This can be used to look up specs for other related items.
`startingInventory`	A snapshot of the player’s inventory at the very start of the request.
`pendingInventory`	A snapshot of the player’s inventory including any item changes that have occurred during the request.
`clientRequestExt`	An object used for passing `ext` data from a client request.
`serverRequestExt`	An object used for passing `ext` data from a server request.

Chaining inventory operations on delete #

The onDelete function can be used to chain additional inventory operations while an instanced item is being deleted. Consider a scenario where a player has a mission (instanced item). Upon mission completion, you can delete the mission and also grant the player a reward.

Below are the parameters and their descriptions for onDelete:

Parameter	Description
`deleteItem`	The instance item to be deleted.
`instancedSpec`	An object that contains spec content for your stackable item catalog (JSON files).
`inventoryContent`	A reference object for all the content in the Inventory service. This can be used to look up specs for other related items.
`startingInventory`	A snapshot of the player’s inventory prior to any updates.
`pendingInventory`	A snapshot of the player’s inventory including any item changes that have occurred during the request.

The onDelete function returns the InventoryModifications data class. This data class can be used for chaining additional item operations such as granting, updating, or destroying items. Below are the possible item operations:

Property	Type	Description
`rewardGrants`	`List<RewardGrant>`	List of rewards to be granted.
`instancedItemServerGrants`	`List<InstancedItemServerGrant>`	List of instanced item to be granted.
`stackableItemGrants`	`List<StackableItemGrant>`	List of stackable item grants to be granted.
`serverInstancedItemUpdates`	`List<ServerInstancedItemUpdate>`	List of instanced items to be updated.
`instancedItemsToDestroy`	`List<InstanceId>`	List of instanced items to be destroyed.

Returning the result #

The newInstanced and update functions must return an InstancedItemPluginResult.

Below are the properties in the InstancedItemPluginResult:

Property	Type	Description
`extInstancedItem`	`ExtInstancedItem?`	Stores the details of the item being created or updated. This can be set to null to stop the creation or update of an item without throwing an exception.
`InventoryModifications`	`InventoryModifications`	This can be used for chaining additional item operations. See the table below for more details.

The following are the possible item operations:

Property	Type	Description
`rewardGrants`	`List<RewardGrant>`	List of rewards to be granted.
`instancedItemServerGrants`	`List<InstancedItemServerGrant>`	List of instanced item to be granted.
`stackableItemGrants`	`List<StackableItemGrant>`	List of stackable item grants to be granted.
`serverInstancedItemUpdates`	`List<ServerInstancedItemUpdate>`	List of instanced items to be updated.
`instancedItemsToDestroy`	`List<InstanceId>`	List of instanced items to be destroyed.