API Reference

Complete reference for public classes, interfaces, and events in ElysPerceptionPlugin.

Core Components

UERPPerceptionComponent

Main perception component managing multi-channel pipeline execution.

Header: Core/ERPPerceptionComponent.h

Properties

Property	Type	Default	Description
PerceptionTickInterval	float	0.0	Tick interval in seconds (0 = every frame)
DefaultSamplingRange	float	2000.0	Default sampling range (cm) passed to samplers
ChannelPipelines	TArray<FERPChannelPipeline>		Multi-channel pipeline configuration
bProvideViewportInfoWhenAvailable	bool	false	Include viewport size and screen reference in context
DefaultScreenReferenceNdc	FVector2D	(0.5, 0.5)	Default screen reference (normalized 0..1)
bEvaluateOnlyForLocalController	bool	true	Only tick for the local player (multiplayer)
bDebugPerception	bool	false	Enable debug logging
DebugPerceptionIntervalSeconds	float	0.0	Debug log throttle interval

Methods

AActor* GetChannelCandidate(FName ChannelId) const;
bool HasChannelCandidate(FName ChannelId) const;
void GetAllChannelCandidates(TArray<FName>& OutChannelIds, TArray<AActor*>& OutCandidates) const;
bool ValidateActorForChannel(AActor* Actor, FName ChannelId) const;

Events

FERPOnChannelCandidateAcquiredSignature OnChannelCandidateAcquired; // (FName ChannelId, AActor* Candidate)
FERPOnChannelCandidateLostSignature OnChannelCandidateLost;         // (FName ChannelId, AActor* Candidate)

Overridable Functions

// Override to customize aim ray (default: owner view point)
void GetPerceptionAimRay(FVector& OutOrigin, FVector& OutDirection) const;

// Override to provide custom screen reference point
bool GetScreenReferenceNdc(FVector2D& OutScreenReferenceNdc) const;

---

UERPDomainComponent (Abstract)

Base class for gameplay domain components that consume perception events.

Header: Core/ERPDomainComponent.h

Properties

Property	Type	Default	Description
PerceptionComponent	UERPPerceptionComponent*	nullptr	Auto-found on owner at BeginPlay
ChannelId	FName	None	Perception channel to listen to

Methods

AActor* GetCurrentCandidate() const;
bool HasCandidate() const;
void SetCandidate(AActor* Candidate);
void ClearCandidate();

Events

FERPOnDomainCandidateChangedSignature OnDomainCandidateChanged; // (AActor* Previous, AActor* New, FName ChannelId)

Virtual Hooks (BlueprintNativeEvent)

bool IsCandidateEligible(AActor* Candidate) const;       // Default: true
void HandleCandidateUpdated(AActor* Previous, AActor* Current); // Default: no-op

---

UERPInteractionComponent

Interaction domain extending UERPDomainComponent. Adds RPC networking.

Header: Domains/Interaction/ERPInteractionComponent.h

Properties

Property	Type	Default	Description
Rules	TArray<UERPInteractionRule*>		Instanced validation rules
MaxInteractionDistance	float	500.0	Server-side distance validation (cm)

Methods

void GetCurrentDescriptor(FERPInteractionDescriptor& OutDescriptor) const;
bool HasDescriptor() const;
void RequestInteraction(); // Handles networking automatically

Events

FERPOnInteractionDescriptorChangedSignature OnDescriptorChanged;    // (AActor*, Descriptor, ChannelId)
FERPOnInteractionExecutedSignature OnInteractionExecuted;           // (AActor*)
FERPOnInteractionFailedSignature OnInteractionFailed;               // (AActor*, Reason)

RPCs (internal)

Server_RequestInteraction(AActor*)     // Server RPC with validation
Client_OnInteractionSuccess(AActor*)   // Client notification
Client_OnInteractionFailed(AActor*, Reason) // Client notification

---

UERPTargetingComponent

Targeting domain extending UERPDomainComponent.

Header: Domains/Targeting/ERPTargetingComponent.h

Properties

