UE5-Modular-Game-Framework/docs/blueprints/03-interaction/16_BPC_InteractionDetector.md

16 — Interaction Detector (BPC_InteractionDetector)

Purpose

The player's "interaction eye" — performs trace-based detection of interactable objects in the world, sorts them by priority/distance, tracks the current best target, and manages the interaction prompt widget. Every interactive system in the game funnels through this component.

Dependencies

• Requires: I_Interactable (interface on all interactable actors), PlayerCameraManager (for trace origin), BPC_MovementStateSystem (block interaction during specific states)
• Required By: WBP_InteractionPrompt (HUD element), BPC_PickupComponent, BPC_InteractableDoorComponent, BPC_LeverPuzzleComponent
• Engine/Plugin Requirements: LineTraceByChannel (ECC_GameTraceChannel1 = Interaction), TimerHandle for scan interval

Class Info

Property	Value
Parent Class	ActorComponent
Class Type	Blueprint Component
Asset Path	Content/Framework/Interaction/BPC_InteractionDetector
Implements Interfaces	None

---

1. Enums

E_InteractionInputMode

Value	Description
Press = 0	Single press to interact
Hold = 1	Hold over duration to confirm
DoubleTap = 2	Two rapid presses
Auto = 3	Automatic on proximity (no input)

E_InteractionPriority

Value	Description
Low = 0	Ambient / cosmetic items
Normal = 1	Standard pickups, doors
High = 2	Story-critical, puzzles
Emergency = 3	Immediate threat (hide spot, weapon)

E_DetectionState

Value	Description
NoTarget = 0	Nothing in range
TargetInRange = 1	Potential target found
TargetConfirmed = 2	Best target selected
Interacting = 3	Currently performing interaction

---

2. Structs

S_InteractableTarget

Field	Type	Description
TargetActor	AActor	The interactable actor
InterfaceRef	I_Interactable	Cast to interface
Priority	E_InteractionPriority	Priority level
Distance	Float	Distance from player to target
InteractionLabel	FText	Display name (e.g. "Open Door", "Pick Up Key")
InputMode	E_InteractionInputMode	How interaction is triggered
HoldDuration	Float	Seconds required if InputMode is Hold
bIsHighlighted	Boolean	Whether target is visually highlighted
TargetLocation	Vector	World location for UI widget

S_InteractionResult

Field	Type	Description
bSuccess	Boolean	Whether interaction was successful
FailureReason	FText	Human-readable failure reason
TargetActor	AActor	The interacted actor
ContextTag	GameplayTag	Tag for event recording

---

3. Variables

Configuration (Instance Editable, Expose On Spawn)

Variable	Type	Default	Category	Description
InteractionRange	Float	250.0	Detection Config	Max trace distance (cm)
DetectionAngle	Float	45.0	Detection Config	Cone half-angle for detection (degrees)
TraceRadius	Float	10.0	Detection Config	Sphere trace radius
ScanInterval	Float	0.1	Detection Config	Seconds between detection scans
MaxTargetsInRange	Integer	16	Detection Config	Max detected targets per scan
bShowDebugTrace	Boolean	false	Detection Config	Visualise trace in editor
TraceChannel	TEnumAsByte<ECollisionChannel>	ECC_GameTraceChannel1	Detection Config	Collision channel for interaction
bBlockDuringDeath	Boolean	true	Detection Config	Block interaction while dead
bBlockDuringHiding	Boolean	true	Detection Config	Block interaction while hidden
bBlockDuringCombat	Boolean	false	Detection Config	Block interaction during combat

Internal (Private / Protected, No Expose)

