The Rusty Barnacle: Inkbeard's NPC behaviour state machine

Student can author npc_behavior Verse with an internal state machine (idle/patrol/chase) and attach it to an NPC spawner.

📖 Reference & full walkthrough: The Rusty Barnacle: Inkbeard's NPC behaviour state machine

🔁 Builds on: west-coves L19 state machine + north-jungle classes

🧩 Your capstone piece: The Kraken hazard NPC: patrols the channel, chases and eliminates straggler racers (support: npc-behavior, npc-spawner-device, verse-npc-custom-behavior, verse-npc-guard-patrol all PASS; spawn-npc FAILS 1 err)

Overview

A state machine is the backbone of believable NPC behavior. Instead of one monolithic script, you divide the NPC's life into discrete states (Idle, Alert, Reset) and define the transitions between them. In UEFN, you wire this up by:

1. Subclassing npc_behavior — Epic's abstract base class for custom NPC logic. Attach it to an NPC Spawner device via a Character Definition asset.
2. Subscribing to trigger_device.TriggeredEvent — so the NPC reacts when a player steps on a pressure plate near the clifftop.
3. Driving a timer_device — to count down the alert window and fire SuccessEvent when time is up, transitioning the NPC back to idle.

When to reach for this pattern:

• You want an NPC that reacts to player proximity or actions.
• You need timed state windows (alert lasts 15 seconds, then resets).
• You want to chain multiple device events without Blueprint spaghetti.

API Reference

npc_behavior

Inherit from this to create a custom NPC behavior. The npc_behavior can be defined for a character in a CharacterDefinition asset, or in a npc_spawner_device.

Full public surface, resolved verbatim from the live Epic digest (Fortnite.digest.verse).

npc_behavior<native><public> := class<abstract>:

trigger_device

Used to relay events to other linked devices.

Full public surface, resolved verbatim from the live Epic digest (Fortnite.digest.verse). Inherited members are merged from trigger_base_device.

trigger_device<public> := class<concrete><final>(trigger_base_device):

Events (subscribe a handler to react):

Methods (call these to make the device act):

timer_device

Provides a way to keep track of the time something has taken, either for scoreboard purposes, or to trigger actions. It can be configured in several ways, either acting as a countdown to an event that is triggered at the end, or as a stopwatch for an action that needs to be completed before a set time runs out.

Full public surface, resolved verbatim from the live Epic digest (Fortnite.digest.verse).

timer_device<public> := class<concrete><final>(creative_device_base):

Events (subscribe a handler to react):

Methods (call these to make the device act):

Walkthrough

The Scene

You have a sun-drenched pirate island. On the clifftop overlooking the lagoon sits Captain Crow, a cel-shaded NPC guard. A pressure-plate trigger_device is hidden under the dock planks. When a player steps on it, Captain Crow enters Alert state and a 15-second timer_device starts counting down. When the timer succeeds (time runs out), Crow returns to Idle. A second trigger fires a cannon-blast VFX to punctuate the alert.

The Verse Device

This is a creative_device (not the npc_behavior subclass itself — see Common Patterns for the behavior class). It lives in your level and wires the trigger + timer together, then calls methods on those devices to drive the state machine.

using { /Fortnite.com/Devices }
using { /Fortnite.com/AI }
using { /Fortnite.com/Characters }
using { /Verse.org/Simulation }

