Skip to main content

ElysAwareness

Version Unreal Engine Proprietary licence

A powerful, modular Unreal Engine plugin for player-side perception and evaluation built on a configurable Pipeline architecture.

Quick Navigation​

Setup Guide - Complete installation and configuration walkthrough

Pipeline System - Understanding the core architecture

Interaction Guide - Implementing proximity-based interactions

Instanced Interaction - Turn ISMC instances into interactable objects with state

Saving & Loading - Persist instance states across game sessions

Targeting Guide - Combat targeting and lock-on systems

Custom Domains - Create your own domains (extend UERPDomainComponent)

Widget Guide - Building interaction prompts, hold-to-interact, targeting UI

Customization - Creating custom pipeline components

API Reference - Complete class documentation

Quick Reference - Cheat sheet and common patterns

Overview​

ElysAwareness provides a data-driven perception system built from reusable components. Instead of hardcoding targeting or interaction logic, you assemble Pipelines that sample, filter, and score candidates each tick, with built-in aggregation and resolution.

Core workflow:

  1. Build a FERPAwarenessContext (origin, forward, viewport info)
  2. Run one or more channels (Target, Interaction, custom) through Pipelines
  3. Receive events when candidates are acquired or lost

Architecture​

The plugin is structured in three layers:

Perception Layer (UERPAwarenessComponent): The engine. Evaluates channels, picks best candidates, fires generic events. Knows nothing about gameplay semantics.

Domain Layer (UERPDomainComponent subclasses): Gameplay interpretation. UERPInteractionComponent and UERPTargetingComponent extend the abstract UERPDomainComponent base class. Each domain listens to a perception channel, applies domain-specific eligibility rules, and maintains state. You can create your own domains by extending UERPDomainComponent.

Presentation Layer (optional): Visual feedback components like UERPBaseInteractionFeedbackComponent and widget base classes. When present on an interactable actor, automatically notified by the domain layer. When absent, silently skipped — you can plug in your own UI logic at any level.

What It Includes​

  • Configurable Pipelines (Samplers, Filters, Scorers with weights, built-in aggregation and resolution)
  • Multi-channel architecture (Target and Interaction by default)
  • Extensible domain system (create custom domains in Blueprint or C++)
  • Registry-based candidate system for declarative, non-spatial perception (map markers, POIs, quest objectives)
  • Pipeline evaluation events exposing all scored candidates (for minimap, radar, multi-candidate displays)
  • Built-in multiplayer support (server-side RPC validation for interactions)
  • Blueprint and C++ friendly APIs
  • Debug logging and validation helpers
  • Visual feedback components (optional, auto-wired when present)
  • Configurable tick interval for performance control

What It Does Not Include​

  • Built-in AI behavior trees or blackboards
  • Complete ready-made UI (the plugin provides abstract widget base classes you extend in Blueprint — see Widget Guide)

Key Concepts​

UERPAwarenessComponent: Attach to PlayerController, Pawn, or custom Actor. Owns channels and Pipelines.

Channels: Independent evaluation tracks (e.g., Target, Interaction). Each has its own Pipeline and winner.

UERPDomainComponent: Abstract base class for gameplay domains. Handles channel binding, candidate tracking, and change events. Extend this to create custom domains.

Pipeline Stages:

  • Sampler: Gathers candidate actors (sphere overlap, box overlap, registry, custom query)
  • Filters: Reject invalid actors (interfaces, distance, custom rules)
  • Scorers: Assign weighted scores (lower is better by default)
  • Aggregation: Combine weighted scorer outputs (built-in weighted average)
  • Resolution: Pick the winner candidate (configurable via ResolverPolicy and StickyBias on the pipeline struct)

Context (FERPAwarenessContext): Channel ID, origin, forward direction, aim ray, viewport projection info, screen projection PC, owning actor. Built per-channel and shared across all pipeline stages.

Interfaces:

  • IERPTargetable: Opt-in for targeting
  • IERPInteractable: Opt-in for interaction (includes ExecuteInteraction with RPC support)
  • IERPAwarenessContextProvider: Customize context building

Quick Start​

Minimal setup (full guide in Setup Guide):

  1. Add component: ERPAwarenessComponent on your PlayerController or Pawn
  2. Configure Target Pipeline (component details):
    • Channel Id: Target
    • Sampler: ERPSphereOverlapSampler (TraceChannel: Visibility, ignore context actor)
    • Filter: ERPTargetableFilter
    • Scorer: ERPDistanceScorer (normalize by range), Weight: 1.0
    • ResolverPolicy: LowestScore (lowest score wins)
  3. Add domain: ERPTargetingComponent set to channel Target
  4. Make actors targetable: Add ERPTargetable interface and return true in CanBeTargetedBy
  5. Bind events: Listen to OnDomainCandidateChanged or OnDescriptorChanged on the targeting component

Multi-Channel Events​

For custom channels beyond Target/Interaction, use generic channel events on UERPAwarenessComponent:

  • OnChannelCandidateAcquired(FName ChannelId, AActor* Candidate)
  • OnChannelCandidateLost(FName ChannelId, AActor* Candidate)
  • OnChannelEvaluated(FName ChannelId, TArray<FERPPipelineScoredCandidate> ScoredCandidates) — all candidates that passed the pipeline (for minimap, radar, etc.)

For single-channel setups with no domain logic, use UERPChannelListenerComponent.

For gameplay domains (eligibility rules, descriptors), extend UERPDomainComponent. See Custom Domains.

Architecture Philosophy​

Modular Building Blocks​

The plugin provides independent building blocks that connect automatically when used together, but never force a specific approach. You can use all of them, some of them, or replace any piece with your own logic.

Perception handles detection and evaluation:

  • Which actors are in range?
  • Which actor scores best?

Domain handles eligibility and state (via UERPDomainComponent subclasses):

  • Can this actor be interacted with right now?
  • What action is available?
  • You can use the built-in ERPInteractionComponent / ERPTargetingComponent, or create your own domain.

Presentation handles visuals (entirely optional):

  • ERPBaseInteractionFeedbackComponent: placed on interactable actors, automatically notified by ERPInteractionComponent when the actor gains/loses focus. If absent, the interaction system works the same — you just handle visuals yourself.
  • Widget base classes (ERPInteractionWidgetBase, ERPTargetingWidgetBase): convenience base classes for UMG widgets. You can also build widgets from scratch on UUserWidget and drive them from domain events directly.

Pick What You Need​

You want to...Use...
Use the full interaction system out of the boxERPInteractionComponent + ERPBaseInteractionFeedbackComponent + widget base classes
Use the interaction system with your own UIERPInteractionComponent + bind to OnDescriptorChanged / OnDomainCandidateChanged
Use perception only and build everything elseERPAwarenessComponent + OnChannelCandidateAcquired / OnChannelCandidateLost
Build a custom domain (stealth, loot, etc.)Extend UERPDomainComponent

The plugin remains UI-agnostic and gameplay-agnostic. Every layer is a building block, not a framework.

Next Steps​

New users: Start with Setup Guide for step-by-step installation and configuration.

Understand the system: Read Pipeline System to learn how detection works.

Implement interactions: Follow Interaction Guide for proximity-based interactions.

Implement targeting: Follow Targeting Guide for combat targeting.

Build your UI: Follow Widget Guide for interaction prompts, hold-to-interact, and targeting widgets.

Create custom domains: See Custom Domains to extend UERPDomainComponent.

Extend the pipeline: Create custom components in Customization.