Verse Tags

With Verse tags, you can find objects (both Creative devices and entities) marked with a specific tag while the game is running. Verse tags let you work with multiple objects without needing to set up properties and assign references in Unreal Editor for Fortnite (UEFN). You can create Verse tags in Verse code, and add or remove them from objects either in UEFN using the UI, or programmatically in more Verse code.

Some examples of what you can do with Verse tags:

• Alter the level setup without having to add or modify device references to your Verse-authored device.

• Find all objects with a specific tag and operate them based on their type, such as turn on lights or toggle barriers.

• Dynamically change which objects are active as the player progresses through the game.

• Conditionally enable objects for an obstacle run based on a player-selected difficulty option.

What Can Be Tagged?

Currently, you can assign Verse tags to the following objects, in the indicated context:

• In-editor only

  • Props

  • Devices

  • Verse-authored devices

• In-editor and at runtime

  • Entities

The following sections show how to create and work with Verse tags in your project.

Creating a Verse Tag

Follow these steps to create a new Verse tag using Verse:

1. Open your Verse file in Visual Studio Code with Verse Explorer.

2. At the top of your Verse file, add the following code to enable referencing the tag class.

   Verse

   using { /Verse.org/Simulation/Tags }

   Copy full snippet(1 line long)

   There is a Verse tag template you can use to create your own tags.

3. Create a new class that inherits from the tag class. The name of your class determines the name of the tag. In this example, the class is named mytag, so the Verse tag's name is mytag.

   Verse

   # Derive from the `tag` class in the Verse.org/Simulation/Tags module to create a new gameplay tag.
   mytag := class(tag){}

   Copy full snippet(2 lines long)

4. Your Verse file should look like this:

   Verse

   using { /Verse.org/Simulation }
   using { /Verse.org/Simulation/Tags }
   		
   # Derive from the `tag` class in the Verse.org/Simulation/Tags module to create a new gameplay tag.
   mytag := class(tag){}

   Copy full snippet(5 lines long)

5. Save your Verse file and click Compile Verse in the UEFN toolbar to compile your code so you can use your new Verse tag.

Verse tags are hierarchical by virtue of their class inheritance structure. These tags can have any number of hierarchical levels. While the names are arbitrary, we recommend using a consistent naming convention to help you organize your tags and their hierarchy.

For example, in the following code snippet, any object having a banana_tag is also classified as having a fruit_tag.

# Tag definitions
using { /Verse.org/Simulation }
using { /Verse.org/Simulation/Tags }

fruit_tag<public> := class(tag){}
apple_tag<public> := class(fruit_tag){}
banana_tag<public> := class(fruit_tag){}

Assigning a Verse Tag in the Editor

Follow these steps to assign a Verse tag in the UEFN editor. This example uses a creative device. For Scene Graph entities, see below.

1. In UEFN in the Outliner, select the device that you want to tag to open its Details panel. In this example, the device is a Button device.

   

2. In the Details panel, click Add New Component and choose Verse Tag Markup from the dropdown.

   

3. Select the VerseTagMarkup component to view its settings in the Details panel.

   

4. Under Tags, edit the Tags property and add your Verse tag. In this example, mytag is added to the device.

   

   Remember you can build a hierarchy of tags set up for classification by inheritance, as shown at the start of this section.

You can add multiple tags to the same object, so it will be discovered by a search for any of those tags. When you have an object with multiple tags, you can find the object using any tag it has. For example, if you create tags named mytag1 and mytag2 then assign both of them to one object, you can find the object when calling either  FindCreativeObjectsWithTag(mytag1)  or FindCreativeObjectsWithTag(mytag2).

Assigning a Verse Tag to Entities

Assigning a Verse tag to an entity in the UEFN editor functions similarly, but there are some differences.

1. Select the entity you want to assign a Verse tag to, and in the Details panel click Edit Tags.

   

