UEFN Verse: Fortnite.digest

In this article, I'll show you how to use the Fortnite.digest file to look up information about the functions and events of the creative devices that are available for use with Verse.

In Visual Studio Code, in your UEFN project Explorer, you'll notice that there are a few ".digest.verse" files. These files are generated during a Fortnite build and should not be modified manually. They serve as a reference to see what is available in the Verse API.

The Fortnite.digest file is the most up-to-date documentation for creative devices in UEFN/Verse. When a new creative device is made available in Verse, it may not yet be in the web documentation, but it will definitely be in Fortnite.digest.

In your UEFN/Verse project, if you Ctrl+click on the name of a creative device class, Visual Studio Code will open Fortnite.digest where the class is defined. In the image below, I clicked on the timer_device class.

Another option is to search directly in the Fortnite.digest file. For example, if you see a creative device that you have in the UEFN editor and want to know what the equivalent Verse class is. In Visual Studio Code, open Fortnite.digest and press F3 to open the search box. The class name follows the pattern name_device.

The image below shows part of the timer_device class. Here we can see the events available to subscribe a function. The events have :listenable and the required parameter is in parentheses. In addition to the events, we have the Enable, Disable and Reset functions that allow the Timer to be controlled using Verse code.

For example, SuccessEvent is an event that receives a ?agent (optional agent) as a parameter. So we need to create a function that receives a ?agent as a parameter to be able to subscribe to the SuccessEvent.

If you don't know how to subscribe a function in an event, see my article UEFN Verse: Functions.

Also, If you don't know how to call the functions of a class, I recommend my other article UEFN Verse: Classes and Instances.

Not all creative device features that appear in the UEFN editor are available for Verse. The Fortnite.digest file is a quick way to look up what's available for Verse within Visual Studio Code.

Table of Contents Verse

UEFN Verse: Fortnite.digest (pt-BR)

Neste artigo vou mostrar como usar o arquivo Fortnite.digest para buscar informações sobre as funções e eventos dos dispositivos criativos que estão disponíveis para serem usados com Verse.

No Visual Studio Code, no Explorer do seu projeto UEFN, veja que existem alguns arquivos ".digest.verse". Esses arquivos são gerados durante uma build do Fortnite e não devem ser modificados manualmente. Eles servem como uma referência para vermos o que está disponível na Verse API.

O arquivo Fortnite.digest é a documentação mais atualizada que existe dos dispositivos criativos no UEFN/Verse. Quando um novo dispositivo criativo é disponibilizado em Verse, pode ser que ele ainda não esteja na documentação web, mas com certeza ele estará no Fortnite.digest.

No seu projeto UEFN/Verse, se você pressionar a tecla Ctrl e clicar no nome de uma classe de dispositivo criativo, o Visual Studio Code vai abrir o Fortnite.digest no local onde a classe é definida. Na imagem abaixo eu cliquei na classe timer_device.

Outra opção é pesquisar direto no arquivo Fortnite.digest. Por exemplo, quando você ver um dispositivo criativo que tem no editor UEFN e quer saber qual é a classe Verse equivalente. No Visual Studio Code, abra o Fortnite.digest e pressione F3 para abrir a caixa de pesquisa. O nome da classe segue o padrão nome_device.

A imagem abaixo mostra uma parte da classe timer_device. Aqui podemos ver os eventos disponíveis para registrarmos uma função. Os eventos possuem :listenable e entre parênteses está o parâmetro necessário. Além dos eventos, temos as funções Enable, Disable e Reset que permite o controle do Timer usando código Verse.

Por exemplo, SuccessEvent é um evento que recebe como parâmetro um ?agent (agent opcional). Então precisamos criar uma função que receba como parâmetro um ?agent para poder registrar no SuccessEvent.

Se você não sabe como registrar uma função em um evento, veja o meu artigo UEFN Verse: Funções.

Caso você não saiba como chamar as funções de uma classe eu recomendo o meu outro artigo UEFN Verse: Classes e Instâncias.

Nem todos os recursos de um dispositivo criativo que aparecem no editor UEFN estão disponível para a linguagem Verse. O arquivo Fortnite.digest é um local onde você pode pesquisar rapidamente direto no Visual Studio Code o que está disponível para Verse.

Sumário Verse  

UEFN Verse: Map

A Map allows the storage of key->value pairs. This is used to make associations between values. The example below creates a Map variable using string for the key type and int (integer) for the value type.

var HealthItemSizes : [string]int = map{"small" => 25, "medium" => 50, "big" => 75, "mega" => 100}

