Spatial Creator Toolkit
Consumable Items
Consumable Items

Consumable Items

image

Consumable Items

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.

⚠️
Consumable items require knowledge of Visual Scripting to implement functionality in a Space package.
🚧
This is a new feature and under development. There will be more functionality and settings to tweak in the future, so stay tuned!

Creating a Consumable Item

✋
In order to create a consumable, you would first need to create a basic item for your world in Studio. If you’re unsure how to create a basic item, you can follow this guide on how to do so.

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.

image
  • 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.
    • 💡
    Setting the Duration to 10 seconds and the Cooldown to 5 seconds means that the item can be consumed every 15 seconds.
    🗒️
    The duration and cooldown timers will continue to run even when outside of the space or when the item is deleted from and/or readded to the backpack. These timers are also based on real-world time, so it will be the same regardless of time scale.

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 Coroutine since the request can be asynchronous and take time to complete if the item wasn’t found in the backpack.
    • Inputs
      • Item ID: The ID of the consumable item to get state for.
    • Outputs
      • Is Active: Returns true if the user has consumed the item in the past Duration seconds. This will always be false if the Duration is 0. In those cases, you will want the On Backpack Item Consumed event 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 0 if the item is not active.
      • On Cooldown: Returns true if this item was deactivated in the past Cooldown seconds. 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 0 if 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.
    • Inputs
      • 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.
    • Outputs
      • 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.
    • Outputs
      • Item ID: The ID of the item that was consumed. After the set Duration for this item, this event will execute. This event will only execute if the item’s Duration is a positive number.

Scripting Graph Examples

The images below show two examples of how consumable items can be implemented.

When consumed, the frozen pizza makes your avatar jump and adds extra upwards force immediately after.
When consumed, the frozen pizza makes your avatar jump and adds extra upwards force immediately after.

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

image

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.

← Previous

Items

XDiscordYouTubeInstagram

Sign up for the Email Newsletter

Join our Slack

Join our Discord

Back to spatial.io

© 2023 Spatial Systems, Inc. All Rights Reserved.