Combat integration (PulseAICombatBridge)

The bridge PulseAICombatBridge connects Pulse AI with the combat of PulseGameplay (GAS based UPulseCombatComponent, melee and ranged abilities). Enable it next to PulseAI and PulseGameplay.

What it adds

  • Profile extension “Combat” (FPulseAICombatProfile): attack set, maximum health, heal to full after Return Home (Pulse.AI.Event.Reset), boss data. On start it adds a UPulseAICombatAgentComponent to the pawn. The team is the Team of the profile itself (Pulse Foundation teams).
  • Death: dead targets are forgotten by everyone, a dead agent stops thinking. Damage as awareness comes from Pulse AI itself (the hit lowers an attribute, see Awareness).
  • Attack sets (UPulseAIAttackSet): attacks with ability, range, angle, cooldown, weight, conditions, token type and telegraph.
  • Attack tokens: only so many agents attack one target at a time (default 2 melee, 3 ranged; Easy -1, Hard +1).
  • Bosses: phases by health, enrage timer, boss bar for all players.
  • Encounters (APulseAIEncounter): waves started by player distance; saved with the encounter records, so a cleared camp stays cleared.
  • Attitude solver “Combat Teams”: friend and foe of combatants from the hostility rule of PulseGameplay (Pulse Foundation teams and alliances); actors without combat component fall back to the solver “Teams”.
  • StateTree nodes and cheats.

Attacks

Field Meaning
Name Id for cooldowns
Ability, Source Object The ability (e.g. UPulseMeleeAttackAbility, UPulseRangedAttackAbility) and its attack or projectile definition
Grant Ability Give the ability on start if missing (weapons from items grant their own)
Min / Max Range, Max Angle Where the target must be
Cooldown, Weight How often and how likely
Token Type Pulse.AI.Token.Melee / .Ranged or empty
Conditions Health, Boss Phase, Has Tag, own (FPulseAIAttackCondition)
Telegraph Time, Cue Announcement before the attack (VFX, HUD warning)
Extra Presses, Press Interval Combo inputs while the ability runs

The task Choose And Execute Attack filters the usable attacks, picks one by weight, takes its token, announces it, starts the ability with the target in the gameplay event data (Pulse.AI.Event.Attack) and waits for its end. The PulseGameplay melee and ranged abilities take the target from the event data.

Tokens

A melee token per attacker and target: the closer agent can take the token of a farther one that held it for a second and is not attacking. While waiting, agents circle (Keep Distance). Condition Token Available lets an agent go in when a token is free. Settings: Project Settings > Pulse > AI > Combat.

Example fighter StateTree

State Condition Tasks
Combat / Attack Can Attack Choose And Execute Attack
Combat / Approach Token Available (melee) Move To current target
Combat / Chase Target farther than 7 m Move To current target
Combat / Circle   Keep Distance (3.5 - 5.5 m, 1.5 s)

See ST_PulseAI_Fighter and ST_PulseAI_Boss in /PulseAICombatBridge/Examples.

Guards

A guard patrols, notices players, raises the alarm in its group, fights with sword and bow, chases within its leash, holds at the edge of it, returns home and patrols again. The bridge ships one, built in place by Tools/make_guard_example.py of the bridge (UPulseAICombatGuardExample in its editor module): the StateTree ST_PulseAI_CombatGuard, the profiles DA_PulseAIProfile_CombatGuard (sword and bow) and DA_PulseAIProfile_CombatArcher (bow, role Ranged), their attack sets and the map LV_PulseAICombat_Guards with a guard post of five guards.

State Condition Tasks
Return Home Beyond Leash Return Home (forget, heal), then the root picks again
Combat / Attack Can Attack Choose And Execute Attack
Combat / Hold Beyond Leash (On Target) Focus Target, back to Combat after 1 s
Combat / Keep Distance Has Role Ranged Keep Distance 8 - 14 m
Combat / Approach Token Available (melee) Move To current target
Combat / Chase Target farther than 7 m Move To current target
Combat / Circle   Keep Distance (3.5 - 5.5 m, 1.5 s)
Search / Investigate, Calm Down Awareness Is at least Suspicious Investigate, Set Awareness Unaware; beyond the leash Return Home
Idle / Patrol, Guard Post   Patrol (goes on where it stopped), without a route Wander 3 m
Alarm Has Target Focus Target for 0.8 s, then Combat

Idle and Search go to Alarm when an awareness or target event comes with a target: the guard stops and faces who it saw. The alarm itself is the one of Pulse AI: becoming Alert by its own discovery (Alarm When Alerted) alarms the guard’s group and friendly agents in the Alarm Radius (30 m); alarmed guards never alarm again. Hold keeps a guard at the edge of its leash (25 m from home) while the target stands beyond it; the bow still reaches.

  • Guard posts: Pulse::AI::Combat::Guards::SpawnGuardPost (C++) spawns a round patrol route and guards on it, every third an archer, all in one AI group. The cheat PulseAICombatSpawnGuards [count] [radius] and the optional setup step Place a guard post of the AI Combat bridge use it.
  • Own guards: copy the profiles (Add Starter Content) and change sight, leash, speeds and attacks; the tree needs only the Combat extension and a patrol route on the agent.
  • Factions: guards that hold a capture point of Pulse Faction Territory need the extension Factions, see Faction integration.
  • Pulse World: on ground made at runtime (voxel islands) the guards need a navigation mesh with Runtime Generation Dynamic and a pawn that keeps a terrain base: a Blueprint of APulseWorldAICharacter (PulseWorldAIBridge) with an Ability System Component and a Pulse Combat component. PulseWorldAIBridge holds them while the collision under them is not ready, for example on an island far from every player.