Variable	Type	Default	Category	Description
BestTargetIndex	Integer	-1	Detection State	Index of currently selected target
DetectedTargets	Array<S_InteractableTarget>	[]	Detection State	All detected targets this scan
CurrentTarget	S_InteractableTarget	-	Detection State	Currently selected best target
DetectionState	E_DetectionState	NoTarget	Detection State	Current state of the detector
bIsPerformingInteraction	Boolean	false	Detection State	Whether interaction is in progress
HoldInteractionProgress	Float	0.0	Detection State	Progress for hold-type interactions
OwnerPlayerController	APlayerController	None	Cache	Cached player controller
OwnerCameraManager	APlayerCameraManager	None	Cache	Cached camera manager
ScanTimerHandle	FTimerHandle	-	Timing	Timer for scan interval
DetectedActors_LastFrame	Set<AActor>	{}	Tracking	Previous frame targets for enter/exit detection

Replicated (if multiplayer)

Variable	Type	Condition	Description
CurrentTarget	S_InteractableTarget	Replicated	Synced selected target

---

4. Functions

Public Functions

StartDetection → void

• Description: Begins the scan loop for interactable targets.
• Parameters: None
• Flow:
  1. Get owner Player Controller
  2. Get Player Camera Manager
  3. Start scan timer (ScanInterval)
  4. If bShowDebugTrace: enable debug line visualisation

StopDetection → void

• Description: Stops the scan loop and clears detected targets.
• Parameters: None
• Flow:
  1. Clear scan timer
  2. Clear DetectedTargets array
  3. Set DetectionState = NoTarget
  4. Fire OnTargetLost
  5. Clear any highlight effects

PerformInteraction → S_InteractionResult

• Description: Executes interaction on the current best target.
• Parameters:

  Param	Type	Description
  InputMode	E_InteractionInputMode	How the input was triggered

• Flow:
  1. If not CurrentTarget valid or CurrentTarget actor is None: return failure
  2. If bIsPerformingInteraction: return failure (already interacting)
  3. If InputMode != CurrentTarget.InputMode: return failure (input mismatch)
  4. Set bIsPerformingInteraction = true
  5. Set DetectionState = Interacting
  6. Fire OnInteractionStarted
  7. Call CurrentTarget.InterfaceRef.ExecuteInteraction (owner)
  8. Wait for I_Interactable.OnInteractionCompleted or timeout
  9. On completion: set bIsPerformingInteraction = false
  10. Resume scanning
  11. Return S_InteractionResult with success/failure

CancelInteraction → void

• Description: Aborts the current interaction if possible.
• Parameters: None
• Flow:
  1. If not bIsPerformingInteraction: return
  2. Call CurrentTarget.InterfaceRef.CancelInteraction
  3. Set bIsPerformingInteraction = false
  4. HoldInteractionProgress = 0.0
  5. Set DetectionState = TargetConfirmed
  6. Fire OnInteractionCancelled

GetBestTarget → S_InteractableTarget

• Description: Returns the current best target.
• Parameters: None
• Flow: Return CurrentTarget

HasTarget → Boolean

• Parameters: None
• Flow: Return DetectionState >= TargetInRange

ForceSetTarget → void

• Description: Forcefully sets a specific target (for scripted interactions).
• Parameters:

  Param	Type	Description
  TargetActor	AActor	The specific actor to target

• Flow:
  1. If TargetActor implements I_Interactable:
     • Build S_InteractableTarget
     • Set CurrentTarget
     • Set DetectionState = TargetConfirmed
     • Fire OnTargetFound
  2. Else: fire OnInteractionError(not interactable)

Private Functions

ScanForInteractables (Timer) → void

• Description: Timer callback — performs trace and sorts targets.
• Flow:
  1. If DetectionState == Interacting: return (skip scan while interacting)
  2. Get camera forward vector and world location
  3. Sphere trace forward (TraceRadius, InteractionRange, TraceChannel)
  4. For each hit actor:
     • If implements I_Interactable: add to DetectedTargets
     • If not: skip
  5. Remove duplicates by actor reference
  6. Sort by Priority (descending), then Distance (ascending)
  7. Clamp to MaxTargetsInRange
  8. Track enter/exit for each actor — fire OnTargetEntered / OnTargetExited
  9. Select BestTarget from sorted list
  10. Update DetectionState accordingly
  11. Fire OnTargetFound or OnTargetLost

