Safe Array Access in Verse: Bounds Checking

What you'll learn

How array indexing in Verse is a failable expression that lives in a failure context, and how the if (Value := Arr[Index]): idiom unifies bounds-checking and access into one safe step. You'll also wire the result into a player's HUD with GetPlayerUI[] and a real text_block widget.

How it works

In most languages you write if (index < length) and then access the array — two separate steps that can drift apart. In Verse, Arr[Index] is itself fallible: it must appear inside a failure context (an if/for condition, a <decides> body, etc.). If the index is valid the access succeeds and binds the value; if it's out of bounds the access fails and control moves to the else branch.

The idiomatic pattern:

if (Value := Arr[Index]):
    # Value is bound and valid here
else:
    # Index was out of bounds

Because the check and the access are the same operation, they can never become inconsistent. Note that text_block, GetPlayerUI, and AddWidget come from /UnrealEngine.com/Temporary/UI, and GetPlayerUI[...] is itself failable, so we bind it in the same if.

Let's build it

This device holds a list of messages. When a player interacts with the trigger, we attempt to read the message at TargetIndex. A valid index shows the message in the HUD; an invalid one shows a safe fallback instead of crashing.

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

# Demonstrates Verse's safe, failable array access driving real player UI.
safe_array_device := class<concrete>(creative_device):

    # The list we will index into.
    Messages : []string = array{"Hello", "Verse", "Island", "Guide"}

    # Try setting this to 10 in the Details panel to trigger the fallback branch.
    @editable TargetIndex : int = 0

    # Drag a trigger device here in the editor.
    @editable Trigger : trigger_device = trigger_device{}

    OnBegin<override>()<suspends>: void =
        # TriggeredEvent sends ?agent (the player may be unknown).
        Trigger.TriggeredEvent.Subscribe(OnTriggered)

    # Handler must match the listenable(?agent) payload.
    OnTriggered(MaybeAgent : ?agent): void =
        # Unwrap the option, then fetch the player's UI (also failable).
        if (Agent := MaybeAgent?, Player := player[Agent], PlayerUI := GetPlayerUI[Player]):
            # SAFE ARRAY ACCESS: bind the element only if the index exists.
            if (Msg := Messages[TargetIndex]):
                # Valid index: show the real message in the HUD.
                PlayerUI.AddWidget(text_block{DefaultText := StringToMessage(Msg)})
                Print("Safe access at {TargetIndex}: {Msg}")
            else:
                # Out of bounds: show a fallback instead of crashing.
                PlayerUI.AddWidget(text_block{DefaultText := StringToMessage("Index out of bounds!")})
                Print("Index {TargetIndex} out of bounds — showed fallback.")

    # Helper to turn a string into a message for the widget.
    StringToMessage<localizes>(Value : string) : message = "{Value}"```

## Try it yourself

1. Place a **Trigger** device and a **Verse device** in your level, then assign the trigger to the `Trigger` field.
2. Build and push your Verse code, then play the island and step on the trigger — index 0 shows `"Hello"`.
3. Change `TargetIndex` to `2` (shows `"Island"`) and re-test.
4. Set `TargetIndex` to `10` and trigger again — instead of crashing you'll see `"Index out of bounds!"`, proving the failure branch works.

## Recap

Array indexing in Verse is a failable expression, so it must live in a failure context like an `if` condition. The `if (Value := Arr[Index]):` idiom does bounds-checking and access in one inseparable step, eliminating an entire class of off-by-one bugs. We combined it with `GetPlayerUI[]` and `AddWidget` to turn safe data access into real on-screen feedback.