Unity Package Types
A consumable item is any item that can be consumed from the user’s backpack in exchange for granting special effects on their avatar and experience. Some examples of what a consumable item can be (but not limited to):
- Some food or drink item that heals the player or enables some dizziness effect.
- A ticket that can be shred to grant access to an exclusive zone within the space.
- A speed potion that makes the player run 50% faster and jump 20% higher for 10 seconds.
After an item is consumed, it is removed from the user’s backpack. For now, only
Basic Item types are allowed to be consumed.
Creating a Consumable Item
Navigate to the settings of the item of your choice and scroll down until you see a toggle for
Consumable under the backpack settings. Enabling this will give some basic functionality to consume the item, and reveal additional settings.
- Duration: How long the item will be active after consuming. You can set this to 0 seconds if you wish to apply an effect immediately instead of a time range.
- Cooldown: How long after the duration expires before it can be consumed again. 0 seconds is a valid value, which will disable the cooldown.
Durationto 10 seconds and the
Cooldownto 5 seconds means that the item can be consumed every 15 seconds.
Adding Consumable Functionality with Visual Scripting
In order to make the consumable actually do something, behavior will need to be defined within a
Script Machine and
Scripting Graph inside of a Space package’s scene.
Relevant scripting nodes that can help facilitate this are listed below:
Get Consumable Item State(asynchronous) — Gets relevant data for a given consumable item in the user’s backpack. The input trigger will need to be from a
Coroutinesince the request can be asynchronous and take time to complete if the item wasn’t found in the backpack.
- Item ID: The ID of the consumable item to get state for.
- Is Active: Returns
trueif the user has consumed the item in the past
Durationseconds. This will always be
0. In those cases, you will want the
On Backpack Item Consumedevent described below. The item can’t be consumed while the effects are active.
- Duration Remaining: The number of seconds left before the item deactivates/expires. This will be
0if the item is not active.
- On Cooldown: Returns
trueif this item was deactivated in the past
Cooldownseconds. The item can’t be consumed until this value is
false(no longer on cooldown).
- Cooldown Remaining: The number of seconds left on the cooldown timer. This will be
0if there’s no cooldown in progress or if the item is still active.
On Backpack Item Consumed— An event node that executes when the specified item is consumed.
- Item ID: When this item with the specified ID is consumed, this event will execute.
On Backpack Any Item Consumed— An event node that executes when any item is consumed.
- Item ID: The ID of the item that was consumed.
On Consumable Item Duration Expired— An event node that executes when the consumable item’s duration expires and is deactivated.
- Item ID: The ID of the item that was consumed. After the set
Durationfor this item, this event will execute. This event will only execute if the item’s
Durationis a positive number.
Scripting Graph Examples
The images below show two examples of how consumable items can be implemented.
The frozen pizza consumable has no
Duration set, so it only needs to listen to the
On Backpack Item Consumed event for the pizza’s item ID. The
On Consumable Item Duration Expired event will not be executed since the
Duration was set to
The nocturnal pill example is a bit more complicated. The
On Backpack Item Consumed event node is used as usual to activate the effect when it’s consumed. However, unlike the pizza example above, there is a
Duration set for the item (in this case, 120 seconds). There needs to be an
On Consumable Item Duration Expired event that needs to be listened for in order to deactivate the item’s effects after the
Duration has elapsed. Alternatively, you can constantly poll the state with
Get Consumable Item State but that can be slower and/or less convenient. The logic will work as long as the user doesn’t leave the space during the item’s
Duration, but will fail to activate the effects if they re-join the space while the item is active. This is fixed by using
Get Consumable Item State when the scene initializes, which will get the initial value and activate the effects automatically.