Awareness

The awareness component keeps one entry per known enemy (FPulseAIKnownTarget): last location and time, a value from 0 to 1, threat, whether it is seen right now and how it was noticed last. Only actors the attitude solver calls hostile become targets; allies are ignored, neutral actors only after they attacked.

The attitude is asked when an actor is noticed. When it changes later (a team, a faction rank), call UPulseAISubsystem::RefreshAttitudes(Actor) (or RefreshAttitude of one awareness component): agents forget the actor when it is no enemy any more and know it as seen when it became one while in view; with no actor every agent checks all it knows and sees. PulseAIFactionBridge does this when reputation ranks, memberships or relations change.

Memory as data

What an agent knows is one plain struct, FPulseAIAwarenessMemory (GetMemory() on the component, also in Blueprint): the known targets, the point of interest, level and value, the current and the forced target. The rules that change it are pure functions in Pulse::AI::Memory (ApplySight, ApplyStimulus, ApplyDamage, ApplyAlarm, SetLevel, Forget, ForgetAll, StepMemory, RefreshLevel, SelectTarget): they take the memory and plain inputs, never a world or an actor, and return a change list (FPulseAIMemoryChanges) in the order the events are sent. The awareness component is a shell around them: it builds the inputs from actors, writes the facts the rules read (CurrentLocation and bPresent of every entry, bCurrentTargetGone), calls one rule, and announces the changes afterwards. Specs test the rules without a world (PulseAI.Memory).

Levels

Level Value Typical behavior
Unaware below Suspicious Threshold (0.2) Patrol, wander, ambient
Suspicious from 0.2 ”?”: look, investigate
Alert from Alert Threshold (0.6) ”!”: search, the target becomes the current target
Combat 1 (enemies only) Fight

The agent’s level is the highest level of all its targets (and of a noise without source).

How the value changes

  • Seeing raises the value by strength / ReactionTime per second. Strength is 1 close and in the middle of the view and falls towards the lose-sight radius and the edge of the view angle (at least 0.2 while seen). Perception modifiers change it.
  • Losing sight: Alert and Combat targets are remembered for ForgetTime seconds at their last location, then the value decays by DecayPerSecond. Weaker impressions decay at once. At 0 the target is forgotten.
  • Noises (AI perception hearing, UPulseAILibrary::ReportNoise) add NoiseAwareness x loudness. Noises without instigator become a point of interest that can be investigated.
  • Damage makes the attacker fully known (Combat) and adds its damage as threat. The awareness watches the attribute source of the pawn (Pulse Foundation attributes, with or without GAS): a damage attribute (DamageAttributes in the settings, health and shield by default) that falls through a change or a gameplay effect with an instigator is damage of that instigator; costs of the pawn itself, allies, rates, loads and other stats (a debuff, a stamina drain) are not. bDamageMakesAware in the settings turns it off; ReportDamage reports damage by hand. Damage of an attacker whose health is depleted (damage over time after its death) is ignored.
  • Only the living become new targets: an actor whose Pulse.Stat.Health is depleted is not remembered (Pulse::AI::IsAlive; an actor without health counts as alive). Targets that are known already stay until they are forgotten (the combat bridge forgets the dead).

Pulse AI reads only the health. A downed player of PulseGameplay combat (health depleted, but alive for combat until a finishing blow or a bleed-out) is therefore no new target, while an agent that knew the player already keeps them as its target until it forgets them. This is intended: agents do not hunt players who are down. A game that wants agents to finish downed players adds its own target rule, for example a StateTree task of the game that picks them through the combat state of PulseGameplay.

  • Alarms from allies raise the target to at least Alert at the reported location.

The current target

The current target is the hostile target with at least Alert value and the highest score of the profile’s target scorers: Distance, Visible, Threat, Current Or Last Attacker (keeps the target and takes revenge). SetForcedTarget overrides the scoring while the forced target is known.

Target ids

