The inventory_component is a Scene Graph component used as a container for Items. For how to add a component to your entity, see Working with Entities and Components.
Entities are only considered items if they have an item_component. Without one, entities are not added to inventories properly and Custom Items and Inventory functionality may break.
References to an “item” are referring to an entity with an
item_component.References to “inventories” are referring to an entity with an
inventory_component.
Class Description
An inventory_component turns an entity into a container for items.
The entity could be a player, a treasure chest, or anything that can hold items.
By default an inventory can hold an infinite number of any kind of item. Through Verse you can write logic inside the component to create restrictions and custom behaviors so an inventory can be tailored to your experience.
The component is listed as inventory_component in the component dropdown list. For more information, check out the inventory_component API reference from the Verse API.
While a prefab may have an inventory_component (which makes it capable of storing items), it may not have the necessary components for player interaction, user interface, and other requirements for the exchange of items. Multiple components may be necessary to mediate between the treasure chest and an entity created to retrieve or store items inside it.
Verse: Inventories
Items added to the inventory become children of the inventory_component's entity. Along with the normal scene graph hierarchy functionality, Inventories can manage themselves and their owned items with specific properties and methods:
AddItem()- Adds items (including subinventories).RemoveItem()- Removes items (includes subinventories).AddItemDistribute()- Add items to the targeted inventory, or any subinventories if the target cannot accept the item.GetItems()- Retrieve items or return immediate children.FindItems()- Find functions return all descendents.GetInventories()- Returns immediate child subinventories of this inventory.FindInventories()- Returns all descendant subinventories of this inventory.AddItemEventandRemoveItemEvent- Subscribable events that trigger when an item enters or exits this inventory.GetEquippedItems()- Can be used for equipping items.EquipItemEvent- Track equipping items with events.UnequipItemEvent- Track unequipping items with events.
Inventory Root
Players have an inventory by default called the Inventory Root. The following explanation does not affect entities that have an inventory_component added through Verse or the prefab editor.
Unlike other inventories, the player’s Inventory Root cannot accept items. Instead, it acts as the parent for subinventories beneath it. This provides a way to target the Inventory Root using AddItemDistribute() which finds an eligible inventory for an item, even if the initial target inventory cannot receive it.
Players must have one or more subinventories beneath the Inventory Root to receive items.
When a player has a single, top-level inventory, other systems can use it as an entry point, even without knowing internal inventory details. Whenever traversing the Scene Graph downwards the Inventory Root is always the first inventory found when searching an entity tree for an entity with an inventory_component. This makes the inventory root a sensible target to attach new inventories to.
# This helper function gets the first inventory component from a child entity of an agent.
# This will be the inventory root.
(Agent:agent).GetInventoryRoot()<transacts><decides>:inventory_component =
for (Child : Agent.GetEntities(), InventoryComponent := Child.GetComponent[inventory_component]){InventoryComponent}[0]The root inventory is only automatically added to players. New entities created with an inventory_component do not have the same restriction.
Inventories Configuration
Every player has an inventory configuration when they are added to a scene. This configuration determines which subinventories they begin with. All players start with an inventory root, but the configuration determines whether they start with any subinventories. The configuration can be set inside the Island settings, under Custom Inventory Configuration.
Below you can see the difference between the two initial configurations provided with the feature. In both cases, new subinventories need to be added as descendants of the Inventory Root. The BR Style configuration comes with a number of Fortnite subinventories. Refer to Fort Inventory Component for more information on Fort Inventories.
Verse Example
Below is a script for a device that uses the helper function GetInventoryRoot[] defined in Verse: Inventories above. The device has an editable field that can be modified in the scene. It adds the selection of items to each player when the player is added to the simulation, functioning like an item granter. Calling AddItemDistribute() ensures that all subinventories are checked to see if they can receive the item:
# Copyright Epic Games, Inc. All Rights Reserved.
using { /Fortnite.com/Devices }
using { /Fortnite.com/Itemization }
using { /Verse.org/SceneGraph }
using { /Verse.org/Simulation }
using { /UnrealEngine.com/Itemization }
Filtering Inventories with Scene Events
When an inventory is targeted to receive or remove an item, it receives a Scene Event. An add_item_query_event when adding, and a remove_item_query_event when removing (the item entity added or removed from the inventory also receives the scene event). The responses to these events are what cause the AddItem() and RemoveItem() functions to succeed or fail.
By overriding how these events are received, the entry or exit of items from an inventory can be controlled. This provides a way to create inventory rules, such as checking the item type before adding, only allowing a certain number of items in the inventory, and more.
The OnReceive() function is implemented in the base component class and is available to all Scene Graph components, including the inventory_component. It is triggered when an entity receives any Scene Event. By overriding OnReceive() you can modify the received Scene Event and add an error to it that causes the add or remove to fail for the inventory. You can write a unique error class to be used in these instances. See the code snippet below for an error class example.
A common requirement of inventories is to apply rules to what items may exist inside. Below is a script for a custom inventory_component which overrides the component method OnReceive(). Here it has been used to make a maximum Inventory size rule:
# Copyright Epic Games, Inc. All Rights Reserved.
using { /Verse.org/SceneGraph }
using { /Verse.org/Simulation }
using { /UnrealEngine.com/Itemization }
# This error can be created if the inventory is at capacity.
no_slots_add_item_error := class(add_item_error):
The video above illustrates how the custom_inventory_component adds three items to the inventory and rejects additional items.
The above behavior only works on the player because the custom_inventory_component has been added to an entity which has then been attached to the player root inventory as a child. Below is a device example code snippet illustrating this behavior:
# Copyright Epic Games, Inc. All Rights Reserved.
using { /Fortnite.com/Devices }
using { /Verse.org/SceneGraph }
using { /Verse.org/Simulation }
using { /UnrealEngine.com/Itemization }
# This device will add a sub inventory using the custom_inventory_component.
AddItemDistribute() used in the custom_loadout_device defined above places items in any eligible subinventory. If the player has other subinventories, the item may end up in them. To control this, remove subinventories or write rules inside the OnReceive() function.
See the above diagram for how the custom_inventory_component would be added as a subinventory via the inventory_giver_device.
For more gameplay examples of inventories and how to use the inventory_component, see the tutorials in Custom Items and Inventories with Scene Graph.