To get a value associated with a key in a Map, use the key inside [] as shown in the example below. Accessing a value in a Map is a failable expression.

if(Points := HealthItemSizes["medium"]):
    Print("The medium Health Item recovers {Points} health points.")

You can add elements to a Map variable using set with a new key. If the key used already exists in the Map, the value associated with this key will be updated.

if(set HealthItemSizes["ultra"] = 150):
    Print("Size ultra added to the map.")

The number of elements in a Map can be accessed using the Length property.

Print("Number of elements in the Map: {HealthItemSizes.Length}")

The For loop can be used to iterate through the elements of a Map as shown in the following example. At each iteration of the For loop, the key and value of an element in the Map are stored in local constants.

for (Key->Value : HealthItemSizes):
    Print("Size: {Key} | Points: {Value}")

Let's create a device in UEFN to demonstrate these Map concepts. In any UEFN project, open Verse Explorer, right-click on the project name and choose the Add new Verse file to project option.

In Device Name put map_device and click the Create Empty button.

Copy the Verse code below into the map_device file:

using { /Fortnite.com/Devices }
using { /Verse.org/Simulation }
using { /UnrealEngine.com/Temporary/Diagnostics }

map_device := class(creative_device):

    @editable
    HealthExtended : logic = true

    var HealthItemSizes : [string]int = map{"small" => 25, "medium" => 50, "big" => 75, "mega" => 100}

    OnBegin<override>()<suspends>:void=

        if(HealthExtended?):        
            if(set HealthItemSizes["ultra"] = 150, set HealthItemSizes["monster"] = 200):
                Print("Health Extended elements added to the map.")
            
        Print("The medium Health Item recovers {GetHealthItemPoints("medium")} health points.")
        
        Print("------- MAP CONTENTS -------")

        for (Key->Value : HealthItemSizes):
            Print("Size: {Key} | Points: {Value}")

        Print("Number of elements in the Map: {HealthItemSizes.Length}")

    GetHealthItemPoints(Size:string):int=

        if(Points := HealthItemSizes[Size]):
            Points
        else:
            0

    # The return keyword is optional. The function returns the result of the last executed expression.

The HealthExtended constant can be edited in the UEFN editor. It is being used to add other elements to the Map.

Save the file and compile the Verse code using the Verse > Build Verse Code option from the UEFN menu.

Access the Content Drawer and add our map_device to the level.

Click the Launch Session button located in the UEFN toolbar to load the level into Fortnite. 

After starting the session in Fortnite, press the Tab key and select the Log tab to view the log with the messages written by the Print functions.

Table of Contents Verse

UEFN Verse: Map (pt-BR)

Um Map permite o armazenado de pares chave->valor. Isto é usado para fazer associação entre valores. O exemplo abaixo cria uma variável Map usando string para o tipo da chave e int (inteiro) para o tipo do valor.

var HealthItemSizes : [string]int = map{"small" => 25, "medium" => 50, "big" => 75, "mega" => 100}

Para consultar um valor associado a uma chave no Map, use a chave dentro de []  como mostra o exemplo abaixo. O acesso a um valor em um Map é uma expressão falível.

if(Points := HealthItemSizes["medium"]):
    Print("The medium Health Item recovers {Points} health points.")

Você pode adicionar elementos em uma variável Map usando o set com uma nova chave. Se a chave usada já existir no Map, o valor associada a esta chave será atualizado.

if(set HealthItemSizes["ultra"] = 150):
    Print("Size ultra added to the map.")

A quantidade de elementos de um Map pode ser acessada usando a propriedade Length.

Print("Number of elements in the Map: {HealthItemSizes.Length}")

O laço For pode ser utilizado para percorrer os elementos de um Map como mostra o exemplo a seguir. A cada iteração do laço For, a chave e o valor de um elemento do Map são armazenados em Key e Value.

for (Key->Value : HealthItemSizes):
    Print("Size: {Key} | Points: {Value}")

Vamos criar um dispositivo no UEFN para mostrar estes conceitos do Map. Em qualquer projeto UEFN, abra o Verse Explorer, clique com o botão-direito no nome do projeto e escolha a opção Add new Verse file to project.

Em Device Name coloque map_device e clique no botão Create Empty.

Copie o código Verse abaixo para o dispositivo map_device:

using { /Fortnite.com/Devices }
using { /Verse.org/Simulation }
using { /UnrealEngine.com/Temporary/Diagnostics }