# Pirate lookout state machine — clifftop dock
# Attach this device to your level. Wire:
#   DockTrigger  -> a trigger_device under the dock planks
#   AlertTimer   -> a timer_device set to Count Down, 15 s
#   CannonTrigger -> a trigger_device that fires cannon VFX
piratelookout_device := class(creative_device):

    # The pressure plate hidden under the dock planks
    @editable
    DockTrigger : trigger_device = trigger_device{}

    # 15-second countdown — configure in UEFN as Count Down, 15 s
    @editable
    AlertTimer : timer_device = timer_device{}

    # Fires the cannon-blast VFX device when alert begins
    @editable
    CannonTrigger : trigger_device = trigger_device{}

    # Track alert state so we don't double-start the timer
    var IsAlerted : logic = false

    OnBegin<override>()<suspends> : void =
        # Start with the timer disabled — we enable it on alert
        AlertTimer.Disable()

        # Allow the dock trigger to fire unlimited times
        DockTrigger.SetMaxTriggerCount(0)

        # Subscribe: player steps on dock -> enter Alert state
        DockTrigger.TriggeredEvent.Subscribe(OnDockTriggered)

        # Subscribe: timer runs out -> return to Idle state
        AlertTimer.SuccessEvent.Subscribe(OnAlertExpired)

        # Subscribe: timer enters urgency mode -> flash cannon again
        AlertTimer.StartUrgencyModeEvent.Subscribe(OnUrgencyMode)

    # Called when a player steps on the dock trigger
    OnDockTriggered(MaybeAgent : ?agent) : void =
        if (IsAlerted?):
            # Already alerted, ignore duplicate triggers
        else:
            set IsAlerted = true
            # Fire the cannon VFX trigger (no agent needed)
            CannonTrigger.Trigger()
            # Enable and start the alert countdown
            AlertTimer.Enable()
            AlertTimer.Start()

    # Called when the 15-second alert window expires (SuccessEvent)
    OnAlertExpired(MaybeAgent : ?agent) : void =
        set IsAlerted = false
        # Stop and reset the timer, disable until next alert
        AlertTimer.ResetForAll()
        AlertTimer.Disable()
        # Re-enable the dock trigger for the next patrol cycle
        DockTrigger.Enable()

    # Called when the timer enters urgency mode (last few seconds)
    OnUrgencyMode(MaybeAgent : ?agent) : void =
        # Fire cannon trigger again as a "last warning" visual
        CannonTrigger.Trigger()```

### Line-by-Line Explanation

| Lines | What's happening |
|---|---|
| `@editable` fields | Expose `DockTrigger`, `AlertTimer`, and `CannonTrigger` to the UEFN editor so you can drag-assign placed devices. |
| `var IsAlerted` | A simple boolean gate — prevents re-entering Alert if the player keeps stepping on the trigger. |
| `AlertTimer.Disable()` | Timer starts disabled; we only enable it when the alert fires, preventing accidental auto-start. |
| `DockTrigger.SetMaxTriggerCount(0)` | `0` = unlimited triggers, so the patrol cycle can repeat forever. |
| `.Subscribe(OnDockTriggered)` | Hooks the `listenable(?agent)` event. The handler receives `?agent` (optional). |
| `CannonTrigger.Trigger()` | Fires the cannon VFX trigger with no agent — the no-arg overload is perfect here. |
| `AlertTimer.Enable()` then `AlertTimer.Start()` | Enable must come before Start or the timer ignores the call. |
| `AlertTimer.ResetForAll()` | Resets the countdown back to 15 s for all agents, ready for the next cycle. |
| `OnUrgencyMode` | `StartUrgencyModeEvent` fires when the timer enters its urgency window (configured in UEFN). We fire the cannon again as a dramatic "last warning". |

---

## Common Patterns

### Pattern 1 — Custom `npc_behavior` Subclass (the NPC's own brain)

This is the class you assign in the Character Definition asset. It runs *inside* the NPC and can use `focus_interface` to make Captain Crow stare at the lagoon.

```verse
using { /Fortnite.com/AI }
using { /Fortnite.com/Characters }
using { /Verse.org/Simulation }
using { /UnrealEngine.com/Temporary/SpatialMath }

# Assign this class in the NPC's CharacterDefinition asset
captain_crow_behavior := class(npc_behavior):

    # Called by the engine when the NPC spawns
    OnBegin<override>()<suspends> : void =
        # Get the fort_character for this NPC
        if (Char := GetCharacter[]):
            # Get the focus interface and make Crow stare at the lagoon
            if (Focus := Char.GetFocusInterface[]):
                # MaintainFocus never returns on its own — use race to cancel
                race:
                    # Stare at a fixed lagoon landmark (world coords)
                    Focus.MaintainFocus(vector3{X := 12000.0, Y := -3400.0, Z := 200.0})
                    # After 8 seconds, break the focus (NPC resumes default)
                    block:
                        Sleep(8.0)

Key point: MaintainFocus has the <suspends> effect — it never returns unless canceled. Wrap it in a race block alongside a Sleep or another event so you can break out of it.

Pattern 2 — Timed Alert Window with SetActiveDuration

Dynamically shorten or lengthen the alert window at runtime — useful if the player is carrying a "wanted" item that makes guards more persistent.

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