2. From there, you can add your Verse tag directly, and manipulate your tags in a similar way to how you can for a Creative device.

Assigning a Verse Tag Using Verse Code

When coding with Verse, you can assign Verse tags directly to Scene Graph entities, without using the UEFN editor UI. The following code snippets demonstrate how to assign Verse tags.

This example uses the following hierarchical tags, defined in Verse.

#Tag definitions
using { /Verse.org/SceneGraph }
using { /Verse.org/Simulation/Tags }

vehicle_tag := class<abstract>(tag){}
motorcycle_tag := class<abstract>(vehicle_tag){}
ducati_tag := class(motorcycle_tag){}
triumph_tag := class(motorcycle_tag){}

color_tag :=  class<abstract>(tag){}

To check whether an entity already has a defined tag, you can adapt the following code snippet.

# An example of how to check if an entity has any tags
ExampleContains():void =
    MotorcycleEntity := entity{}
    MotorcycleEntity.AddTag(ducati_tag{})
    if:
        MotorcycleEntity.ContainsTag[tag]
    then:
        Print("The entity has at least one tag")

To assign these tags to an example Scene Graph entity, you can adapt the following code snippets.

# Example 1 for adding tags and checking their existence. 
ExampleAddTag1():void =
    MotorcycleEntity := entity{}
    MotorcycleEntity.AddTag(ducati_tag{})
    MotorcycleEntity.AddTag(red_tag{})

    if:
        MotorcycleEntity.ContainsTag[ducati_tag]
        MotorcycleEntity.ContainsTag[red_tag]
    then:

You can also add and remove tags using Verse code, as broadly or as narrowly as you choose, as shown in the following examples.

# Example 1 of adding and removing tags, and checking their existence. 
ExampleAddRemoveTag1():void =
    MotorcycleEntity := entity{}
    MotorcycleEntity.AddTag(ducati_tag{})
    MotorcycleEntity.AddTag(red_tag{})

    if:
        MotorcycleEntity.ContainsAllTags[vehicle_tag, red_tag]
    then:
        Print("The entity is a red vehcile.")

Finding Creative Objects with a Verse Tag

Once you have Creative objects with Verse tags assigned, you can find them by Verse tag during a game using the Verse function FindCreativeObjectsWithTag(). In the following example, calling FindCreativeObjectsWithTag(mytag) results in TaggedDevices containing all the objects that have mytag assigned to them:

using { /Fortnite.com/Devices }
using { /Verse.org/Simulation }
using { /Verse.org/Simulation/Tags }

FindCreativeObjectsWithTagExample1(InDevice:creative_device):void =
    TaggedObjects := InDevice.FindCreativeObjectsWithTag(mytag)

The FindCreativeObjectsWithTag() function call returns an array of all objects that implement creative_object_interface. For example, if you assign mytag to both a Button device and a Customizable Light device in your level, then this function call returns both devices.

You can convert the result of FindCreativeObjectsWithTag() to one of its implementing classes (called type casting) using the syntax NewObjectReference := object_type_to_cast_to[ObjectReference], where object_type_to_cast_to is the object type you want. For example, if you want to turn a Customizable Light device off or on, you must convert the result to customizable_light_device before calling the function TurnOff() or TurnOn().

When working with tags set up in a hierarchy, the results vary according to where the tag you find is in the hierarchy. Continuing with the fruit example shown before, the following expression returns only objects tagged with banana_tag:

using { /Fortnite.com/Devices }
using { /Verse.org/Simulation }
using { /Verse.org/Simulation/Tags }

FindCreativeObjectsWithTagExample2(InDevice:creative_device):void =
    TaggedObjects := InDevice.FindCreativeObjectsWithTag(banana_tag)

By contrast, the following expression also returns objects with either banana_tag or apple_tag, as those tags are defined as also having fruit_tag by their classification in the hierarchy.

