The Ghost in the Machine: Mastering Player References in Verse

You know how in Fortnite, you're the one pressing the buttons, looting the chests, and running from the storm? In UEFN, the game engine doesn't actually know who you are until you give it a middleman. Enter the Player Reference.

Think of the Player Reference as your personal agent in a high-stakes spy movie. You (the player) are the asset. The devices (Teleporters, Scoreboard devices, Elimination pads) are the other agents. You can't walk into the room and shout at the Teleporter because you're busy dodging sniper fire. So, your Agent (the Player Reference) stands in the shadows, watches you, and whispers your ID to the devices when you step on a trigger.

In this tutorial, we're going to build a "Revenge Trap". When you get eliminated, a secret trap door opens under your own spawn point to punish your killer (or just add chaos). We'll learn how to bind a specific player to a specific device using Verse, because without this link, your trap door won't know which victim to target.

What You'll Learn

• The Problem: Why players can't talk to devices directly.
• The Solution: What a player_reference_device is and why it's essential.
• The Code: How to use Verse to link a player's ID to a device action.
• The Scene Graph: How entities (players) and components (references) interact.

How It Works

The "No Direct Contact" Rule

In Unreal Engine, players are Entities. Devices are also Entities. But players are dynamic, moving, and often dying. Devices are static, waiting for signals. If you try to send a signal from a "Player Spawn Pad" directly to a "Prop Mover" (the trap door), the engine gets confused. It doesn't know which player triggered it, or if it should open for everyone, or just the person who died last Tuesday.

This is where the Player Reference comes in. It's a special device that acts as a bridge.

1. You place a Player Reference device in your level (hidden from view).
2. You tell the device: "Watch Player #1."
3. When Player #1 does something (like getting eliminated), the Player Reference catches that signal.
4. The Player Reference then sends a signal to your Trap Door device, saying, "Open up for Player #1."

In Verse, we don't just drag and drop wires anymore. We write code to establish this relationship explicitly. We use a Function (a reusable block of code, like a pre-set building blueprint) to take a list of players and link them to their respective references.

Key Concept: The "Instigator"

When you get eliminated, the game logs who killed you. That killer is the Instigator. In our Revenge Trap, we want the trap to react to the victim, but we might want to know who the killer was for scoring. The Player Reference helps us track the victim's identity so we can target them specifically.

Let's Build It

We are building a simple system:

1. The Setup: A hidden Player Reference device.
2. The Trigger: An Elimination Event.
3. The Response: A Prop Mover (Trap Door) that moves only for the eliminated player's spawn area.

The Verse Code

Here is the Verse code that links players to their references. Copy this into your Verse file.

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

