How to Talk to Your NPC: Getting the Agent in Verse

So you've spawned a bot in Fortnite. It's standing there. It looks cool. But right now, it's about as responsive as a statue in a lobby. You want to tell it to heal you, shoot that guy, or just stand still and look menacing. To do any of that, you need to know who you're talking to.

In Verse, every NPC is an Agent. Think of an Agent like a player's connection to the game server. Just as you have a unique ID when you jump out of the Battle Bus, every NPC has an Agent ID that lets Verse track its health, position, and inventory. If you don't "Get" the Agent, you're trying to send a text to a phone number that doesn't exist.

In this tutorial, we're going to build a simple "Boss Health Bar" system. We'll learn how to grab the NPC's Agent ID so we can monitor its HP in real-time. No abstract math, just straight-up boss battle mechanics.

What You'll Learn

• The Agent Concept: What an Agent is and why it's the NPC's "player profile."
• GetAgent[]: The specific Verse command to grab that profile.
• Behavior Context: Why this command only works inside specific NPC scripts.
• Real-Time Tracking: Using the Agent to pull live data (like HP) for a UI display.

How It Works

The Agent vs. The Model

In Fortnite, you have a character model (the mesh you see) and your player state (your health, shield, XP, and inventory). In Verse, the Agent is the data layer. It's the invisible "ghost" that holds all the numbers. The 3D model is just a puppet; the Agent is the puppeteer.

Why Can't I Just Call It?

You might think you can just say MyBoss.GetAgent() from anywhere in your code. But Verse is strict about context. An NPC doesn't know it's an NPC unless it's inside its own Behavior.

Think of a Behavior like a specific mission objective. If you're in the "Heal Teammate" behavior, you know who you are. If you're in the "Shoot Enemies" behavior, you know who you are. But if you're standing in the middle of the map as a generic script, you don't have a specific NPC identity yet.

The function GetAgent[] is like asking, "Who am I right now?" It only works if you are currently inside the NPC's specific Behavior script. It's like asking a soldier, "Who is your commander?" The soldier knows. A random civilian on the street doesn't.

The Syntax

The code is deceptively simple:

MyAgent := GetAgent[]

Let's break that down like it's a loot drop:

1. MyAgent: This is a Variable. A variable is just a labeled box where you store information so you can use it later. Here, we're storing the NPC's identity in a box named MyAgent.
2. :=: This is the Assignment Operator. It's the arrow that says "Put this thing into that box."
3. GetAgent[]: This is the Function. A function is a pre-built tool that does a specific job. GetAgent does one job: it looks at the current NPC context and returns its Agent ID. The [] means it doesn't need any extra input (arguments) to work. It just works.

Let's Build It

We're going to create a simple NPC Behavior that prints the Agent's ID to the debug console every time the NPC takes damage. This proves we can "talk" to the NPC.

Prerequisites:

1. Create an NPC in UEFN.
2. Add a Behavior component to it.
3. Open the Verse script attached to that Behavior.

Here is the code. Copy this into your script.

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