Every known target has an id (FPulseAITargetId): today the identity of its object in this session (kind Object with an FObjectKey), never saved or replicated. The actor on the entry is only a cache next to the id. Two facts the component writes from that cache before the rules run: CurrentLocation (where the target is now) and bPresent (it still exists). The rules (Pulse::AI::ShouldForget, SelectBestTarget, the built-in scorers) read only these, never the actor, so their result does not depend on when the garbage collector runs. A respawned pawn of a player is a new target, as before.

Blueprint has no generic struct compare: use Equal (Target Id) and Get Target Id Of Actor to check whether a known target is a given actor.

Own target scorers

USTRUCT(meta = (DisplayName = "Far Away"))
struct FMyTargetScorer_Far : public FPulseAITargetScorer
{
	GENERATED_BODY()

	virtual float Score(const FPulseAIKnownTarget& InTarget, const FPulseAIScoreContext& InContext) const override
	{
		return FMath::Clamp(FVector::Dist(InTarget.CurrentLocation, InContext.Location) / 3000.f, 0.f, 1.f);
	}
};

Read CurrentLocation and the other entry data, not Actor: entries without an actor (later entities) have no cache, and a scorer that reads the actor stays bound to it. InContext.CurrentTargetId names the current target.

Investigating

GetInvestigateLocation returns the last known location of the current target, otherwise of the strongest target or noise. The task Investigate walks there and looks around.

Own sources and modifiers

FPulseAIStimulus stimulus;
stimulus.Actor = Player;
stimulus.Location = Player->GetActorLocation();
stimulus.Type = Pulse::AI::Tags::Stimulus_Hearing;
stimulus.Strength = 0.5f;
UPulseAIAwarenessComponent::FindAwareness(Guard)->ReportStimulus(stimulus);

A perception modifier changes how well targets are noticed, e.g. darkness:

USTRUCT(meta = (DisplayName = "Darkness"))
struct FMyPerceptionModifier_Darkness : public FPulseAIPerceptionModifier
{
	GENERATED_BODY()

	virtual float ModifySight(const AActor* InSelf, const AActor* InTarget, float InStrength) const override
	{
		return InStrength * GetLightLevelAt(InTarget->GetActorLocation());
	}
};

The built-in Target Has Tag modifier lowers sight and hearing for targets with tags (crouching, stealth).

Events

Order: the memory is complete before anything is announced. Then the component’s events of a call come in the order of its change list (target spotted, noise, damaged, alarm or target lost; level changed; target changed), and after them the agent announces its replicated awareness and target. A listener that changes the awareness again (forgets, reports a stimulus) does not interleave: its announcements queue behind the running ones. The agent announces its own net changes in the order they were written, also when a listener stops or restarts it in between.

Exceptions kept on purpose: alarms and SetAwareness add a target without the StateTree event TargetSpotted; ForgetTarget and ForgetAll send OnTargetLost without the StateTree event TargetLost; a current target whose actor was destroyed is cleared without TargetChanged (a forgotten living target sends TargetChanged with none).

Event Payload
Pulse.AI.Event.TargetSpotted / TargetLost / TargetChanged / Damaged / Alarm / Noise FPulseAITargetEvent (target, location)
Pulse.AI.Event.AwarenessChanged FPulseAIAwarenessEvent (old and new level)
Pulse.AI.Event.Reset none (Return Home arrived)

The components also broadcast native and Blueprint events, and the message bus gets Pulse.Message.AI.AwarenessChanged and Pulse.Message.AI.Alarm (quests: “spotted by a guard”). Their context (Pulse::AI::MakeContext): the agent’s pawn as instigator, what it noticed as target and, when that belongs to a player, as player, the profile as source, the agent’s team as tags; the amount is the new level (0 unaware to 3 combat) or the number of allies an alarm reached, the location the agent’s (for alarms where the target was).


This site uses Just the Docs, a documentation theme for Jekyll.