map_device := class(creative_device):

    @editable
    HealthExtended : logic = true

    var HealthItemSizes : [string]int = map{"small" => 25, "medium" => 50, "big" => 75, "mega" => 100}

    OnBegin<override>()<suspends>:void=

        if(HealthExtended?):        
            if(set HealthItemSizes["ultra"] = 150, set HealthItemSizes["monster"] = 200):
                Print("Health Extended elements added to the map.")
            
        Print("The medium Health Item recovers {GetHealthItemPoints("medium")} health points.")
        
        Print("------- MAP CONTENTS -------")

        for (Key->Value : HealthItemSizes):
            Print("Size: {Key} | Points: {Value}")

        Print("Number of elements in the Map: {HealthItemSizes.Length}")

    GetHealthItemPoints(Size:string):int=

        if(Points := HealthItemSizes[Size]):
            Points
        else:
            0

    # O comando return é opcional. A função retorna o resultado da última expressão executada.

A constante HealthExtended pode ser editada no editor do UEFN. Ela está sendo usada para adicionar outros elementos no Map.

Salve o arquivo e compile o código Verse usando a opção Verse > Build Verse Code do menu do UEFN. 

Acesse o Content Drawer e adicione o nosso dispositivo Verse map_device ao nível. 

Clique no botão Launch Session localizado na barra de ferramentas do UEFN para carregar o nível no Fortnite. 

Após iniciar a partida no Fortnite, pressione a tecla Tab e selecione a aba Registro para visualizar o log com as mensagens escritas pelas funções Print.

Sumário Verse 

UEFN Verse: Option

In the Verse language there is a type called Option that allows a variable to have a value or be empty.

An Option is defined by using "?" in front of the type. The line below defines a variable called MaybeGrade which is an Option of integer type.

var MaybeGrade : ?int = false

The false indicates this Option is empty. It is common to start the name of Option type variables with Maybe because it already indicates that it can have a value or be empty.

You might be thinking that we could have just used the value 0 in the variable to indicate that it has no value. However, this can be confusing. How do we know if the value 0 indicates that a grade has not yet been assigned or if the grade value was actually 0. 

The following code shows how to assign a value to an Option:

set MaybeGrade = option{ 8 }

Inside the { } you can have any type of expression. If the expression fails, the Option will be false indicating that it is empty.

To access the value stored in an Option, you must use the ? operator within a failable context (such as if).

if (Grade := MaybeGrade?):
    Print("Grade = {Grade}")

The Print will only be executed if MaybeGrade has a value.

Let's create a device in UEFN with an example of using Option. This example will simulate a challenge. Imagine an obstacle course. The agents (players) have a limited amount of time to overcome the obstacles and press a button. 

We'll use an Option variable named MaybeBestAgent to store the first agent who presses the button. If no agent presses the button before the timer runs out, the Option MaybeBestAgent will remain empty.

In any UEFN project, open Verse Explorer, right-click on the project name and choose the Add new Verse file to project option.

In Device Name put option_device and click the Create Empty button.

Copy the Verse code below into the option_device file:

using { /Fortnite.com/Devices }
using { /Verse.org/Simulation }
using { /UnrealEngine.com/Temporary/Diagnostics }

option_device := class(creative_device):

    var MaybeBestAgent : ?agent = false

    @editable
    Button : button_device = button_device{}

    @editable
    TimerDevice : timer_device = timer_device{}

    @editable
    ScoreManagerDevice : score_manager_device = score_manager_device{}
    
    OnBegin<override>()<suspends>:void=

        Button.InteractedWithEvent.Subscribe(ButtonPressed)
        
        TimerDevice.SuccessEvent.Subscribe(HandleTimerFinished)

    ButtonPressed(Agent:agent):void=    

        # Stores the first agent to press the button
        if ( not MaybeBestAgent? ):
            set MaybeBestAgent = option{ Agent }

    HandleTimerFinished(MaybeAgent:?agent):void=
    
    # Checks if any agent managed to press the button before the timer ends
        if(BestAgent := MaybeBestAgent?):
            ScoreManagerDevice.Activate(BestAgent)
        else:
            Print("Nobody won the challenge!")

The button_device, timer_device and score_manager_device are being used. 

The ButtonPressed() function will be executed when an agent presses the button_device. It will store the agent if the Option MaybeBestAgent is empty.

The HandleTimerFinished() function will be executed when the Timer ends. If the Option MaybeBestAgent has an agent, he will receive a score.

Save the file and compile the Verse code using the Verse > Build Verse Code option from the UEFN menu.

Access the Content Drawer and add our option_device to the level. Also add the button_device, timer_device, and score_manager_device. Remember, we are just simulating the challenge. 

