Interaction Payloads

Documentation Unreal Engine Player Combat Interaction

An interaction option's Payload is what the character does when it runs: walk up to the chest, play the opening, and tell the chest the frame the lid lifts. A dodge can break out of it.

Set it up

10 minutes
  1. 1

    Make the chest

    Create a Blueprint Actor BP_Chest with a collision mesh, and tick Replicates. Add an Arrow where the character should stand, pointing at the chest, with OpenSpot in its Component Tags, then UPC Interactable.
    Components
    + Add
    BP_Chest (Self)
    Static Mesh
    Add
    Arrow
    Add
    UPC Interactable
    Add
    The arrow marks the spot and its facing.
  2. 2

    Add the Open option

    Add an Options element: Option Id Open, Verb Open, Name Chest. Set Payload to Play Montage with the demo's AM_UPC_ChestOpen, which already carries the commit notify on the frame the hands lift the lid, and Approach, Spot Component Tag to OpenSpot.
    Details
    UPC Interactable
    UPC
    Interactable
    Options
    1 Array element
    Index [ 0 ]
    Option Id
    Open
    Activation Input Tag
    UPC.Input.Interact
    Prompt
    Verb
    Open
    Name
    Chest
    Icon
    None
    Payload (Optional)
    Play Montage
    Montage
    AM_UPC_ChestOpen
    Play Rate
    1.0
    Section Name
    None
    Approach
    Spot Component Tag
    OpenSpot
    Acceptance Radius
    0.0
    Override Timeout
    Restrictions
    Cancel by Ability
    Priority
    0
    Enabled
    Anchor Component Tag
    None
    Anchor Socket
    None
    The character walks onto the component tagged OpenSpot, plays the montage, and the chest hears On Option Interacted at the montage's commit notify.
  3. 3

    Open the lid when it lands

    Add a Boolean IsOpen set to RepNotify. Set it true from On Option Interacted (server) and swing the lid in OnRep_IsOpen so every player sees it.
  4. 4

    Press Play

    Press E beside the chest: the character walks onto the arrow, turns, plays the opening, and the lid swings as the hands lift it.

Pick a payload kind

KindDoes, and lands
(empty)Nothing on the character; lands at once.
Play MontagePlays Montage at Play Rate from Section Name; lands at its commit notify, else as it blends out.
DelayWaits Delay Seconds (0.5), for a search with no animation.
Trigger Ability / EventSends a gameplay event to the character, or activates its abilities carrying Ability Tags; lands straight after.
Run AbilityHands the option to an ability of the character's: no walk, no restrictions, no On Option Interacted.
Payload AssetRuns an Action Payload asset, a reusable Blueprint object; lands at a commit notify, else when it finishes.
World Item PickupThe reach every world item's Pick Up row carries (Pickups, Drops and Holders); lands as the hand closes.
The Interactor skips a row missing what its kind needs; the actor's other rows still show. Every kind but empty and Run Ability plays through the Interactor's Payload Ability Class, which the interaction module grants on its own.

The moment it lands

An option commits on the frame it takes effect. Mark it with a UPC Gameplay Event notify whose Event Tag is UPC.Event.Interaction.Commit: the actor's On Option Interacted fires once, on the server, and the Interactor fires On Interaction Committed.
AM_MyChestOpen
0.0
0.25
0.5
0.75
1.0
1.25
1.5
1.75
2.0
Notifies
UPC Gameplay Event: UPC.Event.Interaction.Commit
Chest
hands reach the lid
lid opens (On Option Interacted)
A montage of your own; the times are an example.
An option cut short before its commit runs nothing, and the actor hears On Option Cancelled. A cut after the commit changes nothing: On Option Interacted has run and On Option Cancelled does not follow.

Walk onto a spot first

Name a tagged scene component in the option's Approach, Spot Component Tag: the character walks onto it at its own speed, turns the way it points, then plays the payload.
Details
UPC Interactable
Options [0]
Approach
Spot Component Tag
OpenSpot
Acceptance Radius
0.0
Override Timeout
Advanced
Mode
Move and Face
Restrictions
Lock Movement
Lock Facing
Lock Camera
End Running Action
The defaults: walk onto the spot and turn to its facing, then hold movement and facing and end any running attack for as long as the interaction runs. The camera stays free.
SettingDoes
Spot Component TagThe component to stand on; empty plays where the character stands.
Acceptance RadiusHow close counts as arrived; 0 uses the Interactor's Approach Acceptance Radius (5 cm).
Override Timeout, TimeoutThis option's patience, in place of the Interactor's Approach Timeout (0, no limit).
Mode (Advanced)Move and Face, Face Only (turn in place, for a lever) or Move Only.
The Interactor's Approach Acceptance Angle (5 degrees; Move Only ignores it) and Approach Stall Seconds (2, ending a walk into a wall) apply too. Giving up cancels with Could Not Reach. The walk uses the character's UPC Attack Approach and Character Movement components, both on the character base.

