player_reference_device: Tracking and Storing Player Agents

Overview

The player_reference_device acts as a dynamic pointer to an agent, allowing you to store, track, and trigger game logic based on a specific player's state. It is essential for mechanics like VIP modes, capture-the-flag carriers, or targeted ability tracking. By subscribing to its events, you can react instantly when the tracked player changes, fails to update, or triggers an activation state.

API Reference

API Reference

(API surface could not be resolved for this device.)

Walkthrough

In this scenario, we are building a "VIP Escort" game mode. The player_reference_device tracks the current VIP. When any player steps on the ExtractionZone (a trigger_device), we call Activate() on the reference device, which ends the round/game (signaling a win condition). We also listen to the reference device's events to track when the VIP is assigned, replaced, or if an update fails.

vip_manager_device := class(creative_device):
    @editable
    VIPReference : player_reference_device = player_reference_device{}
    
    @editable
    ExtractionZone : trigger_device = trigger_device{}

    OnBegin<override>()<suspends>:void =
        ExtractionZone.TriggeredEvent.Subscribe(OnExtraction)
        VIPReference.AgentUpdatedEvent.Subscribe(OnVIPUpdated)
        VIPReference.AgentReplacedEvent.Subscribe(OnVIPReplaced)
        VIPReference.AgentUpdateFailsEvent.Subscribe(OnVIPUpdateFailed)

    OnExtraction(Agent : ?agent):void =
        if (Agent?):
            # Ends the round/game when the extraction zone is triggered
            VIPReference.Activate()

    OnVIPUpdated(Agent : agent):void =
        Print("A new VIP has been assigned!")

    OnVIPReplaced(Agent : agent):void =
        Print("The VIP has been replaced!")

    OnVIPUpdateFailed(Agent : agent):void =
        Print("VIP Update Failed!")

Line-by-Line Explanation

• @editable Fields: We declare VIPReference and ExtractionZone as class fields so they can be linked in the UEFN editor.
• OnBegin: We subscribe to the TriggeredEvent of the trigger device, and the three core agent-tracking events of the player_reference_device.
• OnExtraction: The trigger_device passes an optional ?agent. We unwrap it with if (Agent?): before calling VIPReference.Activate(), which ends the game.
• Event Handlers: AgentUpdatedEvent, AgentReplacedEvent, and AgentUpdateFailsEvent all pass a guaranteed agent (not optional), so our handlers accept Agent : agent directly without needing an unwrap block.

Common patterns

Listening for Activation

If you want to trigger logic when the tracked player activates an objective, subscribe to ActivatedEvent.

activation_tracker_device := class(creative_device):
    @editable
    TargetPlayer : player_reference_device = player_reference_device{}

    OnBegin<override>()<suspends>:void =
        TargetPlayer.ActivatedEvent.Subscribe(OnPlayerActivated)

    OnPlayerActivated(Agent : agent):void =
        Print("The tracked player activated the objective!")

Handling Assignment Failures

When building complex team logic, an agent update might fail (e.g., if the target left the game). Always handle AgentUpdateFailsEvent to prevent broken game states.

vip_assignment_device := class(creative_device):
    @editable
    VIPSlot : player_reference_device = player_reference_device{}

    OnBegin<override>()<suspends>:void =
        VIPSlot.AgentUpdateFailsEvent.Subscribe(OnAssignmentFailed)

    OnAssignmentFailed(Agent : agent):void =
        Print("Failed to assign the VIP role to the agent.")

Gotchas

• Activate() Ends the Game: According to the device's API surface, calling Activate() on the player_reference_device ends the round/game. Do not use it if you merely want to trigger a generic event; use a standard trigger_device instead.
• Agent vs ?agent: Events like AgentUpdatedEvent pass a guaranteed agent, whereas trigger_device.TriggeredEvent passes an optional ?agent. Always match the exact signature in your handler methods to avoid compile errors.
• Updating the Reference: The Verse API for player_reference_device exposes events for when the agent changes, but the actual assignment of the agent is typically handled via UEFN editor pin connections or external game logic rather than a direct Verse method.