Interaction system
The interaction system is implemented in the PulseAbility module and centered around:
UPulseInteractAbilityUPulseAbilityTask_QueryInteractablesUPulseAbilityTask_ManageInteractablesIPulseInteractableInterfaceUPulseInteractableComponent
Since 2.0 interactables also describe themselves for prompts (GetInteractionInfo), can require holding the input, can be locked by conditions (tag query, cooldown, items) and cost something (items, stamina), and the module PulseInteractUI has a ready prompt widget. See Prompts, holding, conditions and costs.
Main runtime flow
At runtime, UPulseInteractAbility does the following:
- Activates locally and starts manage/query tasks (
BeginQueryInteractables). Interactables that are already in range when it activates are found right away. - Query task detects focused interactables (sphere/component overlap or trace).
- Manage task keeps a list of focused interactables and selects one by priority.
- Ability exposes focus/selection/interaction events.
StartInteraction()andEndInteraction()call interface events on the selected target.
Core methods in UPulseInteractAbility:
ActivateAbility(...)BeginQueryInteractables()NewInteractableFocused(...)InteractableFocusLost(...)InteractableSelected(...)StartInteraction()EndInteraction()
Query modes
EPulseInteractQueryType supports three query strategies:
BySphereByComponentByTrace
BySphere
- Creates a transient
USphereComponenton the interactor actor. - Uses overlap begin/end events to add/remove interactables.
- Uses
SphereQueryRadiusandSphereQueryCollisionSettings.
ByComponent
- Uses existing primitive components on the interactor.
- Components are discovered by tag:
Pulse.Ability.Interact.InteractableComponent
- Components must generate overlaps.
ByTrace
- Performs periodic trace queries using
FPulseTraceParams. - Supports sync and async trace (
bAsyncTrace). - Start/end is provided by a trace location provider (
UPulseTraceLocationProvider).
Supported provider classes include:
UPulseTraceLocationProvider_DefaultUPulseTraceLocationProvider_PawnUPulseTraceLocationProvider_CameraUPulseInteractTraceLocationProvider_BP
Focus, selection, and interaction semantics
Focused interactables
Query task stores currently focused actors/components and emits:
OnInteractableFound/OnInteractableLostinterface callbacks- ability-side notifications (
NewInteractableFocused,InteractableFocusLost)
Selected interactable
Manage task sorts focused interactables by prioritizer result and selects the highest one.
- Old selected receives
OnInteractableUnselected - New selected receives
OnInteractableSelected
Interaction
StartInteraction():
- Checks selected target.
- Validates
CanBeInteractedWith. - Sets
InteractingActor/InteractingComponent. - Calls
OnInteractionStarted. - Completes the interaction: right away when the hold time of the target is 0, otherwise after the hold time (
FPulseInteractionInfo::HoldDuration). Completing callsOnInteractionCompletedon the target and fires the ability’sOnInteractionCompletedevents.
EndInteraction():
- Calls
OnInteractionEnded. Ending before the hold time is over cancels the interaction (it never completes).
Toggle instead of hold (accessibility settings of Pulse Foundation, “Toggle instead of hold” or “Toggle: Interact”): the press starts a held interaction, releasing the key does not stop it, a second press cancels it. Once it completed it ends a quarter second later, so the server completes its own hold first. The machine of the player decides (ShouldToggleHold, override it for other rules); the cheats PulseInteractStart and PulseInteractEnd press and release like the key.
- Clears interacting references.
GetInteractionTime() returns elapsed world seconds while actively interacting. GetHoldDuration(), GetHoldProgress() (0..1, below 0 when not interacting) and IsInteractionCompleted() describe a held interaction; GetHoldState() (C++) returns it as one value, FPulseInteractHoldState (start in world time, hold time, completed, deferred release). Holding runs in world time: the bar and the completion timer share one clock, so both stop while the game is paused and follow slow motion. The rules of a press and a release are plain functions in Pulse::Ability::Interact::Hold (PulseInteractHold.h, specs PulseInteract.Hold).
Started means “the input went down”, completed means “the interaction took effect”. Put the effect of an interactable (open the door, pick the item up) into OnInteractionCompleted, so holding, conditions and costs work for it.
Interactable interface contract
IPulseInteractableInterface defines:
- availability checks:
CanBeFocusedCanBeInteractedWith
- lifecycle callbacks:
OnInteractableFoundOnInteractableLostOnInteractableSelectedOnInteractableUnselectedOnInteractionStartedOnInteractionEndedOnInteractionCompleted(2.0, default does nothing)
- prompt information:
GetInteractionInfo(Interactor)(2.0, default: onlybAvailablefromCanBeInteractedWith) - priority/replication hooks:
GetInteractablePriorityShouldReplicateInteraction
- kind of interactable:
GetInteractableTags(default: none), the tags of the messages
Important behavior:
- If actor implements the interface, actor-level interaction takes precedence.
- If only components implement it, component selection logic is applied.
- With the sphere or component query,
CanBeFocusedis asked when the overlap begins. An object in range that refuses focus (or loses it while still in range) is asked again on every focus update, so it can become focusable later without the player moving (a construction site placed next to the player, a door that unlocks).
An actor that implements the interface itself must implement CanBeFocused and CanBeInteractedWith: in Blueprint, interface functions with a return value return false until they are implemented. The interactable components (UPulseInteractableComponent, UPulseInteractBoxComponent, UPulseInteractSphereComponent) have these as properties (bCanBeFocused, bCanBeInteractedWith, InteractablePriority, InteractableTags) and call Blueprint events for every callback, so a Blueprint actor needs no interface at all.
Example: a lever with a UPulseInteractSphereComponent (radius 150) that binds its OnInteractableSelected, OnInteractableUnselected and OnInteractionStarted events and toggles bPulled. It needs a pawn with the interact ability (see Interaction in Getting started).
Component selection for multi-component actors
When an actor has multiple interactable components, the ability resolves one active component using:
- Blueprint override
GetInteractableComponentToFocus_BP(...), or UPulseInteractComponentSelectorinstance, or- fallback to first component
Built-in selectors:
UPulseInteractComponentSelector_PriorityUPulseInteractComponentSelector_Closest
Component changes while focused trigger:
- ability callback
InteractableComponentChanged(...) - old component
OnInteractableLost - new component
OnInteractableFound
Prioritization
Selection priority is handled by UPulseInteractPrioritizer.
Built-in options:
UPulseInteractPrioritizer_Default(usesGetInteractablePriority)UPulseInteractPrioritizer_Closest(distance-based with optional look-at bonus)- Blueprint extension via
UPulseInteractPrioritizer_BPandUPulseInteractPrioritizer_Closest_BP
Gameplay tags and events
Declared in PulseInteractAbility.cpp / PulseInteractAbility.h:
- Focus:
Pulse.Gameplay.Event.Interact.Focus.GainedPulse.Gameplay.Event.Interact.Focus.Lost
- Selection:
Pulse.Gameplay.Event.Interact.Selected
- Interaction:
Pulse.Gameplay.Event.Interact.StartedPulse.Gameplay.Event.Interact.CompletedPulse.Gameplay.Event.Interact.Ended
- Component change:
Pulse.Gameplay.Event.Interact.Component.Changed
- Trigger tags:
Pulse.Gameplay.Event.Interact.Started.TriggerPulse.Gameplay.Event.Interact.Ended.Trigger
When bSendGameplayEventOnInteractionEvent is enabled, ability emits gameplay events for focus/selection/interaction transitions.
Messages
Started, completed and ended interactions also go to the PulseFoundation message bus (UPulseMessageSubsystem), for reactions that do not know the ability (sounds, statistics, quest objectives such as “talk to”):
| Channel | When | Payload |
|---|---|---|
Pulse.Message.Interact.Started | OnInteractionStarted | FPulseInteractMessage |
Pulse.Message.Interact.Completed | OnInteractionCompleted | FPulseInteractMessage |
Pulse.Message.Interact.Ended | OnInteractionEnded | FPulseInteractMessage |
FPulseInteractMessage has Ability, Interactor (the avatar, usually the pawn), Target and Component. Its context (FPulseContext, Pulse::Ability::Interact::Message::MakeContext) has the interactor as Player and Instigator, the interactable actor as Target, the component (or the actor) as Source, the tags of the interactable (GetInteractableTags, InteractableTags on the interactable components) as Tags and 1 as Amount, so listeners and conditions of other plugins read it without knowing the payload. Give an interactable a tag for its kind (“NPC.Smith”, “Interact.Chest”) and a quest objective or an achievement counts interactions with that kind through a Context Tags condition. The message is sent wherever the ability runs: on the local player, and on the server as well for replicated interaction. Focus and selection changes are not sent; UI follows them through UMVVMPulseInteract.
Replicated interaction variant
UPulseRepInteractAbility extends UPulseInteractAbility and enables ReplicationPolicy = ReplicateYes.
Key points:
- Replication eligibility checks actor/component replication status.
- Replication intent is delegated to
ShouldReplicateInteraction(...)on the interactable object. - Start/end interaction has server RPC paths (
ServerStartInteraction,ServerEndInteraction). A start counts for the rate of the request guard of PulseFoundation (kindPulse.Request.Interaction.Start, no answer); a flood of starts is dropped, an end is always let in. - The server checks
CanBeInteractedWithagain (conditions, cooldowns, costs) and runs its own hold timer, so the interaction completes on the server as well; the costs are paid there (e.g. take items). - When client and server disagree for a moment (the server already ended, the client starts twice), the server ignores the call instead of failing RPC validation, so the client is not disconnected.
- The server checks the reach of every start before anything else, so doors, gathering, death bags and pickups are all protected at once: the distance from the interactor to the closest point of the target’s bounds must be within
ServerReachplusServerReachTolerance(150 cm for latency; it takes the place of Reach Tolerance of the request guard of PulseFoundation, because a query can reach from the camera, farther than from the pawn), and withbServerCheckLineOfSighta line from the interactor’s eyes to the target (its closest point or its center) must be free onServerLineOfSightChannel(Visibility); the target, its owner and every actor attached to them or to the interactor (equipment, held items) do not block. Both go throughPulse::Requests::CheckReachandHasLineOfSight(Pulse::Ability::Interact::Reach::CheckReach).ServerReach0 takes the reach from the query:SphereQueryRadius, the trace distance of the trace location provider (GetReach), or the bounds of the query components; 500 cm when none is known. A refused start is logged (LogPulseInteract, Verbose) and ignored. OverrideCheckServerReachfor rules of your own. The component a client names must belong to the actor it names (Component->GetOwner() == Actor), else the start is ignored before the reach check: the reach is measured at the actor, the effect goes to the component. A plain actor component (no scene component) is measured at the bounds of its owner. A target that does not implementUPulseInteractableInterfaceis ignored as well, at the start and at the end, so a client cannot stop a Development server with any actor or component (the generatedExecute_functionscheckthe interface). - A client’s held interaction is checked again on the server when its hold completes: the target must still be within reach (
CheckServerReach) andCanBeInteractedWithmust still allow it, else the server ends the interaction (EndInteraction) instead of completing it, so walking away while holding cancels it. Instant interactions are only checked at their start. Subclasses add rules of their own inCanCompleteInteraction. - The interactor is checked on the server at every start and completion (
CheckServerInteractor). The interaction ability is Local Only and stays active after its one activation on the client, so its activation tags never ran on the server and do not run again when the player dies. The server checks the tag requirements of the ability (ActivationBlockedTags,ActivationRequiredTags,DoesAbilitySatisfyTagRequirements) on the interactor’s ability system, and with Server Block Dead Interactor (on) it refuses an interactor withPulse.Combat.State.Dead(the tag of PulseCombat, looked up by name; nothing happens without it; the respawn component sets it too while a player is dead by the death source Attribute or Manual): a dead player keeps its pawn during the respawn delay, but loots no death bag from its corpse, opens no door, takes no pickup and gathers nothing. Server Blocked Interactor Tags adds more (for examplePulse.Combat.State.Downed). A refusal is logged (LogPulseInteract, Verbose) and ignored.
UI integration via MVVM
UMVVMPulseInteract (ModelViewViewModel) mirrors interaction state for UI:
InteractAbilitySelectedInteractablebIsInteracting,bIsInteractionCompletedSelectedInteractionInfo(FPulseInteractionInfoof the selected interactable),GetHoldDuration()GetHoldProgress()(poll it while interacting; it counts world time and stops while the game is paused),RefreshInteractionInfo()(read the info again, e.g. for cooldown texts; broadcasts only on changes)FocusedInteractables(optional list mode)
It subscribes to native ability events:
OnInteractableFocusedNativeOnInteractableLostNativeOnInteractableSelectedNativeOnInteractionStartedNativeOnInteractionEndedNativeOnInteractionCompletedNativeOnInteractableComponentChangedNative
This gives a clean binding surface for interaction prompts and status widgets without polling.
Connecting the ViewModel
There are three ways to give UMVVMPulseInteract its ability:
- Resolver (no Blueprint code): in the ViewModel panel of the widget, set the creation type to Resolver and pick Pulse Interact Resolver (
UPulseInteractViewModelResolver). It creates the ViewModel for the owning player of the widget.bListAllFocusedInteractablescan be set on the resolver. BindToPlayer(PlayerController): the ViewModel follows the interact ability of the controller’s pawn, also when the ability is granted later, the pawn changes or respawns.UnbindFromPlayerstops it.InteractAbilityset by hand.
Options 1 and 2 use Pulse::Ability::Interact::FindInteractAbility(Avatar) (looks the ability up through the ability system component of the avatar) and the global event Pulse::Ability::Interact::OnInteractAbilityAvatarSet(), which an interact ability broadcasts when it gets its avatar.
Prompts, holding, conditions and costs
Interaction info
IPulseInteractableInterface::GetInteractionInfo(Interactor) returns what a prompt shows for one interactor:
| Field | Meaning |
|---|---|
ActionText | What the interaction does (“Open”, “Pull”) |
DisplayName | Name of the interactable (“Chest”) |
Icon | Optional texture or material |
InputAction | Optional input action whose key is shown; empty = the prompt’s default |
HoldDuration | Seconds the input must be held; 0 = completes when it starts |
CostText | What it costs (“1x Key”), empty if nothing |
bAvailable, UnavailableReason | Whether the interactor can interact now, and why not (“Locked”, “Ready in 3 s”) |
UPulseInteractableComponent fills it from its properties InteractionText, DisplayName, Icon, InputAction, HoldDuration, its Conditions and its Costs. Actors that implement the interface themselves can override it.
Conditions and costs
UPulseInteractableComponent uses the condition and cost lists of Pulse Foundation (see Conditions, costs and rewards and the Pulse Foundation docs), so the same entries work for doors, recipes, skills and quests:
| Property | What it does |
|---|---|
Conditions (FPulseConditionList) | Must pass, otherwise the interactable is unavailable (CanBeInteractedWith returns false). The first failing line is the reason in the prompt (“Locked”, “Ready in 3 s”). |
Costs (FPulseCostList) | Paid when the interaction completes. The prompt shows them as CostText (“1x Key”, “10 Stamina”); a cost the interactor cannot pay makes it unavailable with the text of that cost (“Needs 1x Key”, “Needs 10 Stamina”). |
The context of both: the interactor is Player and Instigator, the owner of the component is Target, the component is Source (MakeContext). CanInteract(Interactor) checks both from Blueprint and returns an FPulseResult: Pulse.Result.Failure.Conditions or .Costs with the line as message. When the interaction completes on the authority, the component checks the conditions again (they can change while the input is held) and pays the costs, all or nothing; when either fails, the interaction has no effect and OnInteractionCompleted of the component is not broadcast. It pays inside a Pulse::Inventory::FItemCostLedger: when a later cost of the list fails and the payment is rolled back, the interactor gets the very stacks back that its Items costs took, with their instance traits (a half spoiled or bound stack as it was), not new items.
Entries that fit interactions:
| Entry | Kind | Module | Does |
|---|---|---|---|
Cooldown (FPulseCondition_InteractCooldown) | Condition | PulseAbility | Fails for Seconds after a completed interaction of this component; line “Ready in {Seconds} s” |
Actor Tag Query (FPulseCondition_ActorTagQuery) | Condition | PulseFoundation | The tags of the interactor (ability system or IGameplayTagAssetInterface, for a player also controller and player state) match a query |
Has Item (FPulseCondition_HasItem) | Condition | PulseInventory | The interactor has items without using them up (a key that opens every chest) |
Items (FPulseCost_Items) | Cost | PulseInventory | Takes items when the interaction completes (a key that breaks) |
Attribute (FPulseCost_Attribute) | Cost | PulseFoundation | Pays with an attribute of the interactor when the interaction completes (Pulse.Stat.Stamina for pushing a boulder); with bAllowPartial it passes while anything is left and pays what there is |
Own conditions and costs derive from FPulseCondition and FPulseCost (Pulse Foundation) and show up in every list.
The Attribute cost reads and changes the attribute through the attribute contract of Pulse Foundation, so stamina costs work for an interactor with the stamina set of PulseAttributes (GAS adapter) and for one with the Pulse Attributes component alike; no GAS cost effect on the interact ability is needed. A client’s prompt reads the stamina its source replicates to the owner; the server pays.
The cooldown counts the completions each machine sees: the server enforces it for everyone, a client’s prompt only knows its own completions.
Prompt widget (PulseInteractUI)
UPulseInteractPromptWidget follows the interact ability of its owning player by itself (own UMVVMPulseInteract, BindToPlayer), shows up with the theme’s motion when an interactable is selected and hides again when there is none. The class of that view model comes from Project Settings > Pulse > Gameplay > Interact UI (UPulseInteractUISettings, InteractViewModelClass, default UMVVMPulseInteract): a child class (C++ or Blueprint) adds fields of its own without a widget subclass; an empty setting or a class that does not fit uses UMVVMPulseInteract (specs PulseInteractUI.ViewModels). All parts are optional bound widgets:
| Widget | Shows |
|---|---|
KeyPanel, KeyImage, KeyText | The key of the input action (or DefaultKey): its icon (CommonInput controller data or the Pulse key icons, see the key icons of the PulseFoundation UI themes), otherwise the key name; hidden without a key |
IconImage | Icon of the info |
ActionText, NameText | Action (“Interact” if empty) and name |
HoldHintText | HoldHint (“Hold”) for held interactions |
CostText, ReasonText | Cost and unavailable reason, hidden when empty |
HoldRing | Progress as a ring around the key (HoldDisplay Ring): an image whose material takes HoldRingParameter, e.g. the theme brush Pulse.UI.Brush.ProgressRing; stays visible as the key’s frame |
HoldBar | Progress as a bar (HoldDisplay Bar), hidden for instant interactions |
Settings: HoldDisplay (Ring or Bar, SetHoldDisplay at runtime), bKeyboardKeysAsText (keyboard keys as plain letters, e.g. inside the ring; gamepad buttons keep their icon), DefaultInputAction (key shown when the interactable names none), DefaultKey (E, when no action gives a key), bShowWhenUnavailable, InfoRefreshInterval (how often cooldowns and item counts are read again), UnavailableOpacity, and bFollowTarget with TargetOffset / ScreenOffset to place the prompt above the target (the prompt must be in a canvas panel then). Blueprint events: On Prompt Shown, On Prompt Hidden, On Prompt Updated, On Interaction Completed. The designer preview uses PreviewInfo, PreviewKey and PreviewHoldProgress. A hidden prompt is collapsed; it updates from the core ticker while it exists.
The default prompt /PulseGameplay/Interact/W_DefaultInteractPrompt uses the Pulse Style roles of the UI theme and sits in the gameplay area of W_DefaultHUDWidget (InteractPrompt, right below the crosshair): a 46 px ring with the key inside, the action and “Hold” next to it as text over the world. It contains both the ring and a bar; HoldDisplay picks one.
A UI host without a layout of its own (the default presenter of Pulse Foundation, or a game presenter) shows no prompt by itself. With Add By Code in PromptPlacement of the Interact UI settings, UPulseInteractUISubsystem adds the default prompt (or the Widget Class of the placement, a child of UPulseInteractPromptWidget) to the gameplay part of the host below the middle of the screen (anchor (0.5, 0.72)), once the host is ready and again after every map change; a prompt the host already shows is used instead (Get Prompt returns either). The subsystem exists only while the placement adds by code (off by default, because W_DefaultHUDWidget contains the prompt). Specs: PulseInteractUI.Placement.
The plugin does not bind input: the game activates the ability, calls StartInteraction when its interact input goes down and EndInteraction when it is released (needed for held interactions). In Blueprints Find Interact Ability (UInteractUtils) returns the interact ability of a pawn for these calls. A child of UPulseRepInteractAbility with Activate On Give activates itself when it is given to a locally controlled pawn; BP_PulseGameplayExample_Pawn in /PulseGameplay/Examples/Player gives it in Event Possessed and also activates it in Event Receive Restarted, for clients that learn their controller after the ability arrived.
Switching it off. UPulseInteractUISubsystem is switchable: add it to Disabled Subsystems (Project Settings > Pulse > Foundation > Subsystems) when your game brings its own interaction prompt. See Replacing and switching off subsystems.
Cheats
| Cheat | Does |
|---|---|
PulseInteractGrant [class] | Gives the pawn an interact ability (UPulseRepInteractAbility by default); adds an ability system component to pawns without one |
PulseInteractSpawnTest [hold] [cooldown] | Spawns a replicated test cube with an interactable in front of the player |
PulseInteractStart, PulseInteractEnd | Start and end interacting with the selected interactable |
PulseInteractInfo | Prints the selected interactable, its info and the hold progress |
PulseInteractSendStart far\|pawn\|mesh\|any [class] | Testing only: sends the server a start with the nearest test cube wherever it is, with the own pawn as its actor, with its mesh, or with the nearest interactable of any kind (any, a door or a pickup; class narrows it by a part of the class name), to watch the server ignore it |
Start, end and info activate the ability if the game did not. In PIE, clients need EnableCheats first.