What the character gives up while it runs

Restrictions hold from the moment the server confirms the option until it ends, the walk included.
SettingDefaultDoes
End Running ActionOnEnds the swing playing as the option starts. Off, that swing finishes.
Lock MovementOnStops the player walking it.
Lock FacingOnKeeps the facing the walk left. Needs UPC Attack Approach.
Lock CameraOffStops the player turning the camera.
The character also holds UPC.State.Interacting and UPC.State.ActionsBlocked while the option runs, which drops combat presses.

Let a dodge break out

The dodge has to be a gameplay ability granted on its own key (Input), since UPC.State.ActionsBlocked shuts the action graph, dodge move included. The demo's GA_UPC_Dash (Demo/Abilities) is set up this way; no demo ability set grants it. Three edits:
  1. The ability. In its Class Defaults, add UPC.Ability.Interaction to Cancel Abilities with Tag (what it ends as it starts) and keep UPC.State.ActionsBlocked out of Activation Blocked Tags (what stops it starting).
  2. The ability set. Add a row to the character's ability set naming GA_UPC_Dash, with the dodge's Input Tag and Input Action.
  3. The action graph. The graph answers a key before a granted ability, so delete its transition on the dodge's Input Tag (or give the ability another tag), or the graph's dodge takes the press.
Cancel by Ability on the option, on by default, allows the break. Off, the option also ignores Cancel All Abilities, such as a call a game makes on death.
Undo a half-done job in On Option Cancelled. Its Reason:
ReasonWhen
Cancelled By AbilityA dodge, stagger or hit reaction took over.
Approach SupersededSomething else steered the character before it arrived.
InterruptedThe animation stopped, or the action ended early.
LostThe character or actor went away, the actor stopped allowing the option, or the ability left.
Could Not ReachThe walk gave up.

Answer per character

A door the character pulls from one side and pushes from the other implements the UPC Interaction Option Provider interface (Class Settings, Interfaces). Each function gets the option's own setting as Authored and returns true with a replacement, or false to keep Authored; a function you leave unimplemented returns false.
FunctionThe door answers
Get Interaction ApproachReturn true and Authored copied with Spot Component Tag set to the near side's tag, so Acceptance Radius and Mode stay as authored.
Get Interaction PayloadA Play Montage of the pull or the push. Payload holds any payload kind, so wrap it: Make Play Montage into Make Instanced Struct, into Payload.
Get Interaction RestrictionsWhat this character may still do.
They run once as the option starts, so a trace is fine, and cannot change actor variables; the option's events carry the answered row.
An answer must run through the same ability as the authored row's kind, or the authored row plays and a warning logs:
Authored rowAnswers it accepts
Any kind but empty and Run AbilityAny of those kinds (a pull montage answered with a push montage)
Run AbilityA Run Ability naming the same ability
EmptyEmpty

A payload of your own

  1. Make a Blueprint Class of UPCActionPayload named BP_SearchShelf and override Execute. Its Host pin is the ability running the payload: drag off it for Play Montage, Play Delay or Get Payload Target Actor (the actor). Return what Play Montage or Play Delay returns: true keeps the run going until that montage or wait ends, and the end lands the option. False ends the run and lands it at once.
  2. Right-click in the Content Browser, UPC, Actions, Action Payload, pick BP_SearchShelf and name it PA_SearchShelf.
  3. Set the option's Payload to Payload Asset with that asset.
BP_SearchShelf · Execute: search for 2 seconds, then the option lands
Execute
Host
Play Delay
Target
Seconds2.0
Return Value
Return Node
Return Value
Details
UPC Interactable
Options [0]
Payload (Optional)
Payload Asset
Payload
PA_SearchShelf
Runs an Action Payload asset from the Content Browser, such as a Blueprint payload of your own.
Every option using the asset shares that one object, so keep no per-run state in its variables.

Hand the option to an ability

Run Ability passes the option to an ability the character has.
Details
UPC Interactable
Options [0]
Payload (Optional)
Run Ability
Ability
None
Event Tag
None
The named ability takes the option from here.
  1. Grant the ability once, in the character's ability set (Input).
  2. In its Class Defaults, set Net Execution Policy to Server Initiated or Server Only; any other makes the row invalid. Set Net Security Policy to Server Only, or Data Validation warns.
  3. Implement Activate Ability From Event. The plugin starts the ability itself with Event Tag (UPC.Event.Interaction when empty), so it needs no trigger of its own; the event's Target is the actor, and Get Interaction Option Id on the event's Target Data names the option the player chose.