Property	Type	Default	Description
Rules	TArray<UERPTargetRule*>		Instanced validation rules

Methods

const UERPTargetDescriptor* GetCurrentDescriptor() const;

Events

FERPOnTargetDescriptorChangedSignature OnDescriptorChanged; // (AActor*, Descriptor*, ChannelId)

---

UERPChannelListenerComponent

Lightweight single-channel event mirror. No domain logic.

Header: Core/ERPChannelListenerComponent.h

Methods

AActor* GetCurrentCandidate() const;
bool HasCandidate() const;
void SetPerceptionComponent(UERPPerceptionComponent* InPerceptionComponent);
void SetChannelId(FName InChannelId);

Events

FERPOnCandidateAcquiredSignature OnCandidateAcquired; // (AActor*)
FERPOnCandidateLostSignature OnCandidateLost;         // (AActor*)

---

UERPBaseInteractionFeedbackComponent

Visual feedback component for interactable actors.

Header: Domains/Interaction/ERPBaseInteractionFeedbackComponent.h

Properties

Property	Type	Default	Description
CustomDepthStencilValue	int32	1	Stencil value when focused

Methods

void SetInteractionFocused(APlayerController* PC, bool bFocused);
void UpdateInteractionDescriptor(APlayerController* PC, const FERPInteractionDescriptor& Descriptor);
bool IsInteractionFocused() const;

Default Behavior

OnInteractionFocused_Implementation: Toggles RenderCustomDepth and sets CustomDepthStencilValue on owner mesh components.

Override OnInteractionFocused in Blueprint to replace with custom behavior.

---

Widget Base Classes

UERPInteractionWidgetBase (Abstract)

Base widget for interaction prompts. Descriptor-driven with focus tracking.

Header: UI/Interaction/ERPInteractionWidgetBase.h

Methods

void UpdateFromDescriptor(const FERPInteractionDescriptor& Descriptor); // Cache + notify
void SetFocused(bool bNewFocused);                                       // Focus state
const FERPInteractionDescriptor& GetDescriptor() const;
bool IsFocused() const;
FText GetCurrentInputDisplayKey() const;       // Key from cached descriptor's InputAction
FText GetInputActionDisplayKey(const UInputAction* InputAction) const;

Virtual Hooks (BlueprintNativeEvent)

void OnDescriptorUpdated(const FERPInteractionDescriptor& Descriptor); // Default: no-op
void OnFocusChanged(bool bNewFocused);          // Default: toggle visibility

---

UERPHoldInteractionWidgetBase (Abstract)

Extends UERPInteractionWidgetBase with hold-to-interact progress tracking.

Header: UI/Interaction/ERPHoldInteractionWidgetBase.h

Methods

void SetHoldProgress(float Progress);  // 0.0 to 1.0, auto-detects start/complete/cancel
void ResetHold();                      // Reset + fire OnHoldCancelled if holding
float GetCurrentProgress() const;
bool IsHolding() const;

Virtual Hooks (BlueprintNativeEvent)

void OnHoldProgressChanged(float Progress); // Default: no-op
void OnHoldStarted();                       // Default: no-op
void OnHoldCompleted();                     // Default: no-op
void OnHoldCancelled();                     // Default: no-op

---

UERPTargetingWidgetBase (Abstract)

Base widget for targeting UI (reticles, lock-on indicators, info panels).

Header: UI/Targeting/ERPTargetingWidgetBase.h

Methods

void UpdateFromDescriptor(const UERPTargetDescriptor* Descriptor);
void SetTargetActive(bool bActive);
void SetTargetActor(AActor* Actor);
const UERPTargetDescriptor* GetDescriptor() const;
bool IsTargetActive() const;
AActor* GetTargetActor() const;

Virtual Hooks (BlueprintNativeEvent)

void OnDescriptorUpdated(const UERPTargetDescriptor* Descriptor); // Default: no-op
void OnTargetActiveChanged(bool bActive);       // Default: toggle visibility
void OnTargetActorChanged(AActor* NewTargetActor); // Default: no-op