Select the Score Manager in the level. In the Details tab, set the Score Value that the winner of the challenge will receive.

Select the Timer Device in the level. In the Details tab, set the Duration in seconds of the timer. Check Start at Game Start to start the Timer automatically.

Finally select our Option Device in the level. In the Details tab add the references for the devices we are going to use.

Save the level and click the Launch Session button to load the level into Fortnite. You can press the button to receive your score or wait for the timer to finish and see a message that nobody won the challenge.

Table of Contents Verse

UEFN Verse: Option (pt-BR)

Na linguagem Verse existe um tipo chamado Option que permite que uma variável tenha um valor ou fique vazia.

Um Option é definido usando "?" na frente do tipo. A linha abaixo define uma variável chamada MaybeGrade que é um Option do tipo inteiro.

var MaybeGrade : ?int = false

O valor false indica que o Option está vazio. É comum iniciar o nome das variáveis do tipo Option com Maybe porque já indica que ela pode ter um valor ou estar vazia.

Você pode estar pensando que poderíamos ter apenas usado o valor 0 na variável para indicar que ela não tem valor. Entretanto isso pode confundir. Como vamos saber se o valor 0 indica que uma nota (grade) ainda não foi atribuída ou se o valor da nota foi realmente 0. 

O código a seguir mostra como atribuir um valor a um Option:

set MaybeGrade = option{ 8 }

Dentro do { } pode ter qualquer tipo de expressão. Se a expressão falhar, o Option ficará com false indicando que está vazio.

Para acessar o valor armazenado em um Option, é preciso usar o operador ? dentro de um contexto de falha (como o if).

if (Grade := MaybeGrade?):
    Print("Grade = {Grade}")

O Print só será executado se MaybeGrade tiver um valor.

Vamos criar um dispositivo no UEFN com um exemplo de uso do Option. Este exemplo irá simular um desafio. Imagine uma corrida de obstáculos. Os agentes (jogadores) tem um tempo limitado para superar os obstáculos e pressionar um botão. 

Usaremos uma variável Option com o nome MaybeBestAgent para guardar o primeiro agente que conseguir pressionar o botão. Se nenhum agente conseguir pressionar o botão antes do tempo acabar, o Option MaybeBestAgent continuará vazio.

Em qualquer projeto UEFN, abra o Verse Explorer, clique com o botão-direito no nome do projeto e escolha a opção Add new Verse file to project.

Em Device Name coloque option_device e clique no botão Create Empty.

Copie o código Verse abaixo para o dispositivo option_device:

using { /Fortnite.com/Devices }
using { /Verse.org/Simulation }
using { /UnrealEngine.com/Temporary/Diagnostics }

option_device := class(creative_device):

    var MaybeBestAgent : ?agent = false

    @editable
    Button : button_device = button_device{}

    @editable
    TimerDevice : timer_device = timer_device{}

    @editable
    ScoreManagerDevice : score_manager_device = score_manager_device{}
    
    OnBegin<override>()<suspends>:void=

        Button.InteractedWithEvent.Subscribe(ButtonPressed)
        
        TimerDevice.SuccessEvent.Subscribe(HandleTimerFinished)

    ButtonPressed(Agent:agent):void=    

        # Guarda o primeiro agente que pressionar o botão
        if ( not MaybeBestAgent? ):
            set MaybeBestAgent = option{ Agent }

    HandleTimerFinished(MaybeAgent:?agent):void=
    
    # Verifica se algum agente conseguiu pressionar o botão antes do tempo acabar
        if(BestAgent := MaybeBestAgent?):
            ScoreManagerDevice.Activate(BestAgent)
        else:
            Print("Ninguém venceu o desafio!")

Estão sendo usados os dispositivos button_device, timer_device e score_manager_device. 

A função ButtonPressed() será executada quando um agente pressionar o button_device. Ela irá guardar o agente se o Option MaybeBestAgent ainda estiver vazio. 

A função HandleTimerFinished() será executada quanto o Timer terminar a contagem. Se o Option MaybeBestAgent possuir um agente, ele receberá uma pontuação.

Salve o arquivo e compile o código Verse usando a opção Verse > Build Verse Code do menu do UEFN. 

Acesse o Content Drawer e adicione o nosso dispositivo Verse option_device ao nível. Adicione também os dispositivos button_device, timer_device e score_manager_device. Lembre-se que estamos apenas simulando o desafio.  

Selecione o Score Manager no nível. Na aba Details defina o Score Value que o vencedor do desafio irá receber.