CalculateInteractionScore → Float

• Description: Computes a score for a target based on priority, distance, and facing angle.
• Parameters:

  Param	Type	Description
  Target	S_InteractableTarget	The target to score

• Flow:
  1. Score = Priority * 100 - Distance * 0.5
  2. Facing bonus: if angle < 15 deg, add 50
  3. Return Max(0, Score)

HighlightTarget → void

• Description: Applies highlight effect to target actor.
• Parameters:

  Param	Type	Description
  Target	S_InteractableTarget	Target to highlight
  bHighlighted	Boolean	Whether to enable or disable

• Flow:
  1. Call Target.InterfaceRef.SetHighlighted(bHighlighted)

GetViewTraceOrigin → Vector, Vector

• Description: Returns camera location and forward direction for trace.
• Parameters: None
• Flow:
  1. If OwnerCameraManager valid:
     • Return cam location and forward vector
  2. Else: fall back to owner actor location and forward

---

5. Event Dispatchers

Dispatcher	Parameters	Bind Access	Description
OnTargetFound	S_InteractableTarget NewTarget	Public	New best target selected
OnTargetLost	S_InteractableTarget LostTarget	Public	Current target lost from view / range
OnTargetEntered	AActor TargetActor	Public	Actor entered detectable range
OnTargetExited	AActor TargetActor	Public	Actor left detectable range
OnInteractionStarted	S_InteractableTarget Target	Public	Interaction began
OnInteractionCompleted	S_InteractionResult Result	Public	Interaction finished
OnInteractionCancelled	S_InteractableTarget Target	Public	Interaction was cancelled
OnInteractionError	FText ErrorMessage	Public	Interaction blocked or failed
OnHoldProgressUpdated	Float Progress, S_InteractableTarget Target	Public	Hold interaction progress [0..1]

---

6. Overridden Events / Custom Events

Event: BeginPlay

• Description: Cache references, bind to relevant systems, start detection.
• Flow:
  1. Get owning actor → ensure it is a Pawn
  2. Get Player Controller from owner
  3. Get Player Camera Manager from controller
  4. Bind to BPC_MovementStateSystem.OnPostureChanged — block when hidden
  5. Bind to BPC_HealthSystem.OnDeathStateChanged — block when dead
  6. StartDetection()

Custom Event: OnInputInteractPressed

• Description: Handles press input for interaction.
• Flow:
  1. If DetectionState < TargetConfirmed: return
  2. If CurrentTarget.InputMode == Press:
     • PerformInteraction(Press)
  3. If CurrentTarget.InputMode == Hold:
     • Start hold timer
  4. If CurrentTarget.InputMode == DoubleTap:
     • Wait for second press within threshold

Custom Event: OnHoldProgressTick (Timer) → void

• Description: Ticks hold interaction progress and fires progress dispatcher.
• Flow:
  1. HoldInteractionProgress += DeltaTime / CurrentTarget.HoldDuration
  2. Clamp to 1.0
  3. Fire OnHoldProgressUpdated
  4. If HoldInteractionProgress >= 1.0: PerformInteraction(Hold)

Custom Event: OnInputInteractReleased

• Description: Cancels hold interaction if button released early.
• Flow:
  1. If CurrentTarget.InputMode == Hold and not completed:
     • CancelInteraction()
     • HoldInteractionProgress = 0.0

---

7. Blueprint Graph Logic Flow