Bosses

Set Boss in the Combat extension and list the phases (health threshold, phase tag). Entering a phase adds the phase tag to the boss’ ability system and sends Pulse.AI.Event.BossPhase; after EnrageTime seconds of fighting Pulse.AI.Boss.Enraged and Pulse.AI.Event.Enraged follow. Attack condition Boss Phase unlocks attacks per phase. While the boss fights, every player gets a boss bar (UPulseCombatHUDSubsystem::PushBossBar).

The boss is one plain struct, FPulseAIBossState (GetBossState(): boss data, phase, enraged, fighting and the server time the fight started), changed by pure rules (Pulse::AI::Combat::StepBoss, ResetBoss, …). The enrage counts from the fight start: a fight that ends and starts again starts the count again. A reset (Return Home) ends the fight, goes back to the first phase and removes the enrage; a restarted or revived boss keeps an enrage it already had. Events come in the order fighting (boss bar), phase, enraged, on the server and on clients; a listener that changes the boss again (for example ResetCombat from OnEnraged) has its events sent after the running ones.

Encounters

Place an APulseAIEncounter, fill its waves (pawn class, profile, count; the next wave starts when at most N of the current one live and a minimum delay passed) and spawn points. It starts when a player comes within the activation radius, is cleared when all are dead (an agent whose pawn is removed counts as defeated) and resets when all players are beyond the reset radius. Spawned agents share the encounter’s group (alarms reach all) and difficulty. Messages: Pulse.Message.AI.Encounter.Started, .Wave, .Cleared, .Reset with FPulseAIEncounterMessage (encounter, id, wave) for quests; their context has the encounter as target, its id as tag, the number of waves started as amount and its location.

The flow is one plain struct, FPulseAIEncounterState (GetEncounterState(): stage, wave, times, members), changed by the pure rules in Pulse::AI::Combat::Encounter. Event order: OnStarted and the Started message come after wave 0 spawned, followed by OnWaveStarted(0); every event is sent after the state is complete. A listener that starts, resets, clears or loads the encounter again stops the remaining events of the outer call, so for example the Cleared message never follows the Reset message of a listener. On a reset the state is Idle before the agents are removed.

Saving encounters

Turn on the setup step Save encounters of the AI Combat bridge (Pulse window, Set Up): it adds the UPulseAIEncounterRecordsComponent to the game state (automatic component EncounterRecordsComponent in Project Settings > Pulse > AI Combat). The component keeps one record per encounter and saves it as bytes through Pulse Foundation’s IPulseByteSaveable, so a PulseSave manager collects it from the game state without a save bridge. A cleared camp stays cleared after loading, also when it streamed out or its chunk was generated again, because the records live on the game state, not on the encounter.

  • Keys come from the encounter’s Save Identity (default tag Pulse.AI.Save.Encounter): [<Level>.]<ActorName>.Pulse.AI.Save.Encounter for placed encounters (the level part for sublevels and level instances, none for the persistent level and World Partition cells), World.Pulse.AI.Save.Encounter.<Key> for scope World with a Key.
  • Placed encounters need nothing. Encounters spawned while playing (generated camps, quest or cheat spawns) need scope World and a Key, set before BeginPlay: Expose On Spawn of SaveIdentity, or Set Save Identity before Finish Spawning. Without it they are not saved (a Log line says why). EncounterId is a quest tag several camps may share; it is not part of the key.
  • Save State (bSaveState, on by default, Expose On Spawn) turns saving off for one encounter.
  • A running fight is saved as waiting: after loading it starts again from wave 0 when a player comes near. While the game loads (UPulseSaveStatusSubsystem, held by the save system) encounters do not start by distance.
  • A load during a fight removes the spawned agents: OnReset (and the Reset message) first, then OnStateLoaded. OnStateLoaded also fires when an encounter that comes back pulls its cleared record.
  • Two encounters with the same key: the first keeps it, the second is not saved (a warning names both; give one a Key).
  • Without the records component nothing is saved (a Log line once per world), and Pulse Check warns about encounters with Save State in the open level.

Nodes

Node Kind
Choose And Execute Attack Task
Can Attack, Token Available, Target Is Dead, Boss Phase Conditions
Threat Considerations

Health Below and the consideration Health are nodes of Pulse AI (StateTree nodes): they read the attribute contract and work without the bridge. Health, the health of targets in attack conditions and boss phases come from the attribute source too (Pulse::Attributes::Read); dead is the state of the combat component, or depleted health for actors without one.

Cheats

Command Does
PulseAICombatSpawn [profile] [count] [distance] Spawns test fighters (APulseAICombatTestCharacter)
PulseAIEncounterSpawn [waves] Spawns an encounter with fighter waves and a boss
PulseAICombatSpawnGuards [count] [radius] Spawns a guard post: guards with sword and bow on a round route, one alarm group
PulseAICombatInfo Tokens on you, attacks and cooldowns of the closest fighter

Use PulseCombatGrant to make yourself a combatant and PulseCombatHit / PulseCombatKill target to fight back.


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