---

Interfaces

IERPInteractable

Header: Domains/Interaction/ERPInteractable.h

bool CanBeInteractedWith(AActor* InteractingActor) const;
void GetInteractionDescriptor(FERPInteractionDescriptor& OutDescriptor) const;
bool ExecuteInteraction(AActor* InstigatorActor);

IERPTargetable

Header: Domains/Targeting/ERPTargetable.h

bool CanBeTargetedBy(AActor* TargetingActor) const;
UERPTargetDescriptor* GetTargetDescriptor() const;

---

Pipeline Base Classes

UERPSamplerBase

void Sample(const FERPPerceptionContext& Context, float Range, TArray<AActor*>& OutCandidates) const;

UERPFilterBase

bool Passes(const FERPPerceptionContext& Context, AActor* Candidate) const;

UERPScorerBase

float Score(const FERPPerceptionContext& Context, AActor* Candidate) const;

UERPAggregatorBase

float Aggregate(const TArray<float>& Scores) const; // Default: sum

UERPResolverBase

bool Resolve(const TArray<FERPPipelineScoredCandidate>& ScoredCandidates,
    FERPPipelineScoredCandidate& OutBest) const; // Default: lowest score wins

---

Data Structures

FERPPerceptionContext

struct FERPPerceptionContext
{
    AActor* ContextActor;              // Perception owner
    FVector Origin;                    // Position
    FVector Forward;                   // Facing direction
    bool bHasAimRay;
    FVector AimOrigin;
    FVector AimDirection;
    bool bHasViewport;
    FVector2D ViewportSizePx;
    bool bHasScreenReference;
    FVector2D ScreenReferenceNdc;      // Normalized 0..1
    APlayerController* ScreenProjectionPC; // For viewport scorers
};

FERPInteractionDescriptor

struct FERPInteractionDescriptor
{
    FText DisplayName;                              // "Open", "Talk", "Pick Up"
    FText PromptText;                               // "Press E to open"
    const UInputAction* InputAction;                // For key display in widgets
    TSoftObjectPtr<UTexture2D> Icon;                // Interaction type icon
    float HoldDuration = 0.0f;                      // 0 = instant, >0 = hold-to-interact (seconds)
    int32 RequiredPresses = 0;                      // 0 = not multi-press, >0 = press N times
    FGameplayTagContainer InteractionTags;
    TMap<FName, TObjectPtr<UObject>> PresentationHints;

    bool IsHoldInteraction() const;                 // HoldDuration > 0
    bool IsMultiPressInteraction() const;            // RequiredPresses > 0
};

FERPScorerEntry

struct FERPScorerEntry
{
    UERPScorerBase* Scorer;
    float Weight = 1.0f;
};

FERPChannelPipeline

struct FERPChannelPipeline
{
    FName ChannelId;
    FName SamplerCacheId;                // Optional: force cache sharing
    UERPSamplerBase* Sampler;            // Required
    TArray<UERPFilterBase*> Filters;
    TArray<FERPScorerEntry> Scorers;     // Scorer + Weight pairs
    UERPAggregatorBase* Aggregator;      // Optional (default: sum)
    UERPResolverBase* Resolver;          // Required
};

---

Default Implementations

Samplers

• UERPSphereOverlapSampler - Sphere overlap query

Filters

• UERPTargetableFilter - Requires IERPTargetable
• UERPInteractableFilter - Requires IERPInteractable
• UERPDistanceFilter - Range-based filtering
• UERPImplementsInterfaceFilter - Generic interface check

Scorers

• UERPDistanceScorer - Distance-based (lower = closer = better)
• UERPConeScorer - Angle from forward direction
• UERPViewportEllipseScorer - Screen-space ellipse (requires bProvideViewportInfoWhenAvailable)

Validation Rules

• UERPInteractionRule - Base for interaction validation rules
• UERPTargetRule - Base for targeting validation rules

---

Next Steps

See Quick Reference for common patterns.

Review Customization for extension examples.

Create custom domains with Custom Domains.