flowchart TD
    A[Scan Timer Fires] --> B[Get Camera Location / Forward]
    B --> C[SphereTraceForObjects]
    C --> D[Hit actors found?]
    D -->|No| E[Clear targets]
    E --> F[DetectionState = NoTarget]
    F --> G[Fire OnTargetLost]
    
    D -->|Yes| H[Filter by I_Interactable]
    H --> I[Sort by Priority then Distance]
    I --> J[Select BestTarget]
    J --> K{BestTarget changed?}
    K -->|Yes| L[Unhighlight old target]
    L --> M[Highlight new target]
    M --> N[Fire OnTargetFound]
    K -->|No| O[Keep current target]
    
    P[OnInputInteractPressed] --> Q{DetectionState >= Confirmed?}
    Q -->|No| R[Return]
    Q -->|Yes| S{InputMode match?}
    S -->|Press| T[PerformInteraction]
    S -->|Hold| U[Start hold timer]
    S -->|DoubleTap| V[Start double-tap timer]
    T --> W[Call ExecuteInteraction on target]
    W --> X[Fire OnInteractionStarted]
    X --> Y{Interaction succeeded?}
    Y -->|Yes| Z[Fire OnInteractionCompleted]
    Y -->|No| AA[Fire OnInteractionError]

---

8. Communication Matrix

Who Talks	How	What Is Sent
BPC_InteractionDetector	Dispatcher	OnTargetFound -> WBP_InteractionPrompt (show prompt)
BPC_InteractionDetector	Dispatcher	OnTargetLost -> WBP_InteractionPrompt (hide prompt)
BPC_InteractionDetector	Dispatcher	OnInteractionStarted -> BPC_PlayerMetricsTracker (log event)
BPC_InteractionDetector	Dispatcher	OnInteractionCompleted -> BPC_PlayerMetricsTracker (log result)
BPC_InteractionDetector	Dispatcher	OnHoldProgressUpdated -> WBP_InteractionPrompt (progress bar)
BPC_InteractionDetector	Dispatcher	OnInteractionCancelled -> WBP_InteractionPrompt (hide)
BPC_InteractionDetector	Listener	Binds to BPC_MovementStateSystem.OnPostureChanged
BPC_InteractionDetector	Listener	Binds to BPC_HealthSystem.OnDeathStateChanged
BPC_InteractionDetector	Direct	Calls I_Interactable.ExecuteInteraction on target
BPC_InteractionDetector	Direct	Calls I_Interactable.CancelInteraction on target
BPC_InteractionDetector	Direct	Calls I_Interactable.SetHighlighted on target
BPC_InteractionDetector	Direct call (other)	GetBestTarget called by WBP_InteractionPrompt for name
PC_PlayerController	Input Event	Binds press / release / hold to OnInputInteractPressed etc.

---

9. Validation / Testing Checklist

• Trace detects actors implementing I_Interactable at correct range
• Priority sorting: Emergency targets always selected over Low
• Same priority: closest target selected
• Detection respects blocking states (dead, hiding)
• Hold interaction progress updates and fires progress dispatcher
• Double-tap interaction waits for second press within window
• Cancelling hold interaction resets progress and fires cancelled
• Interaction blocked during combat if bBlockDuringCombat is true
• Targeting auto-switches if closer target enters range
• Target exit detection fires when actor moves beyond max range
• Edge case: No targets in range — DetectionState stays NoTarget
• Edge case: Target destroyed mid-interaction — cancels gracefully
• Edge case: Multiple interactables in trace — selects correctly
• Debug trace visualisation draws correct sphere/line
• Scan timer pauses while interacting, resumes after completion

---

10. Reuse Notes

• TraceChannel should be set to a custom object channel (ECC_GameTraceChannel1) with only interactable actors responding.
• Priority values can be overridden per actor via the I_Interactable interface's GetInteractionPriority function.
• The hold interaction progress is designed to drive a radial progress widget in the HUD.
• For controller/console: E_InteractionInputMode.Hold is preferred to prevent accidental interactions.
• The same component can be attached to NPCs if they need interaction detection.
• To support networked games: replicate CurrentTarget and have each client run their own trace locally.

---

Blueprint Spec: Interaction Detector. Conforms to TEMPLATE.md v1.0 — part of the UE5 Modular Game Framework.