# Adjusts the alert timer duration based on a "heat level" variable
alert_duration_device := class(creative_device):

    @editable
    AlertTimer : timer_device = timer_device{}

    @editable
    HeatTrigger : trigger_device = trigger_device{}

    # Heat level: 1 = normal (15 s), 2 = hot (30 s)
    var HeatLevel : int = 1

    OnBegin<override>()<suspends> : void =
        HeatTrigger.TriggeredEvent.Subscribe(OnHeatTriggered)
        AlertTimer.SuccessEvent.Subscribe(OnTimerDone)

    OnHeatTriggered(MaybeAgent : ?agent) : void =
        # Unwrap the optional agent
        if (A := MaybeAgent?):
            # High heat: give the player 30 s of alert time
            set HeatLevel = 2
            AlertTimer.SetActiveDuration(30.0, A)
            AlertTimer.Start(A)
        else:
            # No agent (triggered by code): use default 15 s
            AlertTimer.Start()

    OnTimerDone(MaybeAgent : ?agent) : void =
        set HeatLevel = 1
        AlertTimer.ResetForAll()

Key point: SetActiveDuration(Time, Agent) takes a float and an agent — you must unwrap ?agent first. The no-agent Start() overload is used as a fallback when the trigger fires from code.

Pattern 3 — One-Shot Alarm with SetMaxTriggerCount and GetTriggerCountRemaining

The cannon alarm should only fire once per round. After it fires, disable the trigger and show remaining count in debug logic.

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

# One-shot alarm: fires once, then locks out until round reset
oneshot_alarm_device := class(creative_device):

    @editable
    AlarmTrigger : trigger_device = trigger_device{}

    @editable
    ResetTrigger : trigger_device = trigger_device{}

    OnBegin<override>()<suspends> : void =
        # Clamp to exactly 1 trigger per round
        AlarmTrigger.SetMaxTriggerCount(1)
        # Set a 2-second reset delay before it could theoretically re-fire
        AlarmTrigger.SetResetDelay(2.0)
        # Add a 0.5-second transmit delay before linked devices receive the signal
        AlarmTrigger.SetTransmitDelay(0.5)

        AlarmTrigger.TriggeredEvent.Subscribe(OnAlarmFired)
        ResetTrigger.TriggeredEvent.Subscribe(OnRoundReset)

    OnAlarmFired(MaybeAgent : ?agent) : void =
        # Check how many triggers remain (0 = at limit)
        Remaining := AlarmTrigger.GetTriggerCountRemaining()
        if (Remaining = 0):
            # Lock out the alarm for the rest of the round
            AlarmTrigger.Disable()

    OnRoundReset(MaybeAgent : ?agent) : void =
        # Re-arm the alarm for the next round
        AlarmTrigger.SetMaxTriggerCount(1)
        AlarmTrigger.Enable()

Key point: GetTriggerCountRemaining() returns 0 when GetMaxTriggerCount() is unlimited and when the limit has been reached — check GetMaxTriggerCount() first if you need to distinguish the two cases.

Gotchas

1. npc_behavior has no events or methods of its own — override OnBegin

npc_behavior is an <abstract> class with no built-in events. Your entire NPC logic lives in OnBegin<override>()<suspends>:void. Don't try to call methods on npc_behavior directly from a creative_device — you can't. Use GetNPCBehavior() on an agent to retrieve the behavior instance, then cast it to your subclass.

2. MaintainFocus suspends forever — always wrap in race

focus_interface.MaintainFocus has <suspends> and never returns on its own. If you call it bare in OnBegin, your NPC's brain freezes at that line. Always pair it with a Sleep, an event await, or another race branch that can cancel it.

3. ?agent must be unwrapped before use

TriggeredEvent, SuccessEvent, and FailureEvent all deliver ?agent (optional). Calling .SetActiveDuration(Time, MaybeAgent?) directly won't compile. Unwrap first:

if (A := MaybeAgent?):
    AlertTimer.SetActiveDuration(30.0, A)

4. Enable() before Start() — order matters

Calling AlertTimer.Start() on a disabled timer silently does nothing. Always call AlertTimer.Enable() first, then AlertTimer.Start(). Conversely, call AlertTimer.ResetForAll() before AlertTimer.Disable() so the timer is clean when re-enabled.

5. SetMaxTriggerCount clamps to [0, 20]

Values above 20 are silently clamped. Use 0 for unlimited. If you need more than 20 discrete trigger events in a round, manage the count yourself in Verse with a var counter.

6. message parameters need <localizes> — not raw strings

If you ever pass text to a UI device from your state machine, you cannot pass a raw string. Declare a localizable wrapper:

StateLabel<localizes>(S : string) : message = "{S}"

Then pass StateLabel("Alert"). There is no StringToMessage function.

7. int and float don't auto-convert

SetActiveDuration takes a float. Passing an int literal like 30 will fail — write 30.0 explicitly.