Stackable Items #

Stackable items represent stacks of items with a count and limit such as currencies or health potions. Stackable items of the same type only vary in their amount and do not behave differently from one another (i.e. one stack of gold coins acts the same as another stack of gold coins).

Stackable Specs #

Stackable specs are generally straightforward since there’s a limited amount of behavior that needs to be defined, because stackable items of the same type do not vary from one another.

Here’s an example of a stackable spec for an in-game currency.

    "catalogId": "gold-coins", // id, cannot be changed

    "name": "Gold Coins", // display name, can be changed.

    "limit": 10000,       // the maximum amount of gold a player
                          // can have

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

    "removeIfNone": false // determines if a stack is deleted
                          // when the amount goes to 0. Useful
                          // for consumables.
    "ext": {
      "conversion_to_silver": 100 // custom properties that you
                                  // can define that will be true for
                                  // all Stackables of this type

Stackable Item Plugin #

The Stackable Item Plugin is used to define custom behavior when updating a stackable item. In the following sections, we’ll take a look at the different components that make up the Stackable Item Plugin’s interface.

onUpdateChaining inventory operations on update
StackableItemPluginResultReturning the result

Chaining inventory operations on update #

The StackableItemPlugin.onUpdate function is called when a stackable item is granted or updated.

Below are the parameters and their descriptions for onUpdate:

preUpdateAmountView of stackable item with all prior chained updates applied with catalog limited enforced.
deltaThe difference to add or subtract from the stackable item amount.
stackableSpecAn object that contains spec content for your stackable item catalog (JSON files).
inventoryContentA reference object for all the content in the Inventory service. This can be used to look up specs for other related items.
startingInventoryA snapshot of the player’s inventory prior to any updates.
pendingInventoryA snapshop of the player’s inventory after all updates are processed with enforced catalog limits.

Returning the result #

The onUpdate function returns the InventoryModifications data class. This data class can be to used for chaining additional item operations such as granting, updating, or destroying items.

Below are the possible item operations:

rewardGrantsList<RewardGrant>List of rewards to be granted.
instancedItemServerGrantsList<InstancedItemServerGrant>List of instanced item to be granted.
stackableItemGrantsList<StackableItemGrant>List of stackable item grants to be granted.
serverInstancedItemUpdatesList<ServerInstancedItemUpdate>List of instanced items to be updated.
instancedItemsToDestroyList<InstanceId>List of instanced items to be destroyed.