using { /Fortnite.com/Devices }
using { /Verse.org/Simulation }
using { /Verse.org/Simulation/Tags }

FindCreativeObjectsWithTageExample2(InDevice:creative_device):void =
    TaggedObjects := InDevice.FindCreativeObjectsWithTag(fruit_tag)

With for expressions, you can use failable expressions as a filter and create new variables to use in the for code block. For example, you can add the type conversion of customizable_light_device to the iteration expression in for. Since the device will be converted to customizable_light_device, you'll be able to use the functions specific to that class, such as TurnOff() to turn the light off.

using { /Fortnite.com/Devices }
using { /Verse.org/Simulation }
using { /Verse.org/Simulation/Tags }

FindCreativeObjectsWithTagExample3(InDevice:creative_device):void =
    TaggedObjects := InDevice.FindCreativeObjectsWithTag(mytag)
    
    for (TaggedObject : TaggedObjects, LightDevice := customizable_light_device[TaggedObject]):
        LightDevice.TurnOff()

The following example shows how to conditionally check the type of the object and call different functions based on the type. The example checks if the tagged object is a Customizable Light device that can call TurnOff() to turn the light off, or if the object is a Barrier device that can call Disable() to turn it off.

using { /Fortnite.com/Devices }
using { /Verse.org/Simulation }
using { /Verse.org/Simulation/Tags }

FindCreativeObjectsWithTagExample4(InDevice:creative_device):void =
    TaggedObjects := InDevice.FindCreativeObjectsWithTag(mytag)

    for (TaggedObject : TaggedObjects):
        if (LightDevice := customizable_light_device[TaggedObject]):
            # If the tagged object is a Customizable Light device, turn it off

When calling FindCreativeObjectsWithTag(), the resulting list has an arbitrary order created by the system that isn't modifiable by any method you can use or affect ahead of time. In cases where you add or remove objects between calls to FindCreativeObjectsWithTag() using the same tag, the resulting list might be in a different order for each call result.

Finding Position By Type with Verse Tags

Here is an example of how to filter the objects returned from FindCreativeObjectsWithTag() by type and print their position.

using { /Fortnite.com/Devices }
using { /Verse.org/Simulation }
using { /Verse.org/Simulation/Tags }
using { /Verse.org/SpatialMath }

FindCreativeObjectsWithTagExample5(InDevice:creative_device):void =
    # find all objects with the all_tag
    AllCreativeObjects := InDevice.FindCreativeObjectsWithTag(all_tag)

    # Print the position of all creative_prop objects with the all_tag

Finding Scene Graph Entities with a Verse Tag

Finding scene graph entities with Verse tags is similar to finding Creative objects, but uses different functions called from the Verse API:

• FindDescendantEntitiesWithTag, which inclusively finds all descendant entities of the target that have the specified tag.

• FindAncestorEntitiesWithTag, which inclusively finds all ancestor entities of the target that have the specified tag.

Remember that you must add your entity to a hierarchy to find it using these functions. If you have a stand-alone entity with a tag, it will not be discovered by these functions.

Here's an example of finding hierarchical Verse tags, using the motorcycle example demonstrated previously.

# Example 1 of setting up an entity hierarchy of tagged entities and finding them. 
ExampleFindDescendantEntitiesWithTag1(InEntity:entity):void =
    MotorcycleEntity1 := entity{}
    MotorcycleEntity1.AddTag(ducati_tag{})
    MotorcycleEntity1.AddTag(red_tag{})
    MotorcycleEntity1.AddTag(black_tag{})

    MotorcycleEntity2 := entity{}
    MotorcycleEntity2.AddTag(triumph_tag{})
    MotorcycleEntity2.AddTag(black_tag{})

Exploring Tutorials That Use Verse Tags

The following tutorials show how to use Verse Tags in a game.

• 

  Tagged Lights Puzzle

  Create a puzzle where the player has to find the right combination of lights on and off to spawn an item, using a device created with Verse.