Debug it

Log LogUPCInteraction Verbose says why a walk gave up or an actor refused its commit; Interaction covers the overlay.
AdvancedHow a run goes
The server confirms the optionA cancel at any stop skips to the end
1
Take what the option asks for
Restrictions
A running attack ends (End Running Action), and walking, facing and the camera are held as the Restrictions say. The character reports On Interaction Started.
2
Walk onto the spot
Approach
With a Spot Component Tag, the character walks onto that component at its own speed and turns to its facing. Without one, the payload runs where the character stands.
3
Check again on arrival
Can Interact on the interactable
After a walk, the interactable is asked Can Interact once more, and the server checks the character is still in reach. A no cancels the run with Lost. With no walk, this step is skipped.
4
Play the payload
Play Montage, Delay, Trigger Ability / Event, Payload Asset
The montage plays, the delay runs, the event is sent or the payload asset runs, on the server and on the player's own machine.
5
Commit
a UPC Gameplay Event notify on UPC.Event.Interaction.Commit, or the payload's end
The interactable hears On Option Interacted, once, on the server. The character reports On Interaction Committed. A montage with no commit notify commits as it starts blending out.
6
End
On Interaction Ended, On Option Cancelled
The holds come off and the character reports On Interaction Ended. A run that ended before its commit tells the interactable On Option Cancelled with the reason instead.
A dodge naming UPC.Ability.Interaction in Cancel Abilities with Tag, a montage that is stopped, or a walk that gives up all end the run early; before the commit, nothing commits.
  • On arrival, Can Interact runs again and the server checks reach: within Detection Radius of the actor, or on the spot, plus the arrival radius and 0.3 s of walking. A no cancels with Lost; Face Only skips it.
  • A character another approach steers, such as an attack glide, cancels with Approach Superseded.
  • An actor destroyed before the commit cancels with Lost; after it, the run lands.
  • Lock Movement and Lock Camera reach a possessed character only.
  • A payload ability whose Asset Tags lose UPC.Ability.Interaction warns, since no dodge can then break its interactions.
The demo
BP_UPC_Chest (Open, Break) and BP_UPC_Door (Open, Kick) set a replicated variable on the server and play it in its RepNotify. BP_UPC_Door answers all three per-character functions, from the side the character stands on.
MultiplayerWhat runs where
Only the server starts, abandons or commits a payload, and its end is final. The player's machine plays the walk and montage from its own copy of the actor, with no payload sent.
  • The player's own movement walks the character, so the walk is predicted; a client copy that loses its option or montage ends alone.
  • Per-character answers run on each machine, so read shared state such as positions; in a door's hinge plane the machines can pick different sides.
  • A dodge the server refuses, after the player's machine cancelled, leaves the player cancelled while the server commits.
  • The server judges a remote player's arrival on each move, and accepts one at rest after walking toward the spot within the widened reach.
C++C++
  • A payload kind derives from FUPCInteractionPayloadSpec (a USTRUCT with a DisplayName), overriding IsDefinitionValid, ResolveExecutionAbilityClass, GetExecutionTriggerTag, CanStart and BuildPayload. Build it with InitializeAs<FYourSpec>(); TInstancedStruct::Make given a derived value keeps only the base.
  • A native payload derives from UUPCActionPayload, overriding Execute(UUPCPayloadHostAbility& Host) and optionally CanStart and CollectPreloadAssets; GetActionGraph() is null in an interaction.
  • IUPCInteractionOptionProvider uses GetInteractionApproach_Implementation, GetInteractionRestrictions_Implementation and GetInteractionPayload_Implementation (an FInstancedStruct holding an FUPCInteractionPayloadSpec). UUPCInteractionPayloadAbility::GetInteractable and GetOption read the running option.
  • A Run Ability's event carries the Option Id in its target data: UUPCInteractionStatics::GetInteractionOptionId(EventData.TargetData) reads it, and FGameplayAbilityTargetData_UPCInteraction::Find(EventData.TargetData) returns the actor and OptionId.
AdvancedTroubleshooting
LogFix
"... built nothing to run"Fill in the payload.
"... names approach spot tag '...', but no scene component on the actor carries it"Tag the component, or clear the field.
"... has no Character Movement component to walk with"Add one, or set Mode to Face Only.
"... has no Attack Approach component to hold it"Add UPC Attack Approach.