Skip to main content

API Reference

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

Core Components​

UERPAwarenessComponent​

Main perception component managing multi-channel pipeline execution.

Header: Core/ERPAwarenessComponent.h

Properties​

PropertyTypeDefaultDescription
PerceptionTickIntervalfloat0.0Tick interval in seconds (0 = every frame)
DefaultSamplingRangefloat2000.0Default sampling range (cm) passed to samplers
ChannelPipelinesTArray<FERPChannelPipeline>Multi-channel pipeline configuration
bProvideViewportInfoWhenAvailableboolfalseInclude viewport size and screen reference in context
DefaultScreenReferenceNdcFVector2D(0.5, 0.5)Default screen reference (normalized 0..1)
bEvaluateOnlyForLocalControllerbooltrueOnly tick for the local player (multiplayer)
bDebugPerceptionboolfalseEnable debug logging
DebugPerceptionIntervalSecondsfloat0.0Debug 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)
FERPOnChannelEvaluatedSignature OnChannelEvaluated;                 // (FName ChannelId, TArray<FERPPipelineScoredCandidate> ScoredCandidates)

OnChannelEvaluated fires after each channel evaluation with ALL scored candidates (post-filter, post-scoring). Use this for minimap markers, radar displays, or any UI that needs the full candidate set — not just the winner.

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​

PropertyTypeDefaultDescription
PerceptionComponentUERPAwarenessComponent*nullptrAuto-found on owner at BeginPlay
ChannelIdFNameNonePerception 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 and automatic visual feedback notification.

When the candidate changes, the component automatically looks for an ERPBaseInteractionFeedbackComponent on the candidate actor. If found, it calls SetInteractionFocused and UpdateInteractionDescriptor. If not found, the candidate change is still processed normally — use OnDescriptorChanged / OnDomainCandidateChanged to drive your own UI.

Header: Domains/Interaction/ERPInteractionComponent.h

Properties​

PropertyTypeDefaultDescription
RulesTArray<UERPInteractionRule*>Instanced validation rules
MaxInteractionDistancefloat500.0Server-side distance validation (cm)

Methods​

void GetCurrentDescriptor(FERPInteractionDescriptor& OutDescriptor) const;
bool HasDescriptor() const;
void RequestInteraction();          // Handles networking automatically
void ForceRefreshDescriptor();      // Re-pull descriptor from current candidate and broadcast if changed

Events​

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

ForceRefreshDescriptor​

Call ForceRefreshDescriptor() when an interactable changes its descriptor while remaining the active candidate (e.g., a door goes from "Open" to "Locked"). Perception only fires events on candidate transitions — it does not detect data changes on the same actor.

ForceRefreshDescriptor() re-pulls GetInteractionDescriptor from the current candidate and, if the descriptor changed:

  • Broadcasts OnDescriptorChanged
  • Notifies the ERPBaseInteractionFeedbackComponent on the candidate (if present)

If the descriptor is identical, nothing happens (no spurious events).

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​

PropertyTypeDefaultDescription
RulesTArray<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(UERPAwarenessComponent* InPerceptionComponent);
void SetChannelId(FName InChannelId);

Events​

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

UERPBaseInteractionFeedbackComponent (Optional)​

Visual feedback component for interactable actors. When present on an actor, UERPInteractionComponent automatically calls SetInteractionFocused and UpdateInteractionDescriptor when the actor gains/loses focus. If the actor doesn't have this component, the interaction system works normally — you can handle visuals from domain events instead.

Header: Domains/Interaction/ERPBaseInteractionFeedbackComponent.h

Properties​

PropertyTypeDefaultDescription
CustomDepthStencilValueint321Stencil value used by ApplyDefaultCustomDepthFeedback

Methods​

void SetInteractionFocused(APlayerController* PC, bool bFocused);         // Auto-called by ERPInteractionComponent
void UpdateInteractionDescriptor(APlayerController* PC, const FERPInteractionDescriptor& Descriptor); // Auto-called by ERPInteractionComponent
bool IsInteractionFocused() const;
void ApplyDefaultCustomDepthFeedback(bool bEnable);  // Utility: toggles RenderCustomDepth on owner meshes

Blueprint Hooks (BlueprintImplementableEvent)​

void OnInteractionFocused(APlayerController* PC, bool bFocused); // Implement your visual feedback
void OnDescriptorUpdated(APlayerController* PC, const FERPInteractionDescriptor& Descriptor); // Implement your UI update

These events have no default C++ behavior — you implement whatever you need in Blueprint. Use ApplyDefaultCustomDepthFeedback inside your OnInteractionFocused if you want the built-in outline effect.

UERPCandidateRegistrySubsystem​

World-level registry for declarative candidate registration (non-spatial perception).

Header: Core/ERPCandidateRegistrySubsystem.h

Methods​

void RegisterActor(FName ChannelId, AActor* Actor);       // Register for a channel (idempotent)
void UnregisterActor(FName ChannelId, AActor* Actor);      // Unregister from a channel
void UnregisterFromAll(AActor* Actor);                     // Unregister from all channels
TArray<AActor*> GetRegisteredActors(FName ChannelId);      // Get all valid actors for a channel
bool HasRegisteredActors(FName ChannelId) const;           // Check if channel has any actors
bool IsActorRegistered(FName ChannelId, AActor* Actor) const;

Events​

FERPOnActorRegisteredSignature OnActorRegistered;     // (FName ChannelId, AActor* Actor)
FERPOnActorUnregisteredSignature OnActorUnregistered;  // (FName ChannelId, AActor* Actor)

UERPRegistrationComponent​

Auto-registers the owning actor in the candidate registry on BeginPlay/EndPlay.

Header: Core/ERPRegistrationComponent.h

Properties​

PropertyTypeDefaultDescription
ChannelIdsTArray<FName>Channels to register for

Methods​

void RegisterChannel(FName ChannelId);    // Register for additional channel at runtime
void UnregisterChannel(FName ChannelId);  // Unregister from a channel at runtime

Widget Base Classes​

UERPInteractionWidgetBase (Abstract)​

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

Header: UI/Interaction/ERPInteractionWidgetBase.h

How it receives data: This widget does not fetch data itself. A presenter calls UpdateFromDescriptor() to push the descriptor. The two main patterns are:

  • Actor-side: Your ERPBaseInteractionFeedbackComponent subclass calls Widget->UpdateFromDescriptor(Descriptor) inside its OnDescriptorUpdated override
  • Player-side: Your PlayerController binds to OnDescriptorChanged and calls Widget->UpdateFromDescriptor(Descriptor) directly

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 FERPAwarenessContext& Context, float Range, TArray<AActor*>& OutCandidates) const;

UERPFilterBase​

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

UERPScorerBase​

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

UERPAggregatorBase​

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

UERPResolverBase​

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

Data Structures​

FERPAwarenessContext​

struct FERPAwarenessContext
{
    FName ChannelId;                   // Channel being evaluated (set per-channel)
    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: weighted average)
    UERPResolverBase* Resolver;          // Required
};

Default Implementations​

Samplers​

  • UERPSphereOverlapSampler - Sphere overlap query (spatial, range-limited)
  • UERPBoxOverlapSampler - Box overlap query (non-uniform spatial areas)
  • UERPRegistrySampler - Registry-based query (non-spatial, declarative — reads from UERPCandidateRegistrySubsystem)

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.