Stackable Component

The stackable_component is a Scene Graph component which can add stacking functionality to a Scene Graph entity. For how to add a component to your entity, see Working with Entities and Components.

Class Description

In your inventory, sometimes you will want entities to form stacks. This could be individual coins forming a stack of currency, or multiple applications of a status effect forming stacks on the target. Stacking provides a way to multiply the effect of an entity without managing many instances of the same object.

Stacking functionality is commonly used with items in inventories. Stacking provides a way for items to be consumed multiple times and reduces clutter when UI space is at a premium.

The stackable_component can be added to an entity and provides a way to merge with other compatible entities (forming stacks), or to split a single entity into multiple ones. Compatibility is determined by the stackable_component and ensures that entities do not merge with each other unless certain conditions are met.

A stackable_component has several important fields. StackSize and MaxStackSize indicate the current amount in the component stack, and the maximum number of items that may be contained by this component. 

For more information refer to the stackable_component API reference from the Verse API.

Example

Inside the Prefab Editor the basic_stackable_component is available to use in entity prefab definitions. The component field, split_prefab_type, requires that you create a new prefab when the stack is split. Therefore, when a prefab has a stackable_component and its entity is split, a new entity of that prefab type is created with the required number of stacks on its basic_stackable_component.

You can set split_prefab_type to StackablePrefab which determines what is created when the stack is split.

Verse: Stacking

Using Verse you can create custom behavior with a stackable_component. There are several overrideable methods that affect how stacks are formed and split:

• CanMergeInto[] can be overridden to control which types of entity can merge with this one.

• Split[] is used to remove stacks from a stackable_component and to transfer that amount to a new entity instance.

Verse: Example

In this example, you will create a prefab that can stack with itself and be split into new instances of itself. Then you will create a Verse device that gets all instances of the Prefab and tries to merge them together.

Begin by creating the prefab:

1. Right-click in the content browser to open the context menu, select Entity Prefab. This creates a new EntityPrefabDefinition. A thumbnail for the Entity Prefab appears in the content browser.

   

2. Rename the Entity Prefab thumbnail, Prefab_Brick.

   

3. Create a new Verse file to create a new stackable_component. You will override two methods:

   • CanMergeInto[] is overridden to control which entities can merge with the owner of the component. 

   • Split[] is overridden to handle how new entities are created if the stack is split. 

   Verse

   # Copyright Epic Games, Inc. All Rights Reserved.
   
   
   using { /Fortnite.com/Devices }
   using { /Verse.org/SceneGraph }
   using { /Verse.org/SpatialMath }
   
   
   # Entities with a brick_stackable_component will stack with other entities that have the component.
   # When split, they will form a new entity of the split_brick_prefab type.
   
   Expand code Copy full snippet(39 lines long)

4. Add a new component to the prefab, and add a mesh_component to give it a physical presence in the world.

   

   The SM_Box mesh used is a 1m x 1m Cube with the pivot centred in the bottom face. This provides a way for the mesh to scale usefully with the example device shown below. Be sure to adjust the MaxStackSize.

   Refer to the Mesh Component for more information about adding a mesh_component to an entity.

5. Add instances of this prefab to the world, either by dragging from the content browser or by creating them through Verse. However they will not merge together without a specific function call.

   Below is an example creative device script that attempts to merge all entities with the brick_stackable_component. You can add it below your component script.  

   Verse

   # This device will gather all entities in the Simulation with a brick_stackable_component.
   # It will then try to merge them all into stacks.
   brick_stacking_device := class(creative_device):
   
   
       OnBegin<override>()<suspends>:void =
           if (SimEntity := GetSimulationEntity[]):
               BrickComponents:[]stackable_component = for(Comp:SimEntity.FindDescendantComponents(brick_stackable_component)){Comp}
               var CurrentStack : ?stackable_component = false
   
   
   Expand code Copy full snippet(35 lines long)

   Currently a bug prevents the stack from being removed from the scene and requires additional code to check the StackSize against the MaxStackSize.

   See the Fortnite Release Notes for more information about bugs and fixes.

6. Drag the brick_stacking_device and 15 Prefab_Brick entities into the scene.

   

7. Select Launch Session in the Editor toolbar to playtest your project.

When playtesting the project, the 15 Prefab_Brick entities merge into 3 stacks, each with a StackSize of 5 on their brick_stackable_component.