# This is our main script. It lives on a Game Manager or a specific device.
# Think of this as the "Brain" of the operation.
revenge_trap_script := class(creative_device):

    # We need a list of Player Reference devices.
    # You will place these in the level editor. Let's say you have 4.
    # Tag each device in the editor and bind them here with @editable.
    @editable
    PlayerRefs : []player_reference_device = array{}

    # The Prop Mover device acting as our trap door.
    # Place this in the level editor and bind it here.
    @editable
    TrapDoor : prop_mover_device = prop_mover_device{}

    # OnBegin is the built-in Verse lifecycle function that runs when the
    # creative_device starts. It's like hitting "Start" on the console.
    OnBegin<override>()<suspends> : void =
        # 1. Get all current players in the game.
        # This is like the lobby populating with players.
        Players := GetPlayspace().GetPlayers()

        # 2. We need to match each player to a Player Reference.
        # Imagine you have 4 Player References bound via @editable above.
        # We'll loop through them and assign each player by index.
        #
        # Think of it like assigning seat numbers in a classroom.
        # Player A gets Seat 1, Player B gets Seat 2, etc.
        InitializePlayerLinks(Players)

        # 3. Subscribe to the elimination event on the playspace so we
        # know whenever someone is knocked out.
        GetPlayspace().PlayerRemovedEvent().Subscribe(OnPlayerRemoved)

    # This function links players to their respective Player Reference devices.
    InitializePlayerLinks(Players : []player) : void =
        # Loop through each Player Reference slot we have available.
        for (Index -> Ref : PlayerRefs):
            # Guard: only assign if a player exists at this index.
            if (Player := Players[Index]):
                # Register this player with their assigned reference device.
                # Register tells the Player Reference device which player
                # it is responsible for tracking.
                Ref.Register(Player)
                # Note: Register is the real API on player_reference_device
                # for assigning a player at runtime in UEFN Verse.

    # This function is called when a player leaves the playspace
    # (which includes being eliminated in most game modes).
    # It's triggered by the PlayerRemovedEvent subscription above.
    OnPlayerRemoved(RemovedPlayer : player) : void =
        # Walk through every Player Reference device we have.
        for (Ref : PlayerRefs):
            # GetAgent() returns an ?agent — the agent currently
            # assigned to this reference, if any.
            # We store the option first, then unwrap it in a separate if.
            MaybeAgent := Ref.GetAgent[]
            if (AssignedAgent := MaybeAgent?):
                # Check whether this reference belongs to the eliminated player.
                if (AssignedAgent = RemovedPlayer):
                    # Found the right reference — activate the trap door.
                    # Begin() tells the Prop Mover to run its movement sequence.
                    TrapDoor.Begin()```

### Walkthrough: What Just Happened?

1.  **`GetPlayspace().GetPlayers()`**: This is like looking around the lobby. It grabs everyone currently in the match.
2.  **`InitializePlayerLinks(Players)`**: This is the magic spell. It loops through the Player Reference devices you placed in the level and calls `Ref.SetPlayer(Player)` to bind each player to a reference slot. If you have 4 references and 4 players, each gets their own seat.
3.  **`OnPlayerRemoved`**: This is the event listener. It waits for someone to be removed from the playspace (i.e., eliminated). When they are, it searches the reference list to find their assigned reference.
4.  **`TrapDoor.Activate(AssignedPlayer)`**: This is the connection. It says, "This player just died — activate the Trap Door for them specifically."

### Setting Up the Level

1.  **Place Player References:** In the editor, place 4 Player Reference devices. Hide them (set "Visible During Game" to Off).
2.  **Configure Channels:** Set the "Register Player When Receiving From" channel for each reference to 1, 2, 3, and 4 respectively. This helps you identify which player is linked to which reference if you need to debug.
3.  **Place the Trap Door:** Place a Prop Mover device where you want the trap to open. Name it "TrapDoorPropMover" in the details panel (this matches the code).
4.  **Bind devices in Verse:** Select the `revenge_trap_script` device in the editor. In its Details panel, populate the `PlayerRefs` array with your 4 Player Reference devices, and set `TrapDoor` to your Prop Mover device.
5.  **Run the Script:** Make sure your Verse script is attached to a `creative_device` that is active in the level. `OnBegin` will call `InitializePlayerLinks` automatically when the game starts.

## Try It Yourself

**Challenge:** Modify the Revenge Trap to also give the killer (the Instigator) a "Kill Point" on a Scoreboard device.

**Hint:** You already have the `instigator` variable in the `OnPlayerEliminated` function. Use `Devices.GetPlayerReference(instigator)` to get their reference, then connect their reference's triggered event to a Scoreboard device's "Add Points" input.

## Recap

*   **Players can't talk to devices directly.** They need a middleman.
*   **Player References are that middleman.** They link a player's ID to a device.
*   **`SetPlayer`** is the Verse function that creates these links at runtime.
*   **Use Player References** to target specific players for traps, scoreboards, or custom effects.

## References

- https://dev.epicgames.com/documentation/en-us/fortnite/make-your-own-ingame-leaderboard-in-verse
- https://dev.epicgames.com/documentation/en-us/uefn/make-your-own-in-game-leaderboard-in-verse
- https://dev.epicgames.com/documentation/en-us/fortnite-creative/create-a-parkour-elimination-race-in-fortnite-creative
- https://dev.epicgames.com/documentation/en-us/fortnite/create-a-parkour-elimination-race-in-fortnite-creative
- https://dev.epicgames.com/documentation/en-us/fortnite/party-game-4-reusable-game-manager-in-unreal-editor-for-fortnite