Selecione o Timer Device no nível. Na aba Details defina o tempo em segundos do timer na variável Duration. Marque o checkbox do Start at Game Start para iniciar o Timer automaticamente.

Por último selecione o nosso Option Device no nível. Na aba Details adicione as referências para os dispositivos que vamos usar.

Salve o nível e clique no botão Launch Session para carregar o nível no Fortnite. Você pode pressionar o botão para receber a pontuação ou aguardar o Timer finalizar para ver a mensagem de que ninguém venceu o desafio.

Sumário Verse 

UEFN Verse: For loop

The For loop is used to repeat a block of code a specified number of times.

The code below is a very simple example of using the For loop to write the numbers from 1 to 5 on the screen.

for ( Number := 1..5 ):
    Print("{Number}")

The expression Number := 1..5 is a generator that creates a sequence of integers that starts at 1 and ends at 5. The number of values in the sequence will determine the number of times the For loop will execute the code block. For each execution, the current value of the sequence will be stored in Number to be used in the For code block.

The For loop is often used to iterate through the elements of an Array. The following example writes to the screen all the elements of an Array of integers.

Values : []int = array{4,2,9,6,3}
for ( X : Values ):
    Print("{X}")

At each iteration of the For loop, one of the elements of the Array is stored in X.

It is possible to know the index of the Array element that is being used in the current iteration of the For loop as shown in this code:

Values : []int = array{4,2,9,6,3}
for ( X->Y: Values ):
    Print("Index = {X}, Value = {Y}")

Let's create a device in UEFN to show different ways of using the For loop. Our device has 3 main features:

• Turns on or off a group of lamps;
• Calculates the factorial of a number;
• Finds the index of the largest value stored in an array;

In any UEFN project, open Verse Explorer, right-click on the project name and choose the Add new Verse file to project option.

In Device Name put for_device and click the Create Empty button.

Copy the Verse code below into the for_device file:

using { /Fortnite.com/Devices }
using { /Verse.org/Simulation }
using { /UnrealEngine.com/Temporary/Diagnostics }

for_device := class(creative_device):

    @editable
    FactorialValue : int = 8

    @editable
    ArrayOfIntegers : []int = array{4,2,9,6,3}

    @editable
    LampsArray : []customizable_light_device = array{}

    @editable
    Sensor : volume_device = volume_device{}

    OnBegin<override>()<suspends>:void=

        Sensor.AgentEntersEvent.Subscribe(TurnOnLamps)

        Sensor.AgentExitsEvent.Subscribe(TurnOffLamps)
        
        FactorialResult := CalculateFactorial( FactorialValue )
        Print("Factorial of {FactorialValue} is {FactorialResult}")

        IndexResult := IndexOfHighestValue(ArrayOfIntegers)
        Print("Index of the highest value of the array: {IndexResult}")

    TurnOnLamps(Agent:agent):void=
        for (CurrentLamp : LampsArray):
            CurrentLamp.TurnOn()

    TurnOffLamps(Agent:agent):void=
        for (CurrentLamp : LampsArray):
            CurrentLamp.TurnOff()

    CalculateFactorial(Number:int):int=

        var FactorialResult : int = 1

        for (X := 1..Number):
            set FactorialResult = FactorialResult * X

        return FactorialResult

    IndexOfHighestValue(ValuesArray: []int):int=

        var IndexHighest : int = 0
        var HighestValue : int = 0 

        for ( CurrentIndex -> Value : ValuesArray):
            if( Value > HighestValue ):
                set HighestValue = Value
                set IndexHighest = CurrentIndex 

        return IndexHighest

A Volume Device is being used to detect when an Agent (the player) enters or exits a volume. The lights are turned on when entering the volume and turned off when exiting the volume.

The CalculateFactorial and IndexOfHighestValue functions show other ways to use the For loop.

Save the file and compile the Verse code using the Verse > Build Verse Code option from the UEFN menu.

Access the Content Drawer and add our for_device to the level. We will need 4 customizable_light_device and a Volume Device. Place the Volume Device near the customizable_light_device to make it easier to see.

Select the for_device in the level. In the Details tab, add the elements to the LampsArray and select the reference to the Volume Device that will be used as the Sensor. You can also change the default values ​​that are being used in the FactorialValue constant and the ArrayOfIntegers array.

Save the level and click the Launch Session button to load the level into Fortnite. Move your character to the location of the Volume Device to turn on the lights, then move away to turn them off.

Press the Tab key and select the Log tab to view the log with the messages written by the CalculateFactorial and IndexOfHighestValue functions.

Table of Contents Verse