# This is our main script structure.
# Think of this as the "Brain" of the NPC.
MyBehavior := class(npc_behavior):

    # This function runs automatically when the NPC starts.
    # It's like the "Start of Match" screen.
    OnBegin<override>()<suspends>:void=
        # STEP 1: GET THE AGENT
        # We ask the NPC: "Who are you?"
        # This grabs the unique ID for this specific NPC instance.
        # GetAgent[] can fail, so it must be called inside a failure context (if).
        if (BossAgent := GetAgent[]):

            # Let's verify we got it by printing to the debug console.
            # GetAgent[] returns an agent interface value; Print accepts any.
            Print("Boss NPC behavior has started and Agent is live.")

            # STEP 2: MONITOR DAMAGE IN A LOOP
            # Cast the Agent to fort_character so we can access health events.
            # fort_character is the real interface for Fortnite character stats.
            if (BossCharacter := BossAgent.GetFortCharacter[]):
                # Subscribe to the damage taken event on the fort_character.
                BossCharacter.DamagedEvent().Subscribe(OnTakeDamage)
                # Keep this behavior alive so the subscription stays active.
                loop:
                    Sleep(1.0)

    # STEP 3: HANDLE DAMAGE
    # This function is called by DamagedEvent every time the NPC takes damage.
    # damage_result carries info about the hit (amount, instigator, etc.).
    OnTakeDamage(Result:damage_result):void=
        # Get the Agent so we can identify which NPC was hurt.
        if (BossAgent := GetAgent[]):
            # Cast to fort_character to read live health data.
            # fort_character exposes GetHealth() for current HP.
            if (BossCharacter := BossAgent.GetFortCharacter[]):
                CurrentHP := BossCharacter.GetHealth()
                Print("Ouch! Boss took damage and now has {CurrentHP} HP left.")```

### Walkthrough of the Code

1.  **`using { /Fortnite.com/AI }`**:
    This is like loading a specific DLC pack. The `AI` module contains all the tools needed to talk to NPCs. Without this line, Verse doesn't know what an `npc_behavior` is. It's like trying to build a wall without having the "Building" tool enabled.

2.  **`using { /Fortnite.com/Characters }`**:
    This second module unlocks `fort_character`, the interface that exposes live health and damage data. You need both modules working together — `AI` gives you the Agent, and `Characters` lets you read its stats.

3.  **`OnBegin<override>()`**:
    This is the **Event**. An event is something that happens in the game world that tells your code to wake up. `OnBegin` happens when the NPC spawns into the world. It's the equivalent of the "Welcome to the Island" voice line.

4.  **`BossAgent := GetAgent[]`**:
    This is the core lesson. We are calling `GetAgent[]` inside `OnBegin`. Why? Because `OnBegin` is part of the NPC's Behavior. The NPC knows who it is at this moment. We store the result in `BossAgent`.

5.  **`BossAgent.GetFortCharacter[]`**:
    `GetAgent[]` returns a generic `agent`. To read HP or subscribe to damage events, we must cast it to `fort_character` using `GetFortCharacter[]`. The `if` block handles the case where the cast fails safely, so your game never crashes.

6.  **`BossCharacter.DamagedEvent().Subscribe(OnTakeDamage)`**:
    `DamagedEvent()` fires every time the character receives a hit. `.Subscribe()` hooks our `OnTakeDamage` function to that event, so it runs automatically on every hit without a polling loop.

7.  **`BossCharacter.GetHealth()`**:
    Once we have the `fort_character`, we can use dot notation (`.`) to ask it questions. `GetHealth()` returns the current HP as a `float`. This is how you link the NPC's state to your UI or logic.

## Try It Yourself

Now that you can grab the Agent, let's make it useful.

**Challenge:**
Modify the code above to change the NPC's color when it takes damage. You'll need to:
1.  Get the Agent.
2.  Use the Agent to get the NPC's **Owner** (the physical mesh/model).
3.  Change the material color of that model.

*Hint:* You'll need to look up how to get the `Owner` from an Agent. It's like getting the "Puppet" from the "Puppeteer." Once you have the Owner, you can use `SetMaterialColor` on it. Don't worry if you don't know the exact function name yet—check the UEFN documentation for "Material" functions. The key is that you must start with `GetAgent[]` to ensure you're talking to the right NPC.

## Recap

-   **Agent** is the NPC's data identity, similar to a player's profile.
-   **`GetAgent[]`** is the function to retrieve that identity.
-   You can only use `GetAgent[]` inside an **NPC Behavior** because the NPC needs to know its own context.
-   Once you have the Agent, you can access health, position, and other stats to create dynamic gameplay.

## References

-   https://dev.epicgames.com/documentation/fortnite/verse-starter-07-final-result-in-unreal-editor-for-fortnite
-   https://dev.epicgames.com/documentation/fortnite/verse-starter-01-creating-the-npc-behavior-in-unreal-editor-for-fortnite
-   https://dev.epicgames.com/documentation/en-us/fortnite/create-your-own-npc-medic-in-unreal-editor-for-fortnite
-   https://dev.epicgames.com/documentation/en-us/fortnite/positioning-widgets-on-the-screen-in-unreal-editor-for-fortnite
-   https://dev.epicgames.com/documentation/fortnite/verse-api/fortnitedotcom/ai